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 conexión es específico para su Cuenta de AWS. Para buscar el punto de conexión, puede hacer lo siguiente:
-
Utilice el comando describe-endpoint desde la AWS CLI.
-
Utilice la configuración de la consola del AWS IoT. En Configuración, el punto de conexión aparece en Punto de conexión personalizado
-
Use la página de detalles del objeto de la consola del AWS IoT. En la consola de :
-
Abra Administrar y, en Administrar, seleccione Objetos.
-
En la lista de objetos, seleccione el objeto para el que desea obtener la URI del punto de conexión.
-
Seleccione la pestaña Sombras de dispositivo y seleccione la sombra. Puede ver el URI del punto de conexión en la sección URL de la sombra de dispositivo de la página Detalles de la sombra de dispositivo.
-
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.
nota
Para utilizar las API, debe emplear iotdevicegateway como nombre del servicio de autenticación. Para obtener más información, consulte IoTDataPlane.
También puede usar la API para crear una sombra con nombre proporcionándole name= como parte del parámetro de consulta de la API.shadowName
GetThingShadow
Obtiene la sombra de objeto especificado.
El documento de estado de respuesta incluye el delta entre los estados desired y reported.
Solicitud
La solicitud incluye los encabezados HTTP estándar y el URI siguiente:
HTTP GET https://endpoint/things/thingName/shadow?name=shadowNameRequest body: (none)
El parámetro de consulta name no es necesario para sombras sin nombre (clásicas).
Respuesta
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.
Autorización
Para recuperar una sombra, se necesita una política que permita al intermediario ejecutar la acción iot:GetThingShadow. El servicio de sombra de dispositivo acepta dos formas de autenticación: Signature Version 4 con credenciales 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:
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.
Solicitud
La solicitud incluye los encabezados HTTP estándar, así como el URI y el cuerpo siguientes:
HTTP POST https://endpoint/things/thingName/shadow?name=shadowNameRequest 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.
Respuesta
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.
Autorización
Para actualizar una sombra se necesita una política que permita al intermediario ejecutar la acción iot:UpdateThingShadow. El servicio de sombra de dispositivo acepta dos formas de autenticación: Signature Version 4 con credenciales 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:
DeleteThingShadow
Elimina la sombra de objeto especificado.
Solicitud
La solicitud incluye los encabezados HTTP estándar y el URI siguiente:
HTTP DELETE https://endpoint/things/thingName/shadow?name=shadowNameRequest body: (none)
El parámetro de consulta name no es necesario para sombras sin nombre (clásicas).
Respuesta
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.
Autorización
Para eliminar la sombra de un dispositivo se necesita una política que permita al intermediario ejecutar la acción iot:DeleteThingShadow. El servicio de sombra de dispositivo acepta dos formas de autenticación: Signature Version 4 con credenciales 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:
ListNamedShadowsForThing
Muestra las sombras del objeto especificado.
Solicitud
La solicitud incluye los encabezados HTTP estándar y el URI siguiente:
HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSizeRequest 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. Consulte también
nextToken. - thingName
-
El nombre del objeto para el que mostrar las sombras con nombre.
Respuesta
En caso de éxito, la respuesta incluye encabezados HTTP estándar, así como el código de respuesta siguiente y un Documento 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 el thingName que ha especificado no existe.
HTTP 200 Response body:Shadow name list document
Autorización
Para incluir la sombra de un dispositivo, se necesita una política que permita que el intermediario ejecute la acción iot:ListNamedShadowsForThing. El servicio de sombra de dispositivo acepta dos formas de autenticación: Signature Version 4 con credenciales 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:
