本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Greengrass 探索 RESTful API
AWS IoT Greengrass 提供用戶端裝置可用來識別 Greengrass 核心裝置連線的 `Discover` API 操作。用戶端裝置會使用此資料平面操作來擷取連線至 Greengrass 核心裝置所需的資訊，您可以將它們與 [BatchAssociateClientDeviceWithCoreDevice](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_BatchAssociateClientDeviceWithCoreDevice.html) API 操作建立關聯。當用戶端裝置上線時，可以連線至 AWS IoT Greengrass 雲端服務，並使用 探索 API 來尋找：
+ 每個相關聯 Greengrass 核心裝置的 IP 地址和連接埠。
+ 核心裝置 CA 憑證，用戶端裝置可用來驗證 Greengrass 核心裝置。
**注意**
用戶端裝置也可以使用 中的探索用戶端 AWS IoT Device SDK 來探索 Greengrass 核心裝置的連線資訊。探索用戶端使用探索 API。如需詳細資訊，請參閱下列內容：
[測試用戶端裝置通訊](test-client-device-communications.md)
《 *AWS IoT Greengrass Version 1 開發人員指南*》中的 [Greengrass 探索 RESTful API](https://docs.aws.amazon.com/greengrass/v1/developerguide/gg-discover-api.html)。
若要使用此 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 端點和配額](https://docs.aws.amazon.com/general/latest/gr/greengrassv2.html)*AWS 一般參考*。此 API 操作僅適用於 Greengrass 資料平面端點。您用來管理元件和部署的控制平面端點與資料平面端點不同。
**注意**
AWS IoT Greengrass V1 和 的探索 API 相同 AWS IoT Greengrass V2。如果您有連接到 AWS IoT Greengrass V1 核心的用戶端裝置，您可以將它們連接到 AWS IoT Greengrass V2 核心裝置，而無需變更用戶端裝置上的程式碼。如需詳細資訊，請參閱《 *AWS IoT Greengrass Version 1 開發人員指南*》中的 [Greengrass 探索 RESTful API](https://docs.aws.amazon.com/greengrass/v1/developerguide/gg-discover-api.html)。
**Topics**
+ [探索身分驗證和授權](#greengrass-discover-auth)
+ [請求](#greengrass-discover-request)
+ [回應](#greengrass-discover-response)
+ [使用 cURL 測試探索 API](#greengrass-discover-test-request)
## 探索身分驗證和授權
若要使用 探索 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 政策允許名為 的 AWS IoT 物件`Discover`自行`MyClientDevice1`執行。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "greengrass:Discover",
"Resource": [
"arn:aws:iot:us-west-2:123456789012:thing/MyClientDevice1"
]
}
]
}
```
------
**重要**
核心裝置或 Greengrass 資料平面操作的政策中不支援 的[物件政策變數](https://docs.aws.amazon.com/iot/latest/developerguide/thing-policy-variables.html) (`iot:Connection.Thing.*`)。 AWS IoT 反之，您可以使用與具有類似名稱的多個裝置相符的萬用字元。例如，您可以指定 `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 上連線的用戶端必須實作 [Application Layer Protocol Negotiation (ALPN)](https://tools.ietf.org/html/rfc7301) TLS 延伸模組，並在 `ProtocolName`中`x-amzn-http-ca`做為 傳遞`ProtocolNameList`。如需詳細資訊，請參閱《 *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，每個核心裝置都在自己的群組中，其中 群組只包含該核心裝置及其連線資訊。
### 範例 Discover 回應文件
下列文件顯示與一個 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 探索問題](troubleshooting-client-devices.md#greengrass-discovery-issues)。