终止支持通知：2026 年 10 月 7 日， Amazon 将停止对的支持。 Amazon IoT Greengrass Version 1 2026 年 10 月 7 日之后，您将无法再访问这些 Amazon IoT Greengrass V1 资源。如需了解更多信息，请访问[迁移自 Amazon IoT Greengrass Version 1](https://docs.amazonaws.cn/greengrass/v2/developerguide/migrate-from-v1.html)。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Greengrass Discovery API RESTful
所有与 Amazon IoT Greengrass 内核通信的客户端设备都必须是 Greengrass 组的成员。每个组必须有一个 Greengrass 核心。发现 API 使设备能够检索连接到 Greengrass 核心（与客户端设备位于同一 Greengrass 组中）所需的信息。当客户端设备首次联机时，它可以连接到 Amazon IoT Greengrass 服务并使用发现 API 来查找以下内容：
+ 设备所属的组。一个客户端设备最多可以是 10 个组的成员。
+ 组中 Greengrass 核心的 IP 地址和端口。
+ 组 CA 证书，该证书可用于对 Greengrass 核心设备进行身份验证。
**注意**
客户端设备还可以使用该 Amazon IoT 设备 SDKs 来发现 Greengrass 内核的连接信息。有关更多信息，请参阅 [Amazon IoT 设备软件开发工具包](what-is-gg.md#iot-device-sdk)。
要使用此 API，请将 HTTP 请求发送到发现 API 终端节点。例如：
```
https://greengrass-ats.iot.region.amazonaws.com:port/greengrass/discover/thing/thing-name
```
有关支持 Amazon Web Services 区域和 Amazon IoT Greengrass 发现 API 终端节点的列表，请参阅中的[Amazon IoT Greengrass 终端节点和配额*Amazon Web Services 一般参考*](https://docs.amazonaws.cn/general/latest/gr/greengrass.html)。这是一个仅限数据层面的 API。用于群组管理和 Amazon IoT Core 操作的终端节点与 Discovery API 端点不同。
## 请求
请求包含标准 HTTP 标头，并发送到 Greengrass 发现终端节点，如下面的示例中所示。
端口号取决于核心配置为是通过端口 8443 还是端口 443 发送 HTTPS 流量。有关更多信息，请参阅 [通过端口 443 或网络代理进行连接](gg-core.md#alpn-network-proxy)。
端口 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`。更多信息，请参阅 *Amazon IoT 开发人员指南*中的[协议](https://docs.amazonaws.cn/iot/latest/developerguide/protocols.html)。
这些示例使用 Amazon Trust Services (ATS) 终端节点，该终端节点用于 ATS 根 CA 证书（推荐）。终端节点必须与 CA 证书类型匹配。有关更多信息，请参阅 [服务端点必须与根 CA 证书类型匹配](gg-core.md#certificate-endpoints)。
## 响应
请求成功后，响应将包括标准的 HTTP 标头以及以下代码和正文：
```
HTTP 200
BODY: response document
```
有关更多信息，请参阅 [示例发现响应文档](#gg-discover-response-doc)。
## 发现授权
检索连接信息需要一个允许发起人执行 `greengrass:Discover` 操作的策略。使用客户端证书的 TLS 双向身份验证是唯一接受的身份验证形式。以下是允许发起人执行该操作的示例策略：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "greengrass:Discover",
"Resource": ["arn:aws:iot:us-west-2:123456789012:thing/MyThingName"]
}]
}
```
------
## 示例发现响应文档
以下文档显示了对属于组（包含一个 Greengrass 核心、一个终端节点和一个组 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-----"
]
}
]
}
```
以下文档显示了对属于两个组（包含一个 Greengrass 核心、多个终端节点和多个组 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-----"
]
}
]
}
}
```
**注意**
一个 Greengrass 组必须恰好定义一个 Greengrass 核心。来自该 Amazon IoT Greengrass 服务的任何包含 Greengrass 内核列表的响应都只包含一个 Greengrass 内核。
如果已安装 `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"]}]}
```