本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
Greengrass 发现 RESTful API
Amazon IoT Greengrass提供Discover
客户端设备可以用来识别可以连接的 Greengrass 核心设备的 API 操作。客户端设备使用此数据平面操作来检索连接到 Greengrass 核心设备所需的信息,在其中将它们与批量将客户端设备与核心设备关联API 操作。当客户端设备联机时,它可以连接到Amazon IoT Greengrass云服务并使用发现 API 查找:
-
各个关联 Greengrass 核心设备的 IP 地址和端口。
-
客户端设备可用于对 Greengrass 核心设备进行身份验证的核心设备 CA 证书。
注意
客户端设备还可以在Amazon IoT Device SDK发现 Greengrass 核心设备的连接信息。发现客户端使用发现 API。有关更多信息,请参阅下列内容:
-
Greengrass Discovery RESTful API中的Amazon IoT Greengrass Version 1开发人员指南.
要使用此 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 V1core,你可以将它们连接到Amazon IoT Greengrass V2核心设备而无需更改客户端设备上的代码。有关更多信息,请参阅 。Greengrass Discovery RESTful API中的Amazon IoT Greengrass Version 1开发人员指南.
发现身份验证和授权
要使用发现 API 检索连接信息,客户端设备必须使用带有 X.509 客户端证书的 TLS 相互身份验证才能进行身份验证。有关更多信息,请参阅 。X.509 客户端证书中的Amazon IoT Core开发人员指南.
客户端设备还必须具有执行greengrass:Discover
action. 以下示例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*
要匹配MyGreengrassDevice1
、MyGreengrassDevice2
,等等。
有关更多信息,请参阅 。Amazon IoT Core策略中的Amazon 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 延长和通行证 x-amzn-http-ca
作为ProtocolName
中的ProtocolNameList
. 有关更多信息,请参阅 。协议中的Amazon IoT开发人员指南.
响应
成功后,响应标头包含 HTTP 200 状态代码,响应正文包含发现响应文档。
注意
由于Amazon IoT Greengrass V2使用与相同的发现 APIAmazon 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
\ --key1a23bc4d56.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-----\n
cert-contents
\n-----END CERTIFICATE-----\n" ] } ] }
如果命令输出错误,请参阅排查 Greengrass 发现问题.