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

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

Greengrass 发现 RESTful API

AWS IoT Greengrass提供了 Discover API 操作，客户端设备可以使用该操作来识别 Greengrass 核心设备可以连接的位置。客户端设备使用此数据平面操作来检索连接到 Greengrass 核心设备所需的信息，您可以将它们与 API 操作相关联。BatchAssociateClientDeviceWithCoreDevice当客户端设备上线时，它可以连接到AWS IoT Greengrass云服务并使用发现 API 来查找：

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

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

注意

客户端设备还可以使用中的发现客户端AWS IoT Device SDK来发现 Greengrass 核心设备的连接信息。发现客户端使用发现 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 IoT Greengrass V2终端节点和配额AWS 一般参考。此 API 操作仅在 Greengrass 数据平面端点上可用。用于管理组件和部署的控制平面端点与数据平面端点不同。

注意

AWS IoT Greengrass V1和的发现 API 相同AWS IoT Greengrass V2。如果您有连接到AWS IoT Greengrass V1核心的客户端设备，则无需更改客户端设备上的代码即可将它们连接到AWS IoT Greengrass V2核心设备。有关更多信息，请参阅《开发者指南》中的 Greengrass Discovery RES Tful API。AWS IoT Greengrass Version 1

发现身份验证和授权

要使用发现 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*匹配MyGreengrassDevice1MyGreengrassDevice2、等。

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

请求

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

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

注意

这些示例使用亚马逊信任服务 (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使用与相同的发现 APIAWS IoT Greengrass V1，因此响应会根据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 测试发现 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
注意

-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 发现问题疑难解答。