API de RESTful de detección de Greengrass - AWS IoT Greengrass
Autenticación y autorización de detecciónSolicitudRespuestaPrueba de la API de detección 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 de RESTful de detección de Greengrass

AWS IoT Greengrass proporciona la operación de API Discover que los dispositivos de cliente pueden usar para identificar los dispositivos principales de Greengrass a los que se pueden conectar. Los dispositivos de cliente utilizan esta operación de plano de datos para recuperar la información necesaria para conectarse a los dispositivos principales de Greengrass, en los que se asocian a la operación de API BatchAssociateClientDeviceWithCoreDevice. Cuando un dispositivo de cliente se pone en línea, se puede conectar al servicio de la nube de AWS IoT Greengrass 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 de cliente pueden utilizar para autenticar el dispositivo principal de Greengrass.

nota

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

Para utilizar esta operación de API, envíe solicitudes HTTP a la API de detección en el punto de conexión del plano de datos de Greengrass. Este punto de conexión 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 Regiones de AWS y puntos de conexión admitidos para la API de detección de AWS IoT Greengrass, consulte puntos de conexión y cuotas de AWS IoT Greengrass V2 en la Referencia general de AWS. Esta operación de la API solo está disponible en el punto de conexión del plano de datos de Greengrass. El punto de conexión del plano de control que se utiliza para administrar los componentes y las implementaciones es diferente del punto de conexión del plano de datos.

nota

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

Autenticación y autorización de detección

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

Un dispositivo de cliente también debe tener permiso para ejecutar la acción greengrass:Discover. El siguiente ejemplo de política AWS IoT permite que un objeto AWS IoT denominado MyClientDevice1 realice la acción Discover por sí mismo.

{
  "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 objetos (iot:Connection.Thing.*) no son compatibles con las políticas de AWS IoT para dispositivos principales ni 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 especificar MyGreengrassDevice* para que coincida con MyGreengrassDevice1, MyGreengrassDevice2, etc.

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

Solicitud

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

El número de puerto depende de si el dispositivo principal está configurado para enviar el 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

Estos ejemplos utilizan el punto de conexión de Amazon Trust Services (ATS), que se utiliza con los certificados de CA raíz de 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 respuesta de la detección.

nota

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

Ejemplo de documentos de respuesta de detección

En el siguiente documento, se muestran la respuesta de un dispositivo de cliente que está asociado a un dispositivo principales de Greengrass. El dispositivo principal tiene un punto de conexión y un certificado de la 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-----"
      ]
    }
  ]
}

En el siguiente documento, se muestra la respuesta de un dispositivo de cliente que está asociado a dos dispositivos principales. Los dispositivos principales tienen varios puntos de conexión y varios certificados de la CA del 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-----"
      ]
    }
  ]
}

Prueba de la API de detección con cURL

Si instaló cURL, puede probar la API de detección. En el siguiente ejemplo, se especifican los certificados de un dispositivo de cliente para autenticar una solicitud en el punto de conexión de la API de detección 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 argumento -i especifica la salida de los encabezados de respuesta HTTP. Puede utilizar esta opción para ayudar a identificar los errores.

Si la solicitud tiene éxito, este comando genera una respuesta similar al 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.