API RESTful de Greengrass Discovery - AWS IoT Greengrass
Descubrimiento, autenticación y autorizaciónSolicitudRespuestaPruebe la API de descubrimiento con cURL

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

API RESTful de Greengrass Discovery

AWS IoT Greengrassproporciona la operación de Discover API que los dispositivos cliente pueden usar para identificar los dispositivos principales de Greengrass a los que se pueden conectar. Los dispositivos cliente utilizan esta operación del plano de datos para recuperar la información necesaria para conectarse a los dispositivos principales de Greengrass, donde se asocian a la operación de la BatchAssociateClientDeviceWithCoreDeviceAPI. Cuando un dispositivo cliente se conecta a Internet, puede conectarse al servicio AWS IoT Greengrass en la nube y usar la API de detección para encontrar:

  • La dirección IP y el puerto de cada dispositivo principal de Greengrass asociado.

  • El certificado de CA del dispositivo principal, que los dispositivos cliente pueden usar para autenticar el dispositivo principal de Greengrass.

nota

Los dispositivos cliente también pueden usar el cliente de detección SDK para dispositivos con AWS IoT para descubrir la información de conectividad de los dispositivos principales de Greengrass. El cliente de detección utiliza la API de detección. Para obtener más información, consulte los siguientes temas:

Para usar esta operación de API, envíe solicitudes HTTP a la API de descubrimiento en el punto final del plano de datos de Greengrass. Este punto final de la API tiene el siguiente formato.

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

Para obtener una lista de los puntos finales Regiones de AWS y los puntos finales compatibles con la API de AWS IoT Greengrass descubrimiento, consulte AWS IoT Greengrass V2los puntos finales y las cuotas en. Referencia general de AWS Esta operación de API solo está disponible en el punto final del plano de datos de Greengrass. El punto final del plano de control que se utiliza para administrar los componentes y las implementaciones es diferente del punto final del plano de datos.

nota

La API de descubrimiento es la misma para AWS IoT Greengrass V1 yAWS IoT Greengrass V2. Si tiene dispositivos cliente que se conectan a un AWS IoT Greengrass V1 núcleo, puede conectarlos a los dispositivos AWS IoT Greengrass V2 principales sin cambiar el código de los dispositivos cliente. Para obtener más información, consulte la API RESTful de Greengrass Discovery en la AWS IoT Greengrass Version 1 Guía para desarrolladores.

Descubrimiento, autenticación y autorización

Para usar la API de detección para recuperar información de conectividad, un dispositivo cliente debe usar la autenticación mutua TLS con un certificado de cliente X.509 para autenticarse. Para obtener más información, consulte los certificados de cliente X.509 en la Guía para desarrolladores. AWS IoT Core

Un dispositivo cliente también debe tener permiso para realizar la greengrass:Discover acción. El siguiente ejemplo AWS IoT de política permite AWS IoT que una cosa denominada MyClientDevice1 funcione Discover por sí misma.

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

Las variables de política de cosas (iot:Connection.Thing.*) no se admiten en las AWS IoT políticas de dispositivos principales ni en las operaciones del plano de datos de Greengrass. En su lugar, puede utilizar un comodín que haga coincidir varios dispositivos con nombres similares. Por ejemplo, puede MyGreengrassDevice* especificar que coincida MyGreengrassDevice1MyGreengrassDevice2, etc.

Para obtener más información, consulte AWS IoT Corelas políticas en la Guía para AWS IoT Core desarrolladores.

Solicitud

La solicitud contiene los encabezados HTTP estándar y se envía al punto final de descubrimiento de Greengrass, como se muestra en los siguientes ejemplos.

El número de puerto depende de si el dispositivo principal está configurado para enviar tráfico HTTPS a través del puerto 8443 o el puerto 443. Para obtener más información, consulte Realizar la conexión en el puerto 443 o a través de un proxy de red.

nota

En estos ejemplos se utiliza el punto de conexión Amazon Trust Services (ATS), que funciona con los certificados de CA raíz ATS recomendados. Los puntos de enlace deben coincidir con el tipo de certificado de CA raíz.

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

Los clientes que se conecten por el puerto 443 deben implementar la extensión TLS de Negociación de Protocolo de Capa de Aplicación (ALPN) y pasar x-amzn-http-ca como el ProtocolName en el ProtocolNameList. Para obtener más información, consulte Protocolos en la Guía para desarrolladores de AWS IoT.

Respuesta

En caso de éxito, el encabezado de la respuesta incluye el código de estado HTTP 200 y el cuerpo de la respuesta contiene el documento de detección de la respuesta.

nota

Como AWS IoT Greengrass V2 utiliza la misma API de descubrimiento queAWS IoT Greengrass V1, la respuesta organiza la información según AWS IoT Greengrass V1 conceptos, como los grupos de Greengrass. La respuesta contiene una lista de grupos de Greengrass. EnAWS IoT Greengrass V2, cada dispositivo principal está en su propio grupo, donde el grupo contiene solo ese dispositivo principal y su información de conectividad.

Ejemplo de documentos de respuesta de detección

El siguiente documento muestra la respuesta de un dispositivo cliente que está asociado a un dispositivo principal de Greengrass. El dispositivo principal tiene un punto final y un 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-----"
      ]
    }
  ]
}

El siguiente documento muestra la respuesta de un dispositivo cliente que está asociado a dos dispositivos principales. Los dispositivos principales tienen varios puntos finales y varios 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-----"
      ]
    }
  ]
}

Pruebe la API de descubrimiento con cURL

Si la ha cURL instalado, puede probar la API de descubrimiento. El siguiente ejemplo especifica los certificados de un dispositivo cliente para autenticar una solicitud en el punto final de la API de descubrimiento de 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

El -i argumento especifica la salida de los encabezados de respuesta HTTP. Puede utilizar esta opción para ayudar a identificar los errores.

Si la solicitud se realiza correctamente, este comando genera una respuesta similar a la del siguiente ejemplo.

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

Si el comando genera un error, consulte Solución de problemas de detección de Greengrass.