API REST de sombra de dispositivo

Una sombra expone el siguiente URI para actualizar la información de estado:

https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow

El punto de enlace específico con Cuenta de AWS . Para buscar el punto de enlace, puede:

• Usardescribe-endpointdesde laAWS CLI.

• UsarAWS IoTconfiguración de la consola. EnConfiguración, el extremo se muestra enPunto de enlace personalizado

• UsarAWS IoTpágina de detalles de la cosa de consola. En la consola de :

  1. OpenAdministracióny enAdministración, elijaObjetos.

  2. En la lista de cosas, elija la cosa para la que desea obtener el URI de punto final.

  3. Elija el iconoSombras del dispositivoElija y luego. Puede ver el URI de endpoint en el panelURL Device ShadowSección sobre de laDetalles Device Shadow(Se ha creado el certificado).

El formato del punto de enlace es el siguiente:

identifier.iot.region.amazonaws.com

La API de REST de sombras sigue los mismos mapeos de puertos y protocolos HTTPS que se describen en Protocolos de comunicación de dispositivos.

GetThingShadow

Obtiene la sombra de objeto especificado.

El documento de estado de respuesta incluye el delta entre los estados desired y reported.

Request

La solicitud incluye los encabezados HTTP estándar y el URI siguiente:

HTTP GET https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)

El parámetro de consulta name no es necesario para sombras sin nombre (clásicas).

Response

En caso de éxito, la respuesta incluye encabezados HTTP estándar, así como el código y el cuerpo siguientes:

HTTP 200
Response Body: response state document

Para obtener más información, consulte Ejemplo de documento de estado de respuesta.

Authorization

Para recuperar una sombra, se necesita una política que permita al intermediario ejecutar la acción iot:GetThingShadow. El servicio Device Shadow acepta dos formas de autenticación: Signature Version 4 con credenciales de IAM o autenticación mutua TLS con un certificado de cliente.

A continuación, se muestra una política de ejemplo que permite a un intermediario recuperar la sombra de un dispositivo:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:GetThingShadow",
      "Resource": [
        "arn:aws:iot:region:account:thing/thing"
      ]
    }
  ]
}

UpdateThingShadow

Actualiza la sombra del objeto especificado.

Las actualizaciones solo afectan a los campos especificados en el documento de estado de la solicitud. Todos los campos que tengan el valor null se eliminarán de la sombra del dispositivo.

Request

La solicitud incluye los encabezados HTTP estándar, así como el URI y el cuerpo siguientes:

HTTP POST https://endpoint/things/thingName/shadow?name=shadowName
Request body: request state document

El parámetro de consulta name no es necesario para sombras sin nombre (clásicas).

Para obtener más información, consulte Ejemplo de documento de estado de solicitud.

Response

En caso de éxito, la respuesta incluye encabezados HTTP estándar, así como el código y el cuerpo siguientes:

HTTP 200
Response body: response state document

Para obtener más información, consulte Ejemplo de documento de estado de respuesta.

Authorization

Para actualizar una sombra se necesita una política que permita al intermediario ejecutar la acción iot:UpdateThingShadow. El servicio Device Shadow acepta dos formas de autenticación: Signature Version 4 con credenciales de IAM o autenticación mutua TLS con un certificado de cliente.

A continuación, se muestra una política de ejemplo que permite a un intermediario actualizar la sombra de un dispositivo:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:UpdateThingShadow",
      "Resource": [
        "arn:aws:iot:region:account:thing/thing"
      ]
    }
  ]
}

DeleteThingShadow

Elimina la sombra de objeto especificado.

Request

La solicitud incluye los encabezados HTTP estándar y el URI siguiente:

HTTP DELETE https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)

El parámetro de consulta name no es necesario para sombras sin nombre (clásicas).

Response

En caso de éxito, la respuesta incluye encabezados HTTP estándar, así como el código y el cuerpo siguientes:

HTTP 200
Response body: Empty response state document

Tenga en cuenta que al eliminar una sombra no se restablece su número de versión a 0.

Authorization

Para eliminar la sombra de un dispositivo se necesita una política que permita al intermediario ejecutar la acción iot:DeleteThingShadow. El servicio Device Shadow acepta dos formas de autenticación: Signature Version 4 con credenciales de IAM o autenticación mutua TLS con un certificado de cliente.

A continuación, se muestra una política de ejemplo que permite a un intermediario eliminar la sombra de un dispositivo:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:DeleteThingShadow",
      "Resource": [
        "arn:aws:iot:region:account:thing/thing"
      ]
    }
  ]
}

ListNamedShadowsForThing

Muestra las sombras del objeto especificado.

Request

La solicitud incluye los encabezados HTTP estándar y el URI siguiente:

HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize
Request body: (none)

nextToken

El token para recuperar el siguiente grupo de resultados.

Este valor se devuelve en los resultados paginados y se utiliza en la llamada que devuelve la página siguiente.

pageSize

El número de nombres de sombra que devolver en cada llamada. Véase también nextToken.

thingName

El nombre del objeto para el que mostrar las sombras con nombre.

Response

En caso de éxito, la respuesta incluye encabezados HTTP estándar, así como el código de respuesta siguiente y unDocumento de respuesta de lista de nombres de sombra.

nota

La sombra sin nombre (clásica) no aparece en esta lista. La respuesta es una lista vacía si solo tiene una sombra clásica o si la opciónthingNameSi especifica no existe.

HTTP 200
Response body: Shadow name list document

Authorization

Para publicar la sombra de un dispositivo se necesita una política que permita al interlocutor ejecutar laiot:ListNamedShadowsForThingaction. El servicio Device Shadow acepta dos formas de autenticación: Signature Version 4 con credenciales de IAM o autenticación mutua TLS con un certificado de cliente.

A continuación, se muestra una política de ejemplo que permite a un intermediario mostrar las sombras con nombre de un objeto:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:ListNamedShadowsForThing",
      "Resource": [
        "arn:aws:iot:region:account:thing/thing"
      ]
    }
  ]
}