As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

API RESTful de descoberta do Greengrass

O AWS IoT Greengrass fornece a operação de API Discover que os dispositivos cliente podem usar para identificar os dispositivos principais do Greengrass em que eles podem se conectar. Os dispositivos cliente usam essa operação de plano de dados para recuperar as informações necessárias para se conectar aos dispositivos principais do Greengrass, em que você os associa à operação da API BatchAssociateClientDeviceWithCoreDevice. Quando um dispositivo cliente fica online, ele pode se conectar ao serviço de nuvem do AWS IoT Greengrass e usar a API de descoberta para encontrar:

Para usar esta operação de API, envie solicitações HTTP para a API de descoberta no endpoint do plano de dados do Greengrass. Este endpoint da API tem o seguinte formato.

https://greengrass-ats.iot.region.amazonaws.com:port/greengrass/discover/thing/thing-name

Para uma lista das Regiões da AWS e endpoints compatíveis para a API de descoberta do AWS IoT Greengrass, consulte endpoints e cotas do AWS IoT Greengrass V2 em Referência geral da AWS. Essa operação de API está disponível somente no endpoint do plano de dados do Greengrass. O endpoint do ambiente de gerenciamento que você usa para gerenciar componentes e implantações é diferente do endpoint do plano de dados.

Autenticação e autorização de descoberta

Para usar a API de descoberta para recuperar informações de conectividade, um dispositivo cliente deve usar a autenticação mútua TLS com um certificado de cliente X.509 para se autenticar. Para obter mais informações, consulte Certificados de cliente X.509 no Guia do desenvolvedor do AWS IoT Core.

Um dispositivo cliente também deve ter permissão para realizar a ação greengrass:Discover. O exemplo de política de AWS IoT a seguir permite que um objeto da AWS IoT chamado MyClientDevice1 execute Discover por conta própria.

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

Para mais informações, consulte Políticas de AWS IoT Core no Guia do desenvolvedor do AWS IoT Core.

Solicitação

A solicitação contém os cabeçalhos HTTP padrão e é enviada ao endpoint de descoberta do Greengrass, conforme mostrado nos exemplos a seguir.

O número da porta depende se o dispositivo principal é configurado para enviar o tráfego HTTPS pela porta 8443 ou pela 443. Para ter mais informações, consulte Conectar-se à porta 443 ou por meio de um proxy de rede.

Resposta

Em caso de sucesso, o cabeçalho da resposta inclui o código de status HTTP 200 e o corpo da resposta contém o documento de resposta de descoberta.

Exemplos de documentos de resposta de descoberta

O documento a seguir mostra a resposta de um dispositivo cliente que está associado a um dispositivo principal do Greengrass. O dispositivo principal tem um endpoint e um certificado de 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-----"
      ]
    }
  ]
}

O documento a seguir mostra a resposta para um dispositivo cliente que está associado a dois dispositivos principais. Os dispositivos principais têm vários endpoints e vários certificados de CA de grupo.

{
  "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-----"
      ]
    }
  ]
}

Testar a API de descoberta com cURL

Se tiver o cURL instalado, você poderá testar a API de descoberta. O exemplo a seguir especifica os certificados de um dispositivo cliente para autenticar uma solicitação no endpoint da API de descoberta do Greengrass.

curl -i \
  --cert 1a23bc4d56.cert.pem \
  --key 1a23bc4d56.private.key \
  https://greengrass-ats.iot.us-west-2.amazonaws.com:8443/greengrass/discover/thing/MyClientDevice1

Se a solicitação for bem-sucedida, este comando emitirá uma resposta semelhante ao exemplo a seguir.

{
  "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"
      ]
    }
  ]
}

Se o comando gerar um erro, consulte Solução de problemas de descoberta do Greengrass.