AWS IoT Greengrass
開発者ガイド

Greengrass Discovery RESTful API

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

  • デバイスが属しているグループ。デバイスは、最大 10 個のグループのメンバーにすることができます。

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

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

この API を使用するには、検出 API エンドポイントに HTTP リクエストを送信します。次に例を示します。

https://greengrass-ats.iot.リージョン.amazonaws.com:port/greengrass/discover/thing/thing-name

AWS IoT Greengrass 検出 API でサポートされる AWS のリージョンとエンドポイントのリストについては、AWS 全般リファレンスの「AWS リージョンとエンドポイント」を参照してください。これはデータプレーンのみの API です。グループ管理と AWS IoT オペレーションのエンドポイントは、検出 API エンドポイントとは異なります。

リクエスト

次の例で示すように、リクエストにはスタンダードな HTTP ヘッダーが含まれ、Greengrass 検出エンドポイントに送信されます。

ポート番号は、コアがポート 8443 またはポート 443 のどちらで HTTPS トラフィックを送信するように設定されているかによって異なります。詳細については、「ポート 443 での接続またはネットワークプロキシを通じた接続」を参照してください。

ポート 8443
HTTP GET https://greengrass-ats.iot.リージョン.amazonaws.com:8443/greengrass/discover/thing/thing-name
ポート 443
HTTP GET https://greengrass-ats.iot.リージョン.amazonaws.com:443/greengrass/discover/thing/thing-name

ポート 443 で接続するクライアントは、Application Layer Protocol Negotiation (ALPN) TLS 拡張機能を実装し、ProtocolNameListProtocolName として x-amzn-http-ca を渡す必要があります。詳細については、AWS IoT 開発者ガイド の「プロトコル」を参照してください。

注記

この例では、ATS ルート CA 証明書 (推奨) で使用される Amazon Trust Services (ATS) エンドポイントを使用します。エンドポイントはルート CA 証明書タイプと一致する必要があります。詳細については、「エンドポイントは証明書タイプと一致する必要がある」を参照してください。

レスポンス

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

HTTP 200 BODY: response document

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

承認

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

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "greengrass:Discover", "Resource": ["arn:aws:iot:us-west-2:123456789012:thing/MyThingName"] }] }

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

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

{ "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 IoT Greengrass コア、複数のエンドポイント、および複数のグループ CA を持つ 2 つのグループのメンバーであるデバイス用のレスポンスを示しています。

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

cURL をインストールしている場合は、検出リクエストをテストできます。次に例を示します。

$ curl --cert 1a23bc4d56.cert.pem --key 1a23bc4d56.private.key https://greengrass-ats.iot.us-west-2.amazonaws.com:8443/greengrass/discover/thing/MyDevice {"GGGroups":[{"GGGroupId":"1234a5b6-78cd-901e-2fgh-3i45j6k1789","Cores":[{"thingArn":"arn:aws:iot:us-west-2:1234567 89012:thing/MyFirstGroup_Core","Connectivity":[{"Id":"AUTOIP_192.168.1.4_1","HostAddress":"192.168.1.5","PortNumber ":8883,"Metadata":""}]}],"CAs":["-----BEGIN CERTIFICATE-----\ncert-contents\n-----END CERTIFICATE-----\n"]}]}