翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Greengrass Discovery RESTful API

AWS IoT Greengrass は、クライアントデバイスが接続できる Greengrass コアデバイスを識別するために使用できる Discover API オペレーションを提供します。クライアントデバイスは、このデータプレーンオペレーションを使用して、BatchAssociateClientDeviceWithCoreDeviceGreengrass コアデバイスに接続するために必要な情報を取得し、 API オペレーションに関連付けます。クライアントデバイスがオンラインになると、AWS IoT Greengrass クラウドサービスに接続し、Discovery API を使用して以下を検索できます。

この API 操作を使用するには、Greengrass データプレーンのエンドポイントの 検出 API に HTTP リクエストを送信します。この API エンドポイントの形式は次のとおりです。

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

AWS IoT Greengrass 検出 API のエンドポイントおよび AWS リージョン の一覧については、「AWS 全般のリファレンス」の「AWS IoT Greengrass V2 エンドポイントとクオータ」を参照してください。この API 操作は Greengrass データプレーンのエンドポイントでのみ利用できます。コンポーネントおよびデプロイの管理に使用するコントロールプレーンのエンドポイントは、データプレーンのエンドポイントとは異なります。

検出認証と認可

検出 API を使用して接続情報を取得するには、クライアントデバイスで X.509 クライアント証明書による TLS 相互認証を使用して認証する必要があります。詳細については、「AWS IoT Core デベロッパーガイド」の「X.509 クライアント証明書」を参照してください。

クライアントデバイスには、greengrass:Discover アクションを実行する権限がある必要があります。以下の AWS IoT ポリシーの例は、MyClientDevice1 という名前の AWS IoT モノに Discover の実行が許可されています。

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

詳細については、「AWS IoT Core デベロッパーガイド」の「AWS IoT Core ポリシー」を参照してください。

リクエスト

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

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

レスポンス

成功すると、レスポンスヘッダーには HTTP 200 ステータスコードが含まれ、レスポンス本文には検出レスポンスドキュメントが含まれます。

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

次のドキュメントは、1 つの Greengrass コアデバイスに関連付けられているクライアントデバイスに対するレスポンスを示しています。コアデバイスには、1 つのエンドポイントと 1 つの CA 証明書があります。

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

次のドキュメントは、2 つのコアデバイスに関連付けられているクライアントデバイスに対するレスポンスを示しています。コアデバイスには、複数のエンドポイントと複数のグループ CA 証明書があります。

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

cURL でディスカバリ API をテストする

cURL をインストールしている場合は、検出 API をテストできます。次の例では、Greengrass ディスカバリ API エンドポイントへのリクエストを認証するクライアントデバイスの証明書を指定しています。

curl -i \
  --cert 1a23bc4d56.cert.pem \
  --key 1a23bc4d56.private.key \
  https://greengrass-ats.iot.us-west-2.amazonaws.com:8443/greengrass/discover/thing/MyClientDevice1

リクエストが成功すると、コマンドで下記の例のようなレスポンスが出力されます。

{
  "GGGroups": [
    {
      "GGGroupId": "greengrassV2-coreDevice-MyGreengrassCore",
      "Cores": [
        {
          "thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore",
          "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"
      ]
    }
  ]
}

コマンドでエラーが出力される場合は、「Greengrass ディスカバリの問題のトラブルシューティング」を参照してください。