Greengrass Discovery RESTful API - AWS IoT Greengrass
发现身份验证和授权请求响应使用 cURL 测试 Discovery API

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Greengrass Discovery RESTful API

AWS IoT Greengrass 可提供 Discover API 操作，客户端设备可以使用该操作来识别客户端设备可以连接的 Greengrass 核心设备。客户端设备使用此数据面板操作来检索连接到 Greengrass 核心设备所需的信息，您可以通过 BatchAssociateClientDeviceWithCoreDevice API 操作将客户端设备与核心设备相关联。当客户端设备联机时，它可以连接到 AWS IoT Greengrass 云服务并使用 Discovery API 来查找以下内容：

  • 每台关联的 Greengrass 核心设备的 IP 地址和端口。

  • 核心设备 CA 证书，客户端设备可以使用该证书对 Greengrass 核心设备进行身份验证。

注意

客户端设备还可以使用 AWS IoT Device SDK 中的发现客户端来发现 Greengrass 核心设备的连接信息。发现客户端使用 Discovery API。有关更多信息，请参阅下列内容：

要使用此 API 操作，请将 HTTP 请求发送到 Greengrass 数据面板端点上的发现 API。此 API 端点具有以下格式。

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

有关 AWS IoT Greengrass Discovery API 支持的 AWS 区域 和端点的列表，请参阅《AWS 一般参考》中的 AWS IoT Greengrass V2 端点和配额。此 API 操作仅在 Greengrass 数据面板端点上可用。用于管理组件和部署的控制面板端点与数据面板端点不同。

注意

Discovery API 同样适用于 AWS IoT Greengrass V1 和 AWS IoT Greengrass V2。如果您有连接到 AWS IoT Greengrass V1 核心的客户端设备，则无需更改客户端设备上的代码即可将客户端设备连接到 AWS IoT Greengrass V2 核心设备。有关更多信息，请参阅《AWS IoT Greengrass Version 1 开发人员指南》中的 Greengrass Discovery RESTful API。

发现身份验证和授权

要使用 Discovery API 检索连接信息，客户端设备必须将 TLS 双向身份验证和 X.509 客户端证书配合使用才能进行身份验证。有关更多信息，请参阅《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"
      ]
    }
  ]
}
重要

核心设备或 Greengrass 数据面板操作的 AWS IoT 策略不支持事物策略变量 (iot:Connection.Thing.*)。相反，您可以使用通配符来匹配多个名称相似的设备。例如，您可以指定 MyGreengrassDevice* 以匹配 MyGreengrassDevice1、MyGreengrassDevice2 等。

有关更多信息，请参阅《AWS IoT Core 开发人员指南》中的 AWS IoT Core 策略。

请求

请求包含标准 HTTP 标头，并已发送到 Greengrass 发现端点，如以下示例所示。

端口号取决于核心设备已配置为通过端口 8443 还是端口 443 发送 HTTPS 流量。有关更多信息，请参阅 通过端口 443 或网络代理进行连接。

注意

这些示例使用 Amazon Trust Services（ATS）端点，该端点使用推荐的 ATS 根 CA 证书。终端节点必须与 CA 证书类型匹配。

端口 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 开发人员指南中的协议。

响应

成功后，响应标头中包含 HTTP 200 状态码，响应正文中包含发现响应文档。

注意

由于 AWS IoT Greengrass V2 使用与 AWS IoT Greengrass V1 相同的发现 API，因此响应会根据 AWS IoT Greengrass V1 概念（例如 Greengrass 组）组织信息。响应中包含 Greengrass 组的列表。在 AWS IoT Greengrass V2 中，每台核心设备都位于自己的组中，该组中仅包含该核心设备及其连接信息。

示例发现响应文档

以下文档显示了与一个 Greengrass 核心设备关联的客户端设备的响应。核心设备拥有一个端点和一个 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-----"
      ]
    }
  ]
}

以下文档显示了与两个核心设备关联的客户端设备的响应。核心设备拥有多个端点和多个组 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 测试 Discovery API

如果已安装 cURL，即可测试发现 API。以下示例指定了客户端设备的证书，用于对发往 Greengrass Discovery 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
注意

-i 参数指定输出 HTTP 响应标头。您可以使用此选项来帮助识别错误。

如果请求成功，此命令将输出类似于以下示例的响应。

{
  "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 Discovery 问题疑难解答。