Greengrass Discovery RESTful API - AWS IoT Greengrass
请求响应发现授权示例发现响应文档

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 地址和端口。

  • 组 CA 证书，该证书可用于对 Greengrass 核心设备进行身份验证。

注意

客户端设备还可以使用 AWS IoT 设备软件开发工具包发现 Greengrass 核心的连接信息。有关更多信息，请参阅AWS IoT Device 软件开发工具包。

要使用此 API，请将 HTTP 请求发送到发现 API 终端节点。例如：

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

有关 AWS IoT Greengrass Discovery API 支持的 Amazon Web Services 区域和端点的列表，请参阅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 上连接的客户端必须实现应用层协议协商 (ALPN) TLS 扩展，并且必须在 ProtocolNameList 中作为 ProtocolName 传递 x-amzn-http-ca。更多信息，请参阅 AWS IoT 开发人员指南中的协议。

注意

这些示例使用 Amazon Trust Services (ATS) 终端节点，该终端节点用于 ATS 根 CA 证书（推荐）。终端节点必须与 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"]
     }]
}

示例发现响应文档

以下文档显示了对属于组（包含一个 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"]}]}