Device Shadow REST API - AWS IoT Core
GetThingShadowUpdateThingShadowDeleteThingShadowListNamedShadowsForThing

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Device Shadow REST API

Uma sombra expõe o seguinte URI para atualizar as informações de estado:

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

O endpoint é específico para o seu Conta da AWS. Para encontrar o endpoint, você pode:

  • Usar o comando describe-endpoint do AWS CLI.

  • Use as configurações AWS IoT do console. Em Configurações, o endpoint está listado em Endpoint personalizado

  • Use a página de detalhes do item do AWS IoT console. No console do:

    1. Abra Gerenciar e, em Gerenciar, escolha Objetos.

    2. Na lista de itens, escolha o item para o qual você deseja obter o endpointURI.

    3. Escolha a guia Sombras do Dispositivo e escolha sua sombra. Você pode visualizar o endpoint URI na URL seção Device Shadow da página de detalhes do Device Shadow.

O formato do endpoint é o seguinte:

identifier.iot.region.amazonaws.com

A sombra REST API segue os mesmos HTTPS protocolos/mapeamentos de portas descritos em. Protocolos de comunicação do dispositivo

nota

Para usar oAPIs, você deve usar iotdevicegateway como nome do serviço para autenticação. Para obter mais informações, consulte I oTData Plane.

Você também pode usar o API para criar uma sombra nomeada fornecendo name=shadowName como parte do parâmetro de consulta doAPI.

GetThingShadow

Obtém o shadow do objeto especificada.

O documento de estado de resposta inclui o delta entre os estados desired e reported.

Solicitação

A solicitação inclui os HTTP cabeçalhos padrão mais o seguinte: URI

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

O parâmetro de consulta name não é necessário para sombras sem nome (clássicas).

Resposta

Em caso de sucesso, a resposta inclui os HTTP cabeçalhos padrão mais o código e o corpo a seguir:

HTTP 200
Response Body: response state document

Para obter mais informações, consulte Exemplo de documento de estado de resposta.

Autorização

Recuperar um shadow requer uma política que permite que o chamador execute a ação iot:GetThingShadow. O serviço Device Shadow aceita duas formas de autenticação: Signature Version 4 com IAM credenciais ou autenticação TLS mútua com um certificado de cliente.

Veja a seguir um exemplo de política que permite que um chamador recupere uma shadow de dispositivo:

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

UpdateThingShadow

Atualiza o shadow do objeto especificada.

As atualizações afetam apenas os campos especificados no documento de estado da solicitação. Os campos com um valor de null são removido da shadow de dispositivo.

Solicitação

A solicitação inclui os HTTP cabeçalhos padrão mais o seguinte URI e o corpo:

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

O parâmetro de consulta name não é necessário para sombras sem nome (clássicas).

Para obter mais informações, consulte Exemplo de documento de estado de solicitação.

Resposta

Em caso de sucesso, a resposta inclui os HTTP cabeçalhos padrão mais o código e o corpo a seguir:

HTTP 200
Response body: response state document

Para obter mais informações, consulte Exemplo de documento de estado de resposta.

Autorização

Atualizar um shadow requer uma política que permite que o chamador execute a ação iot:UpdateThingShadow. O serviço Device Shadow aceita duas formas de autenticação: Signature Version 4 com IAM credenciais ou autenticação TLS mútua com um certificado de cliente.

Veja a seguir um exemplo de política que permite que um chamador atualize uma shadow de dispositivo:

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

DeleteThingShadow

Apaga o shadow do objeto especificada.

Solicitação

A solicitação inclui os HTTP cabeçalhos padrão mais o seguinte: URI

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

O parâmetro de consulta name não é necessário para sombras sem nome (clássicas).

Resposta

Em caso de sucesso, a resposta inclui os HTTP cabeçalhos padrão mais o código e o corpo a seguir:

HTTP 200
Response body: Empty response state document

Observe que a exclusão de uma sombra não redefine seu número da versão para 0.

Autorização

Apagar uma shadow de dispositivo requer uma política que permite que o chamador execute a ação iot:DeleteThingShadow. O serviço Device Shadow aceita duas formas de autenticação: Signature Version 4 com IAM credenciais ou autenticação TLS mútua com um certificado de cliente.

Veja a seguir um exemplo de política que permite que um chamador exclua uma shadow de dispositivo:

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

ListNamedShadowsForThing

Lista as sombras do objeto especificada.

Solicitação

A solicitação inclui os HTTP cabeçalhos padrão mais o seguinte: URI

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

O token para recuperação do próximo conjunto de resultados.

Esse valor é retornado nos resultados paginados e é usado na chamada que retorna a próxima página.

pageSize

O número de nomes de sombra a serem retornados em cada chamada. Consulte também nextToken.

thingName

O nome do objeto para a qual listar as sombras nomeadas.

Resposta

Em caso de sucesso, a resposta inclui os HTTP cabeçalhos padrão mais o seguinte código de resposta e umDocumento de resposta da lista de nomes de sombra.

nota

A sombra sem nome (clássica) não aparece nesta lista. A resposta é uma lista vazia se você tiver apenas uma sombra clássica ou se a thingName especificada não existir.

HTTP 200
Response body: Shadow name list document
Autorização

Listar uma shadow de dispositivo requer uma política que permite que o chamador execute a ação iot:ListNamedShadowsForThing. O serviço Device Shadow aceita duas formas de autenticação: Signature Version 4 com IAM credenciais ou autenticação TLS mútua com um certificado de cliente.

Veja a seguir um exemplo de política que permite que um chamador liste as sombras nomeadas de um objeto:

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