Greengrass 发现 API RESTful

Amazon IoT Greengrass 提供了 Discover API 操作，客户端设备可以使用该操作来识别 Greengrass 核心设备可以连接的位置。客户端设备使用此数据平面操作来检索连接到 Greengrass 核心设备所需的信息，您可以将它们与 API 操作相关联。BatchAssociateClientDeviceWithCoreDevice当客户端设备上线时，它可以连接到 Amazon IoT Greengrass 云服务并使用发现 API 来查找：

每台关联的 Greengrass 核心设备的 IP 地址和端口。
核心设备 CA 证书，客户端设备可以使用该证书对 Greengrass 核心设备进行身份验证。

注意

客户端设备还可以使用中的发现客户端 Amazon IoT Device SDK 来发现 Greengrass 核心设备的连接信息。发现客户端使用 Discovery API。有关更多信息，请参阅下列内容：

测试客户端设备通信
开发者@@ 指南中的 Greengrass 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 IoT Greengrass 发现 API 支持的终端节点列表 Amazon Web Services 区域和终端节点列表，请参阅中的Amazon IoT Greengrass V2 终端节点和配额Amazon Web Services 一般参考。此 API 操作仅在 Greengrass 数据面板端点上可用。用于管理组件和部署的控制面板端点与数据面板端点不同。

注意

Amazon IoT Greengrass V1 和的发现 API 相同 Amazon IoT Greengrass V2。如果您有连接到 Amazon IoT Greengrass V1 核心的客户端设备，则无需更改客户端设备上的代码即可将它们连接到 Amazon IoT Greengrass V2 核心设备。有关更多信息，请参阅《开发者指南》中的 Greengrass RESTful Discovery API。Amazon IoT Greengrass Version 1

发现身份验证和授权

要使用 Discovery API 检索连接信息，客户端设备必须将 TLS 双向身份验证和 X.509 客户端证书配合使用才能进行身份验证。有关更多信息，请参阅《Amazon IoT Core 开发人员指南》中的 X.509 客户端证书。

客户端设备还必须具有执行 greengrass:Discover 操作的权限。以下示例 Amazon IoT 策略允许名MyClientDevice1为 Amazon IoT 的事物自行执行Discover。


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "greengrass:Discover",
      "Resource": [
        "arn:aws:iot:us-west-2:123456789012:thing/MyClientDevice1"
      ]
    }
  ]
}

重要

核心设备或 Greengrass 数据面板操作的 Amazon IoT 策略不支持事物策略变量 (iot:Connection.Thing.*)。相反，您可以使用通配符来匹配多个名称相似的设备。例如，您可以指定 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 扩展，并且必须在 ProtocolNameList 中作为 ProtocolName 传递 x-amzn-http-ca。更多信息，请参阅 Amazon IoT 开发人员指南中的协议。

响应

成功后，响应标头中包含 HTTP 200 状态码，响应正文中包含发现响应文档。

注意

由于 Amazon IoT Greengrass V2 使用与相同的发现 API Amazon IoT Greengrass V1，因此响应会根据 Amazon IoT Greengrass V1 概念（例如 Greengrass 群组）来组织信息。响应中包含 Greengrass 组的列表。在中 Amazon 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-----\ncert-contents\n-----END CERTIFICATE-----\n"
      ]
    }
  ]
}

如果命令输出的是错误，请参阅 Greengrass Discovery 问题疑难解答。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

测试通信