Greengrass Discovery RESTful API - AWS IoT Greengrass

AWS IoT Greengrass Version 1 は機能更新を受信しなくなり、2023 年 6 月 30 日までセキュリティパッチとバグ修正のみ受信します。詳細については、「AWS IoT Greengrass V1 メンテナンスポリシー」を参照してください。重要な新機能新たなプラットフォームのサポートが追加された AWS IoT Greengrass Version 2 への移行を強くお勧めします。

Greengrass Discovery RESTful API

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

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

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

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

注記

クライアントデバイスでは、AWS IoT Device SDK を使用して、Greengrass Core の接続情報を検出することもできます。詳細については、「AWS IoTDevice SDK」を参照してください。

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

https://greengrass-ats.iot.region.amazonaws.com:port/greengrass/discover/thing/thing-name

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

リクエスト

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

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

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

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

注記

この例では、ATS ルート CA 証明書 (推奨) で使用される Amazon Trust Services (ATS) エンドポイントを使用します。エンドポイントはルート CA 証明書タイプと一致する必要があります。詳細については、「サービスエンドポイントはルート 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 つの 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 つの 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-----" ] } ] } }
注記

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

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"]}]}