Greengrass Discovery RESTful API - Amazon IoT Greengrass
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

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

Greengrass Discovery RESTful API

Amazon IoT Greengrass提供DiscoverAPI 操作,客户端设备可以用来识别可以连接的 Greengrass 核心设备。客户端设备使用此数据平面操作检索连接到 Greengrass 核心设备所需的信息,您可以将这些设备与批处理关联设备与核心设备API 操作。当客户端设备联机时,它可以连接到Amazon IoT Greengrass云服务并使用发现 API 查找:

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

  • 核心设备 CA 证书,客户端设备可用于对 Greengrass 核心设备进行身份验证。

注意

客户端设备还可以使用 Amazon IoT Device SDK ,了解 Greengrass 核心设备的连接信息。发现客户端使用发现 API。有关更多信息,请参阅下列内容:

要使用此 API 操作,请将 HTTP 请求发送到 Greengrass 数据平面终端节点上的发现 API。此 API 终端节点采用以下格式。

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

有关受支持的列表 Amazon Web Services 区域 的终端节点和终端节点Amazon IoT Greengrass发现 API,请参阅Amazon IoT Greengrass V2终端节点和配额中的Amazon一般参考。此 API 操作仅在 Greengrass 数据平面终端节点上可用。用于管理组件和部署的控制平面端点与数据平面端点不同。

注意

发现 API 对于Amazon IoT Greengrass V1和Amazon IoT Greengrass V2。如果您的客户端设备连接到Amazon IoT Greengrass V1核心,您可以将它们连接到Amazon IoT Greengrass V2核心设备,而无需更改客户端设备上的代码。有关更多信息,请参阅 。Greengrass Discovery RESTful API中的Amazon IoT Greengrass Version 1开发人员指南

发现身份验证和授权

要使用发现 API 检索连接信息,客户端设备必须使用 TLS 相互身份验证与 X.509 客户端证书进行身份验证。有关更多信息,请参阅 。X.509 客户端证书中的 Amazon IoT Core 开发人员指南

客户端设备还必须具有执行greengrass:Discoveraction. 以下示例Amazon IoT策略允许Amazon IoT命名的事物MyClientDevice1执行Discover为本身。

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

事物策略变量(iot:Connection.Thing.*)中不支持Amazon IoT策略的核心设备或 Greengrass 数据平面操作。相反,您可以使用匹配具有相似名称的多个设备的通配符。例如,您可以指定MyGreengrassDevice*匹配MyGreengrassDevice1MyGreengrassDevice2,依此类推。

有关更多信息,请参阅 。 Amazon IoT Core 策略中的 Amazon IoT Core 开发人员指南

Request

请求包含标准 HTTP 标头,并发送到 Greengrass 发现终端节点,如下面的示例中所示。

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

注意

这些示例使用 Amazon Trust Services (ATS) 终端节点,该终端节点用于推荐的 ATS 根 CA 证书。终端节点必须与 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 扩展和传递x-amzn-http-ca作为ProtocolName中的ProtocolNameList。有关更多信息,请参阅 。协议中的Amazon IoT开发人员指南

Response

请求成功后,响应将包括标准的 HTTP 标头以及以下代码和正文:

HTTP 200 BODY: response document

有关更多信息,请参阅 示例发现响应文档

示例发现响应文档

由于Amazon IoT Greengrass V2使用与Amazon IoT Greengrass V1,响应会根据Amazon IoT Greengrass V1概念,如 Greengrass 组。响应包含 Greengrass 组的列表。InAmazon 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 发现问题疑难解答