AWS IoT Greengrass
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

Greengrass Discovery RESTful API

与 AWS IoT Greengrass Core通信的所有设备都必须是 Greengrass 组的成员。每个组都必须包含 AWS IoT Greengrass Core。发现 API 使设备能够检索连接到 AWS IoT Greengrass Core(与设备位于同一 Greengrass 组中)所需的信息。当设备首次联机时,它可以连接到 AWS IoT Greengrass 云服务并使用发现 API 来查找以下内容:

  • 设备所属的组。一个设备最多可以是 10 个组的成员。

  • 组中的 AWS IoT Greengrass Core的 IP 地址和端口。

  • 组的根 CA 证书,该证书可用于对 AWS IoT Greengrass Core设备进行身份验证。

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

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

有关 AWS IoT Greengrass 发现 API 支持的 AWS 区域和终端节点的列表,请参阅 AWS一般参考 中的 AWS 区域和终端节点。这是一个仅限数据层面的 API。组管理和 AWS IoT 操作的终端节点与发现 API 终端节点不同。

请求

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

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

端口 8443
HTTP GET https://greengrass-ats.iot.区域.amazonaws.com:8443/greengrass/discover/thing/thing-name
端口 443
HTTP GET https://greengrass-ats.iot.区域.amazonaws.com:443/greengrass/discover/thing/thing-name

与端口 443 进行连接的客户端必须实施应用程序层协议协商 (ALPN) TLS 扩展,并将 x-amzn-http-ca 作为 ProtocolNameList 中的 ProtocolName 传递。有关更多信息,请参阅AWS IoT 开发人员指南中的协议

注意

这些示例使用 Amazon Trust Services (ATS) 终端节点,该终端节点用于 ATS 根 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"] }] }

示例发现响应文档

以下文档显示了属于组(包含一个 AWS IoT Greengrass Core、一个终端节点和一个组 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-----" ] } ] }

以下文档显示了属于两个组(包含一个 AWS IoT Greengrass Core、多个终端节点和多个组 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-----" ] } ] } }

注意

一个 AWS IoT Greengrass 组必须正好定义一个 AWS IoT Greengrass Core。来自包含一组 AWS IoT Greengrass 核心的 AWS IoT Greengrass云服务的任何响应仅包含一个 AWS IoT Greengrass Core。

如果已安装 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"]}]}