Greengrass Discovery RESTful API - AWS IoT Greengrass
請求回應Discovery 准許範例 Discover 回應文件

AWS IoT Greengrass Version 1 於 2023 年 6 月 30 日進入延長使用壽命階段。如需詳細資訊，請參閱AWS IoT Greengrass V1 維護政策。在此日期之後， AWS IoT Greengrass V1 將不會發行提供功能、增強功能、錯誤修正或安全性修補程式的更新。在上運行的設備 AWS IoT Greengrass V1 不會中斷，並將繼續運行並連接到雲。我們強烈建議您移轉至 AWS IoT Greengrass Version 2，這會增加重要的新功能，並支援其他平台。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

Greengrass Discovery RESTful API

與AWS IoT Greengrass核心通訊的所有用戶端裝置都必須是 Greengrass 群組的成員。每個群組都必須有一個 Greengrass 核心。探索 API 可讓裝置擷取連線至與用戶端裝置位於相同 Greengrass 群組中的 Greengrass 核心所需的資訊。當用戶端裝置首次上線時，它可以連線到AWS IoT Greengrass服務，並使用探索 API 來尋找：

  • 其所屬的群組。一個用戶端裝置最多可為 10 個群組的成員。

  • 群組中 Greengrass 核心的 IP 位址和連接埠。

  • 群組憑證授權機構憑證可用於驗證 Greengrass 核心裝置。

注意

用戶端裝置也可以使用AWS IoT裝置 SDK 搜尋 Greengrass 核心的連線資訊。如需詳細資訊，請參閱AWS IoT 裝置 SDK。

若要使用此 API，請傳送 HTTP 請求給 Discovery API 端點。例如：

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

如需AWS IoT Greengrass探索 API 支援的 Amazon Web Services 區域和AWS IoT Greengrass端點清單，請參閱 AWS 一般參考. 這是一個僅限 API 的資料平面。適用於群組管理和 AWS IoT Core 操作的端點與來自 Discovery API 的端點不一樣。

請求

此請求包含標準 HTTP 標題並已傳送到 Greengrass Discovery 端點，如下列範例所示。

連接埠號碼取決於核心是否設定為透過連接埠 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 上連線的用戶端必須實x-amzn-http-ca作應用程式層通訊協定交涉 (ALPN) TLS 延伸模組，並按照ProtocolName中的ProtocolNameList. 如需詳細資訊，請參閱AWS IoT開發人員指南中的通訊協定。

注意

這些範例使用 Amazon Trust Services (ATS) 端點，這是用於 ATS 根 CA 憑證 (建議使用)。端點必須符合根 CA 憑證類型。如需詳細資訊，請參閱服務端點必須符合根 CA 憑證類型。

回應

成功時，回應會包括標準 HTTP 標頭以及下列程式碼與本文：

HTTP 200
BODY: response document

如需詳細資訊，請參閱範例 Discover 回應文件。

Discovery 准許

擷取連線資訊需要一項允許發起人執行 greengrass:Discover 動作的政策。TLS 用戶端憑證的共同身分驗證僅接受身分驗證的格式。以下為允許發起人執行此動作的範例政策：

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

範例 Discover 回應文件

下列文件顯示屬於具有一個 Greengrass 核心、一個端點和一個群組 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-----"
      ]
    }
  ]
}

下列文件顯示了對具有一個 Greengrass 核心、多個端點和多個群組 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-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 群組必須只定義一個 Greengrass 核心。來自包含 Greengrass 核心清單的 AWS IoT Greengrass 服務的任何回應都只包含一個 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"]}]}