Greengrass 发现 RESTful API

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

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

注意

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

测试客户端设备通信
开发者@@ 指南中的 Greengrass Discovery RES Tful API。Amazon IoT Greengrass Version 1

要使用此 API 操作，请向 Greengrass 数据平面端点上的发现 API 发送 HTTP 请求。此 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 Discovery RES Tful API。Amazon IoT Greengrass Version 1

发现身份验证和授权

要使用发现 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*匹配MyGreengrassDevice1MyGreengrassDevice2、等。

有关更多信息，请参阅《Amazon IoT Core开发者指南》中的Amazon IoT Core政策。

请求

该请求包含标准的 HTTP 标头，并被发送到 Greengrass 发现端点，如以下示例所示。

端口号取决于核心设备是配置为通过端口 8443 还是端口 443 发送 HTTPS 流量。有关更多信息，请参阅通过端口 443 或网络代理进行连接。

注意

这些示例使用亚马逊信任服务 (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使用与相同的发现 APIAmazon 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 测试发现 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 发现问题疑难解答。

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

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

测试通信