メニュー
AWS Greengrass
開発者ガイド

Greengrass Discovery RESTful API

AWS Greengrass コア と通信するすべてのデバイスは、Greengrass グループのメンバーである必要があります。各グループには AWS Greengrass コア が必要です。Discovery API により、デバイスは、デバイスと同じ Greengrass グループ内の AWS Greengrass コア に接続するために必要な情報を取得します。デバイスが最初にオンラインになると、AWS Greengrass クラウドサービスに接続し、Discovery API を使用して以下を検索できます。

  • デバイスが属しているグループ。

  • グループ内の AWS Greengrass コア の IP アドレスとポート。

  • AWS Greengrass コア デバイスを認証するために使用できる、グループのルート CA 証明書。

この API を使用するには、以下の URI に HTTP リクエストを送信します。

Copy
https://your-aws-endpoint/greengrass/discover/thing/thing-name

エンドポイントは AWS アカウントに固有のものです。エンドポイントを取得するには aws iot describe-endpoint CLI コマンドを使用します。

Copy
$ aws iot describe-endpoint { "endpointAddress": "a1b2c3d4e5f6g7.iot.us-west-2.amazonaws.com" }

接続するときはポート 8443 を使用します。リージョン固有のエンドポイントのリストについては、AWS 全般リファレンスの「AWS IoT リージョンとエンドポイント」を参照してください。これはデータプレーンのみの API です。ルール、証明書、およびポリシーを操作するために使用するエンドポイントは、検出 API をサポートしていません。

リクエスト

リクエストには標準の HTTP ヘッダーが含まれ、以下の URI に送信されます。

Copy
HTTP GET https://your-aws-endpoint/greengrass/discover/thing/thingName

レスポンス

レスポンス

成功した場合、レスポンスには標準の HTTP ヘッダーに加えて、以下のコードと本体が含まれます。

Copy
HTTP 200 BODY: response document

詳細については、検出レスポンスドキュメントの例 を参照してください。

承認

接続情報を取得するには、呼び出し元に greengrass:Discover アクションの実行を許可するポリシーが必要です。クライアント証明書による TLS 相互認証が、許可される唯一の認証形式です。呼び出し元がこのアクションを実行できるポリシー例を次に示します。

Copy
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "greengrass:Discover", "Resource": ["arn:aws:iot:aws-region:aws-account:thing/thing-name"] }] }

検出レスポンスドキュメントの例

次のドキュメントは、1 つの AWS Greengrass コア、1 つのエンドポイント、および 1 つのグループ CA を持つグループのメンバーであるデバイス用のレスポンスを示しています。

Copy
{ "GGGroups": [ { "GGGroupId": "gg-group-01-id", "Cores": [ { "thingArn": "core-01-thing-arn", "Connectivity": [ { "id": "core-01-connection-id", "hostAddress": "core-01-address", "portNumber": core-01-port, "metadata": "core-01-description" } ] } ], "CAs": [ "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----" ] } ] }

次のドキュメントは、1 つの AWS Greengrass コア、複数のエンドポイント、および複数のグループ CA を持つ 2 つのグループのメンバーであるデバイス用のレスポンスを示しています。

Copy
{ "GGGroups": [ { "GGGroupId": "gg-group-01-id", "Cores": [ { "thingArn": "core-01-thing-arn", "Connectivity": [ { "id": "core-01-connection-id", "hostAddress": "core-01-address", "portNumber": core-01-port, "metadata": "core-01-connection-1-description" }, { "id": "core-01-connection-id-2", "hostAddress": "core-01-address-2", "portNumber": core-01-port-2, "metadata": "core-01-connection-2-description" } ] } ], "CAs": [ "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----", "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----", "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----" ] }, { "GGGroupId": "gg-group-02-id", "Cores": [ { "thingArn":"core-02-thing-arn", "Connectivity" : [ { "id": "core-02-connection-id", "hostAddress": "core-02-address", "portNumber": core-02-port, "metadata": "core-02-connection-1-description" } ], "CAs": [ "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----", "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----", "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----" ] } ] } }

注記

AWS Greengrass グループは、厳密に 1 つの AWS Greengrass コア を定義する必要があります。AWS Greengrass コア のリストを含む AWS Greengrass クラウドサービスからのすべてのレスポンスには、1 つの AWS Greengrass コア のみが含まれます。