API REST da Sombra do Dispositivo

Um shadow expõe a 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 URI do endpoint.

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

O formato do endpoint é o seguinte:

identifier.iot.region.amazonaws.com

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

nota

Para usar as APIs, você deve usar iotdevicegateway como nome do serviço para autenticação. Para obter mais informações, consulte IoT DataPlane.

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

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 cabeçalhos HTTP padrão, além da 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

Após o sucesso, a resposta incluirá os cabeçalhos HTTP padrão e os seguintes código e corpo:

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 Sombra do Dispositivo aceita duas formas de autenticação: assinatura da versão 4 com credenciais do IAM ou autenticação mútua do TLS com um certificado 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 cabeçalhos HTTP padrão e os seguintes URI e 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

Após o sucesso, a resposta incluirá os cabeçalhos HTTP padrão e os seguintes código e corpo:

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 Sombra do Dispositivo aceita duas formas de autenticação: assinatura da versão 4 com credenciais do IAM ou autenticação mútua do TLS com um certificado 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 cabeçalhos HTTP padrão, além da 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

Após o sucesso, a resposta incluirá os cabeçalhos HTTP padrão e os seguintes código e corpo:

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 Sombra do Dispositivo aceita duas formas de autenticação: assinatura da versão 4 com credenciais do IAM ou autenticação mútua do TLS com um certificado 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 cabeçalhos HTTP padrão, além da 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

Quando bem-sucedido, a resposta incluirá os cabeçalhos HTTP padrão e o seguinte código de resposta e um Documento 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 Sombra do Dispositivo aceita duas formas de autenticação: assinatura da versão 4 com credenciais do IAM ou autenticação mútua do TLS com um certificado 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"
      ]
    }
  ]
}