Autenticação e autorização de descoberta Solicitação Resposta Teste a API de descoberta com cURL

API RESTful de descoberta do Greengrass

AWS IoT Greengrassfornece a operação de Discover API que os dispositivos cliente podem usar para identificar os principais dispositivos do Greengrass aos quais 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, onde você os BatchAssociateClientDeviceWithCoreDeviceassocia à operação da API. Quando um dispositivo cliente fica on-line, ele pode se conectar ao serviço de AWS IoT Greengrass nuvem e usar a API de descoberta para encontrar:

O endereço IP e a porta de cada dispositivo principal do Greengrass associado.
O certificado CA do dispositivo principal, que os dispositivos clientes podem usar para autenticar o dispositivo principal do Greengrass.

nota

Os dispositivos cliente também podem usar o cliente de descoberta no AWS IoT Device SDK para descobrir informações de conectividade dos dispositivos principais do Greengrass. O cliente de descoberta usa a API de descoberta. Para ver mais informações, consulte:

Teste as comunicações entre dispositivos clientes
API RESTful do Greengrass Discovery no Guia do AWS IoT Greengrass Version 1 desenvolvedor.

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


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

Para obter uma lista de endpoints compatíveis Regiões da AWS e de extremidade para a API de AWS IoT Greengrass descoberta, consulte AWS IoT Greengrass V2endpoints e cotas no. 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 plano de controle que você usa para gerenciar componentes e implantações é diferente do endpoint do plano de dados.

nota

A API de descoberta é a mesma para AWS IoT Greengrass V1 AWS IoT Greengrass V2 e. Se você tiver dispositivos cliente que se conectam a um AWS IoT Greengrass V1 núcleo, você pode conectá-los aos dispositivos AWS IoT Greengrass V2 principais sem alterar o código nos dispositivos cliente. Para obter mais informações, consulte a API RESTful do Greengrass Discovery no Guia do AWS IoT Greengrass Version 1 desenvolvedor.

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 AWS IoT Coredesenvolvedor.

Um dispositivo cliente também deve ter permissão para realizar a greengrass:Discover ação. O exemplo de AWS IoT política a seguir permite que uma AWS IoT coisa chamada MyClientDevice1 funcione Discover por si mesma.


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

Importante

As variáveis de política Thing (iot:Connection.Thing.*) não são suportadas em AWS IoT políticas para dispositivos principais ou operações de plano de dados do Greengrass. Em vez disso, você pode usar um caractere curinga que corresponda a vários dispositivos com nomes semelhantes. Por exemplo, você pode especificar MyGreengrassDevice* para corresponder MyGreengrassDevice1MyGreengrassDevice2, e assim por diante.

Para obter mais informações, consulte AWS IoT Coreas políticas no Guia do AWS IoT Core desenvolvedor.

Solicitação

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

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

nota

Esses exemplos usam o endpoint Amazon Trust Services (ATS), que funciona com os certificados de CA raiz ATS recomendados. Os endpoints devem corresponder ao tipo de certificado da CA raiz.

Porta 8443


HTTP GET https://greengrass-ats.iot.region.amazonaws.com:8443/greengrass/discover/thing/thing-name

Porta 443


HTTP GET https://greengrass-ats.iot.region.amazonaws.com:443/greengrass/discover/thing/thing-name

nota

Os clientes que se conectam na porta 443 devem implementar a extensão TLS do Application Layer Protocol Negotiation (ALPN) e passar x-amzn-http-ca como o ProtocolName no ProtocolNameList. Para obter mais informações, consulte Protocolos no Guia do desenvolvedor do AWS IoT.

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.

nota

Como AWS IoT Greengrass V2 usa a mesma API de descoberta queAWS IoT Greengrass V1, a resposta organiza as informações de acordo com AWS IoT Greengrass V1 conceitos, como grupos do Greengrass. A resposta contém uma lista de grupos do Greengrass. EmAWS IoT Greengrass V2, cada dispositivo principal está em seu próprio grupo, onde o grupo contém somente esse dispositivo principal e suas informações de conectividade.

Exemplos de documentos de resposta de descoberta

O documento a seguir mostra a resposta de um dispositivo cliente associado a um dispositivo principal do Greengrass. O dispositivo principal tem um endpoint e um certificado 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 de um dispositivo cliente associado a dois dispositivos principais. Os dispositivos principais têm vários endpoints e vários certificados 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-----"
      ]
    }
  ]
}

Teste a API de descoberta com cURL

Se você cURL instalou, pode 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

nota

O -i argumento especifica a saída de cabeçalhos de resposta HTTP. Você pode usar essa opção para ajudar a identificar erros.

Se a solicitação for bem-sucedida, esse comando gerará 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.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Testar comunicações

Retransmita mensagens MQTT entre dispositivos clientes e AWS IoT Core