このセクションでは、HTTP ブリッジを使用して、Cloud IoT Core と通信する方法について説明します。HTTP と MQTT の一般的な情報については、プロトコルをご覧ください。
このセクションで説明する各メソッドの詳細については、API ドキュメントを参照してください。
HTTP ブリッジを使用する前に、次の手順を行います。
- テレメトリー イベント用の Cloud Pub/Sub トピックなど、1 つ以上のデバイス レジストリを設定する
- デバイスを作成する
デバイスを認証する
HTTP ブリッジに対する各リクエストには、ヘッダーに JSON Web Token（JWT）が含まれている必要があります。
curl -H 'authorization: Bearer JWT' -H 'cache-control: no-cache' 'https://cloudiotdevice.googleapis.com/v1/projects/{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{device-id}/config?local_version=1'
デバイスのフルパスの末尾は、デバイス ID またはデバイスの数値 ID です。デバイス識別子の詳細については、デバイス登録をご覧ください。
複数のリクエストを連続して送信した場合でも、各リクエストには JWT を含める必要があります。Cloud IoT Core は、HTTP ブリッジを介した認証を「記憶」しません。認証と JWT の詳細については、デバイスのセキュリティとデバイスの認証情報のセクションをご覧ください。
テレメトリー イベントをパブリッシュする
テレメトリー イベントを Cloud IoT Core に公開するには、publishEvent メソッドを使用します。バイナリ ペイロード データは、base64 でエンコードする必要があります。
curl -X POST -H 'authorization: Bearer JWT' -H 'content-type: application/json' --data '{"binary_data": "DATA"}' -H 'cache-control: no-cache' 'https://cloudiotdevice.googleapis.com/v1/projects/{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{device-id}:publishEvent'
テレメトリー イベントは、Google Cloud Console またはデバイス レジストリ リソースの eventNotificationConfigs[i].pubsubTopicName フィールドで指定された Cloud Pub/Sub トピックに転送されます。publishEvent メソッドは、テレメトリー イベントを分類するためのオプションの subFolder フィールドを提供します。サブフォルダから Pub/Sub トピックにデータをパブリッシュする方法については、下記のセクションをご覧ください。
テレメトリー イベントを個別の Pub/Sub トピックに公開する
デバイスは、publishEvent メソッドの subFolder フィールドにサブフォルダを指定することで、データを個別の Pub/Sub トピックにパブリッシュできます。
curl -X POST -H 'authorization: Bearer JWT' -H 'content-type: application/json' --data '{"binary_data": "DATA", "sub_folder": "SUBFOLDER"}' -H 'cache-control: no-cache' 'https://cloudiotdevice.googleapis.com/v1/projects/{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{device-id}:publishEvent'
このサブフォルダは、デバイス レジストリ リソースの eventNotificationConfigs.subfolderMatches フィールドで、eventNotificationConfigs.pubsubTopicName フィールドに一致する Pub/Sub トピックを使用して構成する必要があります。データがサブフォルダに送信されると、そのデータはそのサブフォルダに一致する Pub/Sub トピックに公開されます。
デバイス レジストリの作成で詳しく説明するように、すべてのデバイス レジストリには、一致するサブフォルダがないデフォルトの Pub/Sub トピックが 1 つ必要です。デフォルトの Pub/Sub トピックが存在する場合、次の場合はデバイスが自動的にそのトピックにパブリッシュします。
subFolderフィールドにサブフォルダが指定されていないsubFolderフィールドにサブフォルダが指定されているが、デバイス レジストリに一致する Pub/Sub トピックがない
いずれの場合も、デフォルトの Pub/Sub トピックが存在しない場合、デバイスから送信されるデータは失われます。
過剰な負荷と指数バックオフ
Cloud IoT Core によって、過剰な負荷を発生させるプロジェクトが制限されます。デバイスが失敗したオペレーションを待機することなく再試行すると、同じ Google Cloud プロジェクト内のすべてのデバイスに影響する上限をトリガーできます。
再試行する場合は、導入されたジッターを伴う切り捨て型指数バックオフ アルゴリズムを実装することを強くおすすめします。
デバイスの構成
Cloud IoT Core を使用してデバイスを構成できます。デバイス構成は、ファームウェアの更新、デバイスの再起動、機能の有効化、その他のプロパティの変更に使用できるバイナリデータで構成されます。
HTTP ブリッジを使用してデバイスを構成するには、まず Cloud IoT Core で構成を定義してから、デバイスを介して構成をリクエストします。
HTTP リクエストを圧縮する
デバイスは、HTTP ブリッジを介して gzip 圧縮されたデータを Cloud IoT Core に送信できます。圧縮データを Cloud IoT Core に送信するには、各 HTTP リクエストに content-encoding: gzip HTTP ヘッダーを含める必要があります。
データを圧縮することで、デバイスからクラウド方向への帯域幅を削減できます。ただし、データを圧縮して Cloud IoT Core の合計使用コストを削減することはできません。詳細については、料金をご覧ください。
デバイス構成を更新する
HTTP ブリッジを使用する場合は、API を使用して明示的にデバイス構成をリクエストする必要があります。Cloud IoT Core は、HTTP ブリッジを介してデバイスに構成を push しません。代わりに、デバイスは新しい構成をポーリングする必要があります。
Cloud IoT Core から現在利用可能なデバイス構成を取得するには、getConfig リクエストを使用します。
curl -H 'authorization: Bearer JWT' -H 'cache-control: no-cache' 'https://cloudiotdevice.googleapis.com/v1/projects/{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{deviceid}/config?local_version=0'
localVersion クエリ パラメータを使用して、デバイスに現在存在する構成バージョンを指定できます。次の表に、このパラメータがレスポンスに与える影響を示します。
| デバイスのバージョン | API レスポンス |
|---|---|
localVersion が 0（デフォルト値） |
Cloud IoT Core の最新バージョン |
localVersion がゼロではなく、Cloud IoT Core の現在利用可能なバージョンと同じ |
OK（binary_data フィールドに空の構成を含む） |
localVersion がゼロでなく、Cloud IoT Core の現在利用可能なバージョンより古い（より小さい） |
Cloud IoT Core の現在（より新しい）のバージョン |
localVersion がゼロでなく、Cloud IoT Core の現在利用可能なバージョンより新しい（より大きい） |
OUT_OF_RANGE エラー |
デバイスの状態を設定する
setState リクエストを使用して、デバイスの状態を Cloud IoT Core に報告します。状態データは base64 でエンコードされている必要があります。
curl -X POST -H 'authorization: Bearer JWT' -H 'content-type: application/json' --data '{"state": {"binary_data": "DATA"}}' -H 'cache-control: no-cache' 'https://cloudiotdevice.googleapis.com/v1/projects/{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{deviceid}:setState'
デバイスの状態データを取得するには、Cloud Console でデバイスの詳細を表示するか、API を使用します。詳しくは、デバイスの状態をご覧ください。