本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Greengrass 发现 API RESTful
AWS IoT Greengrass 提供了 `Discover` API 操作，客户端设备可以使用该操作来识别 Greengrass 核心设备可以连接的位置。客户端设备使用此数据平面操作来检索连接到 Greengrass 核心设备所需的信息，您可以将它们与 API 操作相关联。[BatchAssociateClientDeviceWithCoreDevice](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_BatchAssociateClientDeviceWithCoreDevice.html)当客户端设备上线时，它可以连接到 AWS IoT Greengrass 云服务并使用发现 API 来查找：
+ 每台关联的 Greengrass 核心设备的 IP 地址和端口。
+ 核心设备 CA 证书，客户端设备可以使用该证书对 Greengrass 核心设备进行身份验证。
**注意**
客户端设备还可以使用中的发现客户端 AWS IoT Device SDK 来发现 Greengrass 核心设备的连接信息。发现客户端使用 Discovery API。有关更多信息，请参阅下列内容：
[测试客户端设备通信](test-client-device-communications.md)
*开发者@@ [指南中的 Greengrass RESTful 发现 API](https://docs.aws.amazon.com/greengrass/v1/developerguide/gg-discover-api.html)。AWS IoT Greengrass Version 1 *
要使用此 API 操作，请将 HTTP 请求发送到 Greengrass 数据面板端点上的发现 API。此 API 端点具有以下格式。
```
https://greengrass-ats.iot.{{region}}.amazonaws.com:{{port}}/greengrass/discover/thing/{{thing-name}}
```
有关 AWS IoT Greengrass 发现 API 支持的终端节点列表 AWS 区域 和终端节点列表，请参阅中的[AWS IoT Greengrass V2 终端节点和配额*AWS 一般参考*](https://docs.aws.amazon.com/general/latest/gr/greengrassv2.html)。此 API 操作仅在 Greengrass 数据面板端点上可用。用于管理组件和部署的控制面板端点与数据面板端点不同。
**注意**
AWS IoT Greengrass V1 和的发现 API 相同 AWS IoT Greengrass V2。如果您有连接到 AWS IoT Greengrass V1 核心的客户端设备，则无需更改客户端设备上的代码即可将它们连接到 AWS IoT Greengrass V2 核心设备。*有关更多信息，请参阅《开发者指南》中的 [Greengrass RESTful Discovery API](https://docs.aws.amazon.com/greengrass/v1/developerguide/gg-discover-api.html)。AWS IoT Greengrass Version 1 *
**Topics**
+ [发现身份验证和授权](#greengrass-discover-auth)
+ [请求](#greengrass-discover-request)
+ [响应](#greengrass-discover-response)
+ [使用 cURL 测试 Discovery API](#greengrass-discover-test-request)
## 发现身份验证和授权
要使用 Discovery API 检索连接信息，客户端设备必须将 TLS 双向身份验证和 X.509 客户端证书配合使用才能进行身份验证。有关更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [X.509 客户端证书](https://docs.aws.amazon.com/iot/latest/developerguide/x509-client-certs.html)。
客户端设备还必须具有执行 `greengrass:Discover` 操作的权限。以下示例 AWS IoT 策略允许名`MyClientDevice1`为 AWS IoT 的事物自行执行`Discover`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "greengrass:Discover",
"Resource": [
"arn:aws:iot:us-west-2:123456789012:thing/MyClientDevice1"
]
}
]
}
```
------
**重要**
核心设备或 Greengrass 数据面板操作的 AWS IoT 策略不支持[事物策略变量](https://docs.aws.amazon.com/iot/latest/developerguide/thing-policy-variables.html) (`iot:Connection.Thing.{{*}}`)。相反，您可以使用通配符来匹配多个名称相似的设备。例如，您可以指定 `MyGreengrassDevice*` 以匹配 `MyGreengrassDevice1`、`MyGreengrassDevice2` 等。
有关更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [AWS IoT Core 策略](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html)。
## 请求
请求包含标准 HTTP 标头，并已发送到 Greengrass 发现端点，如以下示例所示。
端口号取决于核心设备已配置为通过端口 8443 还是端口 443 发送 HTTPS 流量。有关更多信息，请参阅 [通过端口 443 或网络代理进行连接](configure-greengrass-core-v2.md#configure-alpn-network-proxy)。
**注意**
这些示例使用 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)](https://tools.ietf.org/html/rfc7301) TLS 扩展，并且必须在 `ProtocolNameList` 中作为 `ProtocolName` 传递 `x-amzn-http-ca`。更多信息，请参阅 *AWS IoT 开发人员指南*中的[协议](https://docs.aws.amazon.com/iot/latest/developerguide/protocols.html)。
## 响应
成功后，响应标头中包含 HTTP 200 状态码，响应正文中包含发现响应文档。
**注意**
由于 AWS IoT Greengrass V2 使用与相同的发现 API AWS 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 测试 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-----\n{{cert-contents}}\n-----END CERTIFICATE-----\n"
]
}
]
}
```
如果命令输出的是错误，请参阅 [Greengrass Discovery 问题疑难解答](troubleshooting-client-devices.md#greengrass-discovery-issues)。