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 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 final es específico de su Cuenta de AWS. Para buscar el punto de conexión, puede hacer lo siguiente:
+ Utilice el comando [describe-endpoint](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html) desde la AWS CLI.
+ Utilice la configuración AWS IoT de la consola. En **Configuración**, el punto de conexión aparece en **Punto de conexión personalizado**
+ Usa la página de detalles de la AWS IoT consola. En la consola de :
1. Abra **Administrar** y, en **Administrar**, seleccione **Objetos**.
1. En la lista de objetos, seleccione el objeto para el que desea obtener la URI del punto de conexión.
1. 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 REST oculta sigue las mismas protocols/port asignaciones HTTPS que se describen en. [Protocolos de comunicación de dispositivos](protocols.md)
**nota**
Para utilizarla APIs, debe utilizarla `iotdevicegateway` como nombre de servicio para la autenticación. Para obtener más información, consulte [Io TData Plane](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iot-data-plane/classes/iotdataplane.html).
**Topics**
+ [GetThingShadow](#API_GetThingShadow)
+ [UpdateThingShadow](#API_UpdateThingShadow)
+ [DeleteThingShadow](#API_DeleteThingShadow)
+ [ListNamedShadowsForThing](#API_ListNamedShadowsForThing)
También puede usar la API para crear una sombra con nombre proporcionándole `name=shadowName` como parte del parámetro de consulta de la API.
## 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=shadowName
Request 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](device-shadow-document.md#device-shadow-example-response-json).
**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:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:GetThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012: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.
**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=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](device-shadow-document.md#device-shadow-example-request-json).
**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](device-shadow-document.md#device-shadow-example-response-json).
**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:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:UpdateThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## 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=shadowName
Request 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:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:DeleteThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## 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=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.
**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](device-shadow-document.md#device-shadow-list-json).
**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:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:ListNamedShadowsForThing",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```