

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á.

# AWS IoT tutoriais
<a name="iot-tutorials"></a>

Os AWS IoT tutoriais são divididos em dois caminhos de aprendizado para apoiar dois objetivos diferentes. Escolha o melhor caminho de aprendizado para sua meta.
+ 

**Você quer criar um proof-of-concept para testar ou demonstrar uma ideia de AWS IoT solução**  
Para demonstrar tarefas e aplicativos comuns de IoT usando o AWS IoT Device Client em seus dispositivos, siga o caminho de [Criando demonstrações com o AWS IoT Device Client](iot-tutorials-dc-intro.md) aprendizado. O AWS IoT Device Client fornece software de dispositivo com o qual você pode aplicar seus próprios recursos de nuvem para demonstrar uma end-to-end solução com desenvolvimento mínimo.

  Para obter informações sobre o AWS IoT Device Client, consulte o [AWS IoT Device Client](https://github.com/awslabs/aws-iot-device-client#readme).
+ 

**Você quer aprender a criar software de produção para implantar sua solução**  
Para criar seu próprio software de solução que atenda aos seus requisitos específicos usando um AWS IoT Device SDK, siga o plano de [Construindo soluções com o AWS IoT dispositivo SDKs](iot-tutorials-sdk-intro.md) aprendizado.

  Para obter informações sobre o AWS IoT dispositivo disponível SDKs, consulte[AWS IoTSDKs de dispositivo da](iot-sdks.md#iot-device-sdks). Para obter informações sobre o AWS SDKs, consulte [Ferramentas para desenvolver AWS](https://aws.amazon.com/tools/).

**Topics**
+ [Criando demonstrações com o AWS IoT Device Client](iot-tutorials-dc-intro.md)
+ [Construindo soluções com o AWS IoT dispositivo SDKs](iot-tutorials-sdk-intro.md)

# Criando demonstrações com o AWS IoT Device Client
<a name="iot-tutorials-dc-intro"></a>

Os tutoriais neste plano de aprendizado orientam você pelas etapas para desenvolver um software de demonstração usando o AWS IoT Device Client. O AWS IoT Device Client fornece software que é executado em seu dispositivo de IoT para testar e demonstrar aspectos de uma solução de IoT baseada em. AWS IoT

O objetivo desses tutoriais é facilitar a exploração e a experimentação para que você tenha certeza de que a solução é AWS IoT compatível com sua solução antes de desenvolver o software do seu dispositivo.

**O que você aprenderá nesses tutoriais:**
+ Como preparar um Raspberry Pi para uso como um dispositivo de IoT com AWS IoT
+ Como demonstrar AWS IoT recursos usando o AWS IoT Device Client em seu dispositivo

Neste plano de aprendizado, você instalará o AWS IoT Device Client em seu próprio Raspberry Pi e criará os AWS IoT recursos na nuvem para demonstrar ideias de soluções de IoT. Embora os tutoriais desse plano de aprendizado demonstrem atributos usando um Raspberry Pi, eles explicam as metas e os procedimentos para ajudar você a adaptá-los a outros dispositivos.

## Pré-requisitos para criar demonstrações com o Device Client AWS IoT
<a name="iot-dc-tutorial-overview"></a>

Esta seção descreve o que você precisará ter antes de iniciar os tutoriais neste plano de aprendizado.

**Para fazer os tutoriais desse plano de aprendizado, você precisará:**
+ 

**Um Conta da AWS**  
Você pode usar o existente Conta da AWS, se tiver um, mas talvez seja necessário adicionar funções ou permissões adicionais para usar os AWS IoT recursos que esses tutoriais usam.

  Se você precisar criar um novo Conta da AWS, consulte[Configurar Conta da AWS](setting-up.md).
+ 

**Um Raspberry Pi ou dispositivo IoT compatível**  
Os tutoriais usam o [Raspberry Pi](https://www.raspberrypi.org/) porque, além de seus diferentes formatos, ele é amplamente usado e um dispositivo de demonstração relativamente barato. Os tutoriais foram testados no [Raspberry Pi 3 Modelo B\$1](https://www.raspberrypi.com/products/raspberry-pi-3-model-b-plus/), no [Raspberry Pi 4 Modelo B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) e em uma instância do Amazon EC2 executando o Ubuntu Server 20.04 LTS (HVM). Para usar AWS CLI e executar os comandos, recomendamos que você use a versão mais recente do sistema operacional Raspberry Pi ([Raspberry Pi OS (64 bits)](https://www.raspberrypi.com/software/operating-systems/) ou OS Lite). Versões anteriores do SO podem funcionar, mas nós não as testamos.
**nota**  
Os tutoriais explicam os objetivos de cada etapa para ajudar você a adaptá-los ao hardware de IoT que ainda não testamos. No entanto, eles não descrevem especificamente como adaptá-los a outros dispositivos.
+ 

**Familiaridade com o sistema operacional do dispositivo de IoT**  
As etapas desses tutoriais pressupõem que você esteja familiarizado com o uso de comandos e operações básicas do Linux na interface de linha de comando suportada por um Raspberry Pi. Se você não estiver familiarizado com essas operações, talvez queira dedicar mais tempo para concluir os tutoriais.

  Para concluir esses tutoriais, você já deve entender como:
  + Executar com segurança as operações básicas do dispositivo, como montar e conectar componentes, conectar o dispositivo às fontes de alimentação necessárias e instalar e remover cartões de memória.
  + Carregar e baixar o software e os arquivos do sistema para o dispositivo. Se o dispositivo não usar um dispositivo de armazenamento removível, como um cartão microSD, você precisará saber como se conectar ao dispositivo e fazer o upload e o download do software e dos arquivos do sistema para o dispositivo.
  + Conecte seu dispositivo às redes nas quais você planeja usá-lo.
  + Conecte-se ao seu dispositivo a partir de outro computador usando um terminal SSH ou programa similar.
  + Use uma interface de linha de comando para criar, copiar, mover, renomear e definir as permissões de arquivos e diretórios no dispositivo.
  + Instale novos programas no dispositivo.
  + Transfira arquivos de e para o seu dispositivo usando ferramentas como FTP ou SCP.
+ 

**Um ambiente de desenvolvimento e teste para sua solução de IoT**  
Os tutoriais descrevem o software e o hardware necessários; no entanto, presumem que você poderá realizar operações que talvez não estejam descritas explicitamente. Exemplos desse hardware e dessas operações incluem:
  + 

**Um computador host local para baixar e armazenar arquivos**  
Para o Raspberry Pi, geralmente é um computador pessoal ou laptop que pode ler e gravar em cartões de memória microSD. O computador host local deve:
    + Estar conectado à Internet.
    + Ter a [AWS CLI](https://aws.amazon.com//cli/) instalada e configurada.
    + Tenha um navegador da Web compatível com o AWS console.
  + 

**Uma forma de conectar seu computador host local ao seu dispositivo para se comunicar com ele, inserir comandos e transferir arquivos**  
No Raspberry Pi, isso geralmente é feito usando SSH e SCP do computador host local.
  + 

**Um monitor, mouse e teclado para se conectar ao dispositivo de IoT**  
Eles podem ser úteis, mas não são necessários para concluir os tutoriais.
  + 

**Uma forma de seu computador host local e seus dispositivos de IoT se conectarem à Internet**  
Pode ser uma conexão de rede com fio ou sem fio a um roteador ou gateway conectado à Internet. O host local também deve ser capaz de se conectar ao Raspberry Pi. Isso pode exigir que eles estejam na mesma rede local. Os tutoriais não mostram como configurar isso para seu dispositivo específico ou configuração de dispositivo, mas mostram como você pode testar essa conectividade.
  + 

**Acesso ao roteador da sua rede local para visualizar os dispositivos conectados**  
Para concluir os tutoriais desse plano de aprendizado, você precisará encontrar o endereço IP do seu dispositivo de IoT.

    Em uma rede local, isso pode ser feito acessando a interface administrativa do roteador de rede ao qual seus dispositivos se conectam. Se você puder atribuir um endereço IP fixo ao seu dispositivo no roteador, poderá simplificar a reconexão após cada reinicialização do dispositivo.

    Se você tiver um teclado e um monitor conectados ao dispositivo, **ifconfig** poderá exibir o endereço IP do dispositivo.

    Se nada disso for uma opção, você precisará encontrar uma maneira de identificar o endereço IP do dispositivo após cada reinicialização. 

Depois de ter todos os seus materiais, continue para [Tutorial: Preparando seus dispositivos para o AWS IoT Device Client](iot-dc-prepare-device.md). 

**Topics**
+ [Pré-requisitos para criar demonstrações com o Device Client AWS IoT](#iot-dc-tutorial-overview)
+ [Tutorial: Preparando seus dispositivos para o AWS IoT Device Client](iot-dc-prepare-device.md)
+ [Tutorial: Instalando e configurando o AWS IoT Device Client](iot-dc-install-dc.md)
+ [Tutorial: Demonstre a comunicação de mensagens MQTT com o AWS IoT Device Client](iot-dc-testconn.md)
+ [Tutorial: Demonstre ações remotas (trabalhos) com o AWS IoT Device Client](iot-dc-runjobs.md)
+ [Tutorial: Limpando depois de executar os tutoriais do AWS IoT Device Client](iot-dc-cleanup.md)

# Tutorial: Preparando seus dispositivos para o AWS IoT Device Client
<a name="iot-dc-prepare-device"></a>

Este tutorial orienta você na inicialização do Raspberry Pi para prepará-lo para os tutoriais subsequentes neste percurso de aprendizado.

O objetivo desse tutorial é instalar a versão atual do sistema operacional do dispositivo e garantir que você possa se comunicar com o dispositivo no contexto do ambiente de desenvolvimento.

**Pré-requisitos**  
Antes de começar este tutorial, verifique se você tem os itens listados em [Pré-requisitos para criar demonstrações com o Device Client AWS IoT](iot-tutorials-dc-intro.md#iot-dc-tutorial-overview) disponíveis e prontos para uso.

A conclusão desse tutorial requer cerca de 90 minutos.

**Neste tutorial, você vai:**
+ Instalar e atualizar o sistema operacional do dispositivo.
+ Instalar e verificar qualquer software adicional necessário para executar os tutoriais.
+ Testar a conectividade do dispositivo e instalar os certificados necessários.

Depois de concluir este tutorial, o próximo tutorial prepara seu dispositivo para as demonstrações que usam o AWS IoT Device Client.

**Topics**
+ [Instalar e atualizar o sistema operacional do dispositivo](iot-dc-prepare-device-sys.md)
+ [Instalar e verificar o software necessário no seu dispositivo](iot-dc-prepare-device-sw.md)
+ [Testar o dispositivo e salvar o certificado de CA da Amazon](iot-dc-prepare-device-test.md)

# Instalar e atualizar o sistema operacional do dispositivo
<a name="iot-dc-prepare-device-sys"></a>

Os procedimentos nesta seção descrevem como inicializar o cartão microSD que o Raspberry Pi usa como unidade do sistema. O cartão microSD do Raspberry Pi contém o software do sistema operacional (OS), bem como espaço para o armazenamento de arquivos da aplicação. Se você não estiver usando um Raspberry Pi, siga as instruções do dispositivo para instalar e atualizar o software do sistema operacional do dispositivo.

Depois de concluir esta seção, você poderá iniciar o dispositivo de IoT e conectar-se a ele por meio do programa de terminal no computador host local.

**Equipamentos necessários:**
+ O ambiente local de desenvolvimento e testes
+ Um Raspberry Pi, ou dispositivo de IoT, que pode se conectar à Internet
+ Um cartão de memória microSD com capacidade de pelo menos 8 GB ou armazenamento suficiente para o sistema operacional e o software necessário.
**nota**  
Ao selecionar um cartão microSD para esses exercícios, escolha um que seja tão grande quanto necessário, mas tão pequeno quanto possível.  
Um cartão SD pequeno será mais rápido de fazer backup e atualizar. No Raspberry Pi, você não precisará de mais do que um cartão microSD de 8 GB para esses tutoriais. Se você precisar de mais espaço para a aplicação específica, os arquivos de imagem menores salvos nesses tutoriais poderão redimensionar o sistema de arquivos em um cartão maior para usar todo o espaço compatível do cartão que você escolher.

**Equipamento opcional:**
+ Um teclado USB conectado ao Raspberry Pi
+ Um monitor HDMI e um cabo para conectar o monitor ao Raspberry Pi

**Topics**
+ [Carregue o sistema operacional do dispositivo no cartão microSD](#iot-dc-prepare-device-sys-step1)
+ [Inicie o dispositivo de IoT com o novo sistema operacional](#iot-dc-prepare-device-sys-step2)
+ [Conectar o computador host local ao dispositivo](#iot-dc-prepare-device-sys-step3)

## Carregue o sistema operacional do dispositivo no cartão microSD
<a name="iot-dc-prepare-device-sys-step1"></a>

Esse procedimento usa o computador host local para carregar o sistema operacional do dispositivo em um cartão microSD.

**nota**  
Se o dispositivo não usar uma mídia de armazenamento removível para o sistema operacional, instale o sistema operacional usando o procedimento para esse dispositivo e continue na [Inicie o dispositivo de IoT com o novo sistema operacional](#iot-dc-prepare-device-sys-step2).

**Para instalar o sistema operacional no Raspberry Pi**

1. No computador host local, baixe e descompacte a imagem do sistema operacional Raspberry Pi que você deseja usar. As versões mais recentes estão disponíveis em [ https://www.raspberrypi.com/software/sistemas operacionais/](https://www.raspberrypi.com/software/operating-systems/) 

**Como escolher uma versão do sistema operacional Raspberry Pi**  
Este tutorial usa a versão **Raspberry Pi OS Lite** porque é a menor versão compatível com esses tutoriais neste percurso de aprendizado. Essa versão do sistema operacional Raspberry Pi tem apenas uma interface de linha de comando e não tem uma interface gráfica de usuário. Uma versão do sistema operacional Raspberry Pi mais recente com uma interface gráfica de usuário também funcionará com esses tutoriais; no entanto, os procedimentos descritos neste percurso de aprendizado usam somente a interface da linha de comando para realizar operações no Raspberry Pi.

1. Insira o cartão microSD no computador host local.

1. Usando uma ferramenta de imagem de cartão SD, grave o arquivo de imagem do sistema operacional descompactado no cartão microSD.

1. Depois de gravar a imagem do sistema operacional Raspberry Pi no cartão microSD:

   1. Abra a partição BOOT no cartão microSD em uma janela da linha de comando ou janela do explorador de arquivos. 

   1. Na partição BOOT do cartão microSD, no diretório raiz, crie um arquivo vazio chamado `ssh` sem extensão de arquivo e sem conteúdo. Isso faz com que o Raspberry Pi ative as comunicações SSH na primeira vez em que for iniciado.

1. Ejete o cartão microSD e remova-o com segurança do computador host local.

O cartão microSD está pronto para [Inicie o dispositivo de IoT com o novo sistema operacional](#iot-dc-prepare-device-sys-step2).

## Inicie o dispositivo de IoT com o novo sistema operacional
<a name="iot-dc-prepare-device-sys-step2"></a>

Este procedimento instala o cartão microSD e inicia o Raspberry Pi pela primeira vez usando o sistema operacional baixado.

**Para iniciar o dispositivo de IoT com o novo sistema operacional**

1. Com a alimentação desconectada do dispositivo, insira o cartão microSD da etapa anterior, [Carregue o sistema operacional do dispositivo no cartão microSD](#iot-dc-prepare-device-sys-step1), no Raspberry Pi.

1. Conecte o dispositivo a uma rede com fios.

1. Esses tutoriais interagirão com o Raspberry Pi por meio do computador host local usando um terminal SSH.

   Se você também quiser interagir diretamente com o dispositivo, você pode:

   1. Conectar um monitor HDMI a ele para assistir às mensagens do console do Raspberry Pi antes de conectar a janela do terminal do computador host local ao Raspberry Pi.

   1. Conectar um teclado USB a ele se quiser interagir diretamente com o Raspberry Pi.

1. Conectar a alimentação ao Raspberry Pi e esperar cerca de um minuto para que ele seja inicializado.

   Se você tiver um monitor conectado ao Raspberry Pi, poderá ver processo de inicialização nele.

1. 

   Descubra o endereço IP do dispositivo:
   + Se você conectou um monitor HDMI ao Raspberry Pi, o endereço IP aparecerá nas mensagens exibidas no monitor 
   + Se você tiver acesso ao roteador ao qual o Raspberry Pi está conectado, poderá ver o endereço na interface de administração do roteador.

Depois de ter o endereço IP do Raspberry Pi, você estará pronto para [Conectar o computador host local ao dispositivo](#iot-dc-prepare-device-sys-step3).

## Conectar o computador host local ao dispositivo
<a name="iot-dc-prepare-device-sys-step3"></a>

Este procedimento usa o programa de terminal no computador host local para se conectar ao Raspberry Pi e alterar a senha padrão.

**Para conectar o computador host local ao dispositivo**

1. 

   No computador host local, abra o programa do terminal SSH:
   + Windows: `PuTTY`
   + Linux/macOS: `Terminal`
**nota**  
O PuTTY não é instalado automaticamente no Windows. Se não estiver no computador, talvez seja necessário baixá-lo e instalá-lo.

1. Conecte o programa do terminal ao endereço IP do Raspberry Pi e faça login usando as credenciais padrão.

   ```
   username: pi
   password: raspberry
   ```

1. Depois de fazer login no Raspberry Pi, altere a senha do usuário `pi`.

   ```
   passwd
   ```

   Siga os prompts para alterar a senha.

   ```
   Changing password for pi.
   Current password: raspberry
   New password: YourNewPassword
   Retype new password: YourNewPassword
   passwd: password updated successfully
   ```

Depois de inserir o prompt da linha de comando do Raspberry Pi na janela do terminal e alterar a senha, você estará pronto para continuar em [Instalar e verificar o software necessário no seu dispositivo](iot-dc-prepare-device-sw.md).

# Instalar e verificar o software necessário no seu dispositivo
<a name="iot-dc-prepare-device-sw"></a>

Os procedimentos nesta seção continuam com [a seção anterior](iot-dc-prepare-device-sys.md) para atualizar o sistema operacional do Raspberry Pi e instalar o software no Raspberry Pi que será usado na próxima seção para criar e instalar o AWS IoT Device Client.

Depois de concluir esta seção, seu Raspberry Pi terá um sistema up-to-date operacional, o software exigido pelos tutoriais neste plano de aprendizado, e será configurado para sua localização.

**Equipamentos necessários:**
+ O ambiente local de desenvolvimento e teste da [seção anterior](iot-dc-prepare-device-sys.md)
+ O Raspberry Pi usado na [seção anterior](iot-dc-prepare-device-sys.md)
+ O cartão de memória microSD da [seção anterior](iot-dc-prepare-device-sys.md)

**nota**  
O Raspberry Pi Model 3\$1 e o Raspberry Pi Model 4 podem executar todos os comandos descritos neste percurso de aprendizado. Se seu dispositivo de IoT não conseguir compilar o software ou executar o AWS Command Line Interface, talvez seja necessário instalar os compiladores necessários no computador host local para criar o software e depois transferi-lo para o dispositivo de IoT. Para obter mais informações sobre como instalar e compilar software para o dispositivo, consulte a documentação do software do dispositivo.

**Topics**
+ [Atualizar o software do sistema operacional](#iot-dc-prepare-device-sw-step1)
+ [Instale as aplicações e bibliotecas obrigatórias](#iot-dc-prepare-device-sw-step2)
+ [(Opcional) Salve a imagem do cartão microSD](#iot-dc-prepare-device-sw-step3)

## Atualizar o software do sistema operacional
<a name="iot-dc-prepare-device-sw-step1"></a>

Esse procedimento atualiza o software do sistema operacional.

**Para atualizar o software do sistema operacional no Raspberry Pi**

Execute essas etapas na janela do terminal do computador host local.

1. Digite esses comandos para atualizar o software do sistema no Raspberry Pi.

   ```
   sudo apt-get -y update
   sudo apt-get -y upgrade
   sudo apt-get -y autoremove
   ```

1. Atualize as configurações de localidade e fuso horário do Raspberry Pi (opcional).

   Digite esse comando para atualizar as configurações de localidade e fuso horário do dispositivo.

   ```
   sudo raspi-config
   ```

   1. Para definir a localidade do dispositivo:

      1. Na tela **Ferramenta de Configuração do Software Raspberry Pi (raspi-config)**, escolha a opção **5**.

         **`5 Localisation Options Configure language and regional settings`**

         Use a tecla Tab para ir para **<Select>** e, em seguida, pressione a space bar.

      1. No menu de opções de localização, escolha a opção **L1**.

         **`L1 Locale Configure language and regional settings`**

         Use a tecla Tab para ir para **<Select>** e, em seguida, pressione a space bar.

      1. Na lista de opções de localidade, escolha as localidades que você deseja instalar no Raspberry Pi usando as teclas de seta para rolar e space bar para marcar as que deseja. 

         Nos Estados Unidos, **`en_US.UTF-8`** é uma boa opção.

      1. Depois de selecionar as localidades para o dispositivo, use a tecla Tab para escolher **<OK>** e pressione a space bar para exibir a página de confirmação de **Configuração de localidades**.

   1. Para definir o fuso horário do dispositivo:

      1. Na tela **raspi-config**, escolha a opção **5**.

         **`5 Localisation Options Configure language and regional settings`**

         Use a tecla Tab para ir para **<Select>** e, em seguida, pressione a space bar.

      1. No menu de opções de localização, use a tecla de seta para escolher a opção **L2**:

         **`L2 time zone Configure time zone`**

         Use a tecla Tab para ir para **<Select>** e, em seguida, pressione a space bar.

      1. No menu **Configuração de tzdata**, escolha a área geográfica na lista. 

         Use a tecla Tab para ir para **<OK>** e, em seguida, pressione a space bar.

      1. Na lista de cidades, use as teclas de seta para escolher uma cidade no fuso horário.

         Para definir o fuso horário, use a tecla Tab para ir para **<OK>** e, em seguida, pressione a space bar.

   1. Quando terminar de atualizar as configurações, use a tecla Tab para acessar **<Finish>** e pressione a space bar para fechar a aplicação **raspi-config**.

1. Digite este comando para reiniciar o Raspberry Pi.

   ```
   sudo shutdown -r 0
   ```

1. Aguarde a reinicialização do Raspberry Pi.

1. Depois que o Raspberry Pi for reiniciado, reconecte a janela do terminal no computador host local ao Raspberry Pi.

O software do sistema Raspberry Pi agora está configurado e você está pronto para continuar na [Instale as aplicações e bibliotecas obrigatórias](#iot-dc-prepare-device-sw-step2).

## Instale as aplicações e bibliotecas obrigatórias
<a name="iot-dc-prepare-device-sw-step2"></a>

Esse procedimento instala o software da aplicação e as bibliotecas que os tutoriais subsequentes usam.

Se você estiver usando um Raspberry Pi ou se puder compilar o software necessário no dispositivo de IoT, execute essas etapas na janela do terminal no computador host local. Se você precisar compilar software para o dispositivo de IoT no computador host local, analise a documentação do software do dispositivo de IoT para obter informações sobre como executar essas etapas no dispositivo.

**Para instalar o software da aplicação e as bibliotecas no Raspberry Pi**

1. Digite esse comando para instalar o software da aplicação e as bibliotecas.

   ```
   sudo apt-get -y install build-essential libssl-dev cmake unzip git python3-pip
   ```

1. Insira esses comandos para confirmar que a versão correta do software foi instalada.

   ```
   gcc --version
   cmake --version
   openssl version
   git --version
   ```

1. 

   Confirme se essas versões do software da aplicação estão instaladas:
   + `gcc` 9.3.0 ou posterior
   + `cmake` 3.10.x ou posterior
   + `OpenSSL`: 1.1.1 ou posterior
   + `git`: 2.20.1 ou posterior

Se o Raspberry Pi tiver versões aceitáveis do software da aplicação necessário, você está pronto para continuar na [(Opcional) Salve a imagem do cartão microSD](#iot-dc-prepare-device-sw-step3).

## (Opcional) Salve a imagem do cartão microSD
<a name="iot-dc-prepare-device-sw-step3"></a>

Ao longo dos tutoriais deste percurso de aprendizado, você encontrará esses procedimentos para salvar uma cópia da imagem do cartão microSD do Raspberry Pi em um arquivo no computador host local. Embora incentivadas, elas não são tarefas obrigatórias. Ao salvar a imagem do cartão microSD onde sugerido, você pode pular os procedimentos que precedem o ponto de salvamento neste percurso de aprendizado, o que pode economizar tempo se você precisar tentar algo novamente. A consequência de não salvar a imagem do cartão microSD periodicamente é que talvez você precise reiniciar os tutoriais do percurso de aprendizado desde o início se o cartão microSD estiver danificado ou se você acidentalmente definir uma aplicação ou as configurações incorretamente.

Neste ponto, o cartão microSD do Raspberry Pi tem um sistema operacional atualizado e o software básico da aplicação carregado. Você pode economizar o tempo necessário para concluir as etapas anteriores salvando o conteúdo do cartão microSD em um arquivo agora. Ter a imagem atual da imagem do cartão microSD do dispositivo permite que você comece a partir deste ponto para continuar ou repetir um tutorial ou procedimento sem a necessidade de instalar e atualizar o software do zero.

**Para salvar a imagem do cartão microSD em um arquivo**

1. Digite este comando para desligar o Raspberry Pi.

   ```
   sudo shutdown -h 0
   ```

1. Depois que o Raspberry Pi for desligado completamente, desligue a energia.

1. Remova o cartão microSD do Raspberry Pi.

1. No computador host local: 

   1. Insira o cartão microSD.

   1. Usando uma ferramenta de imagem de cartão SD, grave a imagem do cartão microSD em um arquivo.

   1. Depois que a imagem do cartão microSD for salva, ejete o cartão do computador host local.

1. Com a alimentação desconectada do Raspberry Pi, insira o cartão microSD no Raspberry Pi.

1. Ligue o Raspberry Pi.

1. Depois de esperar cerca de um minuto, no computador host local, reconecte a janela do terminal no computador host local que estava conectado ao Raspberry Pi. e, em seguida, faça login no Raspberry Pi.

# Testar o dispositivo e salvar o certificado de CA da Amazon
<a name="iot-dc-prepare-device-test"></a>

Os procedimentos nesta seção continuam com a [seção anterior para instalar o](iot-dc-prepare-device-sw.md) AWS Command Line Interface e o certificado da Autoridade de Certificação usado para autenticar suas conexões com AWS IoT Core.

Depois de concluir esta seção, você saberá que seu Raspberry Pi tem o software de sistema necessário para instalar o AWS IoT Device Client e que ele tem uma conexão ativa com a Internet.

**Equipamentos necessários:**
+ O ambiente local de desenvolvimento e teste da [seção anterior](iot-dc-prepare-device-sw.md)
+ O Raspberry Pi usado na [seção anterior](iot-dc-prepare-device-sw.md)
+ O cartão de memória microSD da [seção anterior](iot-dc-prepare-device-sw.md)

**Topics**
+ [Instale o AWS Command Line Interface](#iot-dc-prepare-device-test-step1)
+ [Configure suas Conta da AWS credenciais](#iot-dc-prepare-device-test-step2)
+ [Fazer download do certificado da CA raiz da Amazon](#iot-dc-prepare-device-test-step3)
+ [(Opcional) Salve a imagem do cartão microSD](#iot-dc-prepare-device-test-step4)

## Instale o AWS Command Line Interface
<a name="iot-dc-prepare-device-test-step1"></a>

Este procedimento instala o AWS CLI em seu Raspberry Pi.

Se você estiver usando um Raspberry Pi ou se puder compilar o software no dispositivo de IoT, execute essas etapas na janela do terminal no computador host local. Se você precisar compilar software para o dispositivo de IoT no computador host local, analise a documentação do software do dispositivo de IoT para obter informações sobre as bibliotecas que ele requer.

**Para instalar o AWS CLI em seu Raspberry Pi**

1. Use esses comandos para baixar e instalar a AWS CLI.

   ```
   export PATH=$PATH:~/.local/bin # configures the path to include the directory with the AWS CLI
   git clone https://github.com/aws/aws-cli.git # download the AWS CLI code from GitHub
   cd aws-cli && git checkout v2 # go to the directory with the repo and checkout version 2
   pip3 install -r requirements.txt # install the prerequisite software
   ```

1. Execute este comando para instalar AWS CLI o. Este comando pode levar até 15 minutos para ser concluído.

   ```
   pip3 install . # install the AWS CLI 
   ```

1. Execute esse comando para confirmar se a versão correta do AWS CLI foi instalada.

   ```
   aws --version
   ```

   A versão do AWS CLI deve ser 2.2 ou posterior.

Se AWS CLI exibiu sua versão atual, você está pronto para continuar[Configure suas Conta da AWS credenciais](#iot-dc-prepare-device-test-step2).

## Configure suas Conta da AWS credenciais
<a name="iot-dc-prepare-device-test-step2"></a>

Neste procedimento, você obterá Conta da AWS as credenciais e as adicionará para uso em seu Raspberry Pi.

**Para adicionar suas Conta da AWS credenciais ao seu dispositivo**

1. Obtenha um **ID de chave** de **acesso e uma chave de acesso secreta** Conta da AWS para autenticá-los AWS CLI em seu dispositivo. 

   Se você é novo no AWS IAM, o [ https://aws.amazon.com/premiumsupport/knowledge-center/create-access-key/](https://aws.amazon.com/premiumsupport/knowledge-center/create-access-key/)descreve o processo a ser executado no AWS console para criar credenciais do AWS IAM para usar em seu dispositivo. 

1. Na janela do terminal no computador host local que está conectado ao Raspberry Pi e com as credenciais de **ID da chave de acesso** e **Chave de acesso secreta** do dispositivo:

   1. Execute o aplicativo AWS configure com este comando:

      ```
      aws configure
      ```

   1. Insira as credenciais e informações de configuração quando solicitado:

      ```
      AWS Access Key ID: your Access Key ID
      AWS Secret Access Key: your Secret Access Key
      Default region name: your Região da AWS code
      Default output format: json
      ```

1. Execute esse comando para testar o acesso do seu dispositivo ao seu Conta da AWS AWS IoT Core terminal.

   ```
   aws iot describe-endpoint --endpoint-type iot:Data-ATS
   ```

   Ele deve retornar seu endpoint AWS IoT de dados Conta da AWS específico, como este exemplo:

   ```
   {
       "endpointAddress": "a3EXAMPLEffp-ats.iot.us-west-2.amazonaws.com"
   }
   ```

Se você ver seu endpoint Conta da AWS de AWS IoT dados específico, seu Raspberry Pi tem a conectividade e as permissões para continuar. [Fazer download do certificado da CA raiz da Amazon](#iot-dc-prepare-device-test-step3) 

**Importante**  
Suas Conta da AWS credenciais agora estão armazenadas no cartão microSD do seu Raspberry Pi. Embora isso facilite as interações futuras para você e para o software que você criará nesses tutoriais, elas também serão salvas e duplicadas em qualquer imagem de cartão microSD que você criar após essa etapa, por padrão. AWS   
Para proteger a segurança de suas Conta da AWS credenciais, antes de salvar mais imagens do cartão microSD, considere apagar as credenciais `aws configure` executando novamente e inserindo caracteres aleatórios para o ID da chave de acesso e **a chave de acesso** **secreta** para evitar Conta da AWS que suas credenciais sejam comprometidas.  
Se você descobrir que salvou suas Conta da AWS credenciais inadvertidamente, poderá desativá-las no console do IAM. AWS 

## Fazer download do certificado da CA raiz da Amazon
<a name="iot-dc-prepare-device-test-step3"></a>

Este procedimento baixa e salva uma cópia de um certificado da Autoridade de Certificação (CA) raiz da Amazon. O download desse certificado o salva para uso nos tutoriais subsequentes e também testa a conectividade do dispositivo com os serviços da AWS .

**Para fazer download do certificado da CA raiz da Amazon**

1. Execute o comando a seguir a fim de criar um diretório para o certificado.

   ```
   mkdir ~/certs
   ```

1. Execute este comando para fazer download do certificado da CA raiz da Amazon.

   ```
   curl -o ~/certs/AmazonRootCA1.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem
   ```

1. Execute esses comandos para definir o acesso ao diretório do certificado e o arquivo.

   ```
   chmod 745 ~
   chmod 700 ~/certs
   chmod 644 ~/certs/AmazonRootCA1.pem
   ```

1. Execute esse comando para ver o arquivo de certificado da CA no novo diretório.

   ```
   ls -l ~/certs
   ```

   Você deve ver uma entrada como essa. A data e a hora serão diferentes; no entanto, o tamanho do arquivo e todas as outras informações deverão ser iguais às mostradas aqui.

   ```
   -rw-r--r-- 1 pi pi 1188 Oct 28 13:02 AmazonRootCA1.pem
   ```

   Se o tamanho do arquivo não for `1188`, verifique os parâmetros do comando **curl**. Você pode ter baixado um arquivo incorreto.

## (Opcional) Salve a imagem do cartão microSD
<a name="iot-dc-prepare-device-test-step4"></a>

Neste ponto, o cartão microSD do Raspberry Pi tem um sistema operacional atualizado e o software básico da aplicação carregado. 

**Para salvar a imagem do cartão microSD em um arquivo**

1. Na janela do terminal do computador host local, limpe as credenciais da AWS .

   1. Execute o aplicativo AWS configure com este comando:

      ```
      aws configure
      ```

   1. Substitua as credenciais quando solicitado. Você pode deixar o **Nome da região padrão** e o **Formato de saída padrão** como estão pressionando **Enter**.

      ```
      AWS Access Key ID [****************YT2H]: XYXYXYXYX
      AWS Secret Access Key [****************9plH]: XYXYXYXYX
      Default region name [us-west-2]: 
      Default output format [json]:
      ```

1. Digite este comando para desligar o Raspberry Pi.

   ```
   sudo shutdown -h 0
   ```

1. Depois que o Raspberry Pi for desligado completamente, remova o conector de alimentação.

1. Remova o cartão microSD do dispositivo.

1. No computador host local: 

   1. Insira o cartão microSD.

   1. Usando uma ferramenta de imagem de cartão SD, grave a imagem do cartão microSD em um arquivo.

   1. Depois que a imagem do cartão microSD for salva, ejete o cartão do computador host local.

1. Com a alimentação desconectada do Raspberry Pi, insira o cartão microSD no Raspberry Pi.

1. Ligue o dispositivo.

1. Após cerca de um minuto, no computador host local, reinicie a sessão da janela do terminal e faça login no dispositivo.

   **Não insira novamente suas Conta da AWS credenciais ainda.**

Depois de reiniciar e fazer login no Raspberry Pi, você estará pronto para continuar em [Tutorial: Instalando e configurando o AWS IoT Device Client](iot-dc-install-dc.md).

# Tutorial: Instalando e configurando o AWS IoT Device Client
<a name="iot-dc-install-dc"></a>

Este tutorial mostra a instalação e a configuração do AWS IoT Device Client e a criação dos AWS IoT recursos que você usará nesta e em outras demonstrações.

**Para iniciar este tutorial:**
+ Prepare o computador host local e o Raspberry Pi [com o tutorial anterior](iot-dc-prepare-device.md).

Este tutorial pode levar cerca de 90 minutos para ser concluído.

**Quando você concluir este tópico:**
+ Seu dispositivo de IoT estará pronto para ser usado em outras demonstrações do AWS IoT Device Client.
+ Você terá provisionado seu dispositivo de IoT em. AWS IoT Core
+ Você terá baixado e instalado o AWS IoT Device Client em seu dispositivo.
+ Você terá salvo uma imagem do cartão microSD do dispositivo que pode ser usada em tutoriais subsequentes.

**Equipamentos necessários:**
+ O ambiente local de desenvolvimento e teste da [seção anterior](iot-dc-prepare-device-test.md)
+ O Raspberry Pi usado na [seção anterior](iot-dc-prepare-device-test.md)
+ O cartão de memória microSD do Raspberry Pi usado na [seção anterior](iot-dc-prepare-device-test.md)

**Topics**
+ [Baixe e salve o AWS IoT Device Client](iot-dc-install-download.md)
+ [Provisione seu Raspberry Pi em AWS IoT](iot-dc-install-provision.md)
+ [Configurar o cliente do AWS IoT dispositivo para testar a conectividade](iot-dc-install-configure.md)

# Baixe e salve o AWS IoT Device Client
<a name="iot-dc-install-download"></a>

Os procedimentos nesta seção baixam o AWS IoT Device Client, compilam e instalam no seu Raspberry Pi. Depois de testar a instalação, você pode salvar a imagem do cartão microSD do Raspberry Pi para usar mais tarde quando quiser experimentar os tutoriais novamente.

**Topics**
+ [Baixe e crie o AWS IoT Device Client](#iot-dc-install-dc-download)
+ [Crie os diretórios usados pelos tutoriais](#iot-dc-install-dc-files)
+ [(Opcional) Salve a imagem do cartão microSD](#iot-dc-install-dc-save)

## Baixe e crie o AWS IoT Device Client
<a name="iot-dc-install-dc-download"></a>

Este procedimento instala o AWS IoT Device Client no seu Raspberry Pi.

Execute esses comandos na janela do terminal do computador host local conectado ao Raspberry Pi.

**Para instalar o AWS IoT Device Client em seu Raspberry Pi**

1. Digite esses comandos para baixar e criar o AWS IoT Device Client no seu Raspberry Pi.

   ```
   cd ~
   git clone https://github.com/awslabs/aws-iot-device-client aws-iot-device-client
   mkdir ~/aws-iot-device-client/build && cd ~/aws-iot-device-client/build
   cmake ../
   ```

1. Execute esse comando para criar o AWS IoT Device Client. Este comando pode levar até 15 minutos para ser concluído.

   ```
   cmake --build . --target aws-iot-device-client
   ```

   As mensagens de aviso exibidas durante a compilação do AWS IoT Device Client podem ser ignoradas.

   Esses tutoriais foram testados com o AWS IoT Device Client integrado**gcc**, versão (Raspbian 10.2.1-6\$1rpi1) 10.2.1 20210110 na versão de 30 de outubro de 2021 do Raspberry Pi OS (bullseye) on, versão (Raspbian 8.3.0-6\$1rpi1) 8.3.0 na versão de 7 de maio de 2021 do Raspberry Pi OS (**gcc**buster).

1. Depois que o AWS IoT Device Client terminar de criar, teste-o executando esse comando.

   ```
   ./aws-iot-device-client --help
   ```

Se você ver a ajuda da linha de comando para o AWS IoT Device Client, o AWS IoT Device Client foi criado com sucesso e está pronto para ser usado.

## Crie os diretórios usados pelos tutoriais
<a name="iot-dc-install-dc-files"></a>

Este procedimento cria os diretórios no Raspberry Pi que serão usados para armazenar os arquivos usados pelos tutoriais neste percurso de aprendizado.

**Para criar os diretórios usados pelos tutoriais neste percurso de aprendizado:**

1. Execute esses comandos para criar os diretórios necessários.

   ```
   mkdir ~/dc-configs
   mkdir ~/policies
   mkdir ~/messages
   mkdir ~/certs/testconn
   mkdir ~/certs/pubsub
   mkdir ~/certs/jobs
   ```

1. Execute esses comandos para definir as permissões nos novos diretórios.

   ```
   chmod 745 ~
   chmod 700 ~/certs/testconn
   chmod 700 ~/certs/pubsub
   chmod 700 ~/certs/jobs
   ```

Depois de criar esses diretórios e definir permissões, continue em [(Opcional) Salve a imagem do cartão microSD](#iot-dc-install-dc-save).

## (Opcional) Salve a imagem do cartão microSD
<a name="iot-dc-install-dc-save"></a>

Neste ponto, o cartão microSD do seu Raspberry Pi tem um sistema operacional atualizado, o software básico do aplicativo e AWS IoT o Device Client. 

Se você quiser voltar para tentar esses exercícios e tutoriais novamente, pule os procedimentos anteriores gravando a imagem do cartão microSD que você salvou com esse procedimento em um novo cartão microSD e continue com os tutoriais em [Provisione seu Raspberry Pi em AWS IoT](iot-dc-install-provision.md).

**Para salvar a imagem do cartão microSD em um arquivo:**

Na janela do terminal do computador host local conectado ao Raspberry Pi:

1. Confirme se suas Conta da AWS credenciais não foram armazenadas.

   1. Execute o aplicativo AWS configure com este comando:

      ```
      aws configure
      ```

   1. Se suas credenciais tiverem sido armazenadas (se forem exibidas no prompt), insira a string **XYXYXYXYX** quando solicitada, conforme mostrado aqui. Deixe o **Nome da região padrão** e o **Formato de saída padrão** em branco.

      ```
      AWS Access Key ID [****************YXYX]: XYXYXYXYX
      AWS Secret Access Key [****************YXYX]: XYXYXYXYX
      Default region name: 
      Default output format:
      ```

1. Digite este comando para desligar o Raspberry Pi.

   ```
   sudo shutdown -h 0
   ```

1. Depois que o Raspberry Pi for desligado completamente, remova o conector de alimentação.

1. Remova o cartão microSD do dispositivo.

1. No computador host local: 

   1. Insira o cartão microSD.

   1. Usando uma ferramenta de imagem de cartão SD, grave a imagem do cartão microSD em um arquivo.

   1. Depois que a imagem do cartão microSD for salva, ejete o cartão do computador host local.

Você pode continuar com esse cartão microSD inserido em [Provisione seu Raspberry Pi em AWS IoT](iot-dc-install-provision.md).

# Provisione seu Raspberry Pi em AWS IoT
<a name="iot-dc-install-provision"></a>

Os procedimentos nesta seção começam com a imagem microSD salva que tem o AWS CLI e o AWS IoT Device Client instalado e criam os AWS IoT recursos e certificados de dispositivo que provisionam seu Raspberry Pi. AWS IoT

## Instale o cartão microSD no Raspberry Pi
<a name="iot-dc-install-dc-restore"></a>

Este procedimento instala o cartão microSD com o software necessário carregado e configurado no Raspberry Pi e o configura para que Conta da AWS você possa continuar com os tutoriais neste caminho de aprendizado.

Use um cartão microSD de [(Opcional) Salve a imagem do cartão microSD](iot-dc-install-download.md#iot-dc-install-dc-save) que tenha o software necessário para os exercícios e tutoriais deste percurso de aprendizado.

**Para instalar o cartão microSD no Raspberry Pi**

1. Com a alimentação desconectada do Raspberry Pi, insira o cartão microSD no Raspberry Pi.

1. Ligue o Raspberry Pi.

1. Após cerca de um minuto, no computador host local, reinicie a sessão da janela do terminal e faça login no Raspberry Pi.

1. No computador host local, na janela do terminal e com as credenciais de **ID da chave de acesso** de **Chave de acesso secreta** do Raspberry Pi:

   1. Execute o aplicativo AWS configure com este comando:

      ```
      aws configure
      ```

   1. Insira suas Conta da AWS credenciais e informações de configuração quando solicitado:

      ```
      AWS Access Key ID [****************YXYX]: your Access Key ID
      AWS Secret Access Key [****************YXYX]: your Secret Access Key
      Default region name [us-west-2]: your Região da AWS code
      Default output format [json]: json
      ```

Depois de restaurar suas Conta da AWS credenciais, você estará pronto para continuar[Provisione seu dispositivo em AWS IoT Core](#iot-dc-install-dc-provision).

## Provisione seu dispositivo em AWS IoT Core
<a name="iot-dc-install-dc-provision"></a>

Os procedimentos nesta seção criam os AWS IoT recursos que provisionam seu Raspberry Pi em AWS IoT. Ao criar esses recursos, você deverá registrar várias informações. Essas informações são usadas pela configuração do AWS IoT Device Client no próximo procedimento.

Para que seu Raspberry Pi funcione AWS IoT, ele deve ser provisionado. O provisionamento é o processo de criar e configurar os AWS IoT recursos necessários para oferecer suporte ao seu Raspberry Pi como um dispositivo de IoT.

Com o Raspberry Pi ligado e reiniciado, conecte a janela do terminal no computador host local ao Raspberry Pi e conclua esses procedimentos.

**Topics**
+ [Crie e baixe arquivos de certificado](#iot-dc-install-dc-provision-certs)
+ [Crie AWS IoT recursos](#iot-dc-install-dc-provision-resources)

### Crie e baixe arquivos de certificado
<a name="iot-dc-install-dc-provision-certs"></a>

Este procedimento cria os arquivos de certificado de dispositivo para esta demonstração.

**Para criar e baixar os arquivos de certificado de dispositivo para o Raspberry Pi**

1. Na janela do terminal do computador host local, insira esses comandos para criar os arquivos de certificado de dispositivo para o dispositivo.

   ```
   mkdir ~/certs/testconn
   aws iot create-keys-and-certificate \
   --set-as-active \
   --certificate-pem-outfile "~/certs/testconn/device.pem.crt" \
   --public-key-outfile "~/certs/testconn/public.pem.key" \
   --private-key-outfile "~/certs/testconn/private.pem.key"
   ```

   O comando retorna uma resposta como a seguinte. Registre o valor de `certificateArn` para uso posterior.

   ```
   {
       "certificateArn": "arn:aws:iot:us-west-2:57EXAMPLE833:cert/76e7e4edb3e52f52334be2f387a06145b2aa4c7fcd810f3aea2d92abc227d269",
       "certificateId": "76e7e4edb3e52f5233EXAMPLE7a06145b2aa4c7fcd810f3aea2d92abc227d269",
       "certificatePem": "-----BEGIN CERTIFICATE-----\nMIIDWTCCAkGgAwIBAgI_SHORTENED_FOR_EXAMPLE_Lgn4jfgtS\n-----END CERTIFICATE-----\n",
       "keyPair": {
           "PublicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BA_SHORTENED_FOR_EXAMPLE_ImwIDAQAB\n-----END PUBLIC KEY-----\n",
           "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQE_SHORTENED_FOR_EXAMPLE_T9RoDiukY\n-----END RSA PRIVATE KEY-----\n"
       }
   }
   ```

1. Insira os comandos a seguir para definir as permissões no diretório de certificados e arquivos.

   ```
   chmod 745 ~
   chmod 700 ~/certs/testconn
   chmod 644 ~/certs/testconn/*
   chmod 600 ~/certs/testconn/private.pem.key
   ```

1. Execute este comando para examinar as permissões nos diretórios e arquivos do certificado.

   ```
   ls -l ~/certs/testconn
   ```

   A saída do comando deve ser a mesma vista aqui, com exceção das datas e horários do arquivo, que serão diferentes.

   ```
   -rw-r--r-- 1 pi pi 1220 Oct 28 13:02 device.pem.crt
   -rw------- 1 pi pi 1675 Oct 28 13:02 private.pem.key
   -rw-r--r-- 1 pi pi  451 Oct 28 13:02 public.pem.key
   ```

Neste ponto, você tem os arquivos de certificado do dispositivo instalados no Raspberry Pi e pode continuar em [Crie AWS IoT recursos](#iot-dc-install-dc-provision-resources).

### Crie AWS IoT recursos
<a name="iot-dc-install-dc-provision-resources"></a>

Esse procedimento provisiona seu dispositivo AWS IoT criando os recursos necessários para acessar AWS IoT recursos e serviços.

**Para provisionar seu dispositivo em AWS IoT**

1. Na janela do terminal do computador host local, insira o comando a seguir para obter o endereço do endpoint de dados do dispositivo da sua Conta da AWS.

   ```
   aws iot describe-endpoint --endpoint-type IoT:Data-ATS
   ```

   O comando das etapas anteriores retorna uma resposta como a seguir. Registre o valor de `endpointAddress` para uso posterior.

   ```
   {
       "endpointAddress": "a3qjEXAMPLEffp-ats.iot.us-west-2.amazonaws.com"
   }
   ```

1. Digite este comando para criar um recurso para AWS IoT o seu Raspberry Pi.

   ```
   aws iot create-thing --thing-name "DevCliTestThing"
   ```

   Se seu recurso AWS IoT Thing foi criado, o comando retornará uma resposta como essa.

   ```
   {
       "thingName": "DevCliTestThing",
       "thingArn": "arn:aws:iot:us-west-2:57EXAMPLE833:thing/DevCliTestThing",
       "thingId": "8ea78707-32c3-4f8a-9232-14bEXAMPLEfd"
   }
   ```

1. Na janela do terminal:

   1. Abra um editor de texto, como o `nano`.

   1. Copie este documento de política JSON e cole-o no editor de texto aberto.  
****  

      ```
      {
          "Version":"2012-10-17",		 	 	 
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "iot:Publish",
                      "iot:Subscribe",
                      "iot:Receive",
                      "iot:Connect"
                  ],
                  "Resource": [
                      "*"
                  ]
              }
          ]
      }
      ```
**nota**  
Este documento de política concede generosamente a cada recurso permissão para se conectar, receber, publicar e assinar. Normalmente, as políticas concedem permissão somente a recursos específicos para realizar ações específicas. No entanto, para o teste inicial de conectividade do dispositivo, essa política excessivamente geral e permissiva é usada para minimizar a chance de um problema de acesso durante esse teste. Nos tutoriais subsequentes, documentos de políticas com escopo mais restrito serão usados para demonstrar práticas recomendadas na elaboração de políticas.

   1. Salve o arquivo no editor de texto como **\$1/policies/dev\$1cli\$1test\$1thing\$1policy.json**. 

1. Execute esse comando para usar o documento de política das etapas anteriores para criar uma AWS IoT política.

   ```
   aws iot create-policy \
   --policy-name "DevCliTestThingPolicy" \
   --policy-document "file://~/policies/dev_cli_test_thing_policy.json"
   ```

   Se a política for criada, o comando retornará uma resposta como esta.

   ```
   {
       "policyName": "DevCliTestThingPolicy",
       "policyArn": "arn:aws:iot:us-west-2:57EXAMPLE833:policy/DevCliTestThingPolicy",
       "policyDocument": "{\n    \"Version\": \"2012-10-17\",		 	 	 \n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"iot:Publish\",\n                \"iot:Subscribe\",\n                \"iot:Receive\",\n                \"iot:Connect\"\n            ],\n            \"Resource\": [\n                \"*\"\n            ]\n        }\n    ]\n}\n",
       "policyVersionId": "1"
   }
   ```

1. Execute este comando para anexar a política ao certificado do dispositivo. Substitua `certificateArn` pelo valor de `certificateArn` salvo anteriormente.

   ```
   aws iot attach-policy \
   --policy-name "DevCliTestThingPolicy" \
   --target "certificateArn"
   ```

   Se houver êxito, o comando não retornará nada.

1. Execute esse comando para anexar o certificado do dispositivo ao recurso da AWS IoT coisa. Substitua `certificateArn` pelo valor de `certificateArn` salvo anteriormente.

   ```
   aws iot attach-thing-principal \
   --thing-name "DevCliTestThing" \
   --principal "certificateArn"
   ```

   Se houver êxito, o comando não retornará nada.

Depois de provisionar seu dispositivo com sucesso AWS IoT, você estará pronto para continuar. [Configurar o cliente do AWS IoT dispositivo para testar a conectividade](iot-dc-install-configure.md)

# Configurar o cliente do AWS IoT dispositivo para testar a conectividade
<a name="iot-dc-install-configure"></a>

Os procedimentos nesta seção configuram o AWS IoT Device Client para publicar uma mensagem MQTT do seu Raspberry Pi.

**Topics**
+ [Crie o arquivo de configuração](#iot-dc-install-dc-configure-step1)
+ [Abra o cliente de teste MQTT](#iot-dc-install-dc-configure-step2)
+ [Execute AWS IoT o cliente do dispositivo](#iot-dc-install-dc-configure-step3)

## Crie o arquivo de configuração
<a name="iot-dc-install-dc-configure-step1"></a>

Esse procedimento cria o arquivo de configuração para testar o AWS IoT Device Client.

**Para criar o arquivo de configuração para testar o AWS IoT Device Client**
+ Na janela do terminal do computador host local conectado ao Raspberry Pi:

  1. Insira estes comandos para criar um diretório para os arquivos de configuração e definir a permissão no diretório:

     ```
     mkdir ~/dc-configs
     chmod 745 ~/dc-configs
     ```

  1. Abra um editor de texto, como o `nano`.

  1. Copie este documento JSON e cole-o no editor de texto aberto.

     ```
     {
       "endpoint": "a3qEXAMPLEaffp-ats.iot.us-west-2.amazonaws.com",
       "cert": "~/certs/testconn/device.pem.crt",
       "key": "~/certs/testconn/private.pem.key",
       "root-ca": "~/certs/AmazonRootCA1.pem",
       "thing-name": "DevCliTestThing",
       "logging": {
         "enable-sdk-logging": true,
         "level": "DEBUG",
         "type": "STDOUT",
         "file": ""
       },
       "jobs": {
         "enabled": false,
         "handler-directory": ""
       },
       "tunneling": {
         "enabled": false
       },
       "device-defender": {
         "enabled": false,
         "interval": 300
       },
       "fleet-provisioning": {
         "enabled": false,
         "template-name": "",
         "template-parameters": "",
         "csr-file": "",
         "device-key": ""
       },
       "samples": {
         "pub-sub": {
           "enabled": true,
           "publish-topic": "test/dc/pubtopic",
           "publish-file": "",
           "subscribe-topic": "test/dc/subtopic",
           "subscribe-file": ""
         }
       },
       "config-shadow": {
         "enabled": false
       },
       "sample-shadow": {
         "enabled": false,
         "shadow-name": "",
         "shadow-input-file": "",
         "shadow-output-file": ""
       }
     }
     ```

  1. Substitua o *endpoint* valor pelo endpoint de dados do dispositivo Conta da AWS que você encontrou em[Provisione seu dispositivo em AWS IoT Core](iot-dc-install-provision.md#iot-dc-install-dc-provision).

  1. Salve o arquivo no editor de texto como **\$1/dc-configs/dc-testconn-config.json**.

  1. Execute este comando para definir permissões no novo arquivo de configuração.

     ```
     chmod 644 ~/dc-configs/dc-testconn-config.json
     ```

Após salvar o arquivo, você estará pronto para continuar em [Abra o cliente de teste MQTT](#iot-dc-install-dc-configure-step2).

## Abra o cliente de teste MQTT
<a name="iot-dc-install-dc-configure-step2"></a>

Esse procedimento prepara o **cliente de teste MQTT** no AWS IoT console para assinar a mensagem MQTT que o AWS IoT Device Client publica quando é executado.

**Para preparar o **cliente de teste MQTT** para assinar todas as mensagens MQTT**

1. No computador host local, no [console da AWS IoT](https://console.aws.amazon.com//iot/home#/test), selecione o **cliente de teste MQTT**.

1. Na guia **Assinar um tópico**, em **Filtro de tópicos**, insira **\$1** (um único sinal de cerquilha) e selecione **Assinar** para assinar cada tópico do MQTT.

1. Abaixo do rótulo **Assinaturas**, confirme que pode ver **\$1** (um único sinal de jogo da velha).

Deixe a janela com o **cliente de teste MQTT** aberta enquanto continua na [Execute AWS IoT o cliente do dispositivo](#iot-dc-install-dc-configure-step3).

## Execute AWS IoT o cliente do dispositivo
<a name="iot-dc-install-dc-configure-step3"></a>

Esse procedimento executa o AWS IoT Device Client para que ele publique uma única mensagem MQTT que o **cliente de teste MQTT** receba e exiba.

**Para enviar uma mensagem MQTT do AWS IoT Device Client**

1. Certifique-se de que a janela do terminal conectada ao Raspberry Pi e a janela com o **cliente de teste MQTT** estejam visíveis enquanto você realiza esse procedimento.

1. Na janela do terminal, insira esses comandos para executar o AWS IoT Device Client usando o arquivo de configuração criado em[Crie o arquivo de configuração](#iot-dc-install-dc-configure-step1).

   ```
   cd ~/aws-iot-device-client/build
   ./aws-iot-device-client --config-file ~/dc-configs/dc-testconn-config.json
   ```

   Na janela do terminal, o AWS IoT Device Client exibe mensagens informativas e quaisquer erros que ocorram durante a execução.

   Caso nenhum erro seja exibido na janela do terminal, examine o **cliente de teste do MQTT**.

1. No **cliente de teste do MQTT**, na janela Assinaturas, consulte a mensagem *Olá, mundo\$1* enviada ao tópico de mensagem `test/dc/pubtopic`.

1. Se o AWS IoT Device Client não exibir erros e você ver *Hello World\$1* enviada para a `test/dc/pubtopic` mensagem no **cliente de teste do MQTT**, você demonstrou uma conexão bem-sucedida.

1. Na janela do terminal, digite **^C** (Ctrl-C) para parar o AWS IoT Device Client.

Depois de demonstrar que o AWS IoT Device Client está funcionando corretamente em seu Raspberry Pi e pode se comunicar com AWS IoT, você pode continuar com o. [Tutorial: Demonstre a comunicação de mensagens MQTT com o AWS IoT Device Client](iot-dc-testconn.md)

# Tutorial: Demonstre a comunicação de mensagens MQTT com o AWS IoT Device Client
<a name="iot-dc-testconn"></a>

Este tutorial demonstra como o AWS IoT Device Client pode assinar e publicar mensagens MQTT, que são comumente usadas em soluções de IoT.

**Para iniciar este tutorial:**
+ Configure seu computador host local e Raspberry Pi como [na seção anterior](iot-dc-install-dc.md).

  Se você salvou a imagem do cartão microSD depois de instalar o AWS IoT Device Client, você pode usar um cartão microSD com essa imagem com seu Raspberry Pi.
+ Se você já executou essa demonstração antes, revise [Etapa 2: Limpar suas demonstrações Conta da AWS após a criação com o AWS IoT Device Client](iot-dc-cleanup.md#iot-dc-cleanup-cloud) para excluir todos os AWS IoT recursos que você criou em execuções anteriores para evitar erros de recursos duplicados.

Este tutorial leva cerca de 45 minutos para ser concluído.

**Quando você concluir este tópico:**
+ Você terá demonstrado diferentes maneiras pelas quais seu dispositivo de IoT pode assinar mensagens MQTT AWS IoT e publicar mensagens MQTT em. AWS IoT

**Equipamentos necessários:**
+ O ambiente local de desenvolvimento e teste da [seção anterior](iot-dc-install-dc.md)
+ O Raspberry Pi usado na [seção anterior](iot-dc-install-dc.md)
+ O cartão de memória microSD do Raspberry Pi usado na [seção anterior](iot-dc-install-dc.md)

**Topics**
+ [Preparar o Raspberry Pi para demonstrar a comunicação de mensagens MQTT](iot-dc-testconn-provision.md)
+ [Demonstre a publicação de mensagens com o AWS IoT Device Client](iot-dc-testconn-publish.md)
+ [Demonstre a assinatura de mensagens com o AWS IoT Device Client](iot-dc-testconn-subscribe.md)

# Preparar o Raspberry Pi para demonstrar a comunicação de mensagens MQTT
<a name="iot-dc-testconn-provision"></a>

Esse procedimento cria os recursos no AWS IoT e no Raspberry Pi para demonstrar a comunicação de mensagens MQTT usando o AWS IoT Device Client.

**Topics**
+ [Criar os arquivos de certificado para demonstrar a comunicação MQTT](#iot-dc-testconn-provision-certs)
+ [Provisione seu dispositivo para demonstrar a comunicação MQTT](#iot-dc-testconn-provision-aws)
+ [Configure o arquivo de configuração do AWS IoT Device Client e o cliente de teste MQTT para demonstrar a comunicação MQTT](#iot-dc-testconn-provision-dc-config)

## Criar os arquivos de certificado para demonstrar a comunicação MQTT
<a name="iot-dc-testconn-provision-certs"></a>

Este procedimento cria os arquivos de certificado de dispositivo para esta demonstração.

**Para criar e baixar os arquivos de certificado de dispositivo para o Raspberry Pi**



1. Na janela do terminal do computador host local, insira o comando a seguir para criar os arquivos de certificado de dispositivo para o dispositivo.

   ```
   mkdir ~/certs/pubsub
   aws iot create-keys-and-certificate \
   --set-as-active \
   --certificate-pem-outfile "~/certs/pubsub/device.pem.crt" \
   --public-key-outfile "~/certs/pubsub/public.pem.key" \
   --private-key-outfile "~/certs/pubsub/private.pem.key"
   ```

   O comando retorna uma resposta como a seguinte. Salve o valor de `certificateArn` para uso posterior.

   ```
   {
   "certificateArn": "arn:aws:iot:us-west-2:57EXAMPLE833:cert/76e7e4edb3e52f52334be2f387a06145b2aa4c7fcd810f3aea2d92abc227d269",
   "certificateId": "76e7e4edb3e52f5233EXAMPLE7a06145b2aa4c7fcd810f3aea2d92abc227d269",
   "certificatePem": "-----BEGIN CERTIFICATE-----\nMIIDWTCCAkGgAwIBAgI_SHORTENED_FOR_EXAMPLE_Lgn4jfgtS\n-----END CERTIFICATE-----\n",
   "keyPair": {
       "PublicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BA_SHORTENED_FOR_EXAMPLE_ImwIDAQAB\n-----END PUBLIC KEY-----\n",
       "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQE_SHORTENED_FOR_EXAMPLE_T9RoDiukY\n-----END RSA PRIVATE KEY-----\n"
   }
   }
   ```

1. Insira os comandos a seguir para definir as permissões no diretório de certificados e arquivos.

   ```
   chmod 700 ~/certs/pubsub
   chmod 644 ~/certs/pubsub/*
   chmod 600 ~/certs/pubsub/private.pem.key
   ```

1. Execute este comando para examinar as permissões nos diretórios e arquivos do certificado.

   ```
   ls -l ~/certs/pubsub
   ```

   A saída do comando deve ser a mesma vista aqui, com exceção das datas e horários do arquivo, que serão diferentes.

   ```
   -rw-r--r-- 1 pi pi 1220 Oct 28 13:02 device.pem.crt
   -rw------- 1 pi pi 1675 Oct 28 13:02 private.pem.key
   -rw-r--r-- 1 pi pi  451 Oct 28 13:02 public.pem.key
   ```

1. Digite esses comandos para criar os diretórios para os arquivos de log.

   ```
   mkdir ~/.aws-iot-device-client
   mkdir ~/.aws-iot-device-client/log
   chmod 745 ~/.aws-iot-device-client/log
   echo " " > ~/.aws-iot-device-client/log/aws-iot-device-client.log
   echo " " > ~/.aws-iot-device-client/log/pubsub_rx_msgs.log
   chmod 600 ~/.aws-iot-device-client/log/*
   ```

## Provisione seu dispositivo para demonstrar a comunicação MQTT
<a name="iot-dc-testconn-provision-aws"></a>

Esta seção cria os AWS IoT recursos que provisionam seu Raspberry Pi em AWS IoT. 

**Para provisionar seu dispositivo no AWS IoT:**

1. Na janela do terminal do computador host local, insira o comando a seguir para obter o endereço do endpoint de dados do dispositivo da sua Conta da AWS.

   ```
   aws iot describe-endpoint --endpoint-type IoT:Data-ATS
   ```

   O valor do endpoint não foi alterado desde quando este comando foi executado no tutorial anterior. Uma nova execução deste comando facilita localizar e colar o valor do endpoint de dados no arquivo de configuração usado neste tutorial.

   O comando das etapas anteriores retorna uma resposta como a seguir. Registre o valor de `endpointAddress` para uso posterior.

   ```
   {
   "endpointAddress": "a3qjEXAMPLEffp-ats.iot.us-west-2.amazonaws.com"
   }
   ```

1. Digite este comando para criar um novo recurso para AWS IoT o seu Raspberry Pi.

   ```
   aws iot create-thing --thing-name "PubSubTestThing"
   ```

   Como um recurso de AWS IoT coisas é uma representação *virtual* do seu dispositivo na nuvem, podemos criar vários recursos de coisas AWS IoT para serem usados para finalidades diferentes. Todos os recursos de objetos podem ser usados pelo mesmo dispositivo físico de IoT para representar aspectos diferentes do dispositivo.

   Estes tutoriais usarão apenas um recurso de objeto por vez para representar o Raspberry Pi. Dessa forma, nesses tutoriais, eles representam as diferentes demonstrações para que, depois de criar os AWS IoT recursos para uma demonstração, você possa voltar e repetir a demonstração usando os recursos criados especificamente para cada uma.

   Se seu recurso AWS IoT Thing foi criado, o comando retornará uma resposta como essa.

   ```
   {
   "thingName": "PubSubTestThing",
   "thingArn": "arn:aws:iot:us-west-2:57EXAMPLE833:thing/PubSubTestThing",
   "thingId": "8ea78707-32c3-4f8a-9232-14bEXAMPLEfd"
   }
   ```

1. Na janela do terminal:

   1. Abra um editor de texto, como o `nano`.

   1. Copie este documento JSON e cole-o no editor de texto aberto.  
****  

      ```
      {
          "Version":"2012-10-17",		 	 	 
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "iot:Connect"
                  ],
                  "Resource": [
                      "arn:aws:iot:us-west-2:123456789012:client/PubSubTestThing"
                  ]
              },
              {
                  "Effect": "Allow",
                  "Action": [
                      "iot:Publish"
                  ],
                  "Resource": [
                      "arn:aws:iot:us-west-2:123456789012:topic/test/dc/pubtopic"
                  ]
              },
              {
                  "Effect": "Allow",
                  "Action": [
                      "iot:Subscribe"
                  ],
                  "Resource": [
                      "arn:aws:iot:us-west-2:123456789012:topicfilter/test/dc/subtopic"
                  ]
              },
              {
                  "Effect": "Allow",
                  "Action": [
                      "iot:Receive"
                  ],
                  "Resource": [
                      "arn:aws:iot:us-west-2:123456789012:topic/test/dc/subtopic"
                  ]
              }
          ]
      }
      ```

   1. No editor, em cada `Resource` seção do documento de política, *us-west-2:57EXAMPLE833* substitua por seu Região da AWS, um caractere de dois pontos (:)) e seu número de 12 dígitos Conta da AWS .

   1. Salve o arquivo no editor de texto como **\$1/policies/pubsub\$1test\$1thing\$1policy.json**. 

1. Execute esse comando para usar o documento de política das etapas anteriores para criar uma AWS IoT política.

   ```
   aws iot create-policy \
   --policy-name "PubSubTestThingPolicy" \
   --policy-document "file://~/policies/pubsub_test_thing_policy.json"
   ```

   Se a política for criada, o comando retornará uma resposta como esta.

   ```
   {
                                       "policyName": "PubSubTestThingPolicy",
                                       "policyArn": "arn:aws:iot:us-west-2:57EXAMPLE833:policy/PubSubTestThingPolicy",
                                       "policyDocument": "{\n\"Version\": \"2012-10-17\",		 	 	 \n\"Statement\": [\n{\n\"Effect\": \"Allow\",\n\"Action\": [\n\"iot:Connect\"\n],\n\"Resource\": [\n\"arn:aws:iot:us-west-2:57EXAMPLE833:client/PubSubTestThing\"\n]\n},\n{\n\"Effect\": \"Allow\",\n\"Action\": [\n\"iot:Publish\"\n],\n\"Resource\": [\n\"arn:aws:iot:us-west-2:57EXAMPLE833:topic/test/dc/pubtopic\"\n]\n},\n{\n\"Effect\": \"Allow\",\n\"Action\": [\n\"iot:Subscribe\"\n],\n\"Resource\": [\n\"arn:aws:iot:us-west-2:57EXAMPLE833:topicfilter/test/dc/subtopic\"\n]\n},\n{\n\"Effect\": \"Allow\",\n\"Action\": [\n\"iot:Receive\"\n],\n\"Resource\": [\n\"arn:aws:iot:us-west-2:57EXAMPLE833:topic/test/dc/*\"\n]\n}\n]\n}\n",
                                       "policyVersionId": "1"
                                       }
   ```

1. Execute este comando para anexar a política ao certificado do dispositivo. Substitua `certificateArn` pelo valor de `certificateArn` salvo anteriormente nesta seção.

   ```
   aws iot attach-policy \
   --policy-name "PubSubTestThingPolicy" \
   --target "certificateArn"
   ```

   Se houver êxito, o comando não retornará nada.

1. Execute o comando a seguir para anexar o certificado de dispositivo ao recurso de objeto do AWS IoT . Substitua `certificateArn` pelo valor de `certificateArn` salvo anteriormente nesta seção.

   ```
   aws iot attach-thing-principal \
   --thing-name "PubSubTestThing" \
   --principal "certificateArn"
   ```

   Se houver êxito, o comando não retornará nada.

Depois de provisionar seu dispositivo com sucesso AWS IoT, você estará pronto para continuar[Configure o arquivo de configuração do AWS IoT Device Client e o cliente de teste MQTT para demonstrar a comunicação MQTT](#iot-dc-testconn-provision-dc-config).

## Configure o arquivo de configuração do AWS IoT Device Client e o cliente de teste MQTT para demonstrar a comunicação MQTT
<a name="iot-dc-testconn-provision-dc-config"></a>

Esse procedimento cria um arquivo de configuração para testar o AWS IoT Device Client.

**Para criar o arquivo de configuração para testar o AWS IoT Device Client**

1. Na janela do terminal do computador host local conectado ao Raspberry Pi:

   1. Abra um editor de texto, como o `nano`.

   1. Copie este documento JSON e cole-o no editor de texto aberto.

      ```
      {
        "endpoint": "a3qEXAMPLEaffp-ats.iot.us-west-2.amazonaws.com",
        "cert": "~/certs/pubsub/device.pem.crt",
        "key": "~/certs/pubsub/private.pem.key",
        "root-ca": "~/certs/AmazonRootCA1.pem",
        "thing-name": "PubSubTestThing",
        "logging": {
          "enable-sdk-logging": true,
          "level": "DEBUG",
          "type": "STDOUT",
          "file": ""
        },
        "jobs": {
          "enabled": false,
          "handler-directory": ""
        },
        "tunneling": {
          "enabled": false
        },
        "device-defender": {
          "enabled": false,
          "interval": 300
        },
        "fleet-provisioning": {
          "enabled": false,
          "template-name": "",
          "template-parameters": "",
          "csr-file": "",
          "device-key": ""
        },
        "samples": {
          "pub-sub": {
            "enabled": true,
            "publish-topic": "test/dc/pubtopic",
            "publish-file": "",
            "subscribe-topic": "test/dc/subtopic",
            "subscribe-file": "~/.aws-iot-device-client/log/pubsub_rx_msgs.log"
          }
        },
        "config-shadow": {
          "enabled": false
        },
        "sample-shadow": {
          "enabled": false,
          "shadow-name": "",
          "shadow-input-file": "",
          "shadow-output-file": ""
        }
      }
      ```

   1. Substitua o *endpoint* valor pelo endpoint de dados do dispositivo Conta da AWS que você encontrou em[Provisione seu dispositivo em AWS IoT Core](iot-dc-install-provision.md#iot-dc-install-dc-provision).

   1. Salve o arquivo no editor de texto como **\$1/dc-configs/dc-pubsub-config.json**.

   1. Execute este comando para definir permissões no novo arquivo de configuração.

      ```
      chmod 644 ~/dc-configs/dc-pubsub-config.json
      ```

1. Para preparar o **cliente de teste MQTT** para assinar todas as mensagens MQTT:

   1. No computador host local, no [console da AWS IoT](https://console.aws.amazon.com//iot/home#/test), selecione o **cliente de teste MQTT**.

   1. Na guia **Assinar um tópico**, em **Filtro de tópicos**, insira **\$1** (um único sinal de jogo da velha) e selecione **Assinar**.

   1. Abaixo do rótulo **Assinaturas**, confirme que pode ver **\$1** (um único sinal de jogo da velha).

   Deixe a janela com o **cliente de teste MQTT** aberta enquanto prossegue com este tutorial.

Depois de salvar o arquivo e configurar o **cliente de teste MQTT**, você estará pronto para avançar para [Demonstre a publicação de mensagens com o AWS IoT Device Client](iot-dc-testconn-publish.md).

# Demonstre a publicação de mensagens com o AWS IoT Device Client
<a name="iot-dc-testconn-publish"></a>

Os procedimentos nesta seção demonstram como o AWS IoT Device Client pode enviar mensagens MQTT padrão e personalizadas.

As seguintes declarações de política na política criada na etapa anterior para esses exercícios concedem ao Raspberry Pi permissão para realizar estas ações:
+ 

**`iot:Connect`**  
Fornece o nome do cliente`PubSubTestThing`, seu Raspberry Pi executando o AWS IoT Device Client, para se conectar.

  ```
      {
        "Effect": "Allow",
        "Action": [
          "iot:Connect"
        ],
        "Resource": [
          "arn:aws:iot:us-west-2:57EXAMPLE833:client/PubSubTestThing"
        ]
      }
  ```
+ 

**`iot:Publish`**  
Permite que o Raspberry Pi publique mensagens com um tópico MQTT de `test/dc/pubtopic`.

  ```
      {
        "Effect": "Allow",
        "Action": [
          "iot:Publish"
        ],
        "Resource": [
          "arn:aws:iot:us-west-2:57EXAMPLE833:topic/test/dc/pubtopic"
        ]
      }
  ```

  A ação `iot:Publish` concede permissão para publicar em tópicos MQTT listados na matriz de recursos. A declaração de política não controla o *conteúdo* dessas mensagens.

## Publique a mensagem padrão usando o AWS IoT Device Client
<a name="iot-dc-testconn-publish-default"></a>

Esse procedimento executa o AWS IoT Device Client para que ele publique uma única mensagem MQTT padrão que o **cliente de teste MQTT** recebe e exibe.

**Para enviar a mensagem MQTT padrão do AWS IoT Device Client**

1. Certifique-se de que a janela do terminal do computador host local conectado ao Raspberry Pi e a janela com o **cliente de teste MQTT** estejam visíveis enquanto você realiza esse procedimento.

1. Na janela do terminal, insira esses comandos para executar o AWS IoT Device Client usando o arquivo de configuração criado em[Crie o arquivo de configuração](iot-dc-install-configure.md#iot-dc-install-dc-configure-step1).

   ```
   cd ~/aws-iot-device-client/build
   ./aws-iot-device-client --config-file ~/dc-configs/dc-pubsub-config.json
   ```

   Na janela do terminal, o AWS IoT Device Client exibe mensagens informativas e quaisquer erros que ocorram durante a execução.

   Caso nenhum erro seja exibido na janela do terminal, examine o **cliente de teste do MQTT**.

1. No **cliente de teste do MQTT**, na janela **Assinaturas**, consulte a mensagem *Olá, mundo\$1* enviada ao tópico de mensagem `test/dc/pubtopic`.

1. Se o AWS IoT Device Client não exibir erros e você ver *Hello World\$1* enviada para a `test/dc/pubtopic` mensagem no **cliente de teste do MQTT**, você demonstrou uma conexão bem-sucedida.

1. Na janela do terminal, digite **^C** (Ctrl-C) para parar o AWS IoT Device Client.

Depois de demonstrar que o AWS IoT Device Client publicou a mensagem padrão do MQTT, você pode continuar com o. [Publique uma mensagem personalizada usando o AWS IoT Device Client](#iot-dc-testconn-publish-custom)

## Publique uma mensagem personalizada usando o AWS IoT Device Client
<a name="iot-dc-testconn-publish-custom"></a>

Os procedimentos desta seção criam uma mensagem MQTT personalizada e, depois, executam o AWS IoT Device Client para que ele publique a mensagem MQTT personalizada uma vez para que o **cliente de teste MQTT** a receba e exiba.

### Crie uma mensagem MQTT personalizada para o AWS IoT Device Client
<a name="iot-dc-testconn-publish-custom-create"></a>

Realize as seguintes etapas na janela do terminal do computador host local que está conectado ao Raspberry Pi.

**Para criar uma mensagem personalizada para o AWS IoT Device Client publicar**

1. Na janela do terminal, abra um editor de texto, como o `nano`.

1. No editor de texto, copie e cole o seguinte documento JSON. Essa será a carga útil da mensagem MQTT que o AWS IoT Device Client publica.

   ```
   {
     "temperature": 28,
     "humidity": 80,
     "barometer": 1013,
     "wind": {
       "velocity": 22,
       "bearing": 255
     }
   }
   ```

1. Salve o conteúdo do editor de texto como **\$1/messages/sample-ws-message.json**. 

1. Digite o comando a seguir para definir as permissões do arquivo de mensagem que você acabou de criar.

   ```
   chmod 600 ~/messages/*
   ```

**Para criar um arquivo de configuração para o AWS IoT Device Client usar para enviar a mensagem personalizada**

1. Na janela do terminal, em um editor de texto como`nano`, abra o arquivo de configuração existente do AWS IoT Device Client:**\$1/dc-configs/dc-pubsub-config.json**. 

1. Edite o objeto `samples` para que ele fique assim. Não são necessárias alterações em outras partes deste arquivo.

   ```
     "samples": {
       "pub-sub": {
         "enabled": true,
         "publish-topic": "test/dc/pubtopic",
         "publish-file": "~/messages/sample-ws-message.json",
         "subscribe-topic": "test/dc/subtopic",
         "subscribe-file": "~/.aws-iot-device-client/log/pubsub_rx_msgs.log"
   ```

1. Salve o conteúdo do editor de texto como **\$1/dc-configs/dc-pubsub-custom-config.json**. 

1. Execute este comando para definir permissões no novo arquivo de configuração.

   ```
   chmod 644 ~/dc-configs/dc-pubsub-custom-config.json
   ```

### Publique a mensagem MQTT personalizada usando o AWS IoT Device Client
<a name="iot-dc-testconn-publish-custom-publish"></a>

Essa alteração afeta somente o *conteúdo* da carga da mensagem MQTT, então a política atual permanecerá funcionando. No entanto, se o *tópico MQTT* (conforme definido pelo valor de `publish-topic` em`~/dc-configs/dc-pubsub-custom-config.json`) fosse alterado, a declaração de política `iot::Publish` também precisaria ser modificada para permitir que o Raspberry Pi publique no novo tópico do MQTT.

**Para enviar a mensagem MQTT do AWS IoT Device Client**

1. Certifique-se de que a janela do terminal e a janela com o **cliente de teste MQTT** estejam visíveis enquanto você realiza esse procedimento. Além disso, certifique-se de que o **cliente de teste MQTT** ainda seja assinante no filtro de tópicos **\$1**. Se não o for, assine novamente o filtro de tópicos **\$1**.

1. Na janela do terminal, digite os seguintes comandos para executar o AWS IoT Device Client usando o arquivo de configuração criado em [Crie o arquivo de configuração](iot-dc-install-configure.md#iot-dc-install-dc-configure-step1).

   ```
   cd ~/aws-iot-device-client/build
   ./aws-iot-device-client --config-file ~/dc-configs/dc-pubsub-custom-config.json
   ```

   Na janela do terminal, o AWS IoT Device Client exibe mensagens informativas e quaisquer erros que ocorram durante a execução.

   Caso nenhum erro seja exibido na janela do terminal, examine o cliente de teste do MQTT.

1. No **cliente de teste MQTT**, na janela **Assinaturas**, examine a carga de mensagem personalizada enviada ao tópico de mensagem `test/dc/pubtopic`.

1. Se o AWS IoT Device Client não exibir erros e você ver a carga da mensagem personalizada que você publicou na `test/dc/pubtopic` mensagem no **cliente de teste do MQTT**, você publicou uma mensagem personalizada com sucesso.

1. Na janela do terminal, digite **^C** (Ctrl-C) para parar o AWS IoT Device Client.

Depois de demonstrar que o AWS IoT Device Client publicou uma carga de mensagem personalizada, você pode continuar[Demonstre a assinatura de mensagens com o AWS IoT Device Client](iot-dc-testconn-subscribe.md).

# Demonstre a assinatura de mensagens com o AWS IoT Device Client
<a name="iot-dc-testconn-subscribe"></a>

Nesta seção, você demonstrará dois tipos de assinaturas de mensagens:
+ Assinatura de tópico único
+ Assinatura de tópicos curinga

As seguintes declarações de política na política criada para esses exercícios concedem ao Raspberry Pi permissão para realizar estas ações:
+ 

**`iot:Receive`**  
Permite que o AWS IoT Device Client receba tópicos do MQTT que correspondam aos nomeados no `Resource` objeto.

  ```
      {
        "Effect": "Allow",
        "Action": [
          "iot:Receive"
        ],
        "Resource": [
          "arn:aws:iot:us-west-2:57EXAMPLE833:topic/test/dc/subtopic"
        ]
      }
  ```
+ 

**`iot:Subscribe`**  
Permite que o AWS IoT Device Client assine filtros de tópicos do MQTT que correspondam aos nomeados no `Resource` objeto.

  ```
      {
        "Effect": "Allow",
        "Action": [
          "iot:Subscribe"
        ],
        "Resource": [
          "arn:aws:iot:us-west-2:57EXAMPLE833:topicfilter/test/dc/subtopic"
        ]
      }
  ```

## Assinatura de um único tópico de mensagem MQTT
<a name="iot-dc-testconn-subscribe-simple-topic"></a>

Este procedimento demonstra como o AWS IoT Device Client pode assinar e registrar mensagens MQTT.

Na janela do terminal do computador host local que está conectado ao Raspberry Pi, liste o conteúdo de **\$1/dc-configs/dc-pubsub-custom-config.json** ou abra o arquivo em um editor de texto para examinar seu conteúdo. Localize o objeto `samples`, que deve ser semelhante ao seguinte.

```
  "samples": {
    "pub-sub": {
      "enabled": true,
      "publish-topic": "test/dc/pubtopic",
      "publish-file": "~/messages/sample-ws-message.json",
      "subscribe-topic": "test/dc/subtopic",
      "subscribe-file": "~/.aws-iot-device-client/log/pubsub_rx_msgs.log"
```

Observe que o valor de `subscribe-topic` é o tópico MQTT que o AWS IoT Device Client assinará quando for executado. O AWS IoT Device Client grava as cargas de mensagens que recebe dessa assinatura no arquivo nomeado no `subscribe-file` valor.

**Para assinar um tópico de mensagem MQTT a partir do AWS IoT Device Client**

1. Certifique-se de que a janela do terminal e a janela com o cliente de teste MQTT estejam visíveis enquanto você realiza esse procedimento. Além disso, certifique-se de que o **cliente de teste MQTT** ainda seja assinante no filtro de tópicos **\$1**. Se não o for, assine novamente o filtro de tópicos **\$1**.

1. Na janela do terminal, insira esses comandos para executar o AWS IoT Device Client usando o arquivo de configuração criado em[Crie o arquivo de configuração](iot-dc-install-configure.md#iot-dc-install-dc-configure-step1).

   ```
   cd ~/aws-iot-device-client/build
   ./aws-iot-device-client --config-file ~/dc-configs/dc-pubsub-custom-config.json
   ```

   Na janela do terminal, o AWS IoT Device Client exibe mensagens informativas e quaisquer erros que ocorram durante a execução.

   Caso nenhum erro seja exibido na janela do terminal, continue no console do AWS IoT .

1. No AWS IoT console, no **cliente de teste do MQTT**, escolha a guia **Publicar em um tópico**.

1. Em **Nome do tópico**, digite **test/dc/subtopic**

1. Em **Carga da mensagem**, examine o conteúdo da mensagem.

1. Selecione **Publicar** para publicar a mensagem MQTT.

1. Na janela do terminal, observe a entrada da *mensagem recebida* do AWS IoT Device Client que se parece com esta.

   ```
   2021-11-10T16:02:20.890Z [DEBUG] {samples/PubSubFeature.cpp}: Message received on subscribe topic, size: 45 bytes
   ```

1. Depois de ver a entrada da *mensagem recebida* que mostra que a mensagem foi recebida, digite **^C** (Ctrl-C) para interromper o AWS IoT Device Client.

1. Insira o seguinte comando para visualizar o final do arquivo de log de mensagens e ver a mensagem que foi publicada no **cliente de teste MQTT**.

   ```
   tail ~/.aws-iot-device-client/log/pubsub_rx_msgs.log
   ```

Ao visualizar a mensagem no arquivo de log, demonstrou-se que o AWS IoT Device Client recebeu a mensagem publicada a partir do cliente de teste MQTT.

## Assinar diversos tópicos de mensagens MQTT usando caracteres curinga
<a name="iot-dc-testconn-subscribe-wild-topic"></a>

Esses procedimentos demonstram como o AWS IoT Device Client pode assinar e registrar mensagens MQTT usando caracteres curinga. Para fazer isso, você deve:

1. Atualize o filtro de tópicos que o AWS IoT Device Client usa para assinar tópicos do MQTT.

1. Atualizar a política usada pelo dispositivo para permitir novas assinaturas.

1. Execute o AWS IoT Device Client e publique mensagens do console de teste do MQTT.

**Para criar um arquivo de configuração para assinar diversos tópicos de mensagens MQTT com um filtro de tópicos MQTT curinga**

1. Na janela do terminal do computador host local que está conectado ao Raspberry Pi, abra **\$1/dc-configs/dc-pubsub-custom-config.json** para edição e localize o objeto `samples`.

1. No editor de texto, localize o objeto `samples` e atualize o valor de `subscribe-topic` para que se assemelhe a isto. 

   ```
     "samples": {
       "pub-sub": {
         "enabled": true,
         "publish-topic": "test/dc/pubtopic",
         "publish-file": "~/messages/sample-ws-message.json",
         "subscribe-topic": "test/dc/#",
         "subscribe-file": "~/.aws-iot-device-client/log/pubsub_rx_msgs.log"
   ```

   O novo valor de `subscribe-topic` é um [filtro de tópicos MQTT](topics.md#topicfilters) com um caractere curinga MQTT no final. Isso descreve uma assinatura de todos os tópicos MQTT que começam com `test/dc/`. O AWS IoT Device Client grava as cargas de mensagens que recebe dessa assinatura no arquivo nomeado em`subscribe-file`.

1. Salve o arquivo de configuração modificado como **\$1/dc-configs/dc-pubsub-wild-config.json** e saia do editor de texto.

**Para modificar a política usada pelo Raspberry Pi para permitir a assinatura e recebimento de diversos tópicos de mensagens MQTT**

1. Na janela do terminal do seu computador host local conectado ao Raspberry Pi, em seu editor de texto favorito, abra **\$1/policies/pubsub\$1test\$1thing\$1policy.json** para edição e, depois, localize as declarações de política `iot::Subscribe` e `iot::Receive` no arquivo.

1. Na declaração de política `iot::Subscribe`, atualize a string no objeto Resource para substituir `subtopic` por `*`, de modo que fique semelhante ao seguinte.

   ```
       {
         "Effect": "Allow",
         "Action": [
           "iot:Subscribe"
         ],
         "Resource": [
           "arn:aws:iot:us-west-2:57EXAMPLE833:topicfilter/test/dc/*"
         ]
       }
   ```
**nota**  
Os [caracteres curinga do filtro de tópicos MQTT](topics.md#topicfilters) são `+` (sinal de adição) e `#` (sinal de jogo da velha). Uma solicitação de assinatura com `#` no final assina todos os tópicos que começam com a string que precede o caractere `#` (como, nesse caso, `test/dc/`).   
Entretanto, o valor do recurso na declaração de política autorizando essa assinatura deve usar `*` (asterisco) no lugar de `#` (sinal de jogo da velha) no ARN do filtro de tópicos. Isso ocorre porque o processador de políticas usa um caractere curinga diferente daquele usado pelo MQTT.  
Para acessar mais informações sobre como usar caracteres curinga para tópicos e filtros de tópicos em políticas, consulte [Usando caracteres curinga no MQTT e nas políticas AWS IoT Core](pub-sub-policy.md#pub-sub-policy-cert).

1. Na declaração de política `iot::Receive`, atualize a string no objeto Resource para substituir `subtopic` por `*`, de modo que fique semelhante ao seguinte.

   ```
       {
         "Effect": "Allow",
         "Action": [
           "iot:Receive"
         ],
         "Resource": [
           "arn:aws:iot:us-west-2:57EXAMPLE833:topic/test/dc/*"
         ]
       }
   ```

1. Salve o documento de política atualizado como **\$1/policies/pubsub\$1wild\$1test\$1thing\$1policy.json** e saia do editor.

1. Insira o seguinte comando para atualizar a política deste tutorial para usar as novas definições de recursos.

   ```
   aws iot create-policy-version \
   --set-as-default \
   --policy-name "PubSubTestThingPolicy" \
   --policy-document "file://~/policies/pubsub_wild_test_thing_policy.json"
   ```

   Em caso de êxito, ele retornará uma resposta como a seguinte. Observe que `policyVersionId` agora é `2`, o que indica que esta é a segunda versão desta política. 

   Se você obteve êxito em atualizar a política, avance para o próximo procedimento.

   ```
   {
       "policyArn": "arn:aws:iot:us-west-2:57EXAMPLE833:policy/PubSubTestThingPolicy",
       "policyDocument": "{\n  \"Version\": \"2012-10-17\",		 	 	 \n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"iot:Connect\"\n      ],\n      \"Resource\": [\n        \"arn:aws:iot:us-west-2:57EXAMPLE833:client/PubSubTestThing\"\n      ]\n    },\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"iot:Publish\"\n      ],\n      \"Resource\": [\n        \"arn:aws:iot:us-west-2:57EXAMPLE833:topic/test/dc/pubtopic\"\n      ]\n    },\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"iot:Subscribe\"\n      ],\n      \"Resource\": [\n        \"arn:aws:iot:us-west-2:57EXAMPLE833:topicfilter/test/dc/*\"\n      ]\n    },\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"iot:Receive\"\n      ],\n      \"Resource\": [\n        \"arn:aws:iot:us-west-2:57EXAMPLE833:topic/test/dc/*\"\n      ]\n    }\n  ]\n}\n",
       "policyVersionId": "2",
       "isDefaultVersion": true
   }
   ```

   Caso receba um erro informando que há versões da política demais para que uma nova seja salva, insira o seguinte comando para listar as versões atuais da política. Examine a lista retornada pelo comando a seguir para encontrar uma versão da política que possa ser excluída.

   ```
   aws iot list-policy-versions --policy-name "PubSubTestThingPolicy"
   ```

   Digite o comando a seguir para excluir uma versão que não é mais necessária. Não é possível excluir a versão padrão da política. A versão padrão da política é aquela com um valor de `isDefaultVersion` de `true`.

   ```
   aws iot delete-policy-version \
   --policy-name "PubSubTestThingPolicy" \
   --policy-version-id policyId
   ```

   Depois de excluir uma versão da política, tente a etapa novamente.

Com o arquivo de configuração e a política atualizados, você está pronto para demonstrar assinaturas curinga com o AWS IoT Device Client.

**Para demonstrar como o AWS IoT Device Client assina e recebe vários tópicos de mensagens do MQTT**

1. No **cliente de teste MQTT**, verifique as assinaturas. Se o **cliente de teste MQTT** for assinante do filtro de tópicos **\$1**, avance para a próxima etapa. Caso contrário, no **cliente de teste do MQTT**, na guia **Assinar um tópico**, em **Filtro de tópicos**, insira **\$1** (caractere de cerquilha) e escolha **Assinar** para assinar.

1. Na janela do terminal do computador host local conectado ao Raspberry Pi, execute os comandos a seguir para iniciar o AWS IoT Device Client.

   ```
   cd ~/aws-iot-device-client/build
   ./aws-iot-device-client --config-file ~/dc-configs/dc-pubsub-wild-config.json
   ```

1. Enquanto observa a saída do AWS IoT Device Client na janela do terminal no computador host local, retorne ao **cliente de teste MQTT**. Na guia **Publicar em um tópico**, em **Nome do tópico**, insira **test/dc/subtopic** e selecione **Publicar**. 

1. Na janela do terminal, confirme se a mensagem foi recebida procurando uma mensagem como:

   ```
   2021-11-10T16:34:20.101Z [DEBUG] {samples/PubSubFeature.cpp}: Message received on subscribe topic, size: 76 bytes
   ```

1. Enquanto observa a saída do AWS IoT Device Client na janela do terminal do computador host local, retorne ao **cliente de teste MQTT**. Na guia **Publicar em um tópico**, em **Nome do tópico**, insira **test/dc/subtopic2** e selecione **Publicar**. 

1. Na janela do terminal, confirme se a mensagem foi recebida procurando uma mensagem como:

   ```
   2021-11-10T16:34:32.078Z [DEBUG] {samples/PubSubFeature.cpp}: Message received on subscribe topic, size: 77 bytes
   ```

1. Depois de ver as mensagens que confirmam que ambas foram recebidas, digite **^C** (Ctrl-C) para interromper o AWS IoT Device Client.

1. Insira o seguinte comando para visualizar o final do arquivo de log de mensagens e ver a mensagem que foi publicada no **cliente de teste MQTT**.

   ```
   tail -n 20 ~/.aws-iot-device-client/log/pubsub_rx_msgs.log
   ```
**nota**  
O arquivo de log contém somente cargas de mensagens. Os tópicos de mensagens não são registrados no arquivo de log de mensagens recebidas.  
Você também pode ver a mensagem publicada pelo AWS IoT Device Client no registro recebido. Isso ocorre porque o filtro de tópicos curinga inclui esse tópico de mensagem e, por vezes, a solicitação de assinatura pode ser processada pelo agente de mensagens antes que a mensagem publicada seja enviada aos assinantes.

As entradas no arquivo de log apontam que as mensagens foram recebidas. É possível repetir esse procedimento usando outros nomes de tópicos. Todas as mensagens com um nome de tópico que comece com `test/dc/` devem ser recebidas e registradas em log. Mensagens com nomes de tópicos começando com outro texto são ignoradas.

Depois de demonstrar como o AWS IoT Device Client pode publicar e assinar mensagens MQTT, continue. [Tutorial: Demonstre ações remotas (trabalhos) com o AWS IoT Device Client](iot-dc-runjobs.md)

# Tutorial: Demonstre ações remotas (trabalhos) com o AWS IoT Device Client
<a name="iot-dc-runjobs"></a>

Nestes tutoriais, vamos configurar e implantar trabalhos em um Raspberry Pi para demonstrar como você pode enviar operações remotas para dispositivos de IoT.

**Para iniciar este tutorial:**
+ Configure seu computador host local e Raspberry Pi como [na seção anterior](iot-dc-testconn.md). 
+ Se você não concluiu o tutorial na seção anterior, pode tentar este tutorial usando o Raspberry Pi com um cartão microSD que contém a imagem que você salvou depois de instalar AWS IoT o Device Client. [(Opcional) Salve a imagem do cartão microSD](iot-dc-install-download.md#iot-dc-install-dc-save)
+ Se você já executou essa demonstração antes, revise [Etapa 2: Limpar suas demonstrações Conta da AWS após a criação com o AWS IoT Device Client](iot-dc-cleanup.md#iot-dc-cleanup-cloud) para excluir todos os AWS IoT recursos que você criou em execuções anteriores para evitar erros de recursos duplicados.

Este tutorial leva cerca de 45 minutos para ser concluído.

**Quando você concluir este tópico:**
+ Você terá demonstrado diferentes maneiras pelas quais seu dispositivo de IoT pode usar o AWS IoT Core para executar operações remotas gerenciadas por. AWS IoT 

**Equipamentos necessários:**
+ O ambiente local de desenvolvimento e teste já testado em [uma seção anterior](iot-dc-install-dc.md)
+ O Raspberry Pi testado em [uma seção anterior](iot-dc-install-dc.md)
+ O cartão de memória microSD do Raspberry Pi testado em [uma seção anterior](iot-dc-install-dc.md)

**Topics**
+ [Preparar o Raspberry Pi para execução de trabalhos](iot-dc-runjobs-prepare.md)
+ [Crie e execute o trabalho AWS IoT com o AWS IoT Device Client](iot-dc-runjobs-prepare-define.md)

# Preparar o Raspberry Pi para execução de trabalhos
<a name="iot-dc-runjobs-prepare"></a>

Os procedimentos nesta seção descrevem como preparar seu Raspberry Pi para executar trabalhos usando o AWS IoT Device Client.

**nota**  
Estes procedimentos são específicos ao dispositivo. Caso queira realizar os procedimentos desta seção com mais de um dispositivo simultaneamente, cada dispositivo precisará de sua própria política e de um certificado e um nome de item exclusivos e específicos ao dispositivo. Para que cada dispositivo tenha seus recursos exclusivos, execute o procedimento uma vez para cada dispositivo enquanto modifica os elementos específicos do dispositivo, como descrito nos procedimentos.

**Topics**
+ [Provisione seu Raspberry Pi para demonstrar trabalhos](#iot-dc-runjobs-prepare-provision)
+ [Configurar o AWS IoT Device Client para executar o agente de trabalhos](#iot-dc-runjobs-prepare-config)

## Provisione seu Raspberry Pi para demonstrar trabalhos
<a name="iot-dc-runjobs-prepare-provision"></a>

Os procedimentos nesta seção provisionam seu Raspberry Pi AWS IoT criando AWS IoT recursos e certificados de dispositivo para ele. 

**Topics**
+ [Crie e baixe arquivos de certificado de dispositivo para demonstrar AWS IoT trabalhos](#iot-dc-runjobs-prepare-cert)
+ [Crie AWS IoT recursos para demonstrar AWS IoT empregos](#iot-dc-runjobs-prepare-iot)

### Crie e baixe arquivos de certificado de dispositivo para demonstrar AWS IoT trabalhos
<a name="iot-dc-runjobs-prepare-cert"></a>

Este procedimento cria os arquivos de certificado de dispositivo para esta demonstração.

Se você estiver preparando mais de um dispositivo, esse procedimento deve ser executado em cada dispositivo.

**Para criar e baixar os arquivos de certificado de dispositivo para o Raspberry Pi:**

Na janela do terminal do computador host local conectado ao Raspberry Pi, digite os comandos a seguir.

1. Digite o comando a seguir para criar os arquivos de certificado de dispositivo.

   ```
   aws iot create-keys-and-certificate \
   --set-as-active \
   --certificate-pem-outfile "~/certs/jobs/device.pem.crt" \
   --public-key-outfile "~/certs/jobs/public.pem.key" \
   --private-key-outfile "~/certs/jobs/private.pem.key"
   ```

   O comando retorna uma resposta como a seguinte. Salve o valor de `certificateArn` para uso posterior.

   ```
   {
   "certificateArn": "arn:aws:iot:us-west-2:57EXAMPLE833:cert/76e7e4edb3e52f52334be2f387a06145b2aa4c7fcd810f3aea2d92abc227d269",
   "certificateId": "76e7e4edb3e52f5233EXAMPLE7a06145b2aa4c7fcd810f3aea2d92abc227d269",
   "certificatePem": "-----BEGIN CERTIFICATE-----\nMIIDWTCCAkGgAwIBAgI_SHORTENED_FOR_EXAMPLE_Lgn4jfgtS\n-----END CERTIFICATE-----\n",
   "keyPair": {
       "PublicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BA_SHORTENED_FOR_EXAMPLE_ImwIDAQAB\n-----END PUBLIC KEY-----\n",
       "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQE_SHORTENED_FOR_EXAMPLE_T9RoDiukY\n-----END RSA PRIVATE KEY-----\n"
   }
   }
   ```

1. Insira os comandos a seguir para definir as permissões no diretório de certificados e arquivos.

   ```
   chmod 700 ~/certs/jobs
   chmod 644 ~/certs/jobs/*
   chmod 600 ~/certs/jobs/private.pem.key
   ```

1. Execute este comando para examinar as permissões nos diretórios e arquivos do certificado.

   ```
   ls -l ~/certs/jobs
   ```

   A saída do comando deve ser a mesma vista aqui, com exceção das datas e horários do arquivo, que serão diferentes.

   ```
   -rw-r--r-- 1 pi pi 1220 Oct 28 13:02 device.pem.crt
   -rw------- 1 pi pi 1675 Oct 28 13:02 private.pem.key
   -rw-r--r-- 1 pi pi  451 Oct 28 13:02 public.pem.key
   ```

Após baixar os arquivos de certificado de dispositivo para o Raspberry Pi, você estará pronto para avançar para [Provisione seu Raspberry Pi para demonstrar trabalhos](#iot-dc-runjobs-prepare-provision).

### Crie AWS IoT recursos para demonstrar AWS IoT empregos
<a name="iot-dc-runjobs-prepare-iot"></a>

Crie os AWS IoT recursos para esse dispositivo.

Se você estiver preparando mais de um dispositivo, esse procedimento deve ser executado para todos os dispositivos.



**Para provisionar seu dispositivo no AWS IoT:**

Na janela do terminal do computador host local conectado ao Raspberry Pi:

1. Digite o seguinte comando para obter o endereço do endpoint de dados do dispositivo da sua Conta da AWS.

   ```
   aws iot describe-endpoint --endpoint-type IoT:Data-ATS
   ```

   O valor do endpoint não foi alterado desde a última vez que este comando foi executado. Executar o comando mais uma vez facilita localizar e colar o valor do endpoint de dados no arquivo de configuração usado neste tutorial.

   O comando **describe-endpoint** retorna uma resposta como a seguinte. Registre o valor de `endpointAddress` para uso posterior.

   ```
   {
   "endpointAddress": "a3qjEXAMPLEffp-ats.iot.us-west-2.amazonaws.com"
   }
   ```

1. *uniqueThingName*Substitua por um nome exclusivo para seu dispositivo. Caso queira realizar este tutorial com vários dispositivos, dê um nome único a cada dispositivo. Como, por exemplo, **TestDevice01**, **TestDevice02**, e assim por diante.

   Digite este comando para criar um novo recurso para AWS IoT o seu Raspberry Pi.

   ```
   aws iot create-thing --thing-name "uniqueThingName"
   ```

   Como um recurso de AWS IoT coisas é uma representação *virtual* do seu dispositivo na nuvem, podemos criar vários recursos de coisas AWS IoT para serem usados para finalidades diferentes. Todos os recursos de objetos podem ser usados pelo mesmo dispositivo físico de IoT para representar aspectos diferentes do dispositivo.
**nota**  
Para proteger a política para vários dispositivos, você pode usar `${iot:Thing.ThingName}` em vez do nome do objeto estática, `uniqueThingName`.

   Estes tutoriais usarão apenas um recurso de objeto por vez por dispositivo. Dessa forma, nesses tutoriais, eles representam as diferentes demonstrações para que, depois de criar os AWS IoT recursos para uma demonstração, você possa voltar e repetir as demonstrações usando os recursos criados especificamente para cada uma.

   Se seu recurso AWS IoT Thing foi criado, o comando retornará uma resposta como essa. Registre o valor de `thingArn` para uso posterior quando for criar o trabalho a ser executado nesse dispositivo.

   ```
   {
   "thingName": "uniqueThingName",
   "thingArn": "arn:aws:iot:us-west-2:57EXAMPLE833:thing/uniqueThingName",
   "thingId": "8ea78707-32c3-4f8a-9232-14bEXAMPLEfd"
   }
   ```

1. Na janela do terminal:

   1. Abra um editor de texto, como o `nano`.

   1. Copie este documento JSON e cole-o no editor de texto aberto.  
****  

      ```
      {
          "Version":"2012-10-17",		 	 	 
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "iot:Connect"
                  ],
                  "Resource": [
                      "arn:aws:iot:us-west-2:123456789012:client/uniqueThingName"
                  ]
              },
              {
                  "Effect": "Allow",
                  "Action": [
                      "iot:Publish"
                  ],
                  "Resource": [
                      "arn:aws:iot:us-west-2:123456789012:topic/test/dc/pubtopic",
                      "arn:aws:iot:us-west-2:123456789012:topic/$aws/events/job/*",
                      "arn:aws:iot:us-west-2:123456789012:topic/$aws/events/jobExecution/*",
                      "arn:aws:iot:us-west-2:123456789012:topic/$aws/things/uniqueThingName/jobs/*"
                  ]
              },
              {
                  "Effect": "Allow",
                  "Action": [
                      "iot:Subscribe"
                  ],
                  "Resource": [
                      "arn:aws:iot:us-west-2:123456789012:topicfilter/test/dc/subtopic",
                      "arn:aws:iot:us-west-2:123456789012:topic/$aws/events/jobExecution/*",
                      "arn:aws:iot:us-west-2:123456789012:topicfilter/$aws/things/uniqueThingName/jobs/*"
                  ]
              },
              {
                  "Effect": "Allow",
                  "Action": [
                      "iot:Receive"
                  ],
                  "Resource": [
                      "arn:aws:iot:us-west-2:123456789012:topic/test/dc/subtopic",
                      "arn:aws:iot:us-west-2:123456789012:topic/$aws/things/uniqueThingName/jobs/*"
                  ]
              },
              {
                  "Effect": "Allow",
                  "Action": [
                      "iot:DescribeJobExecution",
                      "iot:GetPendingJobExecutions",
                      "iot:StartNextPendingJobExecution",
                      "iot:UpdateJobExecution"
                  ],
                  "Resource": [
                      "arn:aws:iot:us-west-2:123456789012:topic/$aws/things/uniqueThingName"
                  ]
              }
          ]
      }
      ```

   1. No editor, na `Resource` seção de cada declaração de política, *us-west-2:57EXAMPLE833* substitua por seu Região da AWS, um caractere de dois pontos (:)) e seu número de 12 dígitos Conta da AWS .

   1. No editor, em cada declaração de política, *uniqueThingName* substitua pelo nome da coisa que você deu ao recurso.

   1. Salve o arquivo no editor de texto como **\$1/policies/jobs\$1test\$1thing\$1policy.json**.

      Caso esteja executando esse procedimento para diversos dispositivos, salve o arquivo com esse nome de arquivo em cada dispositivo.

1. *uniqueThingName*Substitua pelo nome do dispositivo e, em seguida, execute esse comando para criar uma AWS IoT política personalizada para esse dispositivo.

   ```
   aws iot create-policy \
   --policy-name "JobTestPolicyForuniqueThingName" \
   --policy-document "file://~/policies/jobs_test_thing_policy.json"
   ```

   Se a política for criada, o comando retornará uma resposta como esta.  
****  

   ```
   {
       "policyName": "JobTestPolicyForuniqueThingName",
       "policyArn": "arn:aws:iot:us-west-2:57EXAMPLE833:policy/JobTestPolicyForuniqueThingName",
       "policyDocument": "{\n\"Version\": \"2012-10-17\",\n\"Statement\": [\n{\n\"Effect\": \"Allow\",\n\"Action\": [\n\"iot:Connect\"\n],\n\"Resource\": [\n\"arn:aws:iot:us-west-2:57EXAMPLE833:client/PubSubTestThing\"\n]\n},\n{\n\"Effect\": \"Allow\",\n\"Action\": [\n\"iot:Publish\"\n],\n\"Resource\": [\n\"arn:aws:iot:us-west-2:57EXAMPLE833:topic/test/dc/pubtopic\"\n]\n},\n{\n\"Effect\": \"Allow\",\n\"Action\": [\n\"iot:Subscribe\"\n],\n\"Resource\": [\n\"arn:aws:iot:us-west-2:57EXAMPLE833:topicfilter/test/dc/subtopic\"\n]\n},\n{\n\"Effect\": \"Allow\",\n\"Action\": [\n\"iot:Receive\"\n],\n\"Resource\": [\n\"arn:aws:iot:us-west-2:57EXAMPLE833:topic/test/dc/*\"\n]\n}\n]\n}\n",
       "policyVersionId": "1"
   }
   ```

1. *uniqueThingName*Substitua pelo nome do dispositivo e `certificateArn` pelo `certificateArn` valor que você salvou anteriormente nesta seção para esse dispositivo e, em seguida, execute esse comando para anexar a política ao certificado do dispositivo. 

   ```
   aws iot attach-policy \
   --policy-name "JobTestPolicyForuniqueThingName" \
   --target "certificateArn"
   ```

   Se houver êxito, o comando não retornará nada.

1.  *uniqueThingName*Substitua pelo nome da coisa do dispositivo, `certificateArn` substitua pelo `certificateArn` valor que você salvou anteriormente nesta seção e, em seguida, execute esse comando para anexar o certificado do dispositivo ao recurso da AWS IoT coisa.

   ```
   aws iot attach-thing-principal \
   --thing-name "uniqueThingName" \
   --principal "certificateArn"
   ```

   Se houver êxito, o comando não retornará nada.

Após provisionar o Raspberry Pi com êxito, você estará pronto para repetir esta seção com outro Raspberry Pi em um teste ou, se todos os dispositivos tiverem sido provisionados, avançar para [Configurar o AWS IoT Device Client para executar o agente de trabalhos](#iot-dc-runjobs-prepare-config).

## Configurar o AWS IoT Device Client para executar o agente de trabalhos
<a name="iot-dc-runjobs-prepare-config"></a>

Este procedimento cria um arquivo de configuração para o AWS IoT Device Client executar o agente de trabalhos:.

Nota: se você estiver preparando mais de um dispositivo, esse procedimento deve ser executado em cada dispositivo.

**Para criar o arquivo de configuração para testar o AWS IoT Device Client:**

1. Na janela do terminal do computador host local conectado ao Raspberry Pi:

   1. Abra um editor de texto, como o `nano`.

   1. Copie este documento JSON e cole-o no editor de texto aberto.

      ```
      {
        "endpoint": "a3qEXAMPLEaffp-ats.iot.us-west-2.amazonaws.com",
        "cert": "~/certs/jobs/device.pem.crt",
        "key": "~/certs/jobs/private.pem.key",
        "root-ca": "~/certs/AmazonRootCA1.pem",
        "thing-name": "uniqueThingName",
        "logging": {
          "enable-sdk-logging": true,
          "level": "DEBUG",
          "type": "STDOUT",
          "file": ""
        },
        "jobs": {
          "enabled": true,
          "handler-directory": ""
        },
        "tunneling": {
          "enabled": false
        },
        "device-defender": {
          "enabled": false,
          "interval": 300
        },
        "fleet-provisioning": {
          "enabled": false,
          "template-name": "",
          "template-parameters": "",
          "csr-file": "",
          "device-key": ""
        },
        "samples": {
          "pub-sub": {
            "enabled": false,
            "publish-topic": "",
            "publish-file": "",
            "subscribe-topic": "",
            "subscribe-file": ""
          }
        },
        "config-shadow": {
          "enabled": false
        },
        "sample-shadow": {
          "enabled": false,
          "shadow-name": "",
          "shadow-input-file": "",
          "shadow-output-file": ""
        }
      }
      ```

   1. Substitua o *endpoint* valor pelo valor do endpoint de dados do dispositivo Conta da AWS que você encontrou em[Provisione seu dispositivo em AWS IoT Core](iot-dc-install-provision.md#iot-dc-install-dc-provision).

   1. *uniqueThingName*Substitua pelo nome da coisa que você usou para este dispositivo.

   1. Salve o arquivo no editor de texto como **\$1/dc-configs/dc-jobs-config.json**.

1. Execute o comando a seguir para definir as permissões de arquivo do novo arquivo de configuração.

   ```
   chmod 644 ~/dc-configs/dc-jobs-config.json
   ```

O **cliente de teste MQTT** não será utilizado neste teste. Embora o dispositivo troque mensagens MQTT relacionadas aos trabalhos AWS IoT, as mensagens de progresso do trabalho são trocadas somente com o dispositivo que está executando o trabalho. Como as mensagens de progresso do trabalho são trocadas somente com o dispositivo que está executando o trabalho, você não pode assiná-las de outro dispositivo, como o AWS IoT console.

Após salvar o arquivo de configuração, você estará pronto para avançar para [Crie e execute o trabalho AWS IoT com o AWS IoT Device Client](iot-dc-runjobs-prepare-define.md).

# Crie e execute o trabalho AWS IoT com o AWS IoT Device Client
<a name="iot-dc-runjobs-prepare-define"></a>

Os procedimentos desta seção criam um documento de trabalho e um recurso de AWS IoT trabalho. Depois de criar o recurso de trabalho, AWS IoT envia o documento de trabalho para os destinos de trabalho especificados nos quais um agente de trabalhos aplica o documento de trabalho ao dispositivo ou cliente.

**Topics**
+ [Criar e armazenar o documento de trabalho para o trabalho de IoT](#iot-dc-runjobs-prepare-define-jobdoc)
+ [Execute um trabalho em AWS IoT um dispositivo de IoT](#iot-dc-runjobs-prepare-define-job)

## Criar e armazenar o documento de trabalho para o trabalho de IoT
<a name="iot-dc-runjobs-prepare-define-jobdoc"></a>

Esse procedimento cria um documento de trabalho simples para incluir em um recurso de AWS IoT trabalho. O documento de trabalho mostra “Olá, mundo” no destino do trabalho.

**Para criar e armazenar um documento de trabalho:**

1. Selecione o bucket do Amazon S3 no qual você salvará seu documento de trabalho. Se você ainda não tiver um bucket do Amazon S3 existente para isso, será preciso criar um. Para obter informações sobre a criação de buckets do Amazon S3, consulte os tópicos de [Introdução ao Amazon S3](https://docs.aws.amazon.com//AmazonS3/latest/userguide/GetStartedWithS3.html).

1. Crie e salve o documento de trabalho deste trabalho

   1. Abra um editor de texto no computador host local.

   1. Copie e cole o texto a seguir no editor.

      ```
      {
          "operation": "echo",
          "args": ["Hello world!"]
      }
      ```

   1. No computador host local, salve o conteúdo do editor em um arquivo nomeado **hello-world-job.json**.

   1. Confirme se o arquivo foi salvo com êxito. Alguns editores de texto acrescentam automaticamente `.txt` ao final do nome de um arquivo ao salvar um arquivo de texto. Se o editor tiver acrescentado `.txt` ao nome do arquivo, faça a correção antes de continuar.

1. *path\$1to\$1file*Substitua o pelo caminho para**hello-world-job.json**, se não estiver em seu diretório atual, *s3\$1bucket\$1name* substitua pelo caminho do bucket do Amazon S3 até o bucket selecionado e, em seguida, execute esse comando para colocar seu documento de trabalho no bucket do Amazon S3.

   ```
   aws s3api put-object \
   --key hello-world-job.json \
   --body path_to_file/hello-world-job.json --bucket s3_bucket_name
   ```

   A URL do documento de trabalho que identifica o documento de trabalho que você armazenou no Amazon S3 é determinada pela substituição de *AWS\$1region* e na URL *s3\$1bucket\$1name* a seguir. Registre o URL resultante para usar posteriormente como *job\$1document\$1path*

   ```
   https://s3_bucket_name.s3.AWS_Region.amazonaws.com/hello-world-job.json
   ```
**nota**  
AWS a segurança impede que você possa abrir esse URL fora do seu Conta da AWS, por exemplo, usando um navegador. O URL é usado pelo mecanismo de AWS IoT trabalhos, que tem acesso ao arquivo, por padrão. Em um ambiente de produção, será preciso garantir que seus serviços do AWS IoT tenham permissão para acessar os documentos de trabalho armazenados no Amazon S3.

Após salvar o URL do documento de trabalho, avance para [Execute um trabalho em AWS IoT um dispositivo de IoT](#iot-dc-runjobs-prepare-define-job).

## Execute um trabalho em AWS IoT um dispositivo de IoT
<a name="iot-dc-runjobs-prepare-define-job"></a>

Os procedimentos nesta seção iniciam o AWS IoT Device Client em seu Raspberry Pi para executar o agente de trabalhos no dispositivo e aguardar a execução dos trabalhos. Ele também cria um recurso de trabalho em AWS IoT, que enviará o trabalho e será executado em seu dispositivo de IoT.

**nota**  
Esse procedimento executa um trabalho em apenas um único dispositivo.

**Para iniciar o atendente de trabalhos no Raspberry Pi:**

1. Na janela do terminal do seu computador host local que está conectado ao seu Raspberry Pi, execute este comando para iniciar o AWS IoT Device Client.

   ```
   cd ~/aws-iot-device-client/build
   ./aws-iot-device-client --config-file ~/dc-configs/dc-jobs-config.json
   ```

1. Na janela do terminal, confirme se o AWS IoT Device Client exibe essas mensagens

   ```
   2021-11-15T18:45:56.708Z [INFO]  {Main.cpp}: Jobs is enabled
                         .
                         .
                         .
   2021-11-15T18:45:56.708Z [INFO]  {Main.cpp}: Client base has been notified that Jobs has started
   2021-11-15T18:45:56.708Z [INFO]  {JobsFeature.cpp}: Running Jobs!
   2021-11-15T18:45:56.708Z [DEBUG] {JobsFeature.cpp}: Attempting to subscribe to startNextPendingJobExecution accepted and rejected
   2021-11-15T18:45:56.708Z [DEBUG] {JobsFeature.cpp}: Attempting to subscribe to nextJobChanged events
   2021-11-15T18:45:56.708Z [DEBUG] {JobsFeature.cpp}: Attempting to subscribe to updateJobExecutionStatusAccepted for jobId +
   2021-11-15T18:45:56.738Z [DEBUG] {JobsFeature.cpp}: Ack received for SubscribeToUpdateJobExecutionAccepted with code {0}
   2021-11-15T18:45:56.739Z [DEBUG] {JobsFeature.cpp}: Attempting to subscribe to updateJobExecutionStatusRejected for jobId +
   2021-11-15T18:45:56.753Z [DEBUG] {JobsFeature.cpp}: Ack received for SubscribeToNextJobChanged with code {0}
   2021-11-15T18:45:56.760Z [DEBUG] {JobsFeature.cpp}: Ack received for SubscribeToStartNextJobRejected with code {0}
   2021-11-15T18:45:56.776Z [DEBUG] {JobsFeature.cpp}: Ack received for SubscribeToStartNextJobAccepted with code {0}
   2021-11-15T18:45:56.776Z [DEBUG] {JobsFeature.cpp}: Ack received for SubscribeToUpdateJobExecutionRejected with code {0}
   2021-11-15T18:45:56.777Z [DEBUG] {JobsFeature.cpp}: Publishing startNextPendingJobExecutionRequest
   2021-11-15T18:45:56.785Z [DEBUG] {JobsFeature.cpp}: Ack received for StartNextPendingJobPub with code {0}
   2021-11-15T18:45:56.785Z [INFO]  {JobsFeature.cpp}: No pending jobs are scheduled, waiting for the next incoming job
   ```

1. Na janela do terminal, depois de ver a seguinte mensagem, avance para o próximo procedimento e crie o recurso de trabalho. Observe que esta pode não ser a última entrada da lista.

   ```
   2021-11-15T18:45:56.785Z [INFO]  {JobsFeature.cpp}: No pending jobs are scheduled, waiting for the next incoming job
   ```

**Para criar um recurso AWS IoT de trabalho**

1. No computador host local:

   1. *job\$1document\$1url*Substitua pelo URL do documento de trabalho de[Criar e armazenar o documento de trabalho para o trabalho de IoT](#iot-dc-runjobs-prepare-define-jobdoc).

   1. *thing\$1arn*Substitua pelo ARN do recurso que você criou para o seu dispositivo e execute esse comando.

      ```
      aws iot create-job \
      --job-id hello-world-job-1 \
      --document-source "job_document_url" \
      --targets "thing_arn" \
      --target-selection SNAPSHOT
      ```

      Em caso de êxito, o comando retornará um resultado semelhante a este.

      ```
      {
        "jobArn": "arn:aws:iot:us-west-2:57EXAMPLE833:job/hello-world-job-1",
        "jobId": "hello-world-job-1"
      }
      ```

1. Na janela do terminal, você deve ver uma saída do AWS IoT Device Client como esta.

   ```
   2021-11-15T18:02:26.688Z [INFO]  {JobsFeature.cpp}: No pending jobs are scheduled, waiting for the next incoming job
   2021-11-15T18:10:24.890Z [DEBUG] {JobsFeature.cpp}: Job ids differ
   2021-11-15T18:10:24.890Z [INFO]  {JobsFeature.cpp}: Executing job: hello-world-job-1
   2021-11-15T18:10:24.890Z [DEBUG] {JobsFeature.cpp}: Attempting to update job execution status!
   2021-11-15T18:10:24.890Z [DEBUG] {JobsFeature.cpp}: Not including stdout with the status details
   2021-11-15T18:10:24.890Z [DEBUG] {JobsFeature.cpp}: Not including stderr with the status details
   2021-11-15T18:10:24.890Z [DEBUG] {JobsFeature.cpp}: Assuming executable is in PATH
   2021-11-15T18:10:24.890Z [INFO]  {JobsFeature.cpp}: About to execute: echo Hello world!
   2021-11-15T18:10:24.890Z [DEBUG] {Retry.cpp}: Retryable function starting, it will retry until success
   2021-11-15T18:10:24.890Z [DEBUG] {JobsFeature.cpp}: Created EphermalPromise for ClientToken 3TEWba9Xj6 in the updateJobExecution promises map
   2021-11-15T18:10:24.890Z [DEBUG] {JobEngine.cpp}: Child process now running
   2021-11-15T18:10:24.890Z [DEBUG] {JobEngine.cpp}: Child process about to call execvp
   2021-11-15T18:10:24.890Z [DEBUG] {JobEngine.cpp}: Parent process now running, child PID is 16737
   2021-11-15T18:10:24.891Z [DEBUG] {16737}: Hello world!
   2021-11-15T18:10:24.891Z [DEBUG] {JobEngine.cpp}: JobEngine finished waiting for child process, returning 0
   2021-11-15T18:10:24.891Z [INFO]  {JobsFeature.cpp}: Job exited with status: 0
   2021-11-15T18:10:24.891Z [INFO]  {JobsFeature.cpp}: Job executed successfully!
   2021-11-15T18:10:24.891Z [DEBUG] {JobsFeature.cpp}: Attempting to update job execution status!
   2021-11-15T18:10:24.891Z [DEBUG] {JobsFeature.cpp}: Not including stdout with the status details
   2021-11-15T18:10:24.891Z [DEBUG] {JobsFeature.cpp}: Not including stderr with the status details
   2021-11-15T18:10:24.892Z [DEBUG] {Retry.cpp}: Retryable function starting, it will retry until success
   2021-11-15T18:10:24.892Z [DEBUG] {JobsFeature.cpp}: Created EphermalPromise for ClientToken GmQ0HTzWGg in the updateJobExecution promises map
   2021-11-15T18:10:24.905Z [DEBUG] {JobsFeature.cpp}: Ack received for PublishUpdateJobExecutionStatus with code {0}
   2021-11-15T18:10:24.905Z [DEBUG] {JobsFeature.cpp}: Removing ClientToken 3TEWba9Xj6 from the updateJobExecution promises map
   2021-11-15T18:10:24.905Z [DEBUG] {JobsFeature.cpp}: Success response after UpdateJobExecution for job hello-world-job-1
   2021-11-15T18:10:24.917Z [DEBUG] {JobsFeature.cpp}: Ack received for PublishUpdateJobExecutionStatus with code {0}
   2021-11-15T18:10:24.918Z [DEBUG] {JobsFeature.cpp}: Removing ClientToken GmQ0HTzWGg from the updateJobExecution promises map
   2021-11-15T18:10:24.918Z [DEBUG] {JobsFeature.cpp}: Success response after UpdateJobExecution for job hello-world-job-1
   2021-11-15T18:10:25.861Z [INFO]  {JobsFeature.cpp}: No pending jobs are scheduled, waiting for the next incoming job
   ```

1. Enquanto o AWS IoT Device Client estiver em execução e aguardando um trabalho, você pode enviar outro trabalho alterando o `job-id` valor e reexecutando o **create-job** da Etapa 1.

Quando terminar de executar os trabalhos, na janela do terminal, digite ^C (Control-c) para interromper o AWS IoT Device Client.

# Tutorial: Limpando depois de executar os tutoriais do AWS IoT Device Client
<a name="iot-dc-cleanup"></a>

Os procedimentos deste tutorial orientam você na remoção dos arquivos e recursos que você criou ao concluir os tutoriais neste percurso de aprendizado.

**Topics**
+ [Etapa 1: Limpar seus dispositivos após criar demonstrações com o AWS IoT Device Client](#iot-dc-cleanup-devices)
+ [Etapa 2: Limpar suas demonstrações Conta da AWS após a criação com o AWS IoT Device Client](#iot-dc-cleanup-cloud)

## Etapa 1: Limpar seus dispositivos após criar demonstrações com o AWS IoT Device Client
<a name="iot-dc-cleanup-devices"></a>

Este tutorial descreve duas opções de como limpar o cartão microSD depois de criar as demonstrações neste percurso de aprendizado. Escolha a opção que fornece o nível de segurança de que você precisa.

Observe que a limpeza do cartão microSD do dispositivo não remove nenhum AWS IoT recurso que você criou. Para limpar os AWS IoT recursos depois de limpar o cartão microSD do dispositivo, você deve revisar o tutorial em. [Etapa 2: Limpar suas demonstrações Conta da AWS após a criação com o AWS IoT Device Client](#iot-dc-cleanup-cloud)

### Opção 1: como limpar regravando o cartão microSD
<a name="iot-dc-cleanup-devices-flash"></a>

A maneira mais fácil e completa de limpar o cartão microSD depois de concluir os tutoriais neste percurso de aprendizado é substituir o cartão microSD por um arquivo de imagem salvo que você criou ao preparar o dispositivo pela primeira vez.

Esse procedimento usa o computador host local para gravar uma imagem salva do cartão microSD em um cartão microSD.

**nota**  
Se o dispositivo não usa uma mídia de armazenamento removível para o sistema operacional, consulte o procedimento desse dispositivo.

**Para gravar uma nova imagem no cartão microSD**

1. No computador host local, localize a imagem salva do cartão microSD que você deseja gravar no cartão microSD. 

1. Insira o cartão microSD no computador host local.

1. Usando uma ferramenta de imagem de cartão SD, grave o arquivo de imagem selecionado no cartão microSD.

1. Depois de gravar a imagem do sistema operacional Raspberry Pi no cartão microSD, ejete o cartão microSD e remova-o com segurança do computador host local.

O cartão microSD está pronto para ser usado.

### Opção 2: como limpar excluindo diretórios de usuários
<a name="iot-dc-cleanup-devices-dirs"></a>

Para limpar o cartão microSD depois de concluir os tutoriais sem regravar a imagem do cartão microSD, você pode excluir os diretórios do usuário individualmente. Isso não é tão completo quanto regravar o cartão microSD por meio de uma imagem salva, pois não remove nenhum arquivo do sistema que possa ter sido instalado.

Se a remoção dos diretórios do usuário for suficientemente completa para suas necessidades, siga este procedimento.

**Para excluir os diretórios de usuário desse percurso de aprendizado do dispositivo**

1. Execute esses comandos para excluir os diretórios, subdiretórios e todos os arquivos que foram criados nesse percurso de aprendizado, na janela do terminal conectada ao dispositivo.
**nota**  
Depois de excluir esses diretórios e arquivos, você não poderá executar as demonstrações sem concluir os tutoriais novamente.

   ```
   rm -Rf ~/dc-configs
   rm -Rf ~/policies
   rm -Rf ~/messages
   rm -Rf ~/certs
   rm -Rf ~/.aws-iot-device-client
   ```

1. Execute esses comandos para excluir os diretórios e arquivos de origem da aplicação na janela do terminal conectada ao dispositivo.
**nota**  
Esses comandos não desinstalam nenhum programa. Eles removem apenas os arquivos de origem usados para criá-los e instalá-los. Depois de excluir esses arquivos, o AWS CLI e o AWS IoT Device Client podem não funcionar.

   ```
   rm -Rf ~/aws-cli
   rm -Rf ~/aws
   rm -Rf ~/aws-iot-device-client
   ```

## Etapa 2: Limpar suas demonstrações Conta da AWS após a criação com o AWS IoT Device Client
<a name="iot-dc-cleanup-cloud"></a>

Esses procedimentos ajudam você a identificar e remover os AWS recursos que você criou ao concluir os tutoriais neste plano de aprendizado.

### Limpe AWS IoT os recursos
<a name="iot-dc-cleanup-cloud-iot"></a>

Esse procedimento ajuda você a identificar e remover os AWS IoT recursos que você criou ao concluir os tutoriais neste plano de aprendizado.


**AWS IoT recursos criados neste plano de aprendizado**  

| Tutorial | Recurso de objetos | Recurso de políticas | 
| --- | --- | --- | 
|  [Tutorial: Instalando e configurando o AWS IoT Device Client](iot-dc-install-dc.md)  |  **DevCliTestThing**  | DevCliTestThingPolicy | 
|  [Tutorial: Demonstre a comunicação de mensagens MQTT com o AWS IoT Device Client](iot-dc-testconn.md)  |  **PubSubTestThing**  | PubSubTestThingPolicy | 
|  [Tutorial: Demonstre ações remotas (trabalhos) com o AWS IoT Device Client](iot-dc-runjobs.md)  | definido pelo usuário (pode haver mais de um) |  *definido pelo usuário* (pode haver mais de um)  | 

**Para excluir os AWS IoT recursos, siga este procedimento para cada recurso que você criou**

1. Substitua `thing_name` pelo nome do recurso do objeto que você deseja excluir e, em seguida, execute esse comando para listar os certificados anexados ao recurso do objeto por meio do computador host local.

   ```
   aws iot list-thing-principals --thing-name thing_name
   ```

   Esse comando retorna uma resposta como essa, que lista os certificados anexados a `thing_name`. Na maioria dos casos, haverá apenas um certificado na lista.

   ```
   {
       "principals": [
           "arn:aws:iot:us-west-2:57EXAMPLE833:cert/23853eea3cf0edc7f8a69c74abeafa27b2b52823cab5b3e156295e94b26ae8ac"
       ]
   }
   ```

1. Para cada certificado listado pelo comando anterior:

   1. Substitua `certificate_ID` pelo ID de certificado do comando anterior. O ID do certificado são os caracteres alfanuméricos que seguem `cert/` no ARN retornado pelo comando anterior. Em seguida, execute esse comando para inativar o certificado.

      ```
      aws iot update-certificate --new-status INACTIVE --certificate-id certificate_ID
      ```

      Se houver êxito, esse comando não retornará nada.

   1. Substitua `certificate_ARN` pelo ARN do certificado da lista de certificados retornados anteriormente e, em seguida, execute esse comando para listar as políticas anexadas a esse certificado.

      ```
      aws iot list-attached-policies --target certificate_ARN
      ```

      Esse comando retorna uma resposta como essa, que lista as políticas anexadas ao certificado. Na maioria dos casos, haverá apenas uma política na lista.

      ```
      {
          "policies": [
              {
                  "policyName": "DevCliTestThingPolicy",
                  "policyArn": "arn:aws:iot:us-west-2:57EXAMPLE833:policy/DevCliTestThingPolicy"
              }
          ]
      }
      ```

   1. Para cada política anexada ao certificado:

      1. Substitua `policy_name` pelo valor `policyName` do comando anterior, substitua `certificate_ARN` pelo ARN do certificado e execute esse comando para separar a política do certificado.

         ```
         aws iot detach-policy --policy-name policy_name --target certificate_ARN
         ```

         Se houver êxito, esse comando não retornará nada.

      1. Substitua `policy_name` pelo valor `policyName` e, em seguida, execute esse comando para ver se a política está anexada a mais certificados.

         ```
         aws iot list-targets-for-policy --policy-name policy_name
         ```

         Se o comando retornar uma lista vazia como essa, a política não será anexada a nenhum certificado, e você continuará listando as versões da política. Se ainda houver certificados anexados à política, continue com a etapa **detach-thing-principal**.

         ```
         {
             "targets": []
         }
         ```

      1. Substitua `policy_name` pelo valor `policyName` e, em seguida, execute esse comando para verificar as versões da política. Para excluir a política, ela deve ter somente uma versão.

         ```
         aws iot list-policy-versions --policy-name policy_name
         ```

         Se a política tiver apenas uma versão, como neste exemplo, você poderá pular para a etapa **delete-policy** e excluir a política agora.

         ```
         {
             "policyVersions": [
                 {
                     "versionId": "1",
                     "isDefaultVersion": true,
                     "createDate": "2021-11-18T01:02:46.778000+00:00"
                 }
             ]
         }
         ```

         Se a política tiver mais de uma versão, como neste exemplo, as versões da política com um valor `isDefaultVersion` de `false` devem ser excluídas antes que a política possa ser excluída.

         ```
         {
             "policyVersions": [
                 {
                     "versionId": "2",
                     "isDefaultVersion": true,
                     "createDate": "2021-11-18T01:52:04.423000+00:00"
                 },
                 {
                     "versionId": "1",
                     "isDefaultVersion": false,
                     "createDate": "2021-11-18T01:30:18.083000+00:00"
                 }
             ]
         }
         ```

         Se você precisar excluir uma versão da política, substitua `policy_name` pelo valor `policyName`, substitua `version_ID` pelo valor `versionId` do comando anterior e execute esse comando para excluir uma versão da política.

         ```
         aws iot delete-policy-version --policy-name policy_name --policy-version-id version_ID
         ```

         Se houver êxito, esse comando não retornará nada.

         Depois de excluir uma versão da política, repita essa etapa até que a política tenha somente uma versão da política.

      1. Substitua `policy_name` pelo valor `policyName` e, em seguida, execute esse comando para excluir a política.

         ```
         aws iot delete-policy --policy-name policy_name
         ```

   1. Substitua `thing_name` pelo nome do objeto, substitua `certificate_ARN` pelo ARN do certificado e, em seguida, execute esse comando para separar o certificado do recurso do objeto.

      ```
      aws iot detach-thing-principal --thing-name thing_name --principal certificate_ARN
      ```

      Se houver êxito, esse comando não retornará nada.

   1. Substitua `certificate_ID` pelo ID de certificado do comando anterior. O ID do certificado são os caracteres alfanuméricos que seguem `cert/` no ARN retornado pelo comando anterior. Em seguida, execute esse comando para excluir o recurso do certificado.

      ```
      aws iot delete-certificate --certificate-id certificate_ID
      ```

      Se houver êxito, esse comando não retornará nada.

1. Substitua `thing_name` pelo nome do objeto e, em seguida, execute esse comando para excluir o objeto.

   ```
   aws iot delete-thing --thing-name thing_name
   ```

   Se houver êxito, esse comando não retornará nada. 

### Limpe AWS os recursos
<a name="iot-dc-cleanup-cloud-aws"></a>

Esse procedimento ajuda você a identificar e remover outros AWS recursos que você criou ao concluir os tutoriais neste plano de aprendizado.


**Outros AWS recursos criados neste plano de aprendizado**  

| Tutorial | Tipo de atributo | Nome ou ID do recurso | 
| --- | --- | --- | 
|  [Tutorial: Demonstre ações remotas (trabalhos) com o AWS IoT Device Client](iot-dc-runjobs.md)  | Objetos do Amazon S3 | hello-world-job.json | 
|  [Tutorial: Demonstre ações remotas (trabalhos) com o AWS IoT Device Client](iot-dc-runjobs.md)  |  AWS IoT recursos de trabalho  | definido pelo usuário | 

**Para excluir os AWS recursos criados nesse plano de aprendizado**

1. Para excluir os trabalhos criados neste percurso de aprendizado

   1. Execute este comando para listar os trabalhos em seu Conta da AWS.

      ```
      aws iot list-jobs
      ```

      O comando retorna uma lista dos AWS IoT trabalhos em seu Conta da AWS e Região da AWS que se parece com isso.

      ```
      {
          "jobs": [
              {
                  "jobArn": "arn:aws:iot:us-west-2:57EXAMPLE833:job/hello-world-job-2",
                  "jobId": "hello-world-job-2",
                  "targetSelection": "SNAPSHOT",
                  "status": "COMPLETED",
                  "createdAt": "2021-11-16T23:40:36.825000+00:00",
                  "lastUpdatedAt": "2021-11-16T23:40:41.375000+00:00",
                  "completedAt": "2021-11-16T23:40:41.375000+00:00"
              },
              {
                  "jobArn": "arn:aws:iot:us-west-2:57EXAMPLE833:job/hello-world-job-1",
                  "jobId": "hello-world-job-1",
                  "targetSelection": "SNAPSHOT",
                  "status": "COMPLETED",
                  "createdAt": "2021-11-16T23:35:26.381000+00:00",
                  "lastUpdatedAt": "2021-11-16T23:35:29.239000+00:00",
                  "completedAt": "2021-11-16T23:35:29.239000+00:00"
              }
          ]
      }
      ```

   1. Para cada trabalho que você reconhece na lista como um trabalho que você criou neste plano de aprendizado, `jobId` substitua pelo `jobId` valor do trabalho a ser excluído e, em seguida, execute esse comando para excluir um AWS IoT trabalho.

      ```
      aws iot delete-job --job-id jobId
      ```

      Se o comando for bem-sucedido, ele não retornará nada.

1. Para excluir os documentos de trabalho que você armazenou em um bucket do Amazon S3 neste percurso de aprendizado.

   1. Substitua `bucket` pelo nome do bucket que você usou e, em seguida, execute esse comando para listar os objetos no bucket do Amazon S3 que você usou.

      ```
      aws s3api list-objects --bucket bucket
      ```

      O comando retorna uma lista dos objetos do Amazon S3 no bucket que se parece com isso.

      ```
      {
          "Contents": [
              {
                  "Key": "hello-world-job.json",
                  "LastModified": "2021-11-18T03:02:12+00:00",
                  "ETag": "\"868c8bc3f56b5787964764d4b18ed5ef\"",
                  "Size": 54,
                  "StorageClass": "STANDARD",
                  "Owner": {
                      "DisplayName": "EXAMPLE",
                      "ID": "e9e3d6ec1EXAMPLEf5bfb5e6bd0a2b6ed03884d1ed392a82ad011c144736a4ee"
                  }
              },
              {
                  "Key": "iot_job_firmware_update.json",
                  "LastModified": "2021-04-13T21:57:07+00:00",
                  "ETag": "\"7c68c591949391791ecf625253658c61\"",
                  "Size": 66,
                  "StorageClass": "STANDARD",
                  "Owner": {
                      "DisplayName": "EXAMPLE",
                      "ID": "e9e3d6ec1EXAMPLEf5bfb5e6bd0a2b6ed03884d1ed392a82ad011c144736a4ee"
                  }
              },
              {
                  "Key": "order66.json",
                  "LastModified": "2021-04-13T21:57:07+00:00",
                  "ETag": "\"bca60d5380b88e1a70cc27d321caba72\"",
                  "Size": 29,
                  "StorageClass": "STANDARD",
                  "Owner": {
                      "DisplayName": "EXAMPLE",
                      "ID": "e9e3d6ec1EXAMPLEf5bfb5e6bd0a2b6ed03884d1ed392a82ad011c144736a4ee"
                  }
              }
          ]
      }
      ```

   1. Para cada objeto que você reconhece na lista como um objeto que você criou neste percurso de aprendizado, substitua `bucket` pelo valor nome do bucket e `key` pelo valor chave do objeto a ser excluído e, em seguida, execute esse comando para excluir um objeto do Amazon S3.

      ```
       aws s3api delete-object --bucket bucket --key key
      ```

      Se o comando for bem-sucedido, ele não retornará nada.

Depois de excluir todos os AWS recursos e objetos que você criou ao concluir esse plano de aprendizado, você pode recomeçar e repetir os tutoriais.

# Construindo soluções com o AWS IoT dispositivo SDKs
<a name="iot-tutorials-sdk-intro"></a>

Os tutoriais desta seção ajudam você a percorrer as etapas para desenvolver uma solução de IoT que possa ser implantada em um ambiente de produção usando o. AWS IoT

Esses tutoriais podem levar mais tempo para serem concluídos do que os da seção sobre, [Criando demonstrações com o AWS IoT Device Client](iot-tutorials-dc-intro.md) pois eles usam o AWS IoT dispositivo SDKs e explicam os conceitos que estão sendo aplicados com mais detalhes para ajudá-lo a criar soluções seguras e confiáveis.

## Comece a criar soluções com o AWS IoT dispositivo SDKs
<a name="iot-sdk-tutorial-overview"></a>

Esses tutoriais orientam você em diferentes AWS IoT cenários. Quando apropriado, os tutoriais usam o AWS IoT dispositivo. SDKs

**Topics**
+ [Comece a criar soluções com o AWS IoT dispositivo SDKs](#iot-sdk-tutorial-overview)
+ [Tutorial: Conectando um dispositivo AWS IoT Core usando o AWS IoT Device SDK](sdk-tutorials.md)
+ [Criação de AWS IoT regras para rotear dados do dispositivo para outros serviços](iot-rules-tutorial.md)
+ [Reter o estado do dispositivo enquanto o dispositivo está off-line com as sombras do dispositivo](iot-shadows-tutorial.md)
+ [Tutorial: Criando um autorizador personalizado para AWS IoT Core](custom-auth-tutorial.md)
+ [Tutorial: Monitorando a umidade do solo com o AWS IoT Raspberry Pi](iot-moisture-tutorial.md)

# Tutorial: Conectando um dispositivo AWS IoT Core usando o AWS IoT Device SDK
<a name="sdk-tutorials"></a>

Este tutorial demonstra como conectar um dispositivo para AWS IoT Core que ele possa enviar e receber dados de AWS IoT e para. Depois de concluir este tutorial, seu dispositivo será configurado para se conectar AWS IoT Core e você entenderá como os dispositivos se comunicam com ele AWS IoT.

**Topics**
+ [Pré-requisitos](#sdk-tutorials-prereq)
+ [Prepare seu dispositivo para AWS IoT](#sdk-tutorials-prepare)
+ [Revisar o protocolo MQTT](#sdk-tutorials-mqtt-review)
+ [Revise o aplicativo de amostra do SDK do dispositivo pubsub.py](#sdk-tutorials-explore-sample)
+ [Conecte seu dispositivo e comunique-se com AWS IoT Core](#sdk-tutorials-experiment)
+ [Reveja os resultados](#sdk-tutorials-conclusion)
+ [Tutorial: Usar a AWS IoT Device SDK para C incorporado](iot-embedded-c-sdk.md)

## Pré-requisitos
<a name="sdk-tutorials-prereq"></a>

Antes de começar este tutorial, verifique se você tem o seguinte:
+ 

**Concluído [Introdução aos AWS IoT Core tutoriais](iot-gs.md)**  
Na seção desse tutorial em que você deve [Configurar o dispositivo](configure-device.md), selecione a opção [Conectar um Raspberry Pi ou outro dispositivo](connecting-to-existing-device.md) para seu dispositivo e use as opções da linguagem Python para configurá-lo.
**nota**  
Mantenha aberta a janela do terminal que você usa nesse tutorial porque você também vai usá-la.
+ 

**Um dispositivo que pode executar o AWS IoT Device SDK v2 para Python.**  
Este tutorial mostra como conectar um dispositivo AWS IoT Core usando exemplos de código Python, que exigem um dispositivo relativamente poderoso. Se você estiver trabalhando com dispositivos com recursos limitados, esses exemplos de código podem não funcionar com eles. Nesse caso, talvez você tenha mais êxito com o tutorial [Tutorial: Usar a AWS IoT Device SDK para C incorporado](iot-embedded-c-sdk.md).
+ 

**Recebeu as informações necessárias para se conectar ao dispositivo**  
Para conectar seu dispositivo a AWS IoT, você deve ter informações sobre o nome da coisa, o nome do host e o número da porta.
**nota**  
Também é possível usar a autenticação personalizada para conectar dispositivos ao AWS IoT Core. Os dados de conexão transmitidos para a função do Lambda do autorizador dependem do protocolo usado.
  + **Nome da coisa**: O nome da AWS IoT coisa à qual você deseja se conectar. Você deve ter se registrado como seu dispositivo como uma AWS IoT coisa. Para obter mais informações, consulte [Gerenciando dispositivos com AWS IoT](iot-thing-management.md).
  + **Nome do host**: o nome do host do endpoint de IoT específico da conta.
  + **Número da porta**: o número da porta à qual se conectar.

  Você pode usar o `configureEndpoint` método no SDK do AWS IoT Python para configurar o nome do host e o número da porta.

  ```
  myAWSIoTMQTTClient.configureEndpoint("random.iot.region.amazonaws.com", 8883)
  ```

## Prepare seu dispositivo para AWS IoT
<a name="sdk-tutorials-prepare"></a>

Em [Introdução aos AWS IoT Core tutoriais](iot-gs.md), você preparou seu dispositivo e conta AWS para que eles pudessem se comunicar. Esta seção analisa os aspectos dessa preparação que se aplicam a qualquer conexão de dispositivo com AWS IoT Core o.

Para que um dispositivo se conecte a AWS IoT Core:

1. É necessário ter uma **Conta da AWS**.

   O procedimento em [Configurar Conta da AWS](setting-up.md) descreve como criar um, Conta da AWS se você ainda não tiver um. 

1. Nessa conta, você deve ter os seguintes **AWS IoT recursos** definidos para o dispositivo em sua Conta da AWS região.

   O procedimento em [Crie AWS IoT recursos](create-iot-resources.md) descreve como criar esses recursos para o dispositivo em sua Conta da AWS e Região.
   + Um **certificado de dispositivo** registrado AWS IoT e ativado para autenticar o dispositivo.

     O certificado geralmente é criado com e anexado a um **AWS IoT objeto**. Embora um objeto não seja necessário para a conexão de um dispositivo AWS IoT, ele disponibiliza AWS IoT recursos adicionais para o dispositivo.
   + Uma **política** anexada ao certificado do dispositivo que o autoriza a se conectar AWS IoT Core e realizar todas as ações desejadas.

1. Uma **conexão com a Internet** que pode acessar os endpoints Conta da AWS do seu dispositivo.

   Os endpoints do dispositivo estão descritos [AWS IoT dados do dispositivo e endpoints de serviço](iot-connect-devices.md#iot-connect-device-endpoints) e podem ser vistos na [página de configurações do AWS IoT console](https://console.aws.amazon.com/iot/home#/settings). 

1. **Software de comunicação**, como o SDKs fornecido pelo AWS IoT dispositivo. Este tutorial usa o [AWS IoT Device SDK v2 para Python](https://github.com/aws/aws-iot-device-sdk-python-v2#aws-iot-device-sdk-v2-for-python).

## Revisar o protocolo MQTT
<a name="sdk-tutorials-mqtt-review"></a>

Antes de falarmos sobre o aplicativo de exemplo, é útil entender o protocolo MQTT.​ O protocolo MQTT oferece algumas vantagens sobre outros protocolos de comunicação de rede, como o HTTP, o que o torna uma escolha popular para dispositivos IoT. Esta seção analisa os principais aspectos do MQTT que se aplicam a este tutorial. Para obter informações sobre como o MQTT se compara ao HTTP, consulte [Escolher um protocolo de aplicativo para a comunicação do dispositivo](protocols.md#protocol-selection).

**O MQTT usa um modelo de publish/subscribe comunicação**  
O protocolo MQTT usa um modelo publish/subscribe de comunicação com seu host. Esse modelo difere do request/response modelo usado pelo HTTP. Com o MQTT, os dispositivos estabelecem uma sessão com o host que é identificado por um ID de cliente exclusivo. Para enviar dados, os dispositivos publicam mensagens identificadas por tópicos para um agente de mensagens no host. Para receber mensagens do agente de mensagens, os dispositivos assinam tópicos enviando filtros de tópicos em solicitações de assinatura ao agente de mensagens.

**O MQTT é compatível com sessões persistentes**  
O agente de mensagens recebe mensagens de dispositivos e publica mensagens em dispositivos que as assinaram. Com [sessões persistentes](mqtt.md#mqtt-persistent-sessions) —sessões que permanecem ativas mesmo quando o dispositivo iniciador está desconectado — os dispositivos podem recuperar mensagens que foram publicadas enquanto estavam desconectados. No lado do dispositivo, o MQTT é compatível com níveis de Qualidade de Serviço ([QoS](mqtt.md#mqtt-qos)) que garantem que o host receba mensagens enviadas pelo dispositivo.

## Revise o aplicativo de amostra do SDK do dispositivo pubsub.py
<a name="sdk-tutorials-explore-sample"></a>

Esta seção analisa o aplicativo de amostra `pubsub.py` do **AWS IoT Device SDK v2 para Python** usado neste tutorial. Aqui, analisaremos como ele se conecta AWS IoT Core para publicar e assinar mensagens do MQTT. A próxima seção apresenta alguns exercícios para ajudar você a explorar como um dispositivo se conecta e se comunica com AWS IoT Core ele.

**O aplicativo `pubsub.py` de amostra demonstra esses aspectos de uma conexão MQTT com: AWS IoT Core**
+ [Protocolos de comunicação](#sdk-tutorials-explore-protocols)
+ [Sessões persistentes](#sdk-tutorials-explore-persistent)
+ [Qualidade do serviço](#sdk-tutorials-explore-qos)
+ [Publicação de mensagens](#sdk-tutorials-explore-publish)
+ [Assinatura de mensagens](#sdk-tutorials-explore-subscribe)
+ [Desconexão e reconexão do dispositivo](#sdk-tutorials-explore-connect)

### Protocolos de comunicação
<a name="sdk-tutorials-explore-protocols"></a>

A amostra `pubsub.py` demonstra uma conexão MQTT usando os protocolos MQTT e MQTT via WSS. A biblioteca [AWS common runtime (AWS CRT)](https://github.com/awslabs/aws-crt-python#aws-crt-python) fornece suporte ao protocolo de comunicação de baixo nível e está incluída no AWS IoT Device SDK v2 para Python.

#### MQTT
<a name="sdk-tutorials-explore-mqtt"></a>

As chamadas de `pubsub.py` exemplo `mtls_from_path` (mostradas aqui) no [https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py](https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py)para estabelecer uma conexão AWS IoT Core usando o protocolo MQTT. `mtls_from_path`usa certificados X.509 e TLS v1.2 para autenticar o dispositivo. A biblioteca AWS CRT lida com os detalhes de nível inferior dessa conexão.

```
mqtt_connection = mqtt_connection_builder.mtls_from_path(
    endpoint=args.endpoint,
    cert_filepath=args.cert,
    pri_key_filepath=args.key,
    ca_filepath=args.ca_file,
    client_bootstrap=client_bootstrap,
    on_connection_interrupted=on_connection_interrupted,
    on_connection_resumed=on_connection_resumed,
    client_id=args.client_id,
    clean_session=False,
    keep_alive_secs=6
)
```

`endpoint`  
O Conta da AWS endpoint do seu dispositivo de IoT  
No aplicativo de amostra, esse valor é passado pela linha de comando.

`cert_filepath`  
O caminho para o arquivo de certificado do dispositivo  
No aplicativo de amostra, esse valor é passado pela linha de comando.

`pri_key_filepath`  
O caminho para o arquivo de chave privada do dispositivo que foi criado com seu arquivo de certificado  
No aplicativo de amostra, esse valor é passado pela linha de comando.

`ca_filepath`  
O caminho para o arquivo CA Raiz. Obrigatório somente se o servidor MQTT usar um certificado que ainda não esteja em seu armazenamento confiável.  
No aplicativo de amostra, esse valor é passado pela linha de comando.

`client_bootstrap`  
O objeto de runtime comum que trata as atividades de comunicação por soquete  
No aplicativo de amostra, esse objeto é instanciado antes da chamada para `mqtt_connection_builder.mtls_from_path`.

`on_connection_interrupted``on_connection_resumed`  
As funções de retorno de chamada para chamar quando a conexão do dispositivo for interrompida e retomada

`client_id`  
O ID que identifica exclusivamente esse dispositivo no Região da AWS  
No aplicativo de amostra, esse valor é passado pela linha de comando.

`clean_session`  
Se deve iniciar uma nova sessão persistente ou, se houver uma, se reconectar a uma existente

`keep_alive_secs`  
O valor keep alive, em segundos, a ser enviado na `CONNECT` solicitação. Um ping será enviado automaticamente nesse intervalo. Se o servidor não receber um ping após 1,5 vezes esse valor, ele assume que a conexão foi perdida.

#### MQTT via WSS
<a name="sdk-tutorials-explore-mqtt-wss"></a>

Os exemplos de chamada `pubsub.py` `websockets_with_default_aws_signing` (mostrados aqui) no [https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py](https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py) para estabelecer conexão com o AWS IoT Core usando o protocolo MQTT via WSS. `websockets_with_default_aws_signing` cria uma conexão do MQTT via WSS usando o [Signature V4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) para autenticar o dispositivo.

```
mqtt_connection = mqtt_connection_builder.websockets_with_default_aws_signing(
    endpoint=args.endpoint,
    client_bootstrap=client_bootstrap,
    region=args.signing_region,
    credentials_provider=credentials_provider,
    websocket_proxy_options=proxy_options,
    ca_filepath=args.ca_file,
    on_connection_interrupted=on_connection_interrupted,
    on_connection_resumed=on_connection_resumed,
    client_id=args.client_id,
    clean_session=False,
    keep_alive_secs=6
)
```

`endpoint`  
O Conta da AWS endpoint do seu dispositivo de IoT  
No aplicativo de amostra, esse valor é passado pela linha de comando.

`client_bootstrap`  
O objeto de runtime comum que trata as atividades de comunicação por soquete  
No aplicativo de amostra, esse objeto é instanciado antes da chamada para `mqtt_connection_builder.websockets_with_default_aws_signing`.

`region`  
A região de AWS assinatura usada pela autenticação Signature V4. Em `pubsub.py`, ele passa o parâmetro inserido na linha de comando.  
No aplicativo de amostra, esse valor é passado pela linha de comando.

`credentials_provider`  
As AWS credenciais fornecidas para uso na autenticação  
No aplicativo de amostra, esse objeto é instanciado antes da chamada para `mqtt_connection_builder.websockets_with_default_aws_signing`.

`websocket_proxy_options`  
Opções de proxy HTTP, se estiver usando um host proxy  
No aplicativo de amostra, esse valor é inicializado antes da chamada para `mqtt_connection_builder.websockets_with_default_aws_signing`.

`ca_filepath`  
O caminho para o arquivo CA Raiz. Obrigatório somente se o servidor MQTT usar um certificado que ainda não esteja em seu armazenamento confiável.  
No aplicativo de amostra, esse valor é passado pela linha de comando.

`on_connection_interrupted``on_connection_resumed`  
As funções de retorno de chamada para chamar quando a conexão do dispositivo for interrompida e retomada

`client_id`  
O ID que identifica exclusivamente esse dispositivo no Região da AWS.  
No aplicativo de amostra, esse valor é passado pela linha de comando.

`clean_session`  
Se deve iniciar uma nova sessão persistente ou, se houver uma, se reconectar a uma existente

`keep_alive_secs`  
O valor keep alive, em segundos, a ser enviado na `CONNECT` solicitação. Um ping será enviado automaticamente nesse intervalo. Se o servidor não receber um ping após 1,5 vezes esse valor, ele presume que a conexão foi perdida.

#### HTTPS
<a name="sdk-tutorials-explore-https"></a>

E quanto ao HTTPS? AWS IoT Core oferece suporte a dispositivos que publicam solicitações HTTPS. Do ponto de vista da programação, os dispositivos enviam solicitações HTTPS para AWS IoT Core o mesmo que qualquer outro aplicativo. Para ver um exemplo de um programa em Python que envia uma mensagem HTTP de um dispositivo, consulte o [exemplo de código HTTPS](http.md#codeexample) usando a biblioteca do Python. `requests` Este exemplo envia uma mensagem para AWS IoT Core usar HTTPS de forma que a AWS IoT Core interprete como uma mensagem MQTT.

Embora AWS IoT Core ofereça suporte a solicitações HTTPS de dispositivos, certifique-se de revisar as informações para que você possa tomar uma decisão informada sobre qual protocolo usar para as comunicações do seu dispositivo. [Escolher um protocolo de aplicativo para a comunicação do dispositivo](protocols.md#protocol-selection)

### Sessões persistentes
<a name="sdk-tutorials-explore-persistent"></a>

No aplicativo de amostra, definir o parâmetro `clean_session` como `False` indica que a conexão deve ser persistente. Na prática, a conexão aberta por essa chamada se reconecta a uma sessão persistente existente, se houver. Caso contrário, ela cria e se conecta a uma nova sessão persistente.

Com uma sessão persistente, as mensagens enviadas ao dispositivo são armazenadas pelo agente de mensagens enquanto o dispositivo não está conectado. Quando um dispositivo se reconecta a uma sessão persistente, o agente de mensagens envia ao dispositivo todas as mensagens armazenadas nas quais ele se inscreveu.

Sem uma sessão persistente, o dispositivo não receberá mensagens enviadas enquanto o dispositivo não estiver conectado. A opção a ser usada depende do seu aplicativo e se as mensagens que ocorrem enquanto um dispositivo não está conectado devem ser comunicadas. Para obter mais informações, consulte [Sessões persistentes do MQTT](mqtt.md#mqtt-persistent-sessions).

### Qualidade do serviço
<a name="sdk-tutorials-explore-qos"></a>

Quando o dispositivo publica e assina mensagens, a Qualidade de Serviço (QoS) preferida pode ser definida. AWS IoT suporta os níveis de QoS 0 e 1 para operações de publicação e assinatura. Para obter mais informações sobre os níveis de QoS em AWS IoT, consulte. [Opções de Qualidade de serviço (QoS) do MQTT](mqtt.md#mqtt-qos)

O tempo de execução do AWS CRT para Python define essas constantes para os níveis de QoS que ele suporta:


**Níveis de qualidade de serviço do Python**  

| Nível de QoS do MQTT | Valor simbólico do Python usado pelo SDK | Descrição | 
| --- | --- | --- | 
| QoS nível 0 | mqtt.QoS.AT\$1MOST\$1ONCE | Somente uma tentativa de enviar a mensagem será feita, seja ela recebida ou não. A mensagem pode não ser enviada, por exemplo, se o dispositivo não estiver conectado ou houver um erro na rede. | 
| QoS nível 1 | mqtt.QoS.AT\$1LEAST\$1ONCE | A mensagem é enviada repetidamente até que uma PUBACK confirmação seja recebida. | 

No aplicativo de amostra, as solicitações de publicação e assinatura são feitas com um nível de QoS de 1 (`mqtt.QoS.AT_LEAST_ONCE`). 
+ 

**QoS na publicação**  
Quando um dispositivo publica uma mensagem com QoS nível 1, ele envia a mensagem repetidamente até receber uma `PUBACK` resposta do agente de mensagens. Se o dispositivo não estiver conectado, a mensagem será colocada na fila para ser enviada após a reconexão.
+ 

**QoS na assinatura**  
Quando um dispositivo assina uma mensagem com QoS nível 1, o agente de mensagens salva as mensagens nas quais o dispositivo está inscrito até que elas possam ser enviadas ao dispositivo. O agente de mensagens reenvia as mensagens até receber uma resposta `PUBACK` do dispositivo.

### Publicação de mensagens
<a name="sdk-tutorials-explore-publish"></a>

Depois de estabelecer com sucesso uma conexão com AWS IoT Core, os dispositivos podem publicar mensagens. A amostra `pubsub.py` faz isso chamando a operação `publish` do `mqtt_connection` objeto.

```
mqtt_connection.publish(
    topic=args.topic,
    payload=message,
    qos=mqtt.QoS.AT_LEAST_ONCE
)
```

`topic`  
O nome do tópico da mensagem que identifica a mensagem  
No aplicativo de amostra, esse valor é passado pela linha de comando.

`payload`  
A carga útil da mensagem formatada como uma string (por exemplo, um documento JSON)  
No aplicativo de amostra, esse valor é passado pela linha de comando.  
Um documento JSON é um formato de carga útil comum e reconhecido por outros AWS IoT serviços; no entanto, o formato de dados da carga útil da mensagem pode ser qualquer coisa com a qual os editores e assinantes concordem. Outros AWS IoT serviços, no entanto, reconhecem apenas JSON e CBOR, em alguns casos, para a maioria das operações.

`qos`  
O nível de QoS para esta mensagem

### Assinatura de mensagens
<a name="sdk-tutorials-explore-subscribe"></a>

Para receber mensagens de AWS IoT outros serviços e dispositivos, os dispositivos assinam essas mensagens pelo nome do tópico. Os dispositivos podem assinar mensagens individuais especificando um [nome de tópico](topics.md#topicnames) e em um grupo de mensagens especificando um [filtro de tópico](topics.md#topicfilters), que pode incluir caracteres curinga. A amostra `pubsub.py` usa o código mostrado aqui para assinar mensagens e registrar as funções de retorno de chamada para processar a mensagem depois de recebida.

```
subscribe_future, packet_id = mqtt_connection.subscribe(
    topic=args.topic,
    qos=mqtt.QoS.AT_LEAST_ONCE,
    callback=on_message_received
)
subscribe_result = subscribe_future.result()
```

`topic`  
Como assinar um tópico do. Pode ser um nome de tópico ou um filtro de tópico.  
No aplicativo de amostra, esse valor é passado pela linha de comando.

`qos`  
Se o agente de mensagens deve armazenar essas mensagens enquanto o dispositivo está desconectado.  
Um valor de `mqtt.QoS.AT_LEAST_ONCE` (QoS nível 1) exige que uma sessão persistente seja especificada (`clean_session=False`) quando a conexão é criada.

`callback`  
A função a ser chamada para processar a mensagem assinada.

A função `mqtt_connection.subscribe` retorna um future e um ID de pacote. Se a solicitação de assinatura foi iniciada com sucesso, o ID do pacote retornado será maior que 0. Para garantir que a assinatura tenha sido recebida e registrada pelo agente de mensagens, você deve aguardar o retorno do resultado da operação assíncrona, conforme mostrado no exemplo de código.

**Função de retorno de chamada**  
O retorno de chamada na amostra `pubsub.py` processa as mensagens assinadas à medida que o dispositivo as recebe.

```
def on_message_received(topic, payload, **kwargs):
    print("Received message from topic '{}': {}".format(topic, payload))
    global received_count
    received_count += 1
    if received_count == args.count:
        received_all_event.set()
```

`topic`  
O tópico da mensagem  
Esse é o nome do tópico específico da mensagem recebida, mesmo que você tenha se inscrito em um filtro de tópicos.

`payload`  
Carga útil da mensagem  
O formato para isso é específico do aplicativo.

`kwargs`  
Possíveis argumentos adicionais, conforme descrito em [https://awslabs.github.io/aws-crt-python/api/mqtt.html#awscrt.mqtt.Connection.subscribe](https://awslabs.github.io/aws-crt-python/api/mqtt.html#awscrt.mqtt.Connection.subscribe).

Na amostra `pubsub.py`, `on_message_received` exibe somente o tópico e sua carga útil. Ele também conta as mensagens recebidas para finalizar o programa após o limite ser atingido.

Seu aplicativo avaliaria o tópico e a carga para determinar quais ações realizar.

### Desconexão e reconexão do dispositivo
<a name="sdk-tutorials-explore-connect"></a>

A amostra `pubsub.py` inclui funções de retorno de chamada que são chamadas quando o dispositivo é desconectado e quando a conexão é restabelecida. As ações que seu dispositivo executa nesses eventos são específicas do aplicativo.

Quando um dispositivo se conecta pela primeira vez, ele precisa se inscrever nos tópicos para receber. Se a sessão de um dispositivo estiver presente quando ele se reconectar, suas assinaturas serão restauradas e todas as mensagens armazenadas dessas assinaturas serão enviadas ao dispositivo após a reconexão.

Se a sessão de um dispositivo não existir mais quando ele se reconectar, ele deverá assinar novamente suas assinaturas. As sessões persistentes têm uma vida útil limitada e podem expirar quando o dispositivo é desconectado por muito tempo.

## Conecte seu dispositivo e comunique-se com AWS IoT Core
<a name="sdk-tutorials-experiment"></a>

Esta seção apresenta alguns exercícios para ajudá-lo a explorar diferentes aspectos da conexão do seu dispositivo a AWS IoT Core. Para esses exercícios, você usará o [cliente de teste MQTT](https://console.aws.amazon.com/iot/home#/test) no AWS IoT console para ver o que seu dispositivo publica e publicar mensagens em seu dispositivo. Esses exercícios usam o exemplo [https://github.com/aws/aws-iot-device-sdk-python-v2/blob/master/samples/pubsub.py](https://github.com/aws/aws-iot-device-sdk-python-v2/blob/master/samples/pubsub.py) do [AWS IoT Device SDK v2 para Python](https://github.com/aws/aws-iot-device-sdk-python-v2/tree/master/samples#sample-apps-for-the-aws-iot-device-sdk-v2-for-python) e se baseiam na sua experiência com tutoriais do [Introdução aos AWS IoT Core tutoriais](iot-gs.md). 

**Topics**
+ [Inscreva-se nos filtros de tópicos curinga](#sdk-tutorials-experiment-wild)
+ [Processar assinaturas de filtros de tópicos](#sdk-tutorials-experiment-process)
+ [Publique mensagens do seu dispositivo](#sdk-tutorials-experiment-publish)

Para esses exercícios, você começará com o programa `pubsub.py` de amostra.

**nota**  
Esses exercícios pressupõem que você concluiu os [Introdução aos AWS IoT Core tutoriais](iot-gs.md) tutoriais e usou a janela do terminal do seu dispositivo a partir desse tutorial.

### Inscreva-se nos filtros de tópicos curinga
<a name="sdk-tutorials-experiment-wild"></a>

Neste exercício, você modificará a linha de comando usada para chamar `pubsub.py` para assinar um filtro de tópico curinga e processará as mensagens recebidas com base no tópico da mensagem.

#### Procedimento de exercício
<a name="sdk-tutorials-experiment-wild-steps"></a>

Para este exercício, imagine que seu dispositivo contenha um controle de temperatura e um controle de luz. Ele usa esses nomes de tópicos para identificar as mensagens sobre eles.

1. Antes de iniciar o exercício, tente executar esse comando nos [Introdução aos AWS IoT Core tutoriais](iot-gs.md) tutoriais do seu dispositivo para garantir que tudo esteja pronto para o exercício.

   ```
   cd ~/aws-iot-device-sdk-python-v2/samples
   python3 pubsub.py --topic topic_1 --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint
   ```

   Você deve ver a mesma saída que viu no [tutorial de introdução](connecting-to-existing-device.md#gs-device-node-app-run).

1. Para este exercício, altere esses parâmetros da linha de comando.    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/sdk-tutorials.html)

   Fazer essas alterações na linha de comando inicial resulta nessa linha de comando. Digite esse comando na janela do terminal do seu dispositivo.

   ```
   python3 pubsub.py --message "" --count 2 --topic device/+/details --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint
   ```

   O programa deve exibir algo semelhante ao seguinte:

   ```
   Connecting to a3qexamplesffp-ats.iot.us-west-2.amazonaws.com with client ID 'test-24d7cdcc-cc01-458c-8488-2d05849691e1'...
   Connected!
   Subscribing to topic 'device/+/details'...
   Subscribed with QoS.AT_LEAST_ONCE
   Waiting for all messages to be received...
   ```

   Se você vir algo assim em seu terminal, seu dispositivo está pronto e ouvindo mensagens onde os nomes dos tópicos começam com `device` e terminam com `/detail`. Então, vamos testar isso.

1. Aqui estão algumas mensagens que seu dispositivo pode receber.    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/sdk-tutorials.html)

1. Usando o cliente de teste MQTT no AWS IoT console, envie as mensagens descritas na etapa anterior para o seu dispositivo.

   1. Abra o [cliente de teste MQTT](https://console.aws.amazon.com/iot/home#/test) no AWS IoT console.

   1. Em **Inscrever-se em um tópico**, no **campo assinatura do tópico**, insira o filtro do tópico: **device/\$1/details** e, em seguida, selecione **Assinar um tópico**.

   1. Na coluna **Assinaturas** do cliente de teste MQTT, selecione **dispositivo/\$1/detalhes**.

   1. Para cada um dos tópicos na tabela anterior, faça o seguinte no cliente de teste do MQTT:

      1. Em **Publicar**, insira o valor da coluna **Nome do tópico** na tabela.

      1. No campo de carga útil da mensagem abaixo do nome do tópico, insira o valor da coluna **Carga útil da mensagem** na tabela.

      1. Observe a janela do terminal em que `pubsub.py` está sendo executada e, no cliente de teste do MQTT, escolha **Publicar no tópico**.

      Você deve ver que a mensagem foi recebida `pubsub.py` na janela do terminal.

#### Resultado do exercício
<a name="sdk-tutorials-experiment-wild-result"></a>

Com isso, `pubsub.py`, assinou as mensagens usando um filtro de tópico curinga, recebeu-as e as exibiu na janela do terminal. Observe como você se inscreveu em um único filtro de tópico e a função de retorno de chamada foi chamada para processar mensagens com dois tópicos distintos.

### Processar assinaturas de filtros de tópicos
<a name="sdk-tutorials-experiment-process"></a>

Com base no exercício anterior, modifique o aplicativo de `pubsub.py` amostra para avaliar os tópicos da mensagem e processar as mensagens inscritas com base no tópico.

#### Procedimento de exercício
<a name="sdk-tutorials-experiment-process-steps"></a>

**Para avaliar o tópico da mensagem**

1. Copie `pubsub.py` para `pubsub2.py`.

1. Abra `pubsub2.py` no seu editor de texto favorito ou IDE.

1. Em `pubsub2.py`, encontre a função `on_message_received`.

1. Em `on_message_received`, insira o código a seguir após a linha que começa com `print("Received message` e antes da linha que começa com `global received_count`.

   ```
       topic_parsed = False
       if "/" in topic:
           parsed_topic = topic.split("/")
           if len(parsed_topic) == 3:
               # this topic has the correct format
               if (parsed_topic[0] == 'device') and (parsed_topic[2] == 'details'):
                   # this is a topic we care about, so check the 2nd element
                   if (parsed_topic[1] == 'temp'):
                       print("Received temperature request: {}".format(payload))
                       topic_parsed = True
                   if (parsed_topic[1] == 'light'):
                       print("Received light request: {}".format(payload))
                       topic_parsed = True
       if not topic_parsed:
           print("Unrecognized message topic.")
   ```

1. Salve suas alterações e execute o programa modificado usando essa linha de comando.

   ```
   python3 pubsub2.py --message "" --count 2 --topic device/+/details --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint
   ```

1. No AWS IoT console, abra o [cliente de teste MQTT](https://console.aws.amazon.com/iot/home#/test).

1. Em **Inscrever-se em um tópico**, no **campo assinatura do tópico**, insira o filtro do tópico: **device/\$1/details** e, em seguida, selecione **Assinar um tópico**.

1. Na coluna **Assinaturas** do cliente de teste MQTT, selecione **dispositivo/\$1/detalhes**.

1. Para cada um dos tópicos nesta tabela, faça o seguinte no cliente de teste do MQTT:    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/sdk-tutorials.html)

   1. Em **Publicar**, insira o valor da coluna **Nome do tópico** na tabela.

   1. No campo de carga útil da mensagem abaixo do nome do tópico, insira o valor da coluna **Carga útil da mensagem** na tabela.

   1. Observe a janela do terminal em que `pubsub.py` está sendo executada e, no cliente de teste do MQTT, escolha **Publicar no tópico**.

   Você deve ver que a mensagem foi recebida `pubsub.py` na janela do terminal.

Você deverá ver algo semelhante a isso na janela do seu terminal.

```
Connecting to a3qexamplesffp-ats.iot.us-west-2.amazonaws.com with client ID 'test-af794be0-7542-45a0-b0af-0b0ea7474517'...
Connected!
Subscribing to topic 'device/+/details'...
Subscribed with QoS.AT_LEAST_ONCE
Waiting for all messages to be received...
Received message from topic 'device/light/details': b'{ "desiredLight": 100, "currentLight": 50 }'
Received light request: b'{ "desiredLight": 100, "currentLight": 50 }'
Received message from topic 'device/temp/details': b'{ "desiredTemp": 20, "currentTemp": 15 }'
Received temperature request: b'{ "desiredTemp": 20, "currentTemp": 15 }'
2 message(s) received.
Disconnecting...
Disconnected!
```

#### Resultado do exercício
<a name="sdk-tutorials-experiment-process-result"></a>

Neste exercício, você adicionou código para que o aplicativo de amostra reconheça e processe várias mensagens na função de retorno de chamada. Com isso, seu dispositivo pode receber mensagens e agir conforme elas.

Outra forma de seu dispositivo receber e processar várias mensagens é assinar mensagens diferentes separadamente e atribuir a cada assinatura sua própria função de retorno de chamada.

### Publique mensagens do seu dispositivo
<a name="sdk-tutorials-experiment-publish"></a>

Você pode usar o aplicativo de amostra pubsub.py para publicar mensagens do seu dispositivo. Embora publique as mensagens como estão, elas não podem ser lidas como documentos JSON. Este exercício modifica o aplicativo de amostra para poder publicar documentos JSON na carga da mensagem que podem ser lidos por. AWS IoT Core

#### Procedimento de exercício
<a name="sdk-tutorials-experiment-publish-steps"></a>

Neste exercício, a seguinte mensagem será enviada com o tópico `device/data`.

```
{
    "timestamp": 1601048303,
    "sensorId": 28,
    "sensorData": [
        {
        "sensorName": "Wind speed",
        "sensorValue": 34.2211224
        }
    ]
}
```

**Para preparar seu cliente de teste MQTT para monitorar as mensagens deste exercício**

1. Em **Inscrever-se em um tópico**, no **campo assinatura do tópico**, insira o filtro do tópico: **device/data** e, em seguida, selecione **IAssinar um tópico**.

1. Na coluna **Assinaturas** do cliente de teste MQTT, selecione **dispositivo/dados**.

1. Mantenha a janela do cliente de teste MQTT aberta para aguardar as mensagens do seu dispositivo.

**Para enviar documentos JSON com o aplicativo de amostra pubsub.py**

1. No seu dispositivo, copie `pubsub.py` para `pubsub3.py`.

1. Edite `pubsub3.py` para alterar a forma como ele formata as mensagens que publica.

   1. Abra `pubsub3.py` em um editor de texto.

   1. Localize esta linha de código:

      `message = "{} [{}]".format(message_string, publish_count)`

   1. Altere para:

      `message = "{}".format(message_string)`

   1. Localize esta linha de código:

      `message_json = json.dumps(message)`

   1. Altere para:

      `message = "{}".json.dumps(json.loads(message))`

   1. Salve as alterações.

1. No seu dispositivo, execute esse comando para enviar a mensagem duas vezes.

   ```
   python3 pubsub3.py  --ca_file ~/certs/Amazon-root-CA-1.pem  --cert ~/certs/device.pem.crt  --key ~/certs/private.pem.key  --topic device/data  --count 2 --message '{"timestamp":1601048303,"sensorId":28,"sensorData":[{"sensorName":"Wind speed","sensorValue":34.2211224}]}'  --endpoint your-iot-endpoint
   ```

1. No cliente de teste MQTT, verifique se ele interpretou e formatou o documento JSON na carga útil da mensagem, da seguinte forma:  
![\[Imagem mostrando como a carga útil de uma mensagem JSON é exibida no cliente MQTT do console. AWS IoT\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/images/mqtt-test-client-output.png)

Por padrão, `pubsub3.py` também assina as mensagens que envia. Você deve ver que ele recebeu as mensagens na saída do aplicativo. A janela do terminal deve parecer com algo semelhante ao seguinte.

```
Connecting to a3qEXAMPLEsffp-ats.iot.us-west-2.amazonaws.com with client ID 'test-5cff18ae-1e92-4c38-a9d4-7b9771afc52f'...
Connected!
Subscribing to topic 'device/data'...
Subscribed with QoS.AT_LEAST_ONCE
Sending 2 message(s)
Publishing message to topic 'device/data': {"timestamp":1601048303,"sensorId":28,"sensorData":[{"sensorName":"Wind speed","sensorValue":34.2211224}]}
Received message from topic 'device/data': b'{"timestamp":1601048303,"sensorId":28,"sensorData":[{"sensorName":"Wind speed","sensorValue":34.2211224}]}'
Publishing message to topic 'device/data': {"timestamp":1601048303,"sensorId":28,"sensorData":[{"sensorName":"Wind speed","sensorValue":34.2211224}]}
Received message from topic 'device/data': b'{"timestamp":1601048303,"sensorId":28,"sensorData":[{"sensorName":"Wind speed","sensorValue":34.2211224}]}'
2 message(s) received.
Disconnecting...
Disconnected!
```

#### Resultado do exercício
<a name="sdk-tutorials-experiment-publish-result"></a>

Com isso, seu dispositivo pode gerar mensagens para enviar AWS IoT Core para testar a conectividade básica e fornecer mensagens do dispositivo AWS IoT Core para processamento. Por exemplo, você pode usar esse aplicativo para enviar dados de teste do seu dispositivo para testar ações de AWS IoT regras.

## Reveja os resultados
<a name="sdk-tutorials-conclusion"></a>

Os exemplos deste tutorial proporcionaram a você uma experiência prática com os conceitos básicos de como os dispositivos podem se comunicar AWS IoT Core— uma parte fundamental de sua solução. AWS IoT Quando seus dispositivos conseguem se comunicar AWS IoT Core, eles podem passar mensagens para AWS serviços e outros dispositivos nos quais possam atuar. Da mesma forma, AWS serviços e outros dispositivos podem processar informações que resultam em mensagens enviadas de volta aos seus dispositivos.

Quando estiver pronto para explorar AWS IoT Core mais, experimente estes tutoriais:
+ [Tutorial:r Como enviar uma notificação do Amazon SNS](iot-sns-rule.md)
+ [Tutorial: Armazenamento de dados do dispositivo em uma tabela do DynamoDB](iot-ddb-rule.md)
+ [Tutorial: Formatando uma notificação usando uma função AWS Lambda](iot-lambda-rule.md)

# Tutorial: Usar a AWS IoT Device SDK para C incorporado
<a name="iot-embedded-c-sdk"></a>

Esta seção descreve como executar o AWS IoT Device SDK para C incorporado.

**Topics**
+ [Etapa 1: instalar a AWS IoT Device SDK para C incorporado](#install-embedded-c-sdk)
+ [Etapa 2: configurar uma aplicação de amostra](#iot-c-sdk-app-config)
+ [Etapa 3: criar e executar a aplicação de exemplo](#iot-c-sdk-app-run)

## Etapa 1: instalar a AWS IoT Device SDK para C incorporado
<a name="install-embedded-c-sdk"></a>

Em geral, o AWS IoT Device SDK para C incorporado destina-se a dispositivos com restrição de recursos que exigem um runtime de linguagem C otimizado. É possível usar o SDK em qualquer sistema operacional e hospedá-lo em qualquer tipo de processador (p. ex., MCUs e MPUs). Se você tiver mais memória e recursos de processamento disponíveis, recomendamos usar um dos SDKs de dispositivos e dispositivos móveis do AWS IoT de ordem superior (por exemplo, C\$1\$1, Java, JavaScript e Python).

Em geral, o AWS IoT Device SDK para C incorporado destina-se a sistemas que usam MCUs ou MPUs low-end que executam sistemas operacionais incorporados. Para o exemplo de programação nesta seção, presumimos que o dispositivo usa Linux.

**Example**  

1. Faça o download de AWS IoT Device SDK para C incorporado para o dispositivo no [GitHub](https://github.com/aws/aws-iot-device-sdk-embedded-C).

   ```
   git clone https://github.com/aws/aws-iot-device-sdk-embedded-c.git --recurse-submodules
   ```

   Isso cria um diretório chamado `aws-iot-device-sdk-embedded-c` no diretório atual.

1. Navegue até esse diretório e confira a versão mais recente. Consulte [github.com/aws/aws-iot-device-sdk-embedded-C/tags](https://github.com/aws/aws-iot-device-sdk-embedded-C/tags) para ver a tag de lançamento mais recente.

   ```
   cd aws-iot-device-sdk-embedded-c
   git checkout latest-release-tag
   ```

1. Instale o OpenSSL versão 1.1.0 ou posterior. As bibliotecas de desenvolvimento do OpenSSL geralmente são chamadas de “libssl-dev” ou “openssl-devel” quando instaladas por meio de um gerenciador de pacotes.

   ```
   sudo apt-get install libssl-dev
   ```

## Etapa 2: configurar uma aplicação de amostra
<a name="iot-c-sdk-app-config"></a>

O AWS IoT Device SDK para C incorporado inclui aplicativos de exemplo para você experimentar. Para simplificar, este tutorial usa a aplicação `mqtt_demo_mutual_auth`, que ilustra como se conectar ao agente de mensagens do AWS IoT Core e assinar e publicar em tópicos MQTT.

1. Copie o certificado e a chave privada que você criou em [Introdução aos AWS IoT Core tutoriais](iot-gs.md) no diretório `build/bin/certificates`.
**nota**  
Os certificados CA raiz e de dispositivo estão sujeitos a expiração ou revogação. Se esses certificados expirarem ou forem revogados, você deverá copiar um novo certificado da CA ou uma chave privada e um certificado do dispositivo no dispositivo.

1. É necessário configurar o exemplo com sua chave privada, certificado, certificado CA raiz e endpoint pessoal do AWS IoT Core. Navegue até o diretório `aws-iot-device-sdk-embedded-c/demos/mqtt/mqtt_demo_mutual_auth`.

   Se você tiver a AWS CLI instalada, será possível usar o comando para localizar o URL do endpoint da sua conta.

   ```
   aws iot describe-endpoint --endpoint-type iot:Data-ATS
   ```

   Se você não tiver a AWS CLI instalada, abra o [console do AWS IoT](https://console.aws.amazon.com/iot/home). No painel de navegação, escolha **Gerenciar** e **Objetos**. Escolha o objeto de IoT para o dispositivo e escolha **Interagir**. Seu endpoint é exibido na seção **HTTPS** da página de detalhes do objeto.

1. Abra o arquivo `demo_config.h` e atualize os valores para o seguinte:  
AWS\$1IOT\$1ENDPOINT  
Seu endpoint pessoal.  
CLIENT\$1CERT\$1PATH  
O caminho do arquivo de certificado, por exemplo `certificates/device.pem.crt"`.  
CLIENT\$1PRIVATE\$1KEY\$1PATH  
O nome do arquivo de chave privada, por exemplo `certificates/private.pem.key`.

   Por exemplo:

   ```
   // Get from demo_config.h
   // =================================================
   #define AWS_IOT_ENDPOINT               "my-endpoint-ats.iot.us-east-1.amazonaws.com"
   #define AWS_MQTT_PORT                  8883
   #define CLIENT_IDENTIFIER              "testclient"
   #define ROOT_CA_CERT_PATH              "certificates/AmazonRootCA1.crt"
   #define CLIENT_CERT_PATH               "certificates/my-device-cert.pem.crt"
   #define CLIENT_PRIVATE_KEY_PATH        "certificates/my-device-private-key.pem.key"
   // =================================================
   ```

1. Verifique se você tem a CMake instalada no dispositivo usando este comando.

   ```
   cmake --version
   ```

   Se vir as informações de versão para o compilador, você poderá continuar para a próxima seção.

   Se receber um erro ou não vir nenhuma informação, você deverá instalar o pacote cmake usando este comando.

   ```
   sudo apt-get install cmake
   ```

   Execute o comando **cmake --version** novamente e confirme se a CMake foi instalada e que você está pronto para continuar.

1. Verifique se você tem as ferramentas de desenvolvimento instaladas em seu dispositivo usando este comando.

   ```
   gcc --version
   ```

   Se vir as informações de versão para o compilador, você poderá continuar para a próxima seção.

   Se receber um erro ou não vir nenhuma informação do compilador, você deverá instalar o pacote `build-essential` usando este comando.

   ```
   sudo apt-get install build-essential
   ```

   Execute o comando **gcc --version** novamente e confirme se as ferramentas de compilação foram instaladas e que você está pronto para continuar.

## Etapa 3: criar e executar a aplicação de exemplo
<a name="iot-c-sdk-app-run"></a>

Este procedimento explica como gerar a aplicação `mqtt_demo_mutual_auth` em seu dispositivo e conectá-la ao [console de AWS IoT](https://console.aws.amazon.com/iot/home) usando o AWS IoT Device SDK para C incorporado.

**Como executar os aplicativos de exemplo do AWS IoT Device SDK para C incorporado**

1. Navegue até `aws-iot-device-sdk-embedded-c` e crie um diretório de compilação.

   ```
   mkdir build && cd build
   ```

1. Insira o comando CMake a seguir para gerar os arquivos de Makefiles necessários para compilação.

   ```
   cmake ..  
   ```

1. Digite o comando a seguir para compilar o arquivo de aplicação executável.

   ```
   make
   ```

1. Execute o aplicativo `mqtt_demo_mutual_auth` com este comando.

   ```
   cd bin
   ./mqtt_demo_mutual_auth
   ```

   Você deve ver uma saída semelhante a:   
![\[Saída de linha de comando para executar a aplicação de amostra AWS IoT Device SDK para C incorporado.\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/images/successful-run2.png)

O dispositivo está conectado à AWS IoT agora usando o AWS IoT Device SDK para C incorporado.

Também é possível usar o console da AWS IoT para visualizar as mensagens MQTT que a aplicação de exemplo está publicando. Para obter informações sobre como usar o cliente MQTT no [console do AWS IoT](https://console.aws.amazon.com/iot/home), consulte [Exibir mensagens MQTT com o cliente AWS IoT MQTT](view-mqtt-messages.md).

# Criação de AWS IoT regras para rotear dados do dispositivo para outros serviços
<a name="iot-rules-tutorial"></a>

Esses tutoriais mostram como criar e testar AWS IoT regras usando algumas das ações de regras mais comuns.

AWS IoT as regras enviam dados de seus dispositivos para outros AWS serviços. Eles recebem mensagens MQTT específicas, formatam os dados nas cargas de mensagens e enviam o resultado para outros AWS serviços.

Recomendamos que você os experimente na ordem em que são mostrados aqui, mesmo que seu objetivo seja criar uma regra que use uma função do Lambda ou algo mais complexo. Os tutoriais são apresentados do básico ao complexo. Eles apresentam novos conceitos de forma incremental para ajudá-lo a aprender os conceitos que você pode usar para criar ações de regras que não têm um tutorial específico.

**nota**  
AWS IoT as regras ajudam você a enviar os dados dos seus dispositivos de IoT para outros AWS serviços. Para fazer isso com sucesso, no entanto, você precisa de um conhecimento prático dos outros serviços para os quais deseja enviar dados. Embora esses tutoriais forneçam as informações necessárias para concluir as tarefas, talvez seja útil descobrir mais sobre os serviços para os quais você deseja enviar dados antes de usá-los em sua solução. Uma explicação detalhada dos outros AWS serviços está fora do escopo desses tutoriais.

**Visão geral do cenário do tutorial**  
O cenário desses tutoriais é o de um dispositivo sensor climático que publica periodicamente os dados. Existem muitos desses dispositivos sensores nesse sistema imaginário. No entanto, os tutoriais desta seção se concentram em um único dispositivo e mostram como você pode acomodar vários sensores.

Os tutoriais desta seção mostram como usar AWS IoT regras para realizar as seguintes tarefas com esse sistema imaginário de dispositivos de sensores climáticos.
+ 

**[Tutorial: como republicar uma mensagem MQTT](iot-repub-rule.md)**  
Este tutorial mostra como republicar uma mensagem MQTT recebida dos sensores meteorológicos como uma mensagem que contém somente a ID do sensor e o valor da temperatura. Ele usa somente serviços AWS IoT Core e demonstra uma consulta SQL simples e como usar o cliente MQTT para testar sua regra.
+ 

**[Tutorial:r Como enviar uma notificação do Amazon SNS](iot-sns-rule.md)**  
Este tutorial mostra como enviar uma mensagem SNS quando um valor de um dispositivo sensor meteorológico excede um valor específico. Ele se baseia nos conceitos apresentados no tutorial anterior e acrescenta como trabalhar com outro AWS serviço, o [Amazon Simple Notification Service](https://docs.aws.amazon.com//sns/latest/dg/welcome.html) (Amazon SNS).

  Se você for novo no Amazon SNS, revise os exercícios de [Conceitos básicos](https://docs.aws.amazon.com//sns/latest/dg/sns-getting-started.html) antes de começar este tutorial. 
+ 

**[Tutorial: Armazenamento de dados do dispositivo em uma tabela do DynamoDB](iot-ddb-rule.md)**  
Este tutorial mostra como armazenar os dados dos dispositivos de sensores climáticos em uma tabela de banco de dados. Ele usa a declaração de consulta de regras e os modelos de substituição para formatar os dados da mensagem para o serviço de destino, o [Amazon DynamoDB](https://docs.aws.amazon.com//amazondynamodb/latest/developerguide/Introduction.html).

  Se você é iniciante no DynamoDB, [revise seus exercícios de introdução](https://docs.aws.amazon.com//amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) antes de começar este tutorial.
+ 

**[Tutorial: Formatando uma notificação usando uma função AWS Lambda](iot-lambda-rule.md)**  
Este tutorial mostra como chamar uma função do Lambda para reformatar os dados do dispositivo e enviá-los como uma mensagem de texto. Ele adiciona um script Python e funções do AWS SDK em uma [AWS Lambda](https://docs.aws.amazon.com//lambda/latest/dg/welcome.html)função para formatar com os dados da carga útil da mensagem dos dispositivos de sensores meteorológicos e enviar uma mensagem de texto.

  Se você é novato no Lambda, [revise seus exercícios de introdução](https://docs.aws.amazon.com//lambda/latest/dg/getting-started.html) antes de começar este tutorial.

**AWS IoT visão geral das regras**  
Todos esses tutoriais criam AWS IoT regras. 

Para que uma AWS IoT regra envie os dados de um dispositivo para outro AWS serviço, ela usa: 


+ Uma declaração de consulta de regra que consiste em:
  + Uma cláusula SQL SELECT que seleciona e formata os dados da carga útil da mensagem
  + Um filtro de tópico (o objeto FROM na instrução de consulta de regra) que identifica as mensagens a serem usadas
  + Uma declaração condicional opcional (uma cláusula SQL WHERE) que especifica condições específicas sobre as quais agir
+ Pelo menos uma ação de regra

Os dispositivos publicam mensagens em tópicos MQTT. O filtro de tópicos na instrução SQL SELECT identifica os tópicos do MQTT aos quais aplicar a regra. Os campos especificados na instrução SQL SELECT formatam os dados da carga útil da mensagem MQTT recebida para uso pelas ações da regra. Para obter uma lista completa de ações de regra, consulte [Ações de regra da AWS IoT](iot-rule-actions.md)​.

**Topics**
+ [Tutorial: como republicar uma mensagem MQTT](iot-repub-rule.md)
+ [Tutorial:r Como enviar uma notificação do Amazon SNS](iot-sns-rule.md)
+ [Tutorial: Armazenamento de dados do dispositivo em uma tabela do DynamoDB](iot-ddb-rule.md)
+ [Tutorial: Formatando uma notificação usando uma função AWS Lambda](iot-lambda-rule.md)

# Tutorial: como republicar uma mensagem MQTT
<a name="iot-repub-rule"></a>

Este tutorial demonstra como criar uma AWS IoT regra que publica uma mensagem MQTT quando uma mensagem MQTT especificada é recebida. A carga útil da mensagem recebida pode ser modificada pela regra antes de ser publicada. Isso possibilita a criação de mensagens personalizadas para aplicativos específicos sem a necessidade de alterar o dispositivo ou o firmware. Você também pode usar o aspecto de filtragem de uma regra para publicar mensagens somente quando uma condição específica for atendida.

As mensagens republicadas por uma regra agem como mensagens enviadas por qualquer outro AWS IoT dispositivo ou cliente. Os dispositivos podem assinar as mensagens republicadas da mesma forma que assinam qualquer outro tópico de mensagem do MQTT.

**O que você aprenderá neste tutorial:**
+ Como usar consultas e funções SQL simples em uma instrução de consulta de regra
+ Como usar o cliente MQTT para testar uma regra AWS IoT 

Este tutorial leva cerca de 30 minutos para ser concluído.

**Topics**
+ [Analise os tópicos e AWS IoT regras do MQTT](#iot-repub-rule-mqtt)
+ [Etapa 1: criar uma AWS IoT regra para republicar uma mensagem MQTT](#iot-repub-rule-define)
+ [Etapa 2: Testar a nova regra](#iot-repub-rule-test)
+ [Etapa 3: revisar os resultados e as próximas etapas](#iot-repub-rule-review)

**Antes de começar este tutorial, verifique se você tem o seguinte:**
+ 

**[Configurar Conta da AWS](setting-up.md)**  
Você precisará do seu AWS IoT console Conta da AWS e do console para concluir este tutorial.
+ 

**Revisado [Exibir mensagens MQTT com o cliente AWS IoT MQTT](view-mqtt-messages.md)**  
Certifique-se de que você pode usar o cliente MQTT para fazer a assinatura e publicar em um tópico. Você usará o cliente MQTT para testar a nova regra neste procedimento.

## Analise os tópicos e AWS IoT regras do MQTT
<a name="iot-repub-rule-mqtt"></a>

Antes de falar sobre AWS IoT regras, é útil entender o protocolo MQTT. Em soluções de IoT, o protocolo MQTT oferece algumas vantagens em relação a outros protocolos de comunicação de rede, como HTTP, o que o torna uma escolha popular para uso por dispositivos de IoT. Esta seção analisa os principais aspectos do MQTT conforme eles se aplicam a este tutorial. Para obter informações sobre como o MQTT se compara ao HTTP, consulte [Escolher um protocolo de aplicativo para a comunicação do dispositivo](protocols.md#protocol-selection).

**Protocolo MQTT**  
O protocolo MQTT usa um modelo publish/subscribe de comunicação com seu host. Para enviar dados, os dispositivos publicam mensagens identificadas por tópicos para o agente de AWS IoT mensagens. Para receber mensagens do agente de mensagens, os dispositivos assinam os tópicos que receberão enviando filtros de tópicos nas solicitações de assinatura para o agente de mensagens. O mecanismo de regras AWS IoT recebe mensagens MQTT do agente de mensagens.

**AWS IoT regras**  
AWS IoT as regras consistem em uma instrução de consulta de regras e em uma ou mais ações de regra. Quando o mecanismo de regras AWS IoT recebe uma mensagem MQTT, esses elementos agem na mensagem da seguinte maneira.
+ 

**Declaração de consulta de regra**  
A instrução de consulta da regra descreve os tópicos do MQTT a serem usados, interpreta os dados da carga útil da mensagem e formata os dados conforme descrito por uma instrução SQL semelhante às instruções usadas por bancos de dados SQL populares. O resultado da instrução de consulta são os dados enviados para as ações da regra.
+ 

**Ação da regra**  
Cada ação de regra em uma regra atua nos dados resultantes da declaração de consulta da regra. AWS IoT suporta [muitas ações de regras](iot-rule-actions.md). Neste tutorial, no entanto, você se concentrará na ação da regra [Nova publicação](republish-rule-action.md), que publica o resultado da instrução de consulta como uma mensagem MQTT com um tópico específico.

## Etapa 1: criar uma AWS IoT regra para republicar uma mensagem MQTT
<a name="iot-repub-rule-define"></a>

A AWS IoT regra que você criará neste tutorial se inscreve nos tópicos do `device/device_id/data` MQTT, onde *device\$1id* está o ID do dispositivo que enviou a mensagem. Esses tópicos são descritos por um [filtro de tópicos](topics.md#topicfilters) como`device/+/data`, em que `+` é um caractere curinga que corresponde a qualquer sequência de caracteres entre os dois caracteres de barra.

Quando a regra recebe uma mensagem de um tópico correspondente, ela republica os valores `device_id` e `temperature` e como uma nova mensagem MQTT com o tópico `device/data/temp`. 

Por exemplo, a carga útil de uma mensagem MQTT com o tópico `device/22/data` tem a seguinte aparência:

```
{
  "temperature": 28,
  "humidity": 80,
  "barometer": 1013,
  "wind": {
    "velocity": 22,
    "bearing": 255
  }
}
```

A regra pega o valor `temperature` da carga útil da mensagem e o `device_id` do tópico e os republica como uma mensagem MQTT com o tópico `device/data/temp` tópico e uma carga útil de mensagem com a seguinte aparência:

```
{
  "device_id": "22",
  "temperature": 28
}
```

Com essa regra, dispositivos que precisam apenas do ID do dispositivo e dos dados de temperatura se inscrevem no tópico `device/data/temp` para receber somente essas informações.

**Para criar uma regra que republica uma mensagem MQTT**

1. Abra [o hub de **regras** do AWS IoT console](https://console.aws.amazon.com//iot/home#/rulehub).

1. Em **Regras**, escolha **Criar** e comece a criar sua nova regra.

1. Na parte superior da opção **Criar uma regra**:

   1. Em **Nome**, insira o nome da regra. Para este tutorial, dê o nome **republish\$1temp**.

      Lembre-se de que o nome de uma regra deve ser exclusivo em sua conta e região e não pode ter espaços. Usamos um caractere sublinhado nesse nome para separar as duas palavras no nome da regra.

   1.  Em **Descrição**, descreva a regra. 

      Uma descrição significativa ajuda você a lembrar ao que essa regra se refere e por que você a criou. A descrição pode ser tão longa quanto necessário, portanto, seja o mais detalhista possível. 

1. Na **declaração de consulta de regra** de **Criar uma regra**:

   1.  Em **Uso da versão SQL**, selecione**2016-03-23**. 

   1. Na caixa de edição **Instrução de consulta de regra**, insira a instrução: 

      ```
      SELECT topic(2) as device_id, temperature FROM 'device/+/data'
      ```

      Esta declaração:
      + Recebe mensagens MQTT com um tópico que corresponda ao filtro de tópicos `device/+/data`.
      + Seleciona o segundo elemento da cadeia de caracteres do tópico e o atribui ao campo `device_id`.
      + Seleciona o campo de valor `temperature` da carga útil da mensagem e o atribui ao campo `temperature`.

1. Em **Definir uma ou mais ações**:

   1. Para abrir a lista de ações de regra para essa regra, escolha **Adicionar ação**.

   1. Em **Selecionar uma ação**, escolha **Republicar uma mensagem em um AWS IoT tópico**.

   1. Na parte inferior da lista de ações, escolha **Configurar ação** para abrir a página de configuração da ação selecionada.

1. Em **Configurar ação**:

   1.  Em **Tópico**, insira **device/data/temp**. Esse é o tópico MQTT da mensagem que essa regra publicará. 

   1.  Em **Qualidade de Serviço**, escolha **0 - A mensagem é entregue zero ou mais vezes**. 

   1.  Em **Escolha ou crie uma função para conceder AWS IoT acesso para realizar essa ação**:

      1.  Selecione **Criar perfil**. A caixa de diálogo **Criar um novo perfil** é aberta. 

      1. Insira um nome que descreva o novo perfil. Neste tutorial, use **republish\$1role**. 

         Quando você cria um novo perfil, as políticas corretas para executar a ação da regra são criadas e anexadas ao novo perfil. Se você alterar o tópico dessa ação de regra ou usar esse perfil em outra ação de regra, deverá atualizar a política desse perfil para autorizar o novo tópico ou ação. Para atualizar uma função existente, escolha **Atualizar função** nesta seção.

      1. Escolha **Criar função** para criar a função e fechar a caixa de diálogo. 

   1. Escolha **Adicionar ação** para adicionar a ação à regra e retornar à página **Criar uma regra**. 

1. A ação **Republicar uma mensagem em um AWS IoT tópico** agora está listada em **Definir uma ou mais ações**.

   No bloco da nova ação, abaixo de **Republicar uma mensagem em um AWS IoT tópico**, você pode ver o tópico no qual sua ação de republicação será publicada.

   Essa é a única ação de regra que você adicionará a essa regra.

1. Em **Criar uma regra**, desça até a parte inferior e escolha **Criar regra** para criar a regra e concluir esta etapa.

## Etapa 2: Testar a nova regra
<a name="iot-repub-rule-test"></a>

Para testar sua nova regra, você usará o cliente MQTT para publicar e assinar as mensagens MQTT usadas por essa regra.

Abra o [cliente MQTT no AWS IoT console](https://console.aws.amazon.com//iot/home#/test) em uma nova janela. Isso permitirá que você edite a regra sem perder a configuração do seu cliente MQTT. O cliente MQTT não retém nenhuma assinatura ou logs de mensagens se você deixar que ele vá para outra página no console.

**Você pode usar o cliente MQTT para testar a regra**

1. No [cliente MQTT no AWS IoT console](https://console.aws.amazon.com//iot/home#/test), assine os tópicos de entrada, neste caso, `device/+/data`.

   1. No Cliente MQTT, em **Assinaturas**, selecione **Assine um tópico**.

   1. Em **Tópico de assinatura**, insira o tópico do filtro de tópico de entrada, **device/\$1/data**.

   1. Deixe os demais campos com as configurações padrão.

   1. Escolha **Assinar um tópico**.

      Na coluna **Assinaturas**, em **Publicar em um tópico **, **device/\$1/data** é exibido. 

1. Assine o tópico que sua regra publicará: `device/data/temp`.

   1. Em **Assinaturas**, escolha **Assinar um tópico** novamente e, em **Tópico de assinatura**, insira o tópico da mensagem republicada, **device/data/temp**.

   1. Deixe os demais campos com as configurações padrão.

   1. Escolha **Assinar um tópico**.

      Na coluna **Assinaturas**, em **dispositivo/\$1/dado**, **device/data/temp** é exibido. 

1. Publique uma mensagem no tópico de entrada com um ID de dispositivo específico, **device/22/data**. Você não pode publicar nos tópicos MQTT que contenham caracteres curinga.

   1. No cliente MQTT, em **Assinaturas**, selecione **Publicar em um tópico**.

   1. No campo **Publicar**, insira o nome do tópico de entrada, **device/22/data**.

   1. Copie os dados de amostra mostrados aqui e, na caixa de edição abaixo do nome do tópico, cole os dados de amostra.

      ```
      {
        "temperature": 28,
        "humidity": 80,
        "barometer": 1013,
        "wind": {
          "velocity": 22,
          "bearing": 255
        }
      }
      ```

   1. Para enviar sua mensagem MQTT, escolha **Publicar no tópico**.

1. Revise as mensagens enviadas.

   1. No cliente MQTT, em **Assinaturas**, há um ponto verde ao lado dos dois tópicos nos quais você se inscreveu anteriormente.

      Os pontos verdes indicam que uma ou mais mensagens novas foram recebidas desde a última vez que você as viu.

   1. Em **Assinaturas**, escolha **dispositivo/\$1/dado** para verificar se a carga útil da mensagem corresponde ao que você acabou de publicar e tem a seguinte aparência:

      ```
      {
        "temperature": 28,
        "humidity": 80,
        "barometer": 1013,
        "wind": {
          "velocity": 22,
          "bearing": 255
        }
      }
      ```

   1. Em **Assinaturas**, escolha verificar se **device/data/temp**a carga útil da mensagem republicada tem a seguinte aparência:

      ```
      {
        "device_id": "22",  
        "temperature": 28
      }
      ```

      Observe que o valor `device_id` valor é uma string citada e o valor `temperature` é numérico. Isso ocorre porque a [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-function-topic](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-function-topic)função extraiu a string do nome do tópico da mensagem de entrada, enquanto o valor `temperature` usa o valor numérico da carga útil da mensagem de entrada.

      Se você quiser transformar o valor `device_id` em um valor numérico, substitua `topic(2)` na instrução de consulta de regra por:

      ```
      cast(topic(2) AS DECIMAL)
      ```

      Observe que converter o valor `topic(2)` em um valor numérico só funcionará se essa parte do tópico contiver somente caracteres numéricos.

1. Se você perceber que a mensagem correta foi publicada no **device/data/temp**tópico, sua regra funcionou. Veja o que mais você pode aprender sobre a ação da regra de republicação na próxima seção.

   Se você não ver que a mensagem correta foi publicada no **dispositivo/\$1/data** ou nos **device/data/temp**tópicos, consulte as dicas de solução de problemas.

### Solução de problemas da regra de republicação de mensagens
<a name="iot-repub-rule-trouble"></a>

Aqui estão algumas objetos para verificar caso você não esteja vendo os resultados esperados.
+ 

**Você recebeu um banner de erro**  
Se um erro apareceu quando você publicou a mensagem de entrada, corrija esse erro primeiro. As etapas a seguir podem ajudá-lo a corrigir esse erro.
+ 

**Você não vê a mensagem de entrada no cliente MQTT**  
Toda vez que você publica sua mensagem de entrada no tópico `device/22/data`, essa mensagem deve aparecer no cliente MQTT, se tiver assinado o filtro de tópicos `device/+/data` conforme descrito no procedimento.

**Pontos importantes**
  + 

**Verifique o filtro de tópicos em que você fez a assinatura**  
Se você fez a assinatura no tópico da mensagem de entrada conforme descrito no procedimento, deverá ver uma cópia da mensagem de entrada toda vez que publicá-la.

    Se você não visualizar a mensagem, verifique o nome do tópico em que você fez a assinatura e compare-o com o tópico no qual você publicou. Os nomes dos tópicos diferenciam maiúsculas de minúsculas e o tópico no qual você fez a assinatura deve ser idêntico ao tópico no qual você publicou a carga útil da mensagem.
  + 

**Verifique a função de publicação de mensagens**  
**No cliente MQTT, em **Assinaturas**, escolha **dispositivo/\$1/dados**, verifique o tópico da mensagem de publicação e escolha Publicar no tópico.** Você deve ver a carga útil da mensagem na caixa de edição abaixo do tópico aparecer na lista de mensagens. 
+ 

**Você não vê sua mensagem republicada no cliente MQTT**  
Para que sua regra funcione, ela deve ter a política correta que a autorize a receber e republicar uma mensagem e deve receber a mensagem.

**Pontos importantes**
  + 

**Verifique o Região da AWS do seu cliente MQTT e a regra que você criou**  
O console no qual você está executando o cliente MQTT deve estar na mesma região AWS da regra que você criou. 
  + 

**Verifique o tópico da mensagem de entrada na instrução de consulta da regra**  
Para que a regra funcione, ela deve receber uma mensagem com o nome do tópico que corresponda ao filtro do tópico na cláusula FROM da instrução de consulta da regra.

    Verifique a ortografia do filtro de tópico na declaração de consulta de regra com a do tópico no cliente MQTT. Os nomes dos tópicos diferenciam maiúsculas de minúsculas e o tópico da mensagem deve corresponder ao filtro de tópico na instrução de consulta da regra.
  + 

**Verifique o conteúdo da carga útil da mensagem de entrada**  
Para que a regra funcione, ela deve encontrar o campo de dados na carga da mensagem declarada na instrução SELECT.

    Verifique a ortografia do campo `temperature` na instrução de consulta da regra com a da carga útil da mensagem no cliente MQTT. Os nomes dos campos diferenciam maiúsculas de minúsculas e o campo `temperature` na instrução de consulta da regra deve ser idêntico ao campo `temperature` na carga útil da mensagem.

    Verifique se o documento JSON na carga útil da mensagem está formatado corretamente. Se o JSON tiver algum erro, como uma vírgula ausente, a regra não poderá lê-lo. 
  + 

**Verifique o tópico da mensagem republicada na ação da regra**  
O tópico no qual a ação da regra de republicação publica a nova mensagem deve corresponder ao tópico no qual você fez a assinatura no cliente MQTT.

    Abra a regra que você criou no console e verifique o tópico no qual a ação da regra republicará a mensagem.
  + 

**Verifique a função que está sendo usada pela regra**  
A ação da regra deve ter permissão para receber o tópico original e publicar o novo tópico. 

    As políticas que autorizam a regra a receber dados de mensagens e republicá-los são específicas para os tópicos usados. Se você alterar o tópico usado para republicar os dados da mensagem, deverá atualizar a função da ação de regra para atualizar sua política conforme o tópico atual.

    Se você suspeitar que esse é o problema, edite a ação da regra de republicação e crie uma nova função. As novas funções criadas pela ação da regra recebem as autorizações necessárias para realizar essas ações.

## Etapa 3: revisar os resultados e as próximas etapas
<a name="iot-repub-rule-review"></a>

**Neste tutorial**
+ Você usou uma consulta SQL simples e algumas funções em uma instrução de consulta de regra para produzir uma nova mensagem MQTT.
+ Você criou uma regra que republicou essa nova mensagem.
+ Você usou o cliente MQTT para testar sua AWS IoT regra.

**Próximas etapas**  
Depois de republicar algumas mensagens com essa regra, experimente usá-la para ver como a alteração de alguns aspectos do tutorial afeta a mensagem republicada. Aqui estão algumas ideias para você começar.
+ Altere o *device\$1id* tópico da mensagem de entrada e observe o efeito na carga útil da mensagem republicada.
+ Altere os campos selecionados na instrução de consulta de regras e observe o efeito na carga útil da mensagem republicada.
+ Experimente o próximo tutorial desta série e aprenda como [Tutorial:r Como enviar uma notificação do Amazon SNS](iot-sns-rule.md).

A ação de regra Republicar usada neste tutorial também pode ajudá-lo a depurar instruções de consulta de regras. Por exemplo, você pode adicionar essa ação a uma regra para ver como sua instrução de consulta de regra está formatando os dados usados por suas ações de regra.

# Tutorial:r Como enviar uma notificação do Amazon SNS
<a name="iot-sns-rule"></a>

Este tutorial demonstra como criar uma AWS IoT regra que envia dados de mensagens MQTT para um tópico do Amazon SNS para que possam ser enviados como uma mensagem de texto SMS. 

Neste tutorial, você cria uma regra que envia dados de mensagens de um sensor meteorológico para todos os assinantes de um tópico do Amazon SNS, sempre que a temperatura exceder o valor definido na regra. A regra detecta quando a temperatura relatada excede o valor definido pela regra e, em seguida, cria uma nova carga útil de mensagem que inclui somente a ID do dispositivo, a temperatura relatada e o limite de temperatura que foi excedido. A regra envia a nova carga útil da mensagem como um documento JSON para um tópico do SNS, que notifica todos os assinantes do tópico do SNS.

**O que você aprenderá neste tutorial:**
+ Como criar e testar uma notificação do Amazon SNS
+ Como chamar uma notificação do Amazon SNS a partir de uma regra AWS IoT 
+ Como usar consultas e funções SQL simples em uma instrução de consulta de regra
+ Como usar o cliente MQTT para testar uma regra AWS IoT 

Este tutorial leva cerca de 30 minutos para ser concluído.

**Topics**
+ [Etapa 1: criar um tópico do Amazon SNS que envia uma mensagem de texto SMS](#iot-sns-rule-create-sns-topic)
+ [Etapa 2: criar uma AWS IoT regra para enviar a mensagem de texto](#iot-sns-rule-create-rule)
+ [Etapa 3: testar a AWS IoT regra e a notificação do Amazon SNS](#iot-sns-rule-test-rule)
+ [Etapa 4: revisar os resultados e as próximas etapas](#iot-sns-rule-review-results)

**Antes de começar este tutorial, verifique se você tem o seguinte:**
+ 

**[Configurar Conta da AWS](setting-up.md)**  
Você precisará do seu AWS IoT console Conta da AWS e do console para concluir este tutorial.
+ 

**Revisado [Exibir mensagens MQTT com o cliente AWS IoT MQTT](view-mqtt-messages.md)**  
Certifique-se de que você pode usar o cliente MQTT para fazer a assinatura e publicar em um tópico. Você usará o cliente MQTT para testar a nova regra neste procedimento.
+ 

**Revisado o [Amazon Simple Notification Service](https://docs.aws.amazon.com//sns/latest/dg/welcome.html)**  
Se você nunca usou o Amazon SNS, consulte a opção [Configuração do acesso para o Amazon SNS](https://docs.aws.amazon.com//sns/latest/dg/sns-setting-up.html). Se você já concluiu outros AWS IoT tutoriais, você já Conta da AWS deve estar configurado corretamente.

## Etapa 1: criar um tópico do Amazon SNS que envia uma mensagem de texto SMS
<a name="iot-sns-rule-create-sns-topic"></a>

Esse procedimento explica como criar o tópico do Amazon SNS para o qual seu sensor meteorológico pode enviar dados de mensagens. O tópico do Amazon SNS então notificará todos os assinantes por meio de uma mensagem de texto SMS sobre o limite de temperatura que foi excedido.

**Para criar um tópico do Amazon SNS que envia uma mensagem de texto SMS**

1. **Crie um tópico do Amazon SNS**.

   1. Faça login no console [do Amazon SNS](https://console.aws.amazon.com//sns/home).

   1. No painel de navegação à esquerda, selecione **Tópicos**.

   1. Na página **Tópicos**, escolha **Criar tópico**.

   1. Em **Detalhes**, escolha o tipo **Padrão**. Por padrão, o console cria um tópico FIFO.

   1. Em **Nome**, insira o nome do tópico do SNS. Para este tutorial, insira **high\$1temp\$1notice**.

   1. Role até o final do formulário e escolha **Criar tópico**.

      O console abrirá a página **Detalhes** do tópico.

1. **Crie uma assinatura do Amazon SNS.**
**nota**  
O número de telefone que você usa nesta assinatura pode incorrer em cobranças de mensagens de texto a partir das mensagens que você enviará neste tutorial.

   1. Na página de detalhes do tópico **high\$1temp\$1notice**, selecione **Criar assinatura**.

   1. Em **Criar assinatura**, na seção **Detalhes**, na lista **Protocolo**, escolha **SMS**.

   1. No **Endpoint**, insira o número de um telefone que pode receber mensagens de texto. Certifique-se de inseri-lo de forma que comece com um `+`, inclua o código do país e da área e não inclua nenhum outro caractere de pontuação.

   1. Selecione **Criar assinatura**.

1. **Teste a notificação do Amazon SNS.**

   1. No [console Amazon SNS ](https://console.aws.amazon.com//sns/home), no painel de navegação esquerdo, selecione **Tópicos**.

   1. Para abrir a página de detalhes do tópico, em **Tópicos**, na lista de tópicos, escolha **high\$1temp\$1notice**.

   1. Para abrir a página **Publicar mensagem no tópico**, na página de detalhes **high\$1temp\$1notice**, selecione **Publicar mensagem**.

   1. Em **Publicar mensagem no tópico**, na seção **Corpo da mensagem**, em **Corpo da mensagem a ser enviada ao endpoint**, insira uma mensagem curta.

   1. Navegue para baixo até o final da página e selecione **Publicar mensagem**.

   1. No telefone com o número usado anteriormente ao criar a assinatura, confirme se a mensagem foi recebida.

   Se você não recebeu a mensagem de teste, verifique novamente o número de telefone e as configurações do seu telefone.

   Certifique-se de poder publicar mensagens de teste no [console do Amazon SNS](https://console.aws.amazon.com//sns/home) antes de continuar o tutorial.

## Etapa 2: criar uma AWS IoT regra para enviar a mensagem de texto
<a name="iot-sns-rule-create-rule"></a>

A AWS IoT regra que você criará neste tutorial se inscreve nos tópicos do `device/device_id/data` MQTT, onde `device_id` está o ID do dispositivo que enviou a mensagem. Esses tópicos são descritos em um filtro de tópicos como `device/+/data`, em que `+` é um caractere curinga que corresponde a qualquer sequência de caracteres entre os dois caracteres de barra. Essa regra também testa o valor do campo `temperature` na carga útil da mensagem.

Quando a regra recebe uma mensagem de um tópico correspondente, ela pega o valor `device_id` do nome do tópico, o valor `temperature` da carga útil da mensagem, adiciona um valor constante ao limite que está testando e envia esses valores como um documento JSON para um tópico de notificação do Amazon SNS. 

 Por exemplo, uma mensagem MQTT do dispositivo de sensor meteorológico número 32 usa o tópico `device/32/data` e tem uma carga de mensagem semelhante a esta: 

```
{
  "temperature": 38,
  "humidity": 80,
  "barometer": 1013,
  "wind": {
    "velocity": 22,
    "bearing": 255
  }
}
```

A declaração de consulta de regra da regra pega o valor `temperature` da carga útil da mensagem, `device_id` do nome do tópico e adiciona o valor `max_temperature` constante para enviar uma carga útil de mensagem semelhante a esta para o tópico do Amazon SNS: 

```
{
  "device_id": "32",
  "reported_temperature": 38,
  "max_temperature": 30
}
```

**Para criar uma AWS IoT regra para detectar um valor de temperatura acima do limite e criar os dados a serem enviados ao tópico do Amazon SNS**

1. Abra [o hub de **regras** do AWS IoT console](https://console.aws.amazon.com//iot/home#/rulehub).

1. Se essa for sua primeira regra, escolha **Criar** ou **Criar uma regra**.

1. Em **Criar uma regra**:

   1. Em **Nome**, insira **temp\$1limit\$1notify**.

      Lembre-se de que o nome de uma regra deve ser exclusivo em sua região Conta da AWS e não pode ter espaços. Usamos um caractere de sublinhado nesse nome para separar as palavras no nome da regra. 

   1. Em **Descrição**, descreva a regra.

      Uma descrição significativa facilita lembrar o que essa regra faz e por que você a criou. A descrição pode ser tão longa quanto necessário, portanto, seja o mais detalhista possível. 

1. Na **declaração de consulta de regra** de **Criar uma regra**:

   1.  Em **Uso da versão SQL**, selecione **23-03-2016**. 

   1. Na caixa de edição **Instrução de consulta de regra**, insira a instrução: 

      ```
      SELECT topic(2) as device_id, 
          temperature as reported_temperature, 
          30 as max_temperature 
        FROM 'device/+/data' 
        WHERE temperature > 30
      ```

      Esta declaração:
      + Recebe mensagens MQTT com um tópico que corresponda ao filtro de tópicos `device/+/data` e que tenha um valor `temperature` maior que 30. 
      + Seleciona o segundo elemento da cadeia de caracteres do tópico e o atribui ao campo `device_id`.
      + Seleciona o campo `temperature` de valor da carga útil da mensagem e o atribui ao campo `reported_temperature`. 
      + Cria um valor constante `30` para representar o valor limite e o atribui ao campo `max_temperature`. 

1. Para abrir a lista de ações de regra para essa regra, em **Definir uma ou mais ações**, escolha **Adicionar ação**.

1. Em **Selecionar uma ação**, selecione **Enviar uma mensagem como uma notificação por push do SNS**.

1. Para abrir a página de configuração da ação selecionada, na parte inferior da lista de ações, escolha **Configurar ação**. 

1. Em **Configurar ação**:

   1. Em **Destino do SNS**, escolha **Selecionar**, encontre seu tópico do SNS chamado **high\$1temp\$1notice** e escolha **Selecionar**.

   1. Em **Formato de mensagem**, selecione **RAW**.

   1. Em **Escolher ou criar uma função para conceder AWS IoT acesso para realizar essa ação**, escolha **Criar função**.

   1. Em **Criar uma nova função**, em **Nome**, insira um nome exclusivo para a nova função. Para este tutorial, use **sns\$1rule\$1role**.

   1. Selecione **Criar perfil**.

   Se estiver repetindo este tutorial ou reutilizando uma função existente, escolha **Atualizar função** antes de continuar. Isso atualiza o documento de política da função para funcionar com o destino do SNS.

1. Escolha **Adicionar ação** e retorne à página **Criar uma regra**.

   No quadro da nova ação, abaixo de **Enviar uma mensagem como notificação push do SNS**, você pode ver o tópico do SNS que sua regra vai chamar. 

   Essa é a única ação de regra que você adicionará a essa regra.

1. Para criar a regra e concluir essa etapa, em **Criar uma regra**, desloque o cursor para baixo até a parte inferior e escolha **Criar regra**.

## Etapa 3: testar a AWS IoT regra e a notificação do Amazon SNS
<a name="iot-sns-rule-test-rule"></a>

Para testar sua nova regra, você usará o cliente MQTT para publicar e assinar as mensagens MQTT usadas por essa regra.

Abra o [cliente MQTT no AWS IoT console](https://console.aws.amazon.com//iot/home#/test) em uma nova janela. Isso permitirá que você edite a regra sem perder a configuração do seu cliente MQTT. Se você deixar o cliente MQTT para ir para outra página no console, ele não reterá nenhuma assinatura ou logs de mensagens.

**Você pode usar o cliente MQTT para testar a regra**

1. No [cliente MQTT no AWS IoT console](https://console.aws.amazon.com//iot/home#/test), assine os tópicos de entrada, neste caso, `device/+/data`.

   1. No Cliente MQTT, em **Assinaturas**, selecione **Assine um tópico**.

   1. Em **Tópico de assinatura**, insira o tópico do filtro de tópico de entrada, **device/\$1/data**.

   1. Deixe os demais campos com as configurações padrão.

   1. Escolha **Assinar um tópico**.

      Na coluna **Assinaturas**, em **Publicar em um tópico**, **device/\$1/data** é exibido. 

1. Publique uma mensagem no tópico de entrada com um ID de dispositivo específico, **device/32/data**. Você não pode publicar nos tópicos MQTT que contenham caracteres curinga.

   1. No cliente MQTT, em **Assinaturas**, selecione **Publicar em um tópico**.

   1. No campo **Publicar**, insira o nome do tópico de entrada, **device/32/data**.

   1. Copie os dados de amostra mostrados aqui e, na caixa de edição abaixo do nome do tópico, cole os dados de amostra.

      ```
      {
        "temperature": 38,
        "humidity": 80,
        "barometer": 1013,
        "wind": {
          "velocity": 22,
          "bearing": 255
        }
      }
      ```

   1. Escolha **Publicar em um tópico** para publicar a mensagem MQTT.

1. Confirme se a mensagem de texto foi enviada.

   1. No cliente MQTT, em **Assinaturas**, há um ponto verde ao lado do tópico assinado anteriormente.

      O ponto verde indica que uma ou mais mensagens novas foram recebidas desde a última vez que você as visualizou.

   1. Em **Assinaturas**, escolha **dispositivo/\$1/dado** para verificar se a carga útil da mensagem corresponde ao que você acabou de publicar e tem a seguinte aparência:

      ```
      {
        "temperature": 38,
        "humidity": 80,
        "barometer": 1013,
        "wind": {
          "velocity": 22,
          "bearing": 255
        }
      }
      ```

   1. Verifique o telefone utilizado para assinar o tópico do SNS e confirme se o conteúdo da carga útil da mensagem tem a seguinte aparência:

      ```
      {"device_id":"32","reported_temperature":38,"max_temperature":30}
      ```

      Observe que o valor `device_id` valor é uma string citada e o valor `temperature` é numérico. Isso ocorre porque a [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-function-topic](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-function-topic)função extraiu a string do nome do tópico da mensagem de entrada, enquanto o valor `temperature` usa o valor numérico da carga útil da mensagem de entrada.

      Se você quiser transformar o valor `device_id` em um valor numérico, substitua `topic(2)` na instrução de consulta de regra por:

      ```
      cast(topic(2) AS DECIMAL)
      ```

      Observe que converter o valor `topic(2)` em um valor numérico `DECIMAL` só funcionará se essa parte do tópico contiver somente caracteres numéricos.

1. Tente enviar uma mensagem MQTT na qual a temperatura não exceda o limite.

   1. No cliente MQTT, em **Assinaturas**, selecione **Publicar em um tópico**.

   1. No campo **Publicar**, insira o nome do tópico de entrada, **device/33/data**.

   1. Copie os dados de amostra mostrados aqui e, na caixa de edição abaixo do nome do tópico, cole os dados de amostra.

      ```
      {
        "temperature": 28,
        "humidity": 80,
        "barometer": 1013,
        "wind": {
          "velocity": 22,
          "bearing": 255
        }
      }
      ```

   1. Para enviar sua mensagem MQTT, escolha **Publicar no tópico**.

   Você deve visualizar a mensagem que enviou na assinatura **device/\$1/data**. No entanto, como o valor da temperatura está abaixo da temperatura máxima na consulta da regra, você não deve receber uma mensagem de texto.

   Se não encontrar o comportamento correto, confira as dicas de solução de problemas.

### Solução de problemas da regra de mensagens do SNS
<a name="iot-sns-rule-trouble"></a>

Aqui estão algumas objetos para verificar caso você não esteja vendo os resultados esperados.
+ 

**Você recebeu um banner de erro**  
Se um erro apareceu quando você publicou a mensagem de entrada, corrija esse erro primeiro. As etapas a seguir podem ajudá-lo a corrigir esse erro.
+ 

**Você não vê a mensagem de entrada no cliente MQTT**  
Toda vez que você publica sua mensagem de entrada no tópico `device/22/data`, essa mensagem deve aparecer no cliente MQTT, se tiver assinado o filtro de tópicos `device/+/data` conforme descrito no procedimento.

**Pontos importantes**
  + 

**Verifique o filtro de tópicos em que você fez a assinatura**  
Se você fez a assinatura no tópico da mensagem de entrada conforme descrito no procedimento, deverá ver uma cópia da mensagem de entrada toda vez que publicá-la.

    Se você não visualizar a mensagem, verifique o nome do tópico em que você fez a assinatura e compare-o com o tópico no qual você publicou. Os nomes dos tópicos diferenciam maiúsculas de minúsculas e o tópico no qual você fez a assinatura deve ser idêntico ao tópico no qual você publicou a carga útil da mensagem.
  + 

**Verifique a função de publicação de mensagens**  
**No cliente MQTT, em **Assinaturas**, escolha **dispositivo/\$1/dados**, verifique o tópico da mensagem de publicação e escolha Publicar no tópico.** Você deve ver a carga útil da mensagem na caixa de edição abaixo do tópico aparecer na lista de mensagens. 
+ 

**Se você não receber uma mensagem SMS**  
Para que sua regra funcione, ela deve ter a política correta que a autorize a receber uma mensagem e enviar uma notificação do SNS, e ela deve receber a mensagem.

**Pontos importantes**
  + 

**Verifique o Região da AWS do seu cliente MQTT e a regra que você criou**  
O console no qual você está executando o cliente MQTT deve estar na mesma região AWS da regra que você criou.
  + 

**Verifique se o valor da temperatura na carga útil da mensagem excede o limite de teste**  
Se o valor da temperatura for menor ou igual a 30, conforme definido na instrução de consulta da regra, a regra não executará nenhuma das ações.
  + 

**Verifique o tópico da mensagem de entrada na instrução de consulta da regra**  
Para que a regra funcione, ela deve receber uma mensagem com o nome do tópico que corresponda ao filtro do tópico na cláusula FROM da instrução de consulta da regra.

    Verifique a ortografia do filtro de tópico na declaração de consulta de regra com a do tópico no cliente MQTT. Os nomes dos tópicos diferenciam maiúsculas de minúsculas e o tópico da mensagem deve corresponder ao filtro de tópico na instrução de consulta da regra.
  + 

**Verifique o conteúdo da carga útil da mensagem de entrada**  
Para que a regra funcione, ela deve encontrar o campo de dados na carga da mensagem declarada na instrução SELECT.

    Verifique a ortografia do campo `temperature` na instrução de consulta da regra com a da carga útil da mensagem no cliente MQTT. Os nomes dos campos diferenciam maiúsculas de minúsculas e o campo `temperature` na instrução de consulta da regra deve ser idêntico ao campo `temperature` na carga útil da mensagem.

    Verifique se o documento JSON na carga útil da mensagem está formatado corretamente. Se o JSON tiver algum erro, como uma vírgula ausente, a regra não poderá lê-lo.
  + 

**Verifique o tópico da mensagem republicada na ação da regra**  
O tópico no qual a ação da regra de republicação publica a nova mensagem deve corresponder ao tópico no qual você fez a assinatura no cliente MQTT.

    Abra a regra que você criou no console e verifique o tópico no qual a ação da regra republicará a mensagem.
  + 

**Verifique a função que está sendo usada pela regra**  
A ação da regra deve ter permissão para receber o tópico original e publicar o novo tópico. 

    As políticas que autorizam a regra a receber dados de mensagens e republicá-los são específicas para os tópicos usados. Se você alterar o tópico usado para republicar os dados da mensagem, deverá atualizar a função da ação de regra para atualizar sua política conforme o tópico atual.

    Se você suspeitar que esse é o problema, edite a ação da regra de republicação e crie uma nova função. As novas funções criadas pela ação da regra recebem as autorizações necessárias para realizar essas ações.

## Etapa 4: revisar os resultados e as próximas etapas
<a name="iot-sns-rule-review-results"></a>

**Neste tutorial:**
+ Você criou e testou um tópico e uma assinatura de notificação do Amazon SNS.
+ Você usou uma consulta SQL simples e funções em uma consulta de regra para criar uma nova mensagem para sua notificação.
+ Você criou uma AWS IoT regra para enviar uma notificação do Amazon SNS usando sua carga de mensagem personalizada.
+ Você usou o cliente MQTT para testar sua AWS IoT regra.

**Próximas etapas**  
Depois de enviar algumas mensagens de texto com essa regra, experimente usá-la para ver como a alteração de alguns aspectos do tutorial afeta a mensagem e quando ela é enviada. Aqui estão algumas ideias para você começar.
+ Altere o *device\$1id* tópico da mensagem de entrada e observe o efeito no conteúdo da mensagem de texto.
+ Altere os campos selecionados na consulta da regra e observe o efeito no conteúdo da mensagem de texto.
+ Altere o teste na consulta da regra para testar uma temperatura mínima em vez de uma temperatura máxima. Lembre-se de mudar o nome de `max_temperature`\$1
+ Adicione uma ação de regra de republicação para enviar uma mensagem MQTT quando uma notificação do SNS for enviada.
+ Experimente o próximo tutorial desta série e aprenda como [Tutorial: Armazenamento de dados do dispositivo em uma tabela do DynamoDB](iot-ddb-rule.md).

# Tutorial: Armazenamento de dados do dispositivo em uma tabela do DynamoDB
<a name="iot-ddb-rule"></a>

Este tutorial demonstra como criar uma AWS IoT regra que envia dados de mensagens para uma tabela do DynamoDB.

Neste tutorial, você cria uma regra que envia dados das mensagens de um dispositivo de sensor climático imaginário para uma tabela do DynamoDB. A regra formata os dados de vários sensores meteorológicos para que possam ser adicionados a uma única tabela de banco de dados.

**O que você aprenderá neste tutorial**
+ Como criar uma tabela do DynamoDB
+ Como enviar dados de mensagens para uma tabela do DynamoDB a partir de uma regra AWS IoT 
+ Como usar modelos de substituição em uma regra AWS IoT 
+ Como usar consultas e funções SQL simples em uma instrução de consulta de regra
+ Como usar o cliente MQTT para testar uma regra AWS IoT 

Este tutorial leva cerca de 30 minutos para ser concluído.

**Topics**
+ [Etapa 1: Criar a tabela no DynamoDB para este tutorial](#iot-ddb-rule-ddb-table)
+ [Etapa 2: criar uma AWS IoT regra para enviar dados para a tabela do DynamoDB](#iot-ddb-rule-topic-rule)
+ [Etapa 3: testar a AWS IoT regra e a tabela do DynamoDB](#iot-ddb-rule-test)
+ [Etapa 4: revisar os resultados e as próximas etapas](#iot-ddb-rule-review)

**Antes de começar este tutorial, verifique se você tem o seguinte:**
+ 

**[Configurar Conta da AWS](setting-up.md)**  
Você precisará do seu AWS IoT console Conta da AWS e do console para concluir este tutorial.
+ 

**Revisado [Exibir mensagens MQTT com o cliente AWS IoT MQTT](view-mqtt-messages.md)**  
Certifique-se de que você pode usar o cliente MQTT para fazer a assinatura e publicar em um tópico. Você usará o cliente MQTT para testar a nova regra neste procedimento.
+ 

**Analisada a visão geral do [Amazon DynamoDB](https://docs.aws.amazon.com//amazondynamodb/latest/developerguide/Introduction.html)**  
Se você nunca usou o DynamoDB, consulte [Getting Started with DynamoDB](https://docs.aws.amazon.com//amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) para se familiarizar com os conceitos e operações básicos do DynamoDB.

## Etapa 1: Criar a tabela no DynamoDB para este tutorial
<a name="iot-ddb-rule-ddb-table"></a>

Neste tutorial, você criará uma tabela do DynamoDB com esses atributos para registrar os dados dos dispositivos imaginários de sensores climáticos: 
+ `sample_time` é uma chave primária e descreve a hora em que a amostra foi registrada.
+ `device_id` é uma chave de classificação e descreve o dispositivo que forneceu a amostra 
+ `device_data` são os dados recebidos do dispositivo e formatados pela instrução de consulta de regra

**Para criar uma tabela do DynamoDB para este tutorial**

1. Abra o [console DynamoDB](https://console.aws.amazon.com//dynamodb/home), e selecione **Criar tabela**.

1. Em **Criar tabela**:

   1.  Em **Nome da tabela**, insira o nome da tabela: **wx\$1data**.

   1. Em **Chave de partição** insira **sample\$1time**, e na lista de opções ao lado do campo, escolha**Number**.

   1. Em **Chave de classificação**, insira **device\$1id**, e, na lista de opções ao lado do campo, escolha**Number**.

   1. Na parte inferior da página, selecione **Criar**.

Você definirá `device_data` posteriormente, quando configurar a ação da regra do DynamoDB.

## Etapa 2: criar uma AWS IoT regra para enviar dados para a tabela do DynamoDB
<a name="iot-ddb-rule-topic-rule"></a>

Nesta etapa, você usará a consulta de regras para formatar os dados dos dispositivos imaginários de sensores climáticos para gravar na tabela do banco de dados.

Um exemplo de carga útil de mensagem recebida de um dispositivo de sensor climático tem o seguinte aspecto:

```
{
  "temperature": 28,
  "humidity": 80,
  "barometer": 1013,
  "wind": {
    "velocity": 22,
    "bearing": 255
  }
}
```

Para a entrada do banco de dados, você usará a instrução de consulta de regra para nivelar a estrutura da carga útil da mensagem para ficar dessa forma:

```
{
  "temperature": 28,
  "humidity": 80,
  "barometer": 1013,
  "wind_velocity": 22,
  "wind_bearing": 255
}
```

Nessa regra, você também usará alguns [Modelos de substituição](iot-substitution-templates.md). Os modelos de substituição são expressões que permitem inserir valores dinâmicos de funções e dados de mensagens.

**Para criar a AWS IoT regra para enviar dados para a tabela do DynamoDB**

1. Abra o hub [ Regras do AWS IoT console](https://console.aws.amazon.com//iot/home#/rulehub). Ou você pode abrir a AWS IoT página inicial em Console de gerenciamento da AWS e navegar até **Roteamento de mensagens>** Regras.

1. Para começar a criar sua nova regra em **Regras**, escolha **Criar regra**.

1. Em **Propriedades da regra**:

   1. Em **Nome do perfil**, insira **wx\$1data\$1ddb**.

      Lembre-se de que o nome de uma regra deve ser exclusivo em sua região Conta da AWS e não pode ter espaços. Usamos um caractere sublinhado nesse nome para separar as duas palavras no nome da regra.

   1. Em **Descrição da regra**, descreva a regra.

      Uma descrição significativa facilita lembrar o que essa regra faz e por que você a criou. A descrição pode ser tão longa quanto necessário, portanto, seja o mais detalhista possível. 

1. Escolha **Próximo** para continuar.

1. Em **instrução SQL**:

   1. Na **versão SQL**, selecione**2016-03-23**.

   1. Na caixa de edição da **instrução SQL**, insira a instrução: 

      ```
      SELECT temperature, humidity, barometer,
        wind.velocity as wind_velocity,
        wind.bearing as wind_bearing,
      FROM 'device/+/data'
      ```

      Esta declaração:
      + Recebe mensagens MQTT com um tópico que corresponda ao filtro de tópicos `device/+/data`.
      + Formata os elementos do atributo `wind` como atributos individuais.
      + Transmite o `temperature`, `humidity` e atributos inalterados `barometer`.

1. Escolha **Próximo** para continuar.

1. Em **Ações de regra**:

   1. Para abrir a lista de ações de regra para essa regra, na **Ação 1**, escolha **DynamoDB**.
**nota**  
Certifique-se de escolher o DynamoDB e não o DBv2 Dynamo como ação de regra.

   1. Em **Nome da tabela**, escolha o nome da tabela do DynamoDB que você criou na etapa anterior: **wx\$1data**.

      Os campos **Tipo de chave de partição** e **Tipo de chave de classificação** são preenchidos com os valores da tabela do DynamoDB.

   1. Em **Chave de partição**, insira **sample\$1time**.

   1. Em **Valor da chave de partição**, insira **\$1\$1timestamp()\$1**.

      Esse é o primeiro dos [Modelos de substituição](iot-substitution-templates.md) que você usará nesta regra. Em vez de usar um valor da carga da mensagem, ele usará o valor retornado da função de datação. Para saber mais, consulte [Datação](iot-sql-functions.md#iot-function-timestamp) na *AWS IoT Core Guia do desenvolvedor*.

   1. Em **Chave de classificação**, insira **device\$1id**.

   1. Em **Valor da chave de classificação**, insira **\$1\$1cast(topic(2) AS DECIMAL)\$1**.

      Esse é o segundo dos [Modelos de substituição](iot-substitution-templates.md) que você vai usar nesta regra. Ele insere o valor do segundo elemento no nome do tópico, que é o ID do dispositivo, depois de convertê-lo em um valor DECIMAL para corresponder ao formato numérico da chave. Para saber mais sobre tópicos, consulte [Tópicos](iot-sql-functions.md#iot-function-topic) no *Guia do desenvolvedor da AWS IoT Core *. Ou, para saber mais sobre a transmissão, consulte [Orientação](iot-sql-functions.md#iot-sql-function-cast) no *AWS IoT Core Guia do desenvolvedor*.

   1. Na coluna **Gravar os dados da mensagem nesta coluna**, insira **device\$1data**.

      Isso criará a coluna `device_data` na tabela do DynamoDB.

   1. Deixe o campo **Operação** em branco.

   1. Em **Perfil do IAM**, selecione **Criar novo perfil**.

   1. Na caixa de diálogo **Criar perfil**, em **Nome do perfil**, insira **wx\$1ddb\$1role**. Essa nova função conterá automaticamente uma política com o prefixo "aws-iot-rule" que permitirá que a **wx\$1data\$1ddb** regra envie dados para a tabela do **wx\$1data** DynamoDB que você criou.

   1. Em **Perfil do IAM**, escolha **wx\$1ddb\$1role**.

   1. Na parte inferior da página, selecione a opção **Próximo**.

1. Na parte inferior da página **Revisar e criar**, escolha a opção **Criar** para criar a regra.

## Etapa 3: testar a AWS IoT regra e a tabela do DynamoDB
<a name="iot-ddb-rule-test"></a>

Para testar a nova regra, você usará o cliente MQTT para publicar e assinar as mensagens MQTT usadas neste teste.

Abra o [cliente MQTT no AWS IoT console](https://console.aws.amazon.com//iot/home#/test) em uma nova janela. Isso permitirá que você edite a regra sem perder a configuração do seu cliente MQTT. O cliente MQTT não retém nenhuma assinatura ou logs de mensagens se você deixar que ele vá para outra página no console. Você também desejará que uma janela de console separada seja aberta para o [hub do DynamoDB Tables no console para visualizar AWS IoT as](https://console.aws.amazon.com//dynamodb/home#tables:) novas entradas que sua regra envia.

**Você pode usar o cliente MQTT para testar a regra**

1. No [cliente MQTT no AWS IoT console](https://console.aws.amazon.com//iot/home#/test), assine o tópico de entrada,`device/+/data`.

   1. No cliente MQTT, escolha **Assinar um tópico**.

   1. Em **Filtro de tópicos**, insira o tópico do filtro de tópico de entrada, **device/\$1/data**.

   1. Escolha **Assinar**.

1. Agora, publique uma mensagem no tópico de entrada com um ID de dispositivo específico, **device/22/data**. Você não pode publicar nos tópicos MQTT que contenham caracteres curinga.

   1. No cliente MQTT, escolha **Publicar em um tópico**.

   1. Em **Nome do tópico**, insira um nome para o tópico, **device/22/data**.

   1. Em **Carga útil da mensagem**, insira os seguintes dados de exemplo.

      ```
      {
        "temperature": 28,
        "humidity": 80,
        "barometer": 1013,
        "wind": {
          "velocity": 22,
          "bearing": 255
        }
      }
      ```

   1. Para publicar a mensagem MQTT, escolha **Publicar**.

   1. Agora, no cliente MQTT, escolha **Assinar um tópico**. Na coluna **Assinar**, escolha a assinatura **device/\$1/data**. Confirme se os dados de amostra da etapa anterior aparecem.

1. Verifique se consegue visualizar a linha na tabela do DynamoDB que sua regra criou.

   1. **No [hub do DynamoDB Tables no console, escolha wx\$1data e, em AWS IoT](https://console.aws.amazon.com//dynamodb/home#tables:) **seguida, escolha** a guia Itens.**

      Se você já estiver na guia **Itens**, talvez precise atualizar a exibição selecionando o ícone de atualização no canto superior direito do cabeçalho da tabela.

   1. Observe que os valores de **sample\$1time** na tabela são links. Abra um. Se acabou de enviar a primeira mensagem, ela será a única na lista.

      Esse link exibe todos os dados nessa linha da tabela.

   1. Expanda a entrada **device\$1data** para ver os dados que resultaram da consulta da regra.

   1. Explore as diferentes representações dos dados disponíveis nessa exibição. Você também pode editar os dados nessa exibição.

   1. Depois de concluir a revisão dessa linha de dados, para salvar as alterações feitas, escolha a opção **Salvar** ou, para sair sem salvar nenhuma alteração, escolha **Cancelar**.

Se não encontrar o comportamento correto, confira as dicas de solução de problemas.

### Solução de problemas da regra do DynamoDB
<a name="iot-ddb-rule-trouble"></a>

Aqui estão algumas objetos para verificar caso você não esteja vendo os resultados esperados.
+ 

**Você recebeu um banner de erro**  
Se um erro apareceu quando você publicou a mensagem de entrada, corrija esse erro primeiro. As etapas a seguir podem ajudá-lo a corrigir esse erro.
+ 

**Você não vê a mensagem de entrada no cliente MQTT**  
Toda vez que você publica sua mensagem de entrada no tópico `device/22/data`, essa mensagem deve aparecer no cliente MQTT, se tiver assinado o filtro de tópicos `device/+/data` conforme descrito no procedimento.

**Pontos importantes**
  + 

**Verifique o filtro de tópicos em que você fez a assinatura**  
Se você fez a assinatura no tópico da mensagem de entrada conforme descrito no procedimento, deverá ver uma cópia da mensagem de entrada toda vez que publicá-la.

    Se você não visualizar a mensagem, verifique o nome do tópico em que você fez a assinatura e compare-o com o tópico no qual você publicou. Os nomes dos tópicos diferenciam maiúsculas de minúsculas e o tópico no qual você fez a assinatura deve ser idêntico ao tópico no qual você publicou a carga útil da mensagem.
  + 

**Verifique a função de publicação de mensagens**  
**No cliente MQTT, em **Assinaturas**, escolha **dispositivo/\$1/dados**, verifique o tópico da mensagem de publicação e escolha Publicar no tópico.** Você deve ver a carga útil da mensagem na caixa de edição abaixo do tópico aparecer na lista de mensagens. 
+ 

**Você não vê os dados na tabela do DynamoDB**  
A primeiro objeto a fazer é atualizar a exibição selecionando o ícone de atualização no canto superior direito do cabeçalho da tabela. Se os dados que você está procurando não forem exibidos, verifique o seguinte.

**Pontos importantes**
  + 

**Verifique o Região da AWS do seu cliente MQTT e a regra que você criou**  
O console no qual você está executando o cliente MQTT deve estar na mesma região AWS da regra que você criou. 
  + 

**Verifique o tópico da mensagem de entrada na instrução de consulta da regra**  
Para que a regra funcione, ela deve receber uma mensagem com o nome do tópico que corresponda ao filtro do tópico na cláusula FROM da instrução de consulta da regra.

    Verifique a ortografia do filtro de tópico na declaração de consulta de regra com a do tópico no cliente MQTT. Os nomes dos tópicos diferenciam maiúsculas de minúsculas e o tópico da mensagem deve corresponder ao filtro de tópico na instrução de consulta da regra.
  + 

**Verifique o conteúdo da carga útil da mensagem de entrada**  
Para que a regra funcione, ela deve encontrar o campo de dados na carga da mensagem declarada na instrução SELECT.

    Verifique a ortografia do campo `temperature` na instrução de consulta da regra com a da carga útil da mensagem no cliente MQTT. Os nomes dos campos diferenciam maiúsculas de minúsculas e o campo `temperature` na instrução de consulta da regra deve ser idêntico ao campo `temperature` na carga útil da mensagem.

    Verifique se o documento JSON na carga útil da mensagem está formatado corretamente. Se o JSON tiver algum erro, como uma vírgula ausente, a regra não poderá lê-lo. 
  + 

**Verifique os nomes da chave e do campo usados na ação da regra**  
Os nomes de campo usados na regra de tópico devem corresponder aos encontrados na carga útil da mensagem JSON da mensagem publicada.

    Abra a regra criada no console e verifique os nomes dos campos na configuração da ação da regra com aqueles usados no cliente MQTT.
  + 

**Verifique a função que está sendo usada pela regra**  
A ação da regra deve ter permissão para receber o tópico original e publicar o novo tópico. 

    As políticas que autorizam a regra a receber dados de mensagens e atualizar a tabela do DynamoDB são específicas para os tópicos utilizados. Se você alterar o tópico ou o nome da tabela do DynamoDB usado pela regra, deverá atualizar a função da ação da regra para que a política esteja de acordo.

    Se você suspeitar que esse é o problema, edite a ação da regra e crie um novo perfil. As novas funções criadas pela ação da regra recebem as autorizações necessárias para realizar essas ações.

## Etapa 4: revisar os resultados e as próximas etapas
<a name="iot-ddb-rule-review"></a>

Depois de enviar algumas mensagens para a tabela do DynamoDB com essa regra, experimente usá-la para ver como a alteração de alguns aspectos do tutorial afeta os dados gravados na tabela. Aqui estão algumas ideias para você começar.
+ Altere o tópico da mensagem de entrada e observe o efeito nos dados. *device\$1id* Você pode usar isso para simular o recebimento de dados de vários sensores meteorológicos.
+ Altere os campos selecionados na instrução de consulta da regra e observe o efeito nos dados. Você pode usar isso para filtrar os dados armazenados na tabela.
+ Adicione uma ação de regra de republicação para enviar uma mensagem MQTT para cada linha adicionada à tabela. Você pode usar isso para depuração.

Depois de concluir este tutorial, confira [Tutorial: Formatando uma notificação usando uma função AWS Lambda](iot-lambda-rule.md).

# Tutorial: Formatando uma notificação usando uma função AWS Lambda
<a name="iot-lambda-rule"></a>

Este tutorial demonstra como enviar dados da mensagem MQTT para uma AWS Lambda ação para formatação e envio para outro serviço. AWS Neste tutorial, a AWS Lambda ação usa o AWS SDK para enviar a mensagem formatada para o tópico do Amazon SNS que você criou no tutorial sobre como fazer isso. [Tutorial:r Como enviar uma notificação do Amazon SNS](iot-sns-rule.md)

No tutorial sobre como fazer isso[Tutorial:r Como enviar uma notificação do Amazon SNS](iot-sns-rule.md), o documento JSON resultante da instrução de consulta da regra foi enviado como o corpo da mensagem de texto. O resultado foi uma mensagem de texto parecida com o seguinte exemplo:

```
{"device_id":"32","reported_temperature":38,"max_temperature":30}
```

Neste tutorial, você usará uma ação de AWS Lambda regra para chamar uma AWS Lambda função que formata os dados da instrução de consulta de regra em um formato mais amigável, como este exemplo:

```
Device 32 reports a temperature of 38, which exceeds the limit of 30.
```

A AWS Lambda função que você criará neste tutorial formata a string da mensagem usando os dados da declaração de consulta de regra e chama a função de [publicação do SNS](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sns.html#SNS.Client.publish) do AWS SDK para criar a notificação.

**O que você aprenderá neste tutorial**
+ Como criar e testar uma AWS Lambda função
+ Como usar o AWS SDK em uma AWS Lambda função para publicar uma notificação do Amazon SNS
+ Como usar consultas e funções SQL simples em uma instrução de consulta de regra
+ Como usar o cliente MQTT para testar uma regra AWS IoT 

Este tutorial leva cerca de 45 minutos para ser concluído.

**Topics**
+ [Etapa 1: criar uma AWS Lambda função que envie uma mensagem de texto](#iot-lambda-rule-create-lambda)
+ [Etapa 2: criar uma AWS IoT regra com uma ação de AWS Lambda regra](#iot-lambda-rule-create-rule)
+ [Etapa 3: testar a AWS IoT regra e a ação da AWS Lambda regra](#iot-lambda-rule-test-rule)
+ [Etapa 4: revisar os resultados e as próximas etapas](#iot-lambda-rule-next-steps)

**Antes de começar este tutorial, verifique se você tem o seguinte:**
+ 

**[Configurar Conta da AWS](setting-up.md)**  
Você precisará do seu AWS IoT console Conta da AWS e do console para concluir este tutorial.
+ 

**Revisado [Exibir mensagens MQTT com o cliente AWS IoT MQTT](view-mqtt-messages.md)**  
Certifique-se de que você pode usar o cliente MQTT para fazer a assinatura e publicar em um tópico. Você usará o cliente MQTT para testar a nova regra neste procedimento.
+ 

**Concluídos os outros tutoriais de regras desta seção**  
Este tutorial requer o tópico de notificação do SNS que você criou no tutorial sobre como fazer isso [Tutorial:r Como enviar uma notificação do Amazon SNS](iot-sns-rule.md). Também pressupõe que você tenha concluído os outros tutoriais relacionados às regras nesta seção.
+ 

**Revisou a visão geral do [AWS Lambda](https://docs.aws.amazon.com//lambda/latest/dg/welcome.html)**  
Se você nunca usou AWS Lambda antes, revise [AWS Lambda](https://docs.aws.amazon.com//lambda/latest/dg/welcome.html)e [Comece a usar o Lambda](https://docs.aws.amazon.com//lambda/latest/dg/getting-started.html) para aprender seus termos e conceitos.

## Etapa 1: criar uma AWS Lambda função que envie uma mensagem de texto
<a name="iot-lambda-rule-create-lambda"></a>

A AWS Lambda função neste tutorial recebe o resultado da declaração de consulta da regra, insere os elementos em uma string de texto e envia a string resultante para o Amazon SNS como mensagem em uma notificação.

Ao contrário do tutorial sobre como[Tutorial:r Como enviar uma notificação do Amazon SNS](iot-sns-rule.md), que usou uma ação de AWS IoT regra para enviar a notificação, este tutorial envia a notificação da função Lambda usando uma função do AWS SDK. No entanto, o tópico real de notificação do Amazon SNS usado neste tutorial é o mesmo que você usou no tutorial sobre como fazer isso [Tutorial:r Como enviar uma notificação do Amazon SNS](iot-sns-rule.md).

**Para criar uma AWS Lambda função que envia uma mensagem de texto**

1. Crie uma nova AWS Lambda função.

   1. No [AWS Lambda console](https://console.aws.amazon.com//lambda/home), selecione **Criar função**.

   1. Em **Criar função**, selecione **Usar um esquema**.

      Pesquise e selecione o esquema **hello-world-python** e, em seguida, escolha **Configurar**.

   1. Em **Informações básicas**:

      1. Em **Nome do perfil**, insira o nome da função, **format-high-temp-notification**. 

      1. Em **Função de execução**, escolha **Criar uma nova função a partir de modelos de AWS política**.

      1. No campo Nome do perfil, digite o nome da nova função, **format-high-temp-notification-role**.

      1. Em **Modelos de política - *opcional***, pesquise e selecione a política ** de publicação do Amazon SNS**.

      1. Escolha a opção **Criar função**.

1. Modifique o código do esquema para formatar e enviar uma notificação do Amazon SNS.

   1. Depois de criar sua função, você deverá ver a página de **format-high-temp-notification**detalhes. Caso contrário, abra-a na página [Função **do Lambda**](https://console.aws.amazon.com//lambda/home#/functions)

   1. Na página de **format-high-temp-notification**detalhes, escolha a guia **Configuração** e vá até o painel **Código da função**.

   1. Na janela **Código da função**, no painel **Ambiente**, escolha o arquivo Python, `lambda_function.py`.

   1. Na janela **Código da função**, exclua todo o código original do programa do esquema e substitua-o por esse código.

      ```
      import boto3
      #
      #   expects event parameter to contain:
      #   {
      #       "device_id": "32",
      #       "reported_temperature": 38,
      #       "max_temperature": 30,
      #       "notify_topic_arn": "arn:aws:sns:us-east-1:57EXAMPLE833:high_temp_notice"
      #   }
      # 
      #   sends a plain text string to be used in a text message
      #
      #      "Device {0} reports a temperature of {1}, which exceeds the limit of {2}."
      #   
      #   where:
      #       {0} is the device_id value
      #       {1} is the reported_temperature value
      #       {2} is the max_temperature value
      #
      def lambda_handler(event, context):
      
          # Create an SNS client to send notification
          sns = boto3.client('sns')
      
          # Format text message from data
          message_text = "Device {0} reports a temperature of {1}, which exceeds the limit of {2}.".format(
                  str(event['device_id']),
                  str(event['reported_temperature']),
                  str(event['max_temperature'])
              )
      
          # Publish the formatted message
          response = sns.publish(
                  TopicArn = event['notify_topic_arn'],
                  Message = message_text
              )
      
          return response
      ```

   1. Escolha **Implantar**.

1. Em uma nova janela, consulte o nome do recurso da Amazon (ARN) do tópico do Amazon SNS no tutorial sobre como fazer isso [Tutorial:r Como enviar uma notificação do Amazon SNS](iot-sns-rule.md).

   1. Em uma nova janela, abra o console [página Tópicos no console do Amazon SNS](https://console.aws.amazon.com//sns/v3/home#/topics). 

   1. Na página **Tópicos**, encontre o tópico de notificação **high\$1temp\$1notice** na lista de tópicos do Amazon SNS.

   1. Encontre o **ARN** do tópico de notificação **high\$1temp\$1notice** para usar na próxima etapa.

1. Crie um caso de teste para sua função do Lambda.

   1. Na página [Lambda **Functions**](https://console.aws.amazon.com//lambda/home#/functions) do console, na página de **format-high-temp-notification**detalhes, escolha **Selecionar um evento de teste** no canto superior direito da página (mesmo que pareça desativado) e escolha **Configurar eventos de teste**.

   1. Em **Selecionar um evento de teste**, escolha **Configurar evento de teste**.

   1. Em **Nome do evento**, insira **SampleRuleOutput**.

   1. No editor JSON abaixo do **Nome do evento**, cole esse exemplo de documento JSON. Esse é um exemplo do que sua AWS IoT regra enviará para a função Lambda.

      ```
      {
        "device_id": "32",
        "reported_temperature": 38,
        "max_temperature": 30,
        "notify_topic_arn": "arn:aws:sns:us-east-1:57EXAMPLE833:high_temp_notice"
      }
      ```

   1. Consulte a janela que tem o **ARN** do tópico de notificação **high\$1temp\$1notice** e copie o valor do ARN.

   1. Substitua o valor `notify_topic_arn` no editor JSON pelo ARN do seu tópico de notificação.

      Mantenha essa janela aberta para que você possa usar esse valor de ARN novamente ao criar a regra AWS IoT .

   1. Escolha **Criar**.

1. Teste a função com dados de amostra.

   1. Na página de **format-high-temp-notification**detalhes, no canto superior direito da página, confirme que **SampleRuleOutput**aparece ao lado do botão **Testar**. Caso contrário, selecione-o na lista de eventos de teste disponíveis.

   1. Para enviar a mensagem de saída da regra de amostra para a função, escolha **Testar**.

Se a função e a notificação funcionarem, você receberá uma mensagem de texto no telefone de assinatura da notificação.

Se você não recebeu uma mensagem de texto no telefone, verifique o resultado da operação. No painel **Código da função**, na guia **Resultado da execução**, revise a resposta para encontrar quaisquer erros ocorridos. Não prossiga para a próxima etapa até que sua função possa enviar a notificação para seu telefone.

## Etapa 2: criar uma AWS IoT regra com uma ação de AWS Lambda regra
<a name="iot-lambda-rule-create-rule"></a>

Nesta etapa, você usará a instrução de consulta de regras para formatar os dados do dispositivo de sensor climático imaginário para enviar para uma função do Lambda, que formatará e enviará uma mensagem de texto.

Um exemplo de carga útil de mensagem recebida dos dispositivos meteorológicos tem a seguinte aparência:

```
{
  "temperature": 28,
  "humidity": 80,
  "barometer": 1013,
  "wind": {
    "velocity": 22,
    "bearing": 255
  }
}
```

Nessa regra, você usará a instrução de consulta de regras para criar uma carga útil de mensagem para a função do Lambda que se parece com esta:

```
{
  "device_id": "32",
  "reported_temperature": 38,
  "max_temperature": 30,
  "notify_topic_arn": "arn:aws:sns:us-east-1:57EXAMPLE833:high_temp_notice"
}
```

Ela contém todas as informações que a função do Lambda precisa para formatar e enviar a mensagem de texto correta.

**Para criar a AWS IoT regra para chamar uma função Lambda**

1. Abra o [hub de **regras** do AWS IoT console](https://console.aws.amazon.com//iot/home#/rulehub).

1. Para começar a criar sua nova regra em **Regras**, escolha a opção **Criar**.

1. Na parte superior da opção **Criar uma regra**:

   1. Em **Nome**, insira o nome da regra, **wx\$1friendly\$1text**.

      Lembre-se de que o nome de uma regra deve ser exclusivo em sua região Conta da AWS e não pode ter espaços. Usamos um caractere sublinhado nesse nome para separar as duas palavras no nome da regra.

   1.  Em **Descrição**, descreva a regra. 

      Uma descrição significativa facilita lembrar o que essa regra faz e por que você a criou. A descrição pode ser tão longa quanto necessário, portanto, seja o mais detalhista possível. 

1. Na **declaração de consulta de regra** de **Criar uma regra**:

   1.  Em **Uso da versão SQL**, selecione**2016-03-23**. 

   1. Na caixa de edição **Instrução de consulta de regra**, insira a instrução: 

      ```
      SELECT 
        cast(topic(2) AS DECIMAL) as device_id, 
        temperature as reported_temperature,
        30 as max_temperature,
        'arn:aws:sns:us-east-1:57EXAMPLE833:high_temp_notice' as notify_topic_arn
      FROM 'device/+/data' WHERE temperature > 30
      ```

      Esta declaração:
      + Recebe mensagens MQTT com um tópico que corresponda ao filtro de tópicos `device/+/data` e que tenha um valor `temperature` maior que 30. 
      + Seleciona o segundo elemento da cadeia de caracteres do tópico, converte-o em um número decimal e o atribui ao campo `device_id`.
      + Seleciona o valor do campo `temperature` na carga da mensagem e o atribui ao campo `reported_temperature`. 
      + Cria um valor constante, `30`, para representar o valor limite e o atribui ao campo `max_temperature`. 
      + Cria um valor constante para o campo `notify_topic_arn`.

   1. Consulte a janela que tem o **ARN** do tópico de notificação **high\$1temp\$1notice** e copie o valor do ARN.

   1. Substitua o valor do ARN (*arn:aws:sns:us-east-1:57EXAMPLE833:high\$1temp\$1notice*) no editor de instruções de consulta de regras pelo ARN do seu tópico de notificação.

1. Em **Definir uma ou mais ações**:

   1. Para abrir a lista de ações de regra para essa regra, escolha **Adicionar ação**.

   1. Em **Selecionar uma ação**, escolha **Enviar uma mensagem para uma função do Lambda**.

   1. Para abrir a página de configuração da ação selecionada, na parte inferior da lista de ações, escolha **Configurar ação**.

1. Em **Configurar ação**:

   1. Em **Nome do perfil**, escolha **Selecionar**.

   1. Selecione **format-high-temp-notification**.

   1. Na parte inferior da opção **Configurar ação**, escolha **Adicionar ação**.

   1. Para criar a regra, na parte inferior da opção **Criar uma regra**, escolha **Criar regra**.

## Etapa 3: testar a AWS IoT regra e a ação da AWS Lambda regra
<a name="iot-lambda-rule-test-rule"></a>

Para testar sua nova regra, você usará o cliente MQTT para publicar e assinar as mensagens MQTT usadas por essa regra.

Abra o [cliente MQTT no AWS IoT console](https://console.aws.amazon.com//iot/home#/test) em uma nova janela. Agora você pode editar a regra sem perder a configuração do cliente MQTT. Se você deixar o cliente MQTT para ir para outra página no console, perderá as assinaturas ou registros de mensagens.

**Você pode usar o cliente MQTT para testar a regra**

1. No [cliente MQTT no AWS IoT console](https://console.aws.amazon.com//iot/home#/test), assine os tópicos de entrada, neste caso, `device/+/data`.

   1. No Cliente MQTT, em **Assinaturas**, selecione **Assine um tópico**.

   1. Em **Tópico de assinatura**, insira o tópico do filtro de tópico de entrada, **device/\$1/data**.

   1. Deixe os demais campos com as configurações padrão.

   1. Escolha **Assinar um tópico**.

      Na coluna **Assinaturas**, em **Publicar em um tópico**, **device/\$1/data** é exibido. 

1. Publique uma mensagem no tópico de entrada com um ID de dispositivo específico, **device/32/data**. Você não pode publicar nos tópicos MQTT que contenham caracteres curinga.

   1. No cliente MQTT, em **Assinaturas**, selecione **Publicar em um tópico**.

   1. No campo **Publicar**, insira o nome do tópico de entrada, **device/32/data**.

   1. Copie os dados de amostra mostrados aqui e, na caixa de edição abaixo do nome do tópico, cole os dados de amostra.

      ```
      {
        "temperature": 38,
        "humidity": 80,
        "barometer": 1013,
        "wind": {
          "velocity": 22,
          "bearing": 255
        }
      }
      ```

   1. Escolha **Publicar em um tópico** para publicar sua mensagem MQTT.

1. Confirme se a mensagem de texto foi enviada.

   1. No cliente MQTT, em **Assinaturas**, há um ponto verde ao lado do tópico assinado anteriormente.

      O ponto verde indica que uma ou mais mensagens novas foram recebidas desde a última vez que você as visualizou.

   1. Em **Assinaturas**, escolha **dispositivo/\$1/dado** para verificar se a carga útil da mensagem corresponde ao que você acabou de publicar e tem a seguinte aparência:

      ```
      {
        "temperature": 38,
        "humidity": 80,
        "barometer": 1013,
        "wind": {
          "velocity": 22,
          "bearing": 255
        }
      }
      ```

   1. Verifique o telefone utilizado para assinar o tópico do SNS e confirme se o conteúdo da carga útil da mensagem tem a seguinte aparência:

      ```
      Device 32 reports a temperature of 38, which exceeds the limit of 30.
      ```

      Se você alterar o elemento ID do tópico no tópico da mensagem, lembre-se de que converter o valor `topic(2)` em um valor numérico só funcionará se esse elemento no tópico da mensagem contiver somente caracteres numéricos.

1. Tente enviar uma mensagem MQTT na qual a temperatura não exceda o limite.

   1. No cliente MQTT, em **Assinaturas**, selecione **Publicar em um tópico**.

   1. No campo **Publicar**, insira o nome do tópico de entrada, **device/33/data**.

   1. Copie os dados de amostra mostrados aqui e, na caixa de edição abaixo do nome do tópico, cole os dados de amostra.

      ```
      {
        "temperature": 28,
        "humidity": 80,
        "barometer": 1013,
        "wind": {
          "velocity": 22,
          "bearing": 255
        }
      }
      ```

   1. Para enviar sua mensagem MQTT, escolha **Publicar no tópico**.

   Você deve ver a mensagem que enviou na assinatura **device/\$1/data**; no entanto, como o valor da temperatura está abaixo da temperatura máxima na consulta da regra, você não deve receber uma mensagem de texto.

   Se não encontrar o comportamento correto, confira as dicas de solução de problemas.

### Solução de problemas com sua AWS Lambda regra e notificação
<a name="iot-lambda-rule-troubleshoot"></a>

Aqui estão algumas objetos para verificar caso você não esteja vendo os resultados esperados.
+ 

**Você recebeu um banner de erro**  
Se um erro apareceu quando você publicou a mensagem de entrada, corrija esse erro primeiro. As etapas a seguir podem ajudá-lo a corrigir esse erro.
+ 

**Você não vê a mensagem de entrada no cliente MQTT**  
Toda vez que você publica sua mensagem de entrada no tópico `device/32/data`, essa mensagem deve aparecer no cliente MQTT, se tiver assinado o filtro de tópicos `device/+/data` conforme descrito no procedimento.

**Pontos importantes**
  + 

**Verifique o filtro de tópicos em que você fez a assinatura**  
Se você fez a assinatura no tópico da mensagem de entrada conforme descrito no procedimento, deverá ver uma cópia da mensagem de entrada toda vez que publicá-la.

    Se você não visualizar a mensagem, verifique o nome do tópico em que você fez a assinatura e compare-o com o tópico no qual você publicou. Os nomes dos tópicos diferenciam maiúsculas de minúsculas e o tópico no qual você fez a assinatura deve ser idêntico ao tópico no qual você publicou a carga útil da mensagem.
  + 

**Verifique a função de publicação de mensagens**  
**No cliente MQTT, em **Assinaturas**, escolha **dispositivo/\$1/dados**, verifique o tópico da mensagem de publicação e escolha Publicar no tópico.** Você deve ver a carga útil da mensagem na caixa de edição abaixo do tópico aparecer na lista de mensagens. 
+ 

**Se você não receber uma mensagem SMS**  
Para que sua regra funcione, ela deve ter a política correta que a autorize a receber uma mensagem e enviar uma notificação do SNS, e ela deve receber a mensagem.

**Pontos importantes**
  + 

**Verifique o Região da AWS do seu cliente MQTT e a regra que você criou**  
O console no qual você está executando o cliente MQTT deve estar na mesma região AWS da regra que você criou.
  + 

**Verifique se o valor da temperatura na carga útil da mensagem excede o limite de teste**  
Se o valor da temperatura for menor ou igual a 30, conforme definido na instrução de consulta da regra, a regra não executará nenhuma das ações.
  + 

**Verifique o tópico da mensagem de entrada na instrução de consulta da regra**  
Para que a regra funcione, ela deve receber uma mensagem com o nome do tópico que corresponda ao filtro do tópico na cláusula FROM da instrução de consulta da regra.

    Verifique a ortografia do filtro de tópico na declaração de consulta de regra com a do tópico no cliente MQTT. Os nomes dos tópicos diferenciam maiúsculas de minúsculas e o tópico da mensagem deve corresponder ao filtro de tópico na instrução de consulta da regra.
  + 

**Verifique o conteúdo da carga útil da mensagem de entrada**  
Para que a regra funcione, ela deve encontrar o campo de dados na carga da mensagem declarada na instrução SELECT.

    Verifique a ortografia do campo `temperature` na instrução de consulta da regra com a da carga útil da mensagem no cliente MQTT. Os nomes dos campos diferenciam maiúsculas de minúsculas e o campo `temperature` na instrução de consulta da regra deve ser idêntico ao campo `temperature` na carga útil da mensagem.

    Verifique se o documento JSON na carga útil da mensagem está formatado corretamente. Se o JSON tiver algum erro, como uma vírgula ausente, a regra não poderá lê-lo.
  + 

**Verifique a notificação do Amazon SNS**  
Em[Etapa 1: criar um tópico do Amazon SNS que envia uma mensagem de texto SMS](iot-sns-rule.md#iot-sns-rule-create-sns-topic), consulte a etapa 3 que descreve como testar a notificação do Amazon SNS e testar a notificação para garantir que a notificação funcione.
  + 

**Verifique a função do Lambda**  
Em [Etapa 1: criar uma AWS Lambda função que envie uma mensagem de texto](#iot-lambda-rule-create-lambda), consulte a etapa 5 que descreve como testar a função do Lambda usando dados de teste e testar a função do Lambda.
  + 

**Verifique a função que está sendo usada pela regra**  
A ação da regra deve ter permissão para receber o tópico original e publicar o novo tópico. 

    As políticas que autorizam a regra a receber dados de mensagens e republicá-los são específicas para os tópicos usados. Se você alterar o tópico usado para republicar os dados da mensagem, deverá atualizar a função da ação de regra para atualizar sua política conforme o tópico atual.

    Se você suspeitar que esse é o problema, edite a ação da regra de republicação e crie uma nova função. As novas funções criadas pela ação da regra recebem as autorizações necessárias para realizar essas ações.

## Etapa 4: revisar os resultados e as próximas etapas
<a name="iot-lambda-rule-next-steps"></a>

**Neste tutorial:**
+ Você criou uma AWS IoT regra para chamar uma função Lambda que enviou uma notificação do Amazon SNS usando sua carga de mensagem personalizada.
+ Você usou uma consulta SQL simples e funções em uma instrução de consulta de regra para criar uma nova carga de mensagem para a função do Lambda.
+ Você usou o cliente MQTT para testar sua AWS IoT regra.

**Próximas etapas**  
Depois de enviar algumas mensagens de texto com essa regra, experimente usá-la para ver como a alteração de alguns aspectos do tutorial afeta a mensagem e quando ela é enviada. Aqui estão algumas ideias para você começar.
+ Altere o *device\$1id* tópico da mensagem de entrada e observe o efeito no conteúdo da mensagem de texto.
+ Altere os campos selecionados na instrução de consulta de regras, atualize a função do Lambda para usá-los em uma nova mensagem e observe o efeito no conteúdo da mensagem de texto.
+ Altere o teste na consulta da regra para testar uma temperatura mínima em vez de uma temperatura máxima. Atualize a função do Lambda para formatar uma nova mensagem e lembre-se de alterar o nome de `max_temperature`.
+ Para saber mais sobre como encontrar erros que possam ocorrer durante o desenvolvimento e o uso de AWS IoT regras, consulte[Monitoramento AWS IoT](monitoring_overview.md).

# Reter o estado do dispositivo enquanto o dispositivo está off-line com as sombras do dispositivo
<a name="iot-shadows-tutorial"></a>

Esses tutoriais mostram como usar o serviço AWS IoT Device Shadow para armazenar e atualizar as informações de estado de um dispositivo. O documento Shadow, que é um documento JSON, mostra a alteração no estado do dispositivo com base nas mensagens publicadas por um dispositivo, aplicativo local ou serviço. Neste tutorial, o documento Shadow mostra a mudança na cor de uma lâmpada. Esses tutoriais também mostram como a sombra armazena essas informações mesmo quando o dispositivo está desconectado da Internet e passa as informações de estado mais recentes para o dispositivo quando ele volta a ficar on-line e solicita essas informações.

Recomendamos que você veja esses tutoriais na ordem em que são mostrados aqui, começando com os recursos AWS IoT que você precisa criar e a configuração de hardware necessária, o que também ajuda você a aprender os conceitos de forma incremental. Esses tutoriais mostram como configurar e conectar um dispositivo Raspberry Pi para uso com. AWS IoT Se você não tiver o hardware necessário, poderá seguir esses tutoriais adaptando-os a um dispositivo de sua escolha ou [criando um dispositivo virtual com o Amazon EC2](creating-a-virtual-thing.md).

**Visão geral do cenário do tutorial**  
O cenário desses tutoriais é um aplicativo ou serviço local que altera a cor de uma lâmpada e publica seus dados em tópicos de sombra reservados. Esses tutoriais são semelhantes à funcionalidade Sombra do Dispositivo descrita no [tutorial interativo de introdução](interactive-demo.md) e são implementados em um dispositivo Raspberry Pi. Os tutoriais nesta seção concentram-se em uma única sombra clássica e mostram como você pode acomodar sombras nomeadas ou vários dispositivos.

Os tutoriais a seguir ajudarão você a aprender como usar o serviço AWS IoT Device Shadow.
+ 

**[Tutorial: preparando seu Raspberry Pi para executar o aplicativo de sombra](create-resources-shadow.md)**  
Este tutorial mostra como configurar um dispositivo Raspberry Pi para conexão com o. AWS IoT Você também criará um documento de AWS IoT política e um recurso, baixará os certificados e anexará a política a esse recurso. Este tutorial leva cerca de 30 minutos para ser concluído.
+ 

**[Tutorial: instalando o Device SDK e executando o aplicativo de amostra para Sombras do Dispositivo](lightbulb-shadow-application.md)**  
Este tutorial mostra como instalar as ferramentas e o software necessários e o AWS IoT Device SDK para Python e, em seguida, executar o aplicativo shadow de amostra. Este tutorial se baseia nos conceitos apresentados em [Conectar um Raspberry Pi ou outro dispositivo](connecting-to-existing-device.md) e leva 20 minutos para ser concluído.
+ 

**[Tutorial: interagindo com a Sombra do Dispositivo usando o aplicativo de amostra e o cliente de teste MQTT](interact-lights-device-shadows.md)**  
Este tutorial mostra como você usa o aplicativo e o **AWS IoT console** de `shadow.py` amostra para observar a interação entre AWS IoT Device Shadows e as mudanças de estado da lâmpada. O tutorial também mostra como enviar mensagens MQTT para os tópicos reservados da Sombra do Dispositivo. A conclusão deste tutorial pode levar cerca de 45 minutos.

**AWS IoT Visão geral do Device Shadow**  
Um Device Shadow é uma representação virtual persistente de um dispositivo gerenciado por um [recurso](iot-thing-management.md) criado por você no AWS IoT registro. O documento Shadow é um documento JSON ou de JavaScript notação usado para armazenar e recuperar as informações do estado atual de um dispositivo. Você pode usar a sombra para obter e definir o estado de um dispositivo por meio de tópicos do MQTT ou HTTP REST APIs, independentemente de o dispositivo estar conectado à Internet.

Um documento de sombra contém uma `state` propriedade que descreve esses aspectos do estado do dispositivo.
+ `desired`: Os aplicativos especificam os estados desejados das propriedades do dispositivo atualizando o objeto `desired`.
+ `reported`: Os dispositivos relatam seu estado atual no objeto `reported`.
+ `delta`: AWS IoT relata diferenças entre o estado desejado e o estado relatado no `delta` objeto.

Veja um exemplo de documento do estado de sombra.

```
{
  "state": {
    "desired": {
      "color": "green"
      },
    "reported": {
      "color": "blue"
      },
    "delta": {
      "color": "green"
      }
   }
}
```

Para atualizar o documento Shadow de um dispositivo, você pode usar os [tópicos reservados do MQTT](reserved-topics.md#reserved-topics-shadow), o [Device Shadow REST APIs](device-shadow-rest-api.md) que suporta o`GET`,`UPDATE`, e `DELETE` as operações com HTTP e a [AWS IoT CLI](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/index.html).

No exemplo anterior, digamos que você queira alterar a cor `desired` para `yellow`. Para fazer isso, envie uma solicitação para a API [UpdateThingShadow](device-shadow-rest-api.md#API_UpdateThingShadow) ou publique uma mensagem no tópico [Atualizar](device-shadow-mqtt.md#update-pub-sub-topic), `$aws/things/THING_NAME/shadow/update`.

```
{
  "state": {
    "desired": {
      "color": yellow
    }
  }
}
```

As atualizações afetam apenas os campos especificados na solicitação. Depois de atualizar com sucesso o Device Shadow, AWS IoT publica o novo `desired` estado no `delta` tópico,`$aws/things/THING_NAME/shadow/delta`. O documento de sombra, nesse caso, tem a seguinte aparência:

```
{
  "state": {
    "desired": {
      "color": yellow
    },
    "reported": {
      "color": green
    },
    "delta": {
      "color": yellow
      }
  }
}
```

O novo estado é então reportado ao AWS IoT Device Shadow usando o `Update` tópico `$aws/things/THING_NAME/shadow/update` com a seguinte mensagem JSON: 

```
{
  "state": {
    "reported": {
      "color": yellow
    }
  }
}
```

Se você quiser obter as informações do estado atual, envie uma solicitação para a API [GetThingShadow](device-shadow-rest-api.md#API_GetThingShadow) ou publique uma mensagem MQTT no tópico [Obter](device-shadow-mqtt.md#get-pub-sub-topic), `$aws/things/THING_NAME/shadow/get`.

Para obter mais informações sobre como usar o serviço de sombra do dispositivo, consulte [AWS IoT Serviço Device Shadow](iot-device-shadows.md).

Para obter mais informações sobre o uso de sombra do dispositivo em dispositivos, aplicativos e serviços, consulte [Usar sombras em dispositivos](device-shadow-comms-device.md) e [Usar sombras em aplicativos e serviços](device-shadow-comms-app.md).

Para obter informações sobre como interagir com AWS IoT sombras, consulte. [Interagir com sombras](device-shadow-data-flow.md)

Para obter informações sobre os tópicos reservados do MQTT e o HTTP REST APIs, consulte [Tópicos MQTT da Sombra do Dispositivo](device-shadow-mqtt.md) e. [API REST da Sombra do Dispositivo](device-shadow-rest-api.md)

# Tutorial: preparando seu Raspberry Pi para executar o aplicativo de sombra
<a name="create-resources-shadow"></a>

Este tutorial demonstra como instalar e configurar um dispositivo Raspberry Pi e criar os AWS IoT recursos necessários para um dispositivo se conectar e trocar mensagens MQTT.

**nota**  
Se estiver planejando [Criar um dispositivo virtual com o Amazon EC2](creating-a-virtual-thing.md), ignore esta página e avance para [Configurar o dispositivo](configure-device.md). Você criará estes recursos quando criar suo objeto virtual. Se você quiser usar um dispositivo diferente em vez do Raspberry Pi, tente seguir esses tutoriais adaptando-os a um dispositivo de sua escolha.

**Neste tutorial, você aprenderá:**
+ Configure um dispositivo Raspberry Pi e configure-o para uso com AWS IoT.
+ Crie um documento AWS IoT de política que autorize seu dispositivo a interagir com os AWS IoT serviços.
+ Crie um recurso de coisa nos certificados AWS IoT do dispositivo X.509 e, em seguida, anexe o documento de política.

  A objeto é a representação virtual de seu dispositivo no registro do AWS IoT . O certificado autentica seu dispositivo no AWS IoT Core, e o documento de política autoriza seu dispositivo a interagir com. AWS IoT

**Como executar este tutorial**  
Para executar o aplicativo de exemplo das Sombras do Dispositivo `shadow.py`, você precisará de um dispositivo Raspberry Pi que se conecte ao AWS IoT. Recomendamos que você siga este tutorial na ordem apresentada aqui, começando com a configuração do Raspberry Pi e seus acessórios e, em seguida, criando uma política e anexando a política a um recurso criado por você. Em seguida, você pode seguir este tutorial usando a interface gráfica do usuário (GUI) suportada pelo Raspberry Pi para abrir o AWS IoT console no navegador da web do dispositivo, o que também facilita o download dos certificados diretamente no Raspberry Pi para conexão. AWS IoT

**Antes de começar este tutorial, verifique se você tem o seguinte:**
+ Um Conta da AWS. Se você não possuir uma, conclua as etapas descritas em [Configurar Conta da AWS](setting-up.md) antes de continuar. Você precisará do seu AWS IoT console Conta da AWS e do console para concluir este tutorial. 
+ O Raspberry Pi e seus acessórios necessários. Você precisará de:
  + Um [Modelo B do Raspberry Pi 3](https://www.raspberrypi.com/products/) ou modelo mais recente. Este tutorial pode funcionar em versões anteriores do Raspberry Pi, mas não o testamos.
  + [Raspberry Pi OS (32 bits)](https://www.raspberrypi.com/software/operating-systems/) ou uma versão posterior. Recomendamos usar a versão mais recente do SO do Raspberry Pi. Versões anteriores do SO podem funcionar, mas nós não as testamos.
  + Uma conexão Ethernet ou Wi-Fi.
  + Teclado, mouse, monitor, cabos e fontes de alimentação.

Este tutorial leva cerca de 30 minutos para ser concluído.

## Etapa 1: instalar e configurar o dispositivo Raspberry Pi
<a name="setup-device-shadow"></a>

Nesta seção, configuraremos um dispositivo Raspberry Pi para uso com AWS IoT.

**Importante**  
Adaptar estas instruções a outros dispositivos e sistemas operacionais pode ser um desafio. Você precisará conhecer seu dispositivo o bastante para interpretar estas instruções e aplicá-las ao seu dispositivo. Se encontrar dificuldades, você pode tentar uma das outras opções de dispositivo como alternativa, como [Criar um dispositivo virtual com o Amazon EC2](creating-a-virtual-thing.md) ou [Use seu PC Windows ou Linux ou Mac como um AWS IoT dispositivo](using-laptop-as-device.md). 

Você precisará configurar seu Raspberry Pi para que ele possa iniciar o sistema operacional (SO), conectar-se à Internet e permitir que você interaja com ele em uma interface de linha de comando. Você também pode usar a interface gráfica do usuário (GUI) compatível com o Raspberry Pi para abrir o AWS IoT console e executar o restante deste tutorial.

**Para configurar o Raspberry Pi**

1. Insira o cartão SD no slot para cartão MicroSD do Raspberry Pi. Alguns cartões SD vêm pré-carregados com um gerenciador de instalação que exibe um menu para instalar o sistema operacional após inicializar a placa. Você também pode usar o Raspberry Pi Imager para instalar o sistema operacional em sua placa.

1. Conecte uma TV ou monitor HDMI ao cabo HDMI que se conecta à porta HDMI do Raspberry Pi. 

1. Conecte o teclado e o mouse às portas USB do Raspberry Pi e, em seguida, conecte o adaptador de alimentação para inicializar a placa.

Após a inicialização do Raspberry Pi, se o cartão SD vier pré-carregado com o gerenciador de instalação, aparecerá um menu para instalar o sistema operacional. Se tiver problemas para instalar o sistema operacional, você pode tentar as etapas a seguir. Para obter mais informações sobre como configurar o Raspberry Pi, consulte [Configurando o Raspberry Pi](https://projects.raspberrypi.org/en/projects/raspberry-pi-setting-up/).

**Se você estiver com problemas para configurar o Raspberry Pi:**
+ Verifique se você inseriu o cartão SD antes de inicializar a placa. Se você conectar o cartão SD após inicializar a placa, o menu de instalação pode não aparecer.
+ Verifique se a TV ou o monitor estão ligados e se a entrada correta está selecionada.
+ Verifique se você está usando um software compatível com Raspberry Pi.

Depois de instalar e configurar o sistema operacional Raspberry Pi, abra o navegador da Web do Raspberry Pi e navegue até o AWS IoT Core console para continuar as demais etapas deste tutorial.

Se você conseguir abrir o AWS IoT Core console, seu Raspberry Pi está pronto e você pode continuar[Tutorial: Provisionando seu dispositivo em AWS IoT](shadow-provision-cloud.md).

Se você estiver com problemas ou precisar de ajuda adicional, consulte [Como obter ajuda para seu Raspberry Pi](https://projects.raspberrypi.org/en/projects/raspberry-pi-setting-up/5).

# Tutorial: Provisionando seu dispositivo em AWS IoT
<a name="shadow-provision-cloud"></a>

Esta seção cria os AWS IoT Core recursos que seu tutorial usará.

**Topics**
+ [Etapa 1: Criar uma AWS IoT política para o Device Shadow](#create-policy-shadow)
+ [Etapa 2: criar um recurso de objeto e vincular a política ao objeto](#create-thing-shadow)
+ [Etapa 3: revisar os resultados e as próximas etapas](#resources-shadow-review)

## Etapa 1: Criar uma AWS IoT política para o Device Shadow
<a name="create-policy-shadow"></a>

Certificados X.509 com os quais autenticam seu dispositivo. AWS IoT Core AWS IoT as políticas são anexadas ao certificado que permite ao dispositivo realizar AWS IoT operações, como assinar ou publicar tópicos reservados do MQTT usados pelo serviço Device Shadow. Seu dispositivo apresenta seu certificado quando se conecta e envia mensagens para AWS IoT Core o. 

Siga as etapas para criar uma política que permita que o dispositivo execute as operações do AWS IoT que são necessárias para executar o programa de exemplo. Recomendamos que você crie uma política que conceda apenas as permissões necessárias para executar a tarefa. Você cria a AWS IoT política primeiro e depois a anexa ao certificado do dispositivo que você criará posteriormente.

**Para criar uma AWS IoT política**

1. No menu à esquerda, escolha **Seguro** e escolha **Políticas**. Se sua conta tiver políticas existentes, escolha **Criar**, caso contrário, na página **Você ainda não tem uma política**, escolha **Criar uma política**.

1. Na página **Criar uma política**:

   1. No campo **Nome**, insira um nome para a política (por exemplo, **My\$1Device\$1Shadow\$1policy**). Não use informações de identificação pessoal nos nomes de política.

   1. No documento de política, você descreve ações de conexão, assinatura, recebimento e publicação que dão permissão ao dispositivo para publicar e assinar os tópicos reservados do MQTT.

      Copie o exemplo de política a seguir e cole-o em seu documento de política. `thingname`Substitua pelo nome da coisa que você criará (por exemplo,`My_light_bulb`), `region` pela AWS IoT região em que você está usando os serviços e `account` pelo seu Conta da AWS número. Para obter mais informações sobre AWS IoT políticas, consulte[AWS IoT Core políticas](iot-policies.md).  
****  

      ```
      {
          "Version":"2012-10-17",		 	 	 
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "iot:Publish"
                  ],
                  "Resource": [
                      "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/get",
                      "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/update"
                  ]
              },
              {
                  "Effect": "Allow",
                  "Action": [
                      "iot:Receive"
                  ],
                  "Resource": [
                      "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/get/accepted",
                      "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/get/rejected",
                      "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/update/accepted",
                      "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/update/rejected",
                      "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/update/delta"
                  ]
              },
              {
                  "Effect": "Allow",
                  "Action": [
                      "iot:Subscribe"
                  ],
                  "Resource": [
                      "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingname/shadow/get/accepted",
                      "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingname/shadow/get/rejected",
                      "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingname/shadow/update/accepted",
                      "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingname/shadow/update/rejected",
                      "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingname/shadow/update/delta"
                  ]
              },
              {
                  "Effect": "Allow",
                  "Action": "iot:Connect",
                  "Resource": "arn:aws:iot:us-east-1:123456789012:client/test-*"
              }
          ]
      }
      ```

## Etapa 2: criar um recurso de objeto e vincular a política ao objeto
<a name="create-thing-shadow"></a>

Os dispositivos conectados AWS IoT podem ser representados por *recursos de coisas* no AWS IoT registro. Um *recurso de objeto* representa um dispositivo específico ou uma entidade lógica, como a lâmpada deste tutorial.

Para aprender a criar algo em AWS IoT, siga as etapas descritas em[Criar um objeto](create-iot-resources.md#create-aws-thing). Aqui estão algumas objetos importantes a serem observadas ao seguir as etapas desse tutorial:

1. Escolha **Criar uma único objeto** e, no campo **Nome**, insira um nome para o objeto que seja igual ao `thingname` (por exemplo, `My_light_bulb`) que você especificou quando criou a política anteriormente.

   Não é possível alterar um nome de objeto após sua criação. Se você deu a ele um nome diferente de `thingname`, crie um objeto nova com o nome como `thingname` e exclua o objeto antiga.
**nota**  
Não use informações de identificação pessoal nos nomes de objetos. O nome do objeto pode surgir em comunicações e relatórios não criptografados.

1. Recomendamos que você baixe cada um dos arquivos de certificado na página **Certificado criado\$1** em um local onde você possa encontrá-los facilmente. Você precisará instalar esses arquivos para executar o aplicativo de amostra.

   Recomendamos que você baixe os arquivos em um subdiretório `certs` em seu diretório `home` no Raspberry Pi e nomeie cada um deles com um nome mais simples, conforme sugerido na tabela a seguir.  
**Nomes de arquivos de certificado**    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/shadow-provision-cloud.html)

1. Depois de ativar o certificado para habilitar conexões AWS IoT, escolha **Anexar uma política** e certifique-se de anexar a política que você criou anteriormente (por exemplo,**My\$1Device\$1Shadow\$1policy**) à coisa.

   Depois de criar uma coisa, você pode ver seu recurso exibido na lista de itens no AWS IoT console.

## Etapa 3: revisar os resultados e as próximas etapas
<a name="resources-shadow-review"></a>

**Neste tutorial, você aprendeu a:**
+ Instalar e configurar o dispositivo Raspberry Pi.
+ Crie um documento AWS IoT de política que autorize seu dispositivo a interagir com os AWS IoT serviços.
+ Crie um recurso de objeto e um certificado de dispositivo X.509 associado e anexe o documento de política a ele.

**Próximas etapas**  
Agora você pode instalar o SDK do AWS IoT dispositivo para Python, executar `shadow.py` o aplicativo de amostra e usar Device Shadows para controlar o estado. Para obter mais informações sobre como executar este tutorial, consulte [Tutorial: instalando o Device SDK e executando o aplicativo de amostra para Sombras do Dispositivo](lightbulb-shadow-application.md).

# Tutorial: instalando o Device SDK e executando o aplicativo de amostra para Sombras do Dispositivo
<a name="lightbulb-shadow-application"></a>

Esta seção mostra como você pode instalar o software necessário e o AWS IoT Device SDK para Python e executar `shadow.py` o aplicativo de amostra para editar o documento Shadow e controlar o estado do shadow. 

**Neste tutorial, você aprenderá:**
+ Use o software instalado e o AWS IoT Device SDK for Python para executar o aplicativo de amostra.
+ Saiba como inserir um valor usando o aplicativo de exemplo publica o valor desejado no console AWS IoT .
+ Revise o aplicativo de amostra `shadow.py` e como ele usa o protocolo MQTT para atualizar o estado da sombra.

**Antes de executar este tutorial:**  
Você deve ter configurado seu Conta da AWS dispositivo Raspberry Pi e criado uma AWS IoT política que dê ao dispositivo permissões para publicar e assinar os tópicos reservados do MQTT do serviço Device Shadow. Para obter mais informações, consulte [Tutorial: preparando seu Raspberry Pi para executar o aplicativo de sombra](create-resources-shadow.md).

Você também deve ter instalado o Git, o Python e o Device AWS IoT SDK for Python. Este tutorial se baseia nos conceitos apresentados no tutorial [Conectar um Raspberry Pi ou outro dispositivo](connecting-to-existing-device.md). Se você ainda não experimentou esse tutorial, recomendamos que siga as etapas descritas nesse tutorial para instalar os arquivos de certificado e o SDK do dispositivo e, em seguida, volte a este tutorial para executar o aplicativo de amostra `shadow.py`.

**Topics**
+ [Etapa 1: execute o aplicativo de exemplo shadow.py](#run-sample-application-shadows)
+ [Etapa 2: revise o aplicativo de amostra do SDK do dispositivo shadow.py](#review-shadow-sample-code)
+ [Etapa 3: solucionar problemas com o aplicativo de amostra `shadow.py`](#shadow-sample-app-troubleshoot)
+ [Etapa 4: revisar os resultados e as próximas etapas](#sample-app-shadow-review)

Este tutorial leva cerca de 20 minutos para ser concluído.

## Etapa 1: execute o aplicativo de exemplo shadow.py
<a name="run-sample-application-shadows"></a>

Antes de executar o aplicativo de amostra `shadow.py`, você precisará das informações a seguir, além dos nomes e do local dos arquivos de certificado instalados.


**Valores de parâmetros de aplicação**  

|  Parâmetro  |  Onde encontrar o valor  | 
| --- | --- | 
| your-iot-thing-name |  Nome da AWS IoT coisa que você criou anteriormente em[Etapa 2: criar um recurso de objeto e vincular a política ao objeto](shadow-provision-cloud.md#create-thing-shadow). Para encontrar esse valor, no [AWS IoT console](https://console.aws.amazon.com/iot/home), escolha **Gerenciar** e, em seguida, escolha **Objetos**.  | 
| your-iot-endpoint |   O *your-iot-endpoint* valor tem um formato de:`endpoint_id-ats.iot.region.amazonaws.com`, por exemplo,`a3qj468EXAMPLE-ats.iot.us-west-2.amazonaws.com`. Para localizar este valor: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/lightbulb-shadow-application.html)  | 

**Instalar e executar o aplicativo de exemplo**

1. Navegue até o diretório do aplicativo de exemplo.

   ```
   cd ~/aws-iot-device-sdk-python-v2/samples/service-clients
   ```

1. Na janela da linha de comando, substitua *your-iot-endpoint* e *your-iot-thing-name* conforme indicado e execute esse comando.

   ```
   python3 shadow.py --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint --thing_name your-iot-thing-name
   ```

1. Observe que o aplicativo de exemplo:

   1. Conecta-se ao serviço de AWS IoT da sua conta.

   1. Assina eventos `Delta` e respostas `Update` e `Get`.

   1. Solicita que você insira o valor desejado no terminal.

   1. Exibe uma saída semelhante à seguinte:

   ```
   Connecting to a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com with client ID 'test-0c8ae2ff-cc87-49d2-a82a-ae7ba1d0ca5a'...
   Connected!
   Subscribing to Delta events...
   Subscribing to Update responses...
   Subscribing to Get responses...
   Requesting current shadow state...
   Launching thread to read user input...
   Finished getting initial shadow state.
   Shadow contains reported value 'off'.
   Enter desired value:
   ```

**nota**  
Se você estiver com problemas para executar o aplicativo de amostra `shadow.py`, examine [Etapa 3: solucionar problemas com o aplicativo de amostra `shadow.py`](#shadow-sample-app-troubleshoot). Para obter informações adicionais que possam ajudá-lo a corrigir o problema, adicione o parâmetro `--verbosity debug` à linha de comando para que o aplicativo de amostra exiba mensagens detalhadas sobre o que está fazendo.

**Insira valores e observe as atualizações no documento de sombra**  
Você pode inserir valores no terminal para especificar o valor `desired`, o que também atualiza o valor `reported`. Digamos que você insira a cor `yellow` no terminal. O valor `reported` também é atualizado para a cor `yellow`. O seguinte mostra as mensagens exibidas no terminal:

```
Enter desired value:
yellow
Changed local shadow value to 'yellow'.
Updating reported shadow value to 'yellow'...
Update request published.
Finished updating reported shadow value to 'yellow'.
```

Quando você publica essa solicitação de atualização, AWS IoT cria uma sombra clássica padrão para o recurso thing. Você pode observar a solicitação de atualização que você publicou nos `desired` valores `reported` e no AWS IoT console examinando o documento Shadow do recurso que você criou (por exemplo,`My_light_bulb`). Para ver a atualização no documento de sombra:

1. No AWS IoT console, escolha **Gerenciar** e, em seguida, escolha **Coisas**.

1. Na lista de itens exibidos, selecione o que você criou, escolha **Sombras** e, em seguida, escolha **Sombra clássica**.

O documento de sombra deve ser semelhante ao seguinte, mostrando os valores `reported` e `desired` definidos para a cor `yellow`. Você vê esses valores na seção **Estado da sombra** do documento.

```
{
"desired": {
  "welcome": "aws-iot",
  "color": "yellow"
},
"reported": {
  "welcome": "aws-iot",
  "color": "yellow"
}
}
```

Você também vê uma seção de **Metadados** que contém as informações de data e hora e o número da versão da solicitação.

Você pode usar a versão do documento de estado para garantir que está atualizando a versão mais recente de um documento de sombra do dispositivo. Se você enviar outra solicitação de atualização, o número da versão será incrementado em 1. Ao fornecer uma versão com uma solicitação de atualização, o serviço rejeitará a solicitação com um código de resposta de conflito HTTP 409 se a versão atual do documento de estado não corresponder à versão fornecida. 

```
{
"metadata": {
  "desired": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620156893
    }
  },
  "reported": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620156893
    }
  }
},
"version": 10
}
```

Para saber mais sobre o documento de sombra e observar as alterações nas informações de estado, vá para o próximo tutorial [Tutorial: interagindo com a Sombra do Dispositivo usando o aplicativo de amostra e o cliente de teste MQTT](interact-lights-device-shadows.md) conforme descrito na seção [Etapa 4: revisar os resultados e as próximas etapas](#sample-app-shadow-review) deste tutorial. Opcionalmente, você também pode aprender sobre o código de amostra `shadow.py` e como ele usa o protocolo MQTT na seção a seguir.

## Etapa 2: revise o aplicativo de amostra do SDK do dispositivo shadow.py
<a name="review-shadow-sample-code"></a>

Esta seção analisa o aplicativo de amostra `shadow.py` do **AWS IoT Device SDK v2 para Python** usado neste tutorial. Aqui, analisaremos como ele se conecta AWS IoT Core usando o protocolo MQTT e MQTT over WSS. A biblioteca [AWS common runtime (AWS-CRT)](https://github.com/awslabs/aws-crt-python#aws-crt-python) fornece suporte ao protocolo de comunicação de baixo nível e está incluída no AWS IoT Device SDK v2 para Python.

Embora este tutorial use MQTT e MQTT sobre WSS, AWS IoT oferece suporte a dispositivos que publicam solicitações HTTPS. Para ver um exemplo de um programa em Python que envia uma mensagem HTTP de um dispositivo, consulte o [exemplo de código HTTPS](http.md#codeexample) usando a biblioteca do Python `requests`. 

Para obter informações sobre como você pode tomar uma decisão informada sobre qual protocolo usar para as comunicações do seu dispositivo, consulte [Escolher um protocolo de aplicativo para a comunicação do dispositivo](protocols.md#protocol-selection).

**MQTT**  
Os exemplos de chamada `shadow.py` `mtls_from_path` (mostrados aqui) no [https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py](https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py) para estabelecer conexão com o AWS IoT Core usando o protocolo MQTT. O `mtls_from_path` usa certificados X.509 e TLS v1.2 para autenticar o dispositivo. A biblioteca AWS-CRT manipula os detalhes de nível inferior dessa conexão.

```
mqtt_connection = mqtt_connection_builder.mtls_from_path(
  endpoint=args.endpoint,
  cert_filepath=args.cert,
  pri_key_filepath=args.key,
  ca_filepath=args.ca_file,
  client_bootstrap=client_bootstrap,
  on_connection_interrupted=on_connection_interrupted,
  on_connection_resumed=on_connection_resumed,
  client_id=args.client_id,
  clean_session=False,
  keep_alive_secs=6
)
```
+ `endpoint`é o AWS IoT endpoint que você transmitiu pela linha de comando e `client_id` é o ID que identifica exclusivamente esse dispositivo no. Região da AWS
+ `cert_filepath`, `pri_key_filepath`, e `ca_filepath` são os caminhos para os arquivos de certificado e chave privada do dispositivo e para o arquivo CA raiz. 
+ `client_bootstrap` é o objeto de runtime comum que manipula as atividades de comunicação por soquete e é instanciado antes da chamada para `mqtt_connection_builder.mtls_from_path`.
+ `on_connection_interrupted` e `on_connection_resumed` são funções de retorno de chamada para ligar quando a conexão do dispositivo é interrompida e retomada.
+ `clean_session` é iniciar uma sessão nova e persistente ou, se houver uma, reconectar-se a uma sessão existente. `keep_alive_secs` é o valor keep alive, em segundos, para enviar a solicitação `CONNECT`. Um ping será enviado automaticamente nesse intervalo. O servidor assume que a conexão será perdida se não receber um ping após 1,5 vezes esse valor.

A amostra `shadow.py` também chama `websockets_with_default_aws_signing` no [https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py](https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py) para estabelecer uma conexão com AWS IoT Core usando o protocolo MQTT sobre WSS. MQTT sobre WSS também usa os mesmos parâmetros que MQTT e usa estes parâmetros adicionais:
+ `region`é a região de AWS assinatura usada pela autenticação Signature V4 e `credentials_provider` são AWS as credenciais fornecidas para uso na autenticação. A região é passada pela linha de comando e o objeto `credentials_provider` é instanciado logo antes da chamada para `mqtt_connection_builder.websockets_with_default_aws_signing`.
+ `websocket_proxy_options` são as opções de proxy HTTP, se estiver usando um host proxy. No aplicativo de amostra `shadow.py`, esse valor é instanciado logo antes da chamada para `mqtt_connection_builder.websockets_with_default_aws_signing`.

**Inscreva-se em tópicos e eventos de sombra**  
A amostra `shadow.py` tenta estabelecer uma conexão e espera ser totalmente conectada. Se não estiver conectado, os comandos serão colocados na fila. Uma vez conectado, o exemplo assina eventos delta e atualiza e obtém mensagens, e publica mensagens com um nível de Qualidade de Serviço (QoS) de 1 (`mqtt.QoS.AT_LEAST_ONCE`). 

Quando um dispositivo assina uma mensagem com QoS nível 1, o agente de mensagens salva as mensagens nas quais o dispositivo está inscrito até que elas possam ser enviadas ao dispositivo. O agente de mensagens reenvia as mensagens até receber uma resposta `PUBACK` do dispositivo. 

Para obter mais informações sobre o protocolo MQTT, consulte [Revisar o protocolo MQTT](sdk-tutorials.md#sdk-tutorials-mqtt-review) e [MQTT](mqtt.md).

Para obter mais informações sobre como MQTT, MQTT sobre WSS, sessões persistentes e níveis de QoS são usados neste tutorial, consulte. [Revise o aplicativo de amostra do SDK do dispositivo pubsub.py](sdk-tutorials.md#sdk-tutorials-explore-sample)

## Etapa 3: solucionar problemas com o aplicativo de amostra `shadow.py`
<a name="shadow-sample-app-troubleshoot"></a>

Ao executar o aplicativo de amostra `shadow.py`, você deve ver algumas mensagens exibidas no terminal e uma solicitação para inserir um valor `desired`. Se o programa gerar um erro, para depurar o erro, você pode começar verificando se executou o comando correto para o seu sistema.

Em alguns casos, a mensagem de erro pode indicar problemas de conexão e ser semelhante a: `Host name was invalid for dns resolution` ou `Connection was closed unexpectedly`. Nesses casos, aqui estão algumas objetos que você pode verificar:
+ 

**Verifique o endereço do endpoint no comando**  
Revise o argumento `endpoint` no comando inserido para executar o aplicativo de amostra (por exemplo, `a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com`) e verifique esse valor no **AWS IoT console**.

  Para verificar se você usou o valor correto:

  1. No **AWS IoT console**, escolha **Gerenciar** e, em seguida, escolha **Objetos**.

  1. Escolha o que você criou para seu aplicativo de amostra (por exemplo, **My\$1light\$1bulb**) e escolha **Interagir**.

  Na página de detalhes do objeto, seu endpoint é exibido na seção **HTTPS**. Você também deve ver uma mensagem que diz: `This thing already appears to be connected.`
+ 

**Verifique a ativação do certificado**  
Os certificados autenticam seu dispositivo com AWS IoT Core.

  Para verificar se o seu certificado está ativo:

  1. No **AWS IoT console**, escolha **Gerenciar** e, em seguida, escolha **Objetos**.

  1. Escolha o que você criou para seu aplicativo de exemplo (por exemplo, **My\$1light\$1bulb**) e escolha **Segurança**.

  1. Selecione o certificado e, na página de detalhes do certificado, escolha Selecionar o certificado e, na página de detalhes do certificado, escolha **Ações**.

  Se na lista suspensa **Ativar** não estiver disponível e você só puder escolher **Desativar**, seu certificado estará ativo. Caso contrário, escolha **Ativar** e execute novamente o programa de amostra.

  Se o programa ainda não for executado, verifique os nomes dos arquivos do certificado na pasta `certs`.
+ 

**Verifique a política anexada ao recurso do objeto**  
Embora os certificados autentiquem seu dispositivo, AWS IoT as políticas permitem que o dispositivo realize AWS IoT operações, como assinar ou publicar tópicos reservados do MQTT.

  Para verificar se a política correta está anexada:

  1. Encontre o certificado conforme descrito anteriormente e escolha **Políticas**.

  1. Escolha a política exibida e verifique se ela descreve as ações `connect`, `subscribe`, `receive` e `publish` que dão permissão ao dispositivo para publicar e assinar os tópicos reservados do MQTT.

     Para obter um exemplo de política, consulte [Etapa 1: Criar uma AWS IoT política para o Device Shadow](shadow-provision-cloud.md#create-policy-shadow).

  Se você receber mensagens de erro que indicam problemas na conexão AWS IoT, isso pode ser devido às permissões que você está usando para a política. Se for esse o caso, recomendamos que você comece com uma política que forneça acesso total aos AWS IoT recursos e, em seguida, execute novamente o programa de amostra. Você pode editar a política atual ou escolher a política atual, escolher **Desanexar** e, em seguida, criar outra política que forneça acesso total e a anexe ao seu recurso. Posteriormente, você poderá restringir a política apenas às ações e políticas necessárias para executar o programa.  
****  

  ```
  {
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:*"
            ],
            "Resource": "*"
        }
    ]
  }
  ```
+ 

**Verifique a instalação do SDK do seu dispositivo**  
Se o programa ainda não for executado, você poderá reinstalar o Device SDK para garantir que a instalação do SDK esteja completa e correta.

## Etapa 4: revisar os resultados e as próximas etapas
<a name="sample-app-shadow-review"></a>

**Neste tutorial, você aprendeu a:**
+ Instale o software, as ferramentas e o AWS IoT Device SDK para Python necessários.
+ Entenda como o aplicativo de amostra, a `shadow.py`, usa o protocolo MQTT para recuperar e atualizar o estado atual da sombra.
+ Execute o aplicativo de amostra para Device Shadows e observe a atualização do documento Shadow no AWS IoT console. Você também aprendeu a solucionar quaisquer problemas e corrigir erros ao executar o programa.

**Próximas etapas**  
Agora você pode executar o aplicativo de amostra `shadow.py` e usar as Sombras do Dispositivo para controlar o estado. Você pode observar as atualizações no documento Shadow no console AWS IoT e observar os eventos delta aos quais o aplicativo de amostra responde. Usando o cliente de teste MQTT, é possível assinar os tópicos de sombra reservados e observar as mensagens recebidas pelos tópicos ao executar o programa de amostra. Para obter mais informações sobre como executar este tutorial, consulte [Tutorial: interagindo com a Sombra do Dispositivo usando o aplicativo de amostra e o cliente de teste MQTT](interact-lights-device-shadows.md).

# Tutorial: interagindo com a Sombra do Dispositivo usando o aplicativo de amostra e o cliente de teste MQTT
<a name="interact-lights-device-shadows"></a>

Para interagir com o aplicativo de amostra `shadow.py`, insira um valor no terminal para o valor `desired`. Por exemplo, você pode especificar cores que se assemelhem aos semáforos e AWS IoT respondam à solicitação e atualizem os valores relatados.

**Neste tutorial, você aprenderá:**
+ Usar o aplicativo de amostra `shadow.py` para especificar os estados desejados e atualizar o estado atual da sombra.
+ Editar o documento Shadow para observar os eventos delta e como o aplicativo de amostra `shadow.py` responde a eles.
+ Utilizar o cliente de teste MQTT para assinar tópicos de sombra e observar atualizações ao executar o programa de amostra.

**Antes de executar este tutorial, você precisa:**  
Configure seu Conta da AWS, configure seu dispositivo Raspberry Pi e crie uma AWS IoT coisa e uma política. Você também deve ter instalado o software necessário, o Device SDK, os arquivos de certificado e executado o programa de amostra no terminal. Para obter mais informações, consulte os tutoriais anteriores [Tutorial: preparando seu Raspberry Pi para executar o aplicativo de sombra](create-resources-shadow.md) e [Etapa 1: execute o aplicativo de exemplo shadow.py](lightbulb-shadow-application.md#run-sample-application-shadows). Você deve concluir esses tutoriais, caso ainda não o tenha feito.

**Topics**
+ [Etapa 1: atualizar os valores desejados e relatados usando o aplicativo de amostra `shadow.py`](#update-desired-shadow-sample)
+ [Etapa 2: exibir mensagens do aplicativo de amostra `shadow.py` no cliente de teste MQTT](#shadow-sample-view-msg)
+ [Etapa 3: solucionar problemas com as interações da Sombra do Dispositivo](#shadow-observe-messages-troubleshoot)
+ [Etapa 4: revisar os resultados e as próximas etapas](#sample-shadow-review)

Este tutorial leva cerca de 45 minutos para ser concluído.

## Etapa 1: atualizar os valores desejados e relatados usando o aplicativo de amostra `shadow.py`
<a name="update-desired-shadow-sample"></a>

No tutorial anterior[Etapa 1: execute o aplicativo de exemplo shadow.py](lightbulb-shadow-application.md#run-sample-application-shadows), você aprendeu a observar uma mensagem publicada no documento Shadow no AWS IoT console ao inserir o valor desejado, conforme descrito na seção[Tutorial: instalando o Device SDK e executando o aplicativo de amostra para Sombras do Dispositivo](lightbulb-shadow-application.md).

No exemplo anterior, definimos a cor desejada como `yellow`. Depois de inserir cada valor, o terminal solicita que você insira outro valor `desired`. Se você inserir novamente o mesmo valor (`yellow`), o aplicativo reconhecerá isso e solicitará que você insira um novo valor `desired`.

```
Enter desired value:
yellow
Local value is already 'yellow'.
Enter desired value:
```

Agora, digamos que você insira a cor`green`. AWS IoT responde à solicitação e atualiza o `reported` valor para`green`. É assim que a atualização acontece quando o estado `desired` é diferente do estado `reported`, causando um delta.

**Como o aplicativo de amostra `shadow.py` simula as interações da Sombra do Dispositivo:**

1. Insira um valor `desired` (digamos `yellow`) no terminal para publicar o estado desejado.

1. Como o estado `desired` é diferente do estado `reported` (digamos, a cor `green`), ocorre um delta e o aplicativo que está inscrito no delta recebe essa mensagem.

1. O aplicativo responde à mensagem e atualiza seu estado para o valor `desired`, `yellow`.

1. O aplicativo então publica uma mensagem de atualização com o novo valor relatado do estado do dispositivo, `yellow`.

A seguir, são mostradas as mensagens exibidas no terminal que mostram como a solicitação de atualização é publicada.

```
Enter desired value:
green
Changed local shadow value to 'green'.
Updating reported shadow value to 'green'...
Update request published.
Finished updating reported shadow value to 'green'.
```

No AWS IoT console, o documento Shadow reflete o valor atualizado `green` para os `desired` campos `reported` e, e o número da versão é incrementado em 1. Por exemplo, se o número da versão anterior foi exibido como 10, o número da versão atual será exibido como 11.

**nota**  
A exclusão de uma sombra não redefine o número da versão para 0. Você verá que a versão sombra é incrementada em 1 quando você publica uma solicitação de atualização ou cria outra sombra com o mesmo nome.

**Edite o documento Shadow para observar eventos delta**  
O aplicativo de amostra `shadow.py` também está inscrito em eventos `delta` e responde quando há uma alteração no valor `desired`. Por exemplo, você pode alterar o valor `desired` para a cor `red`. Para fazer isso, no AWS IoT console, edite o documento Shadow clicando em **Editar** e defina o `desired` valor como `red` no JSON, mantendo o `reported` valor como`green`. Antes de salvar as alterações, mantenha o terminal do Raspberry Pi aberto, pois você verá as mensagens exibidas no terminal quando a alteração ocorrer.

```
{
"desired": {
  "welcome": "aws-iot",
  "color": "red"
},
"reported": {
  "welcome": "aws-iot",
  "color": "green"
}
}
```

Depois de salvar o novo valor, o aplicativo de amostra `shadow.py` responde a essa alteração e exibe mensagens no terminal indicando o delta. Em seguida, você deverá ver as seguintes mensagens aparecerem abaixo da solicitação para inserir o valor `desired`.

```
Enter desired value:
Received shadow delta event.
Delta reports that desired value is 'red'. Changing local value...
Changed local shadow value to 'red'.
Updating reported shadow value to 'red'...
Finished updating reported shadow value to 'red'.
Enter desired value:
Update request published.
Finished updating reported shadow value to 'red'.
```

## Etapa 2: exibir mensagens do aplicativo de amostra `shadow.py` no cliente de teste MQTT
<a name="shadow-sample-view-msg"></a>

Você pode usar o **cliente de teste do MQTT** no **AWS IoT console** para monitorar as mensagens do MQTT que são passadas no seu Conta da AWS. Ao assinar tópicos MQTT reservados usados ​​pelo serviço Sombra do Dispositivo, você pode observar as mensagens recebidas pelos tópicos ao executar o aplicativo de amostra.

Se você ainda não usou o cliente de teste MQTT, pode revisar [Exibir mensagens MQTT com o cliente AWS IoT MQTT](view-mqtt-messages.md). Isso ajudará você a aprender a usar o **cliente de teste MQTT** no **console do AWS IoT ** para visualizar as mensagens MQTT à medida que elas passam pelo agente de mensagens.

1. 

**Abra o cliente de teste MQTT**

   Abra o [cliente de teste do MQTT no console do AWS IoT](https://console.aws.amazon.com//iot/home#/test) em uma nova janela para que você possa observar as mensagens recebidas pelos tópicos do MQTT sem perder a configuração do seu cliente de teste do MQTT. O cliente de teste MQTT não retém assinaturas ou logs de mensagens se você deixá-lo para ir para outra página no console. Nesta seção do tutorial, você pode abrir o documento Shadow do seu AWS IoT produto e o cliente de teste MQTT em janelas separadas para observar mais facilmente a interação com o Device Shadows.

1. 

**Assine os tópicos Shadow reservados do MQTT**

   Você pode usar o cliente de teste MQTT para inserir os nomes dos tópicos reservados do MQTT da Sombra do Dispositivo e se inscrever neles para receber atualizações ao executar o aplicativo de amostra `shadow.py`. Para se inscrever nos tópicos:

   1. No **cliente de teste MQTT** no **AWS IoT console**, escolha **Subscribe to a topic (Se inscreva em um tópico)**.

   1.  Na seção **Filtro de tópicos**, digite: **\$1aws/things/ /shadow/update/ \$1 *thingname***. Aqui, `thingname` é o nome do recurso de objeto que você criou anteriormente (por exemplo, `My_light_bulb`).

   1. Mantenha os valores padrão para as configurações adicionais e escolha **Inscrever-se**.

   Ao usar o caractere curinga **\$1** na assinatura do tópico, você pode se inscrever em vários tópicos do MQTT ao mesmo tempo e observar todas as mensagens trocadas entre o dispositivo e sua sombra em uma única janela. Para obter mais informações sobre os caracteres curinga e seu uso, consulte[Tópicos do MQTT](topics.md).

1. 

**Execute um programa de amostra `shadow.py` e observe as mensagens**

   Na janela de linha de comando do Raspberry Pi, se você desconectou o programa, execute o aplicativo de exemplo novamente e observe as mensagens no **cliente de teste MQTT** no **console AWS IoT **.

   1. Execute o comando a seguir para reiniciar o programa de amostra. *your-iot-endpoint*Substitua *your-iot-thing-name* e pelos nomes da AWS IoT coisa que você criou anteriormente (por exemplo,`My_light_bulb`) e pelo endpoint para interagir com o dispositivo. 

      ```
      cd ~/aws-iot-device-sdk-python-v2/samples/service-clients
      python3 shadow.py --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint --thing_name your-iot-thing-name
      ```

      Em seguida, o aplicativo de amostra `shadow.py` é executado e recupera o estado de sombra atual. Se você excluiu a sombra ou limpou os estados atuais, o programa define o valor atual como `off` e, em seguida, solicita que você insira um valor `desired`.

      ```
      Connecting to a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com with client ID 'test-0c8ae2ff-cc87-49d2-a82a-ae7ba1d0ca5a'...
      Connected!
      Subscribing to Delta events...
      Subscribing to Update responses...
      Subscribing to Get responses...
      Requesting current shadow state...
      Launching thread to read user input...
      Finished getting initial shadow state.
      Shadow document lacks 'color' property. Setting defaults...
      Changed local shadow value to 'off'.
      Updating reported shadow value to 'off'...
      Update request published.
      Finished updating reported shadow value to 'off'...
      Enter desired value:
      ```

      Por outro lado, se o programa estava em execução e você o reiniciou, você verá o valor de cor mais recente relatado no terminal. **No cliente de teste do MQTT, você verá uma atualização nos tópicos **\$1aws/things/ /shadow/get e *thingname* \$1aws/things/**/. *thingname* shadow/get/accepted**

      Suponha que a última cor relatada tenha sido `green`. A seguir, mostra o conteúdo do arquivo ***thingname*\$1aws/things/**/JSON. shadow/get/accepted

      ```
      {
      "state": {
        "desired": {
          "welcome": "aws-iot",
          "color": "green"
        },
        "reported": {
          "welcome": "aws-iot",
          "color": "green"
        }
      },
      "metadata": {
        "desired": {
          "welcome": {
            "timestamp": 1620156892
          },
          "color": {
            "timestamp": 1620161643
          }
        },
        "reported": {
          "welcome": {
            "timestamp": 1620156892
          },
          "color": {
            "timestamp": 1620161643
          }
        }
      },
      "version": 10,
      "timestamp": 1620173908
      }
      ```

   1. Insira um valor `desired` no terminal, como `yellow`. O aplicativo de amostra `shadow.py` responde e exibe as seguintes mensagens no terminal que mostram a alteração no valor `reported` para `yellow`.

      ```
      Enter desired value:
      yellow
      Changed local shadow value to 'yellow'.
      Updating reported shadow value to 'yellow'...
      Update request published.
      Finished updating reported shadow value to 'yellow'.
      ```

      No **cliente de teste do MQTT** no **console da AWS IoT **, em **Assinaturas**, você vê que os seguintes tópicos receberam uma mensagem:
      + **\$1aws/things/ *thingname* /shadow/update**: mostra que os valores e os valores mudam para a cor. `desired` `updated` `yellow`
      + **\$1aws/things/*thingname*/shadow/update/accepted**: mostra os valores atuais dos `reported` estados `desired` e e seus metadados e informações de versão.
      + **\$1aws/things/*thingname*/shadow/update/documents**: mostra os valores anteriores e atuais dos `reported` estados e e seus metadados `desired` e informações de versão.

      Como o documento **\$1aws/things/*thingname*/shadow/update/documents**também contém informações contidas nos outros dois tópicos, podemos revisá-lo para ver as informações do estado. O estado anterior mostra o valor relatado definido como `green`, seus metadados e informações de versão e o estado atual que mostra o valor relatado atualizado para `yellow`.

      ```
      {
      "previous": {
        "state": {
          "desired": {
            "welcome": "aws-iot",
            "color": "green"
          },
          "reported": {
            "welcome": "aws-iot",
            "color": "green"
          }
        },
        "metadata": {
          "desired": {
            "welcome": {
              "timestamp": 1617297888
            },
            "color": {
              "timestamp": 1617297898
            }
          },
          "reported": {
            "welcome": {
              "timestamp": 1617297888
            },
            "color": {
              "timestamp": 1617297898
            }
          }
        },
        "version": 10
      },
      "current": {
        "state": {
          "desired": {
            "welcome": "aws-iot",
            "color": "yellow"
          },
          "reported": {
            "welcome": "aws-iot",
            "color": "yellow"
          }
        },
        "metadata": {
          "desired": {
            "welcome": {
              "timestamp": 1617297888
            },
            "color": {
              "timestamp": 1617297904
            }
          },
          "reported": {
            "welcome": {
              "timestamp": 1617297888
            },
            "color": {
              "timestamp": 1617297904
            }
          }
        },
        "version": 11
      },
      "timestamp": 1617297904
      }
      ```

   1. Agora, se você inserir outro valor `desired`, verá mais alterações nos valores `reported` e nas atualizações de mensagens recebidas por esses tópicos. O número da versão também aumenta em 1. Por exemplo, se você inserir o valor `green`, o estado anterior reportará o valor `yellow` e o estado atual relatará o valor `green`.

1. 

**Edite o documento de sombra para observar eventos delta**

   Para observar as alterações no tópico delta, edite o documento de sombra no console AWS IoT . Por exemplo, você pode alterar o valor `desired` para a cor `red`. Para fazer isso, no AWS IoT console, escolha **Editar** e defina o `desired` valor como vermelho no JSON, mantendo o `reported` valor definido como. `green` Antes de salvar a alteração, mantenha o terminal aberto, pois você verá a mensagem delta relatada no terminal.

   ```
   {
   "desired": {
     "welcome": "aws-iot",
     "color": "red"
   },
   "reported": {
     "welcome": "aws-iot",
     "color": "green"
   }
   }
   ```

   O aplicativo de amostra `shadow.py` responde a essa alteração e exibe mensagens no terminal indicando o delta. No cliente de teste MQTT, os tópicos `update` receberão uma mensagem mostrando as alterações nos valores `desired` e `reported`.

   Você também vê que o tópico **\$1aws/things//*thingname***recebeu uma mensagem. shadow/update/delta Para ver a mensagem, escolha esse tópico, que está listado em **Assinaturas**.

   ```
   {
   "version": 13,
   "timestamp": 1617318480,
   "state": {
     "color": "red"
   },
   "metadata": {
     "color": {
       "timestamp": 1617318480
     }
   }
   }
   ```

## Etapa 3: solucionar problemas com as interações da Sombra do Dispositivo
<a name="shadow-observe-messages-troubleshoot"></a>

Ao executar o aplicativo de amostra de sombra, você pode encontrar problemas ao observar as interações com o serviço Sombra do Dispositivo. 

Se o programa for executado com êxito e solicitar que você insira um valor `desired`, você poderá observar as interações da Sombra do Dispositivo usando o documento de sombra e o cliente de teste MQTT, conforme descrito anteriormente. No entanto, se você não conseguir ver as interações, aqui estão algumas objetos que você pode verificar:
+ 

**Verifique o nome da coisa e sua sombra no AWS IoT console**  
Se você não vê as mensagens no documento de sombra, revise o comando e verifique se ele corresponde ao nome do objeto no **AWS IoT console**. Você também pode verificar se tem uma sombra clássica escolhendo seu recurso e, em seguida, escolhendo **Sombras**. Este tutorial se concentra, principalmente, nas interações com a sombra clássica.

   Você também pode confirmar se o dispositivo usado está conectado à Internet. No **AWS IoT console**, escolha o que você criou anteriormente e, em seguida, escolha **Interagir**. Na página de detalhes do objeto, você deve ver uma mensagem aqui que diz: `This thing already appears to be connected.` 
+ 

**Verifique os tópicos reservados do MQTT nos quais você se inscreveu**  
Se você não vir as mensagens aparecendo no cliente de teste MQTT, verifique se os tópicos que você assinou estão formatados corretamente. Os tópicos do MQTT Device Shadow têm um formato **\$1aws/things/ *thingname* /shadow/** e podem ter`update`, ou `delete` segui-lo`get`, dependendo das ações que você deseja realizar na sombra. **Este tutorial usa o tópico **\$1aws/things/ *thingname* /shadow/ \$1**. Portanto, certifique-se de inseri-lo corretamente ao assinar o tópico na seção Filtro de tópicos do cliente de teste.**

  Ao inserir o nome do tópico, certifique-se de que *thingname* seja igual ao nome da AWS IoT coisa que você criou anteriormente. Você também pode se inscrever em tópicos adicionais do MQTT para ver se uma atualização foi realizada com sucesso. Por exemplo, você pode se inscrever no tópico **\$1aws/things/*thingname*/**para receber uma mensagem sempre que uma solicitação de atualização falhar, shadow/update/rejected para que você possa depurar problemas de conexão. Para obter mais informações sobre os tópicos reservados, consulte [Tópicos de sombra](reserved-topics.md#reserved-topics-shadow) e [Tópicos MQTT da Sombra do Dispositivo](device-shadow-mqtt.md).

## Etapa 4: revisar os resultados e as próximas etapas
<a name="sample-shadow-review"></a>

**Neste tutorial, você aprendeu a:**
+ Usar o aplicativo de amostra `shadow.py` para especificar os estados desejados e atualizar o estado atual da sombra.
+ Editar o documento Shadow para observar os eventos delta e como o aplicativo de amostra `shadow.py` responde a eles.
+ Utilizar o cliente de teste MQTT para assinar tópicos de sombra e observar atualizações ao executar o programa de amostra.

**Próximas etapas**  
Você pode assinar tópicos adicionais reservados do MQTT para observar atualizações no aplicativo da sombra. Por exemplo, se você se inscrever apenas no tópico **\$1aws/things/*thingname*/shadow/update/accepted**, verá somente as informações do estado atual quando uma atualização for realizada com sucesso.

Você também pode assinar tópicos de sombra adicionais para depurar problemas ou aprender mais sobre as interações da Sombra do Dispositivo e também depurar quaisquer problemas com as interações da Sombra do Dispositivo. Para obter mais informações, consulte [Tópicos de sombra](reserved-topics.md#reserved-topics-shadow) e [Tópicos MQTT da Sombra do Dispositivo](device-shadow-mqtt.md).

Você também pode optar por estender seu aplicativo usando sombras nomeadas ou usando hardware adicional conectado ao Raspberry Pi LEDs e observar alterações em seu estado usando mensagens enviadas do terminal.

Para obter mais informações sobre o serviço Sombra do Dispositivo e como usar o serviço em dispositivos, aplicativos e serviços, consulte [AWS IoT Serviço Device Shadow](iot-device-shadows.md), [Usar sombras em dispositivos](device-shadow-comms-device.md) e [Usar sombras em aplicativos e serviços](device-shadow-comms-app.md).

# Tutorial: Criando um autorizador personalizado para AWS IoT Core
<a name="custom-auth-tutorial"></a>

Este tutorial demonstra as etapas para criar, validar e usar a autenticação personalizada usando a AWS CLI. Opcionalmente, usando este tutorial, você pode usar o Postman para enviar dados ao AWS IoT Core usando a API de publicação HTTP.

Este tutorial mostra como criar um exemplo de função do Lambda que implementa a lógica de autorização e autenticação e um autorizador personalizado usando a chamada **create-authorizer** com a assinatura de token ativada. O autorizador é então validado usando o. E**test-invoke-authorizer**, finalmente, você pode enviar dados AWS IoT Core usando a API HTTP Publish para um tópico de teste do MQTT. A solicitação de amostra especificará o autorizador a ser invocado usando o `x-amz-customauthorizer-name` cabeçalho e transmitirá os cabeçalhos token-key-name e `x-amz-customauthorizer-signature` na solicitação.

**O que você aprenderá neste tutorial:**
+ Como criar uma função do Lambda para ser um manipulador de autorizador personalizado
+ Como criar um autorizador personalizado usando o AWS CLI com a assinatura de token ativada
+ Como testar seu autorizador personalizado usando o comando **test-invoke-authorizer**
+ Como publicar um tópico do MQTT usando o [Postman](https://www.postman.com/) e validar a solicitação com seu autorizador personalizado

Este tutorial leva cerca de 60 minutos para ser concluído.

**Topics**
+ [Etapa 1: criar uma função do Lambda para seu autorizador personalizado](#custom-auth-tutorial-define)
+ [Etapa 2: criar um par de chaves pública e privada do autorizador privado](#custom-auth-tutorial-keys)
+ [Etapa 3: Criar um recurso de autorizador personalizado e sua autorização](#custom-auth-tutorial-authorizer)
+ [Etapa 4: testar o autorizador ligando test-invoke-authorizer](#custom-auth-tutorial-test)
+ [Etapa 5: testar a publicação da mensagem MQTT usando o Postman](#custom-auth-tutorial-postman)
+ [Etapa 6: visualizar mensagens no cliente de teste MQTT](#custom-auth-tutorial-testclient)
+ [Etapa 7: revisar os resultados e as próximas etapas](#custom-auth-tutorial-review)
+ [Etapa 8: Limpeza](#custom-auth-tutorial-cleanup)

**Antes de começar este tutorial, verifique se você tem o seguinte:**
+ 

**[Configurar Conta da AWS](setting-up.md)**  
Você precisará do seu AWS IoT console Conta da AWS e do console para concluir este tutorial. 

  A conta que você usa para este tutorial funciona melhor quando inclui pelo menos as seguintes políticas gerenciadas da AWS :
  + [https://console.aws.amazon.com//iam/home#/policies/arn:aws:iam::aws:policy/IAMFullAccess$jsonEditor](https://console.aws.amazon.com//iam/home#/policies/arn:aws:iam::aws:policy/IAMFullAccess$jsonEditor)
  + [https://console.aws.amazon.com//iam/home#/policies/arn:aws:iam::aws:policy/AWSIoTFullAccess$jsonEditor](https://console.aws.amazon.com//iam/home#/policies/arn:aws:iam::aws:policy/AWSIoTFullAccess$jsonEditor)
  + [https://console.aws.amazon.com//iam/home#/policies/arn:aws:iam::aws:policy/AWSLambda_FullAccess$jsonEditor](https://console.aws.amazon.com//iam/home#/policies/arn:aws:iam::aws:policy/AWSLambda_FullAccess$jsonEditor)
**Importante**  
As políticas do IAM usadas neste tutorial são mais permissivas do que você deveria seguir em uma implementação de produção. Em um ambiente de produção, certifique-se de que as políticas de sua conta e recursos concedam somente as permissões necessárias.  
Ao criar políticas do IAM para produção, determine qual acesso os usuários e perfis precisam e, em seguida, crie políticas que permitam que eles executem apenas essas tarefas.  
Para obter mais informações, consulte [Práticas recomendadas de segurança no IAM](https://docs.aws.amazon.com//IAM/latest/UserGuide/best-practices.html).
+ 

**Instalou o AWS CLI**  
Para obter informações sobre como instalar o AWS CLI, consulte [Instalando a AWS CLI](https://docs.aws.amazon.com//cli/latest/userguide/cli-chap-install.html). Este tutorial requer uma AWS CLI versão `aws-cli/2.1.3 Python/3.7.4 Darwin/18.7.0 exe/x86_64` ou posterior.
+ 

**Ferramentas do OpenSSL**  
Os exemplos neste tutorial usam o [LibreSSL 2.6.5](https://www.libressl.org/). Você também pode usar as ferramentas [OpenSSL v1.1.1i](https://www.openssl.org/) para este tutorial.
+ 

**Revisou a visão geral do [AWS Lambda](https://docs.aws.amazon.com//lambda/latest/dg/welcome.html)**  
Se você nunca usou AWS Lambda antes, revise [AWS Lambda](https://docs.aws.amazon.com//lambda/latest/dg/welcome.html)e [Comece a usar o Lambda](https://docs.aws.amazon.com//lambda/latest/dg/getting-started.html) para aprender seus termos e conceitos.
+ 

**Consultar como criar solicitações no Postman**  
Para obter mais informações, consulte [Solicitações de criação](https://learning.postman.com/docs/sending-requests/requests/).
+ 

**Remover autorizadores personalizados do tutorial anterior**  
Você só Conta da AWS pode ter um número limitado de autorizadores personalizados configurados ao mesmo tempo. Para ver informações sobre como remover um autorizador personalizado, consulte [Etapa 8: Limpeza](#custom-auth-tutorial-cleanup).

## Etapa 1: criar uma função do Lambda para seu autorizador personalizado
<a name="custom-auth-tutorial-define"></a>

A autenticação personalizada AWS IoT Core usa [recursos do autorizador](https://docs.aws.amazon.com//iot/latest/apireference/API_AuthorizerDescription.html) que você cria para autenticar e autorizar clientes. A função que você criará nesta seção autentica e autoriza os clientes à medida que eles se conectam AWS IoT Core e AWS IoT acessam os recursos.

A função do Lambda faz o seguinte:
+ Se uma solicitação vier do **test-invoke-authorizer**, ela retornará uma política do IAM com uma ação `Deny`.
+ Se uma solicitação vier do Postman usando HTTP e o parâmetro `actionToken` tiver um valor de `allow`, ela retornará uma política do IAM com uma ação `Allow`. Caso contrário, ele retornará uma política do IAM com uma ação `Deny`.

**Para criar uma função do Lambda para seu autorizador personalizado**

1. No console do [Lambda](https://console.aws.amazon.com//lambda/home#), abra [Funções](https://console.aws.amazon.com//lambda/home#/functions).

1. Escolha a opção **Criar função**.

1. Confirme se **Criar do zero** está selecionado.

1. Em **Basic information**:

   1. Em **Nome do perfil**, insira **custom-auth-function**.

   1. Em **Runtime**, confirme **Node.js 18.x** 

1. Escolha a opção **Criar função**.

   O Lambda cria uma função Node.js e uma [função de execução](https://docs.aws.amazon.com//lambda/latest/dg/lambda-intro-execution-role.html) que concede à função permissão para fazer upload de logs. A função Lambda assume a função de execução quando você invoca sua função e usa a função de execução para criar credenciais para o AWS SDK e ler dados de fontes de eventos.

1. Para ver o código e a configuração da função no [AWS Cloud9](https://docs.aws.amazon.com/cloud9/latest/user-guide/welcome.html)editor, escolha **custom-auth-function**na janela do designer e escolha **index.js** no painel de navegação do editor.

   Para linguagens de script, como o Node.js, o Lambda inclui uma função básica que retorna uma resposta de sucesso. Você pode usar o editor do [AWS Cloud9](https://docs.aws.amazon.com/cloud9/latest/user-guide/welcome.html) para editar sua função, desde que seu código-fonte não exceda 3 MB.

1. Substitua o código **index.js** no editor pelo código a seguir:

   ```
   // A simple Lambda function for an authorizer. It demonstrates
   // How to parse a CLI and Http password to generate a response.
   
   export const handler = async (event, context, callback) => {
   
       //Http parameter to initiate allow/deny request
       const HTTP_PARAM_NAME='actionToken';
       const ALLOW_ACTION = 'Allow';
       const DENY_ACTION = 'Deny';
   
       //Event data passed to Lambda function
       var event_str = JSON.stringify(event);
       console.log('Complete event :'+ event_str);
   
       //Read protocolData from the event json passed to Lambda function
       var protocolData = event.protocolData;
       console.log('protocolData value---> ' + protocolData);
   
       //Get the dynamic account ID from function's ARN to be used
       // as full resource for IAM policy
       var ACCOUNT_ID = context.invokedFunctionArn.split(":")[4];
       console.log("ACCOUNT_ID---"+ACCOUNT_ID);
   
       //Get the dynamic region from function's ARN to be used
       // as full resource for IAM policy
       var REGION = context.invokedFunctionArn.split(":")[3];
       console.log("REGION---"+REGION);
   
       //protocolData data will be undefined if testing is done via CLI.
       // This will help to test the set up.
       if (protocolData === undefined) {
   
           //If CLI testing, pass deny action as this is for testing purpose only.
           console.log('Using the test-invoke-authorizer cli for testing only');
           callback(null, generateAuthResponse(DENY_ACTION,ACCOUNT_ID,REGION));
   
       } else{
   
           //Http Testing from Postman
           //Get the query string from the request
           var queryString = event.protocolData.http.queryString;
           console.log('queryString values -- ' + queryString);
           /*         global URLSearchParams       */
           const params = new URLSearchParams(queryString);
           var action = params.get(HTTP_PARAM_NAME);
   
           if(action!=null && action.toLowerCase() === 'allow'){
   
               callback(null, generateAuthResponse(ALLOW_ACTION,ACCOUNT_ID,REGION));
   
           }else{
   
               callback(null, generateAuthResponse(DENY_ACTION,ACCOUNT_ID,REGION));
   
           }
   
       }
   
   };
   
   // Helper function to generate the authorization IAM response.
   var generateAuthResponse = function(effect,ACCOUNT_ID,REGION) {
   
       var full_resource = "arn:aws:iot:"+ REGION + ":" + ACCOUNT_ID + ":*";
       console.log("full_resource---"+full_resource);
   
       var authResponse = {};
       authResponse.isAuthenticated = true;
       authResponse.principalId = 'principalId';
   
       var policyDocument = {};
       policyDocument.Version = '2012-10-17';		 	 	 
       policyDocument.Statement = [];
       var statement = {};
       statement.Action = 'iot:*';
       statement.Effect = effect;
       statement.Resource = full_resource;
       policyDocument.Statement[0] = statement;
       authResponse.policyDocuments = [policyDocument];
       authResponse.disconnectAfterInSeconds = 3600;
       authResponse.refreshAfterInSeconds = 600;
   
       console.log('custom auth policy function called from http');
       console.log('authResponse --> ' + JSON.stringify(authResponse));
       console.log(authResponse.policyDocuments[0]);
   
       return authResponse;
   }
   ```

1. Escolha **Implantar**.

1. Depois que **Alterações implantadas** aparecer acima do editor:

   1. Role até a seção **Visão geral da função** acima do editor.

   1. Copie o **ARN da função** e salve-o para usar posteriormente neste tutorial.

1. Teste a função do .

   1. Selecione a guia **Testar**.

   1. Usando as configurações de teste padrão, escolha **Invocar**.

   1. Se o teste for concluído com êxito, nos **Resultados da execução**, abra a visualização **Detalhes**. Você deve ver o documento de política que a função retornou.

      Se o teste falhou ou você não vê um documento de política, analise o código para encontrar e corrigir os erros.

## Etapa 2: criar um par de chaves pública e privada do autorizador privado
<a name="custom-auth-tutorial-keys"></a>

Seu autorizador personalizado requer uma chave pública e privada para autenticá-lo. Os comandos nesta seção usam ferramentas OpenSSL para criar esse par de chaves.

**Parar criar o par de chaves pública e privada do autorizador privado**

1. Crie o arquivo da chave privada.

   ```
   openssl genrsa -out private-key.pem 4096
   ```

1. Verifique o arquivo da chave privada criado.

   ```
   openssl rsa -check -in private-key.pem -noout
   ```

   Se o comando não exibir nenhum erro, o arquivo de chave privada é válido.

1. Crie o arquivo da chave pública.

   ```
   openssl rsa -in private-key.pem -pubout -out public-key.pem
   ```

1. Verifique o arquivo da chave pública.

   ```
   openssl pkey -inform PEM -pubin -in public-key.pem -noout
   ```

   Se o comando não exibir nenhum erro, o arquivo de chave pública é válido.

## Etapa 3: Criar um recurso de autorizador personalizado e sua autorização
<a name="custom-auth-tutorial-authorizer"></a>

O autorizador AWS IoT personalizado é o recurso que une todos os elementos criados nas etapas anteriores. Nesta seção, você criará um recurso de autorizador personalizado e concederá a ele permissão para executar a função do Lambda criada anteriormente. Você pode criar um recurso de autorização personalizado usando o AWS IoT console AWS CLI, o ou a AWS API. 

Para este tutorial, você só precisa criar um autorizador personalizado. Esta seção descreve como criar usando o AWS IoT console e o AWS CLI, para que você possa usar o método mais conveniente para você. Não há diferença entre os recursos de autorizador personalizado criados por nenhum dos métodos.

### Criar um recurso de autorizador personalizado
<a name="custom-auth-tutorial-authorizer-resource"></a>

**Escolha uma destas opções para criar seu recurso de autorizador personalizado**
+ [Crie um autorizador personalizado usando o console AWS IoT](#create-custom-auth-in-console)
+ [Criar um autorizador personalizado usando a AWS CLI](#create-custom-auth-in-cli)

**Para criar um autorizador personalizado (console)**

1. Abra a [página do autorizador personalizado do AWS IoT console](https://console.aws.amazon.com//iot/home#/authorizerhub) e escolha **Criar autorizador**.

1. Em **Criar autorizador**:

   1. Em **Nome do autorizador**, insira **my-new-authorizer**.

   1. Em **Status do autorizador**, marque **Ativo**.

   1. Em **Função do autorizador**, escolha a função do Lambda criada anteriormente.

   1. Em **Validação de token - opcional**:

      1. Ative a **Validação do token**.

      1. Em **Nome da chave do token**, insira **tokenKeyName**.

      1. Escolha **Adicionar chave**.

      1. Em **Nome da chave**, insira **FirstKey**.

      1. Em **Chave pública**, insira o conteúdo do arquivo `public-key.pem`. Certifique-se de incluir as linhas do arquivo com `-----BEGIN PUBLIC KEY-----` e `-----END PUBLIC KEY-----` e não adicionar ou remover nenhum avanço de linha, retornos de carro ou outros caracteres do conteúdo do arquivo. A string inserida deve ser semelhante a este exemplo.

         ```
         -----BEGIN PUBLIC KEY-----
         MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAvEBzOk4vhN+3LgslvEWt
         sLCqNmt5Damas3bmiTRvq2gjRJ6KXGTGQChqArAJwL1a9dkS9+maaXC3vc6xzx9z
         QPu/vQOe5tyzz1MsKdmtFGxMqQ3qjEXAMPLEOmqyUKPP5mff58k6ePSfXAnzBH0q
         lg2HioefrpU5OSAnpuRAjYKofKjbc2Vrn6N2G7hV+IfTBvCElf0csalS/Rk4phD5
         oa4Y0GHISRnevypg5C8n9Rrz91PWGqP6M/q5DNJJXjMyleG92hQgu1N696bn5Dw8
         FhedszFa6b2x6xrItZFzewNQkPMLMFhNrQIIyvshtT/F1LVCS5+v8AQ8UGGDfZmv
         QeqAMAF7WgagDMXcfgKSVU8yid2sIm56qsCLMvD2Sq8Lgzpey9N5ON1o1Cvldwvc
         KrJJtgwW6hVqRGuShnownLpgG86M6neZ5sRMbVNZO8OzcobLngJ0Ibw9KkcUdklW
         gvZ6HEJqBY2XE70iEXAMPLETPHzhqvK6Ei1HGxpHsXx6BNft582J1VpgYjXha8oa
         /NN7l7Zbj/euAb41IVtmX8JrD9z613d1iM5L8HluJlUzn62Q+VeNV2tdA7MfPfMC
         8btGYladFAnitThaz6+F0VSBJPu7pZQoLnqyEp5zLMtF+kFl2yOBmGAP0RBivRd9
         JWBUCG0bqcLQPeQyjbXSOfUCAwEAAQ==
         -----END PUBLIC KEY-----
         ```

1. Selecione **Criar autorizador**.

1. Se o recurso do autorizador personalizado tiver sido criado, você verá a lista de autorizadores personalizados, onde deve aparecer o seu novo autorizador personalizado, e você poderá continuar na próxima seção para testá-lo.

   Se você vir um erro, analise-o, tente criar seu autorizador personalizado novamente e verifique as entradas. Observe que cada recurso de autorizador personalizado deve ter um nome exclusivo.

**Para criar um autorizador personalizado (AWS CLI)**

1. Substitua seus valores por `authorizer-function-arn` e `token-signing-public-keys` e, em seguida, execute o seguinte comando:

   ```
   aws iot create-authorizer \
   --authorizer-name "my-new-authorizer" \
   --token-key-name "tokenKeyName" \
   --status ACTIVE \
   --no-signing-disabled \
   --authorizer-function-arn "arn:aws:lambda:Region:57EXAMPLE833:function:custom-auth-function" \
   --token-signing-public-keys FirstKey="-----BEGIN PUBLIC KEY-----
   MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAvEBzOk4vhN+3LgslvEWt
   sLCqNmt5Damas3bmiTRvq2gjRJ6KXGTGQChqArAJwL1a9dkS9+maaXC3vc6xzx9z
   QPu/vQOe5tyzz1MsKdmtFGxMqQ3qjEXAMPLEOmqyUKPP5mff58k6ePSfXAnzBH0q
   lg2HioefrpU5OSAnpuRAjYKofKjbc2Vrn6N2G7hV+IfTBvCElf0csalS/Rk4phD5
   oa4Y0GHISRnevypg5C8n9Rrz91PWGqP6M/q5DNJJXjMyleG92hQgu1N696bn5Dw8
   FhedszFa6b2x6xrItZFzewNQkPMLMFhNrQIIyvshtT/F1LVCS5+v8AQ8UGGDfZmv
   QeqAMAF7WgagDMXcfgKSVU8yid2sIm56qsCLMvD2Sq8Lgzpey9N5ON1o1Cvldwvc
   KrJJtgwW6hVqRGuShnownLpgG86M6neZ5sRMbVNZO8OzcobLngJ0Ibw9KkcUdklW
   gvZ6HEJqBY2XE70iEXAMPLETPHzhqvK6Ei1HGxpHsXx6BNft582J1VpgYjXha8oa
   /NN7l7Zbj/euAb41IVtmX8JrD9z613d1iM5L8HluJlUzn62Q+VeNV2tdA7MfPfMC
   8btGYladFAnitThaz6+F0VSBJPu7pZQoLnqyEp5zLMtF+kFl2yOBmGAP0RBivRd9
   JWBUCG0bqcLQPeQyjbXSOfUCAwEAAQ==
   -----END PUBLIC KEY-----"
   ```

**Em que:**
   + O valor `authorizer-function-arn` é o nome do recurso da Amazon (ARN) da função do Lambda que você criou para o seu autorizador personalizado.
   + O valor `token-signing-public-keys` inclui o nome da chave, **FirstKey** e o conteúdo do arquivo `public-key.pem`. Certifique-se de incluir as linhas do arquivo com `-----BEGIN PUBLIC KEY-----` e `-----END PUBLIC KEY-----` e não adicionar ou remover nenhum avanço de linha, retornos de carro ou outros caracteres do conteúdo do arquivo. 

     Nota: tome cuidado ao inserir a chave pública, pois qualquer alteração em seu valor a tornará inutilizável.

1. Se o autorizador personalizado for criado, o comando retornará o nome e o ARN do novo recurso, como o seguinte.

   ```
   {
       "authorizerName": "my-new-authorizer",
       "authorizerArn": "arn:aws:iot:Region:57EXAMPLE833:authorizer/my-new-authorizer"
   }
   ```

   Salve o valor `authorizerArn` para uso na próxima etapa.

   Lembre-se de que cada recurso de autorizador personalizado deve ter um nome exclusivo.

### Autorizar o recurso de autorizador personalizado
<a name="custom-auth-tutorial-authorizer-permission"></a>

Nesta seção, você concederá permissão ao recurso de autorizador personalizado que acabou de criar para executar a função do Lambda. Para conceder a permissão, você pode usar o comando da CLI [add-permission](https://docs.aws.amazon.com//cli/latest/reference/lambda/add-permission.html).

**Conceda permissão para sua função Lambda usando o AWS CLI**

1. Depois de inserir os valores, digite o seguinte comando. Observe que o valor `statement-id` deve ser exclusivo. Substitua `Id-1234` por outro valor se você já tiver executado esse tutorial antes ou se receber um erro `ResourceConflictException`.

   ```
   aws lambda add-permission  \
   --function-name "custom-auth-function" \
   --principal "iot.amazonaws.com" \
   --action "lambda:InvokeFunction" \
   --statement-id "Id-1234" \
   --source-arn authorizerArn
   ```

1. Se o comando for executado com êxito, ele retornará uma declaração de permissão, como neste exemplo. Você pode continuar na próxima seção para testar o autorizador personalizado.

   ```
   {
       "Statement": "{\"Sid\":\"Id-1234\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"iot.amazonaws.com\"},\"Action\":\"lambda:InvokeFunction\",\"Resource\":\"arn:aws:lambda:Region:57EXAMPLE833:function:custom-auth-function\",\"Condition\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:lambda:Region:57EXAMPLE833:function:custom-auth-function\"}}}"
   }
   ```

   Se o comando não for executado com êxito, ele retornará um erro, como neste exemplo. Será necessário verificar e corrigir o erro antes de continuar.

   ```
   An error occurred (AccessDeniedException) when calling the AddPermission operation: User: arn:aws:iam::57EXAMPLE833:user/EXAMPLE-1 is not authorized to perform: lambda:AddPer
   mission on resource: arn:aws:lambda:Region:57EXAMPLE833:function:custom-auth-function
   ```

## Etapa 4: testar o autorizador ligando test-invoke-authorizer
<a name="custom-auth-tutorial-test"></a>

Com todos os recursos definidos, nesta seção, você ligará test-invoke-authorizer da linha de comando para testar o passe de autorização.

Observe que, ao invocar o autorizador a partir da linha de comando, `protocolData` não está definido; portanto, o autorizador sempre retornará um documento DENY. No entanto, esse teste confirma que seu autorizador personalizado e a função do Lambda estão configurados corretamente, mesmo que não teste totalmente a função do Lambda.

**Para testar seu autorizador personalizado e sua função Lambda usando o AWS CLI**

1. No diretório que contém o arquivo `private-key.pem` criado na etapa anterior, execute o seguinte comando.

   ```
   echo -n "tokenKeyValue" | openssl dgst -sha256 -sign private-key.pem | openssl base64 -A
   ```

   Esse comando cria uma string de assinatura para ser usada na próxima etapa. A string de assinatura é semelhante a esta:

   ```
   dBwykzlb+fo+JmSGdwoGr8dyC2qB/IyLefJJr+rbCvmu9Jl4KHAA9DG+V+MMWu09YSA86+64Y3Gt4tOykpZqn9mn
   VB1wyxp+0bDZh8hmqUAUH3fwi3fPjBvCa4cwNuLQNqBZzbCvsluv7i2IMjEg+CPY0zrWt1jr9BikgGPDxWkjaeeh
   bQHHTo357TegKs9pP30Uf4TrxypNmFswA5k7QIc01n4bIyRTm90OyZ94R4bdJsHNig1JePgnuOBvMGCEFE09jGjj
   szEHfgAUAQIWXiVGQj16BU1xKpTGSiTAwheLKUjITOEXAMPLECK3aHKYKY+d1vTvdthKtYHBq8MjhzJ0kggbt29V
   QJCb8RilN/P5+vcVniSXWPplyB5jkYs9UvG08REoy64AtizfUhvSul/r/F3VV8ITtQp3aXiUtcspACi6ca+tsDuX
   f3LzCwQQF/YSUy02u5XkWn+sto6KCkpNlkD0wU8gl3+kOzxrthnQ8gEajd5Iylx230iqcXo3osjPha7JDyWM5o+K
   EWckTe91I1mokDr5sJ4JXixvnJTVSx1li49IalW4en1DAkc1a0s2U2UNm236EXAMPLELotyh7h+flFeloZlAWQFH
   xRlXsPqiVKS1ZIUClaZWprh/orDJplpiWfBgBIOgokJIDGP9gwhXIIk7zWrGmWpMK9o=
   ```

   Copie essa string de assinatura para usá-la na próxima etapa. Tome cuidado para não incluir caracteres extras nem omitir nenhum.

1. Nesse comando, substitua o valor `token-signature` pela string de assinatura da etapa anterior e execute esse comando para testar seu autorizador.

   ```
   aws iot test-invoke-authorizer \
   --authorizer-name my-new-authorizer \
   --token tokenKeyValue \
   --token-signature dBwykzlb+fo+JmSGdwoGr8dyC2qB/IyLefJJr+rbCvmu9Jl4KHAA9DG+V+MMWu09YSA86+64Y3Gt4tOykpZqn9mnVB1wyxp+0bDZh8hmqUAUH3fwi3fPjBvCa4cwNuLQNqBZzbCvsluv7i2IMjEg+CPY0zrWt1jr9BikgGPDxWkjaeehbQHHTo357TegKs9pP30Uf4TrxypNmFswA5k7QIc01n4bIyRTm90OyZ94R4bdJsHNig1JePgnuOBvMGCEFE09jGjjszEHfgAUAQIWXiVGQj16BU1xKpTGSiTAwheLKUjITOEXAMPLECK3aHKYKY+d1vTvdthKtYHBq8MjhzJ0kggbt29VQJCb8RilN/P5+vcVniSXWPplyB5jkYs9UvG08REoy64AtizfUhvSul/r/F3VV8ITtQp3aXiUtcspACi6ca+tsDuXf3LzCwQQF/YSUy02u5XkWn+sto6KCkpNlkD0wU8gl3+kOzxrthnQ8gEajd5Iylx230iqcXo3osjPha7JDyWM5o+KEWckTe91I1mokDr5sJ4JXixvnJTVSx1li49IalW4en1DAkc1a0s2U2UNm236EXAMPLELotyh7h+flFeloZlAWQFHxRlXsPqiVKS1ZIUClaZWprh/orDJplpiWfBgBIOgokJIDGP9gwhXIIk7zWrGmWpMK9o=
   ```

   Se o comando for executado com êxito, ele retornará as informações geradas por sua função de autorizador personalizado, como neste exemplo.

   ```
   {
       "isAuthenticated": true,
       "principalId": "principalId",
       "policyDocuments": [
           "{\"Version\":\"2012-10-17\",		 	 	 \"Statement\":[{\"Action\":\"iot:*\",\"Effect\":\"Deny\",\"Resource\":\"arn:aws:iot:Region:57EXAMPLE833:*\"}]}"
       ],
       "refreshAfterInSeconds": 600,
       "disconnectAfterInSeconds": 3600
   }
   ```

   Se o comando retornar um erro, analise-o e verifique novamente os comandos usados nesta seção.

## Etapa 5: testar a publicação da mensagem MQTT usando o Postman
<a name="custom-auth-tutorial-postman"></a>

1. Para obter o endpoint de dados do dispositivo a partir da linha de comando, chame [describe-endpoint](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-endpoint.html) conforme mostrado aqui

   ```
   aws iot describe-endpoint --output text --endpoint-type iot:Data-ATS
   ```

   Salve esse endereço para uso como *device\$1data\$1endpoint\$1address* em uma etapa posterior.

1. Abra uma nova janela do Postman e crie uma nova solicitação HTTP POST.

   1. No seu computador, abra o aplicativo Postman.

   1. No Postman, no menu **Arquivo**, escolha **Novo…**.

   1. Na caixa de diálogo **Novo**, selecione **Solicitação**.

   1. Em Salvar solicitação,

      1. Em **Nome da solicitação**, insira **Custom authorizer test request**.

      1. Em **Selecionar uma coleção ou pasta para salvar:** escolha ou crie uma coleção na qual salvar essa solicitação.

      1. Escolha **Salvar em *collection\$1name***.

1. Crie a solicitação do POST para testar seu autorizador personalizado.

   1. No seletor do método de solicitação ao lado do campo URL, escolha **POST**. 

   1. No campo URL, crie o URL para sua solicitação usando o seguinte URL com o comando *device\$1data\$1endpoint\$1address* from the [describe-endpoint](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-endpoint.html) em uma etapa anterior.

      ```
      https://device_data_endpoint_address:443/topics/test/cust-auth/topic?qos=0&actionToken=allow
      ```

      Observe que esse URL inclui o parâmetro de consulta `actionToken=allow` que fará com que a função do Lambda retorne um documento de política que permita acesso à AWS IoT. Depois de inserir o URL, os parâmetros de consulta também serão exibidos na guia **Parâmetros** do Postman.

   1. Na guia **Autenticação**, no campo **Tipo**, escolha **Sem autenticação**.

   1. Na guia Cabeçalhos:

      1. Se houver uma chave de **host** marcada, desmarque-a.

      1. Na parte inferior da lista de cabeçalhos, adicione estes novos cabeçalhos e confirme se estão marcados. Substitua o **Host** valor pelo seu *device\$1data\$1endpoint\$1address* e o **x-amz-customauthorizer-signature** valor pela string de assinatura que você usou com o **test-invoke-authorize** comando na seção anterior.    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/custom-auth-tutorial.html)

   1. Na guia Corpo:

      1. Na caixa de opção de formato de dados, escolha **Bruto**.

      1. Na lista de tipos de dados, escolha **JavaScript**.

      1. No campo de texto, insira esta carga de mensagem JSON para sua mensagem de teste:

         ```
         {
             "data_mode": "test",
             "vibration": 200,
             "temperature": 40
         }
         ```

1. Escolha **Enviar** para enviar a solicitação.

   Se a solicitação for concluída com êxito, ela retornará:

   ```
   {
       "message": "OK",
       "traceId": "ff35c33f-409a-ea90-b06f-fbEXAMPLE25c"
   }
   ```

   A resposta bem-sucedida indica que seu autorizador personalizado permitiu a conexão AWS IoT e que a mensagem de teste foi entregue ao broker in AWS IoT Core. 

   Se retornar um erro, revise a mensagem de erro*device\$1data\$1endpoint\$1address*, a string de assinatura e os outros valores do cabeçalho.

Mantenha essa solicitação no Postman para uso na próxima seção.

## Etapa 6: visualizar mensagens no cliente de teste MQTT
<a name="custom-auth-tutorial-testclient"></a>

Na etapa anterior, você enviou mensagens simuladas do dispositivo AWS IoT usando o Postman. A resposta bem-sucedida indicou que seu autorizador personalizado permitiu a conexão à AWS IoT e que a mensagem de teste foi entregue ao agente no AWS IoT Core. Nesta seção, você usará o cliente de teste MQTT no AWS IoT console para ver o conteúdo da mensagem da mesma forma que outros dispositivos e serviços.

**Para ver as mensagens de teste autorizadas pelo seu autorizador personalizado**

1. No AWS IoT console, abra o [cliente de teste MQTT](https://console.aws.amazon.com//iot/home#/test).

1. Na guia **Assinar um tópico**, em **Filtro de tópicos**, insira **test/cust-auth/topic**, que é o tópico da mensagem usado no exemplo do Postman da seção anterior.

1. Escolha **Assinar**.

   Mantenha essa janela visível para a próxima etapa.

1. No Postman, na solicitação criada na seção anterior, escolha **Enviar**.

   Analise a resposta para verificar se ela foi concluída com êxito. Caso contrário, solucione o erro conforme descrito na seção anterior.

1. No **cliente de teste do MQTT**, deve ser possível ver uma nova entrada que mostra o tópico da mensagem e, se expandida, a carga da mensagem da solicitação enviada pelo Postman.

   Se você não vir suas mensagens no **cliente de teste do MQTT**, aqui estão alguns itens que você deve verificar:
   + Certifique-se de que sua solicitação do Postman tenha sido retornada com êxito. Se AWS IoT rejeitar a conexão e retornar um erro, a mensagem na solicitação não será passada para o agente de mensagens.
   + Verifique se o Conta da AWS e Região da AWS usado para abrir o AWS IoT console é o mesmo que você está usando no URL do Postman.
   + Garanta que você esteja usando o endpoint adequado para o autorizador personalizado. O endpoint de IoT padrão pode não aceitar o uso de autorizadores personalizados com funções do Lambda. Em vez disso, você pode usar configurações de domínio para definir um novo endpoint e depois especificá-lo para o autorizador personalizado.
   + Verifique se você inseriu o tópico corretamente no **cliente de teste do MQTT**. O filtro do tópico diferencia letras maiúsculas de minúsculas. Em caso de dúvida, você também pode se inscrever no **\$1** tópico, que assina todas as mensagens MQTT que passam pelo agente de mensagens Conta da AWS e Região da AWS usadas para abrir o AWS IoT console.

## Etapa 7: revisar os resultados e as próximas etapas
<a name="custom-auth-tutorial-review"></a>

**Neste tutorial:**
+ Você criou uma função do Lambda para ser um manipulador de autorizador personalizado
+ Você criou um autorizador personalizado com a assinatura de token ativada
+ Você testou seu autorizador personalizado usando o comando **test-invoke-authorizer**
+ Você publicou um tópico do MQTT usando o [Postman](https://www.postman.com/) e validou a solicitação com seu autorizador personalizado
+ Você usou o **cliente de teste MQTT** para visualizar as mensagens enviadas do seu teste do Postman

**Próximas etapas**  
Depois de enviar algumas mensagens do Postman para verificar se o autorizador personalizado está funcionando, experimente analisar como a alteração de diferentes aspectos deste tutorial afeta os resultados. Aqui estão alguns exemplos para você começar.
+ Altere a string da assinatura para que não seja mais válido ver como as tentativas de conexão não autorizadas são processadas. Você deve receber uma resposta de erro, como essa, e a mensagem não deve aparecer no **cliente de teste do MQTT**. 

  ```
  {
      "message": "Forbidden",
      "traceId": "15969756-a4a4-917c-b47a-5433e25b1356"
  }
  ```
+ Para saber mais sobre como encontrar erros que possam ocorrer durante o desenvolvimento e o uso de AWS IoT regras, consulte[Monitoramento AWS IoT](monitoring_overview.md).

## Etapa 8: Limpeza
<a name="custom-auth-tutorial-cleanup"></a>

Se quiser repetir este tutorial, talvez seja necessário remover alguns dos autorizadores personalizados. Você Conta da AWS pode ter apenas um número limitado de autorizadores personalizados configurados ao mesmo tempo e você pode obter um `LimitExceededException` ao tentar adicionar um novo sem remover um autorizador personalizado existente.

**Para remover um autorizador personalizado (console)**

1. Abra a [página do autorizador personalizado do AWS IoT console](https://console.aws.amazon.com//iot/home#/authorizerhub) e, na lista de autorizadores personalizados, encontre o autorizador personalizado a ser removido.

1. Abra a página de detalhes do autorizador personalizado e, no menu **Ações**, escolha **Editar**.

1. Desmarque a opção **Ativar autorizador** e, em seguida, selecione **Atualizar**.

   Não é possível excluir um autorizador personalizado enquanto ele estiver ativo.

1. Na página de detalhes do autorizador personalizado, abra o menu **Ações** e selecione **Excluir**.

**Para remover um autorizador personalizado (AWS CLI)**

1. Liste os autorizadores personalizados que você instalou e localize o nome do autorizador personalizado que deseja excluir.

   ```
   aws iot list-authorizers 
   ```

1. Defina o autorizador personalizado como `inactive` executando esse comando após substituir `Custom_Auth_Name` pelo `authorizerName` do autorizador personalizado a ser excluído.

   ```
   aws iot update-authorizer --status INACTIVE --authorizer-name Custom_Auth_Name
   ```

1. Exclua o autorizador personalizado executando esse comando após substituir `Custom_Auth_Name` pelo `authorizerName` do autorizador personalizado a ser excluído.

   ```
   aws iot delete-authorizer --authorizer-name Custom_Auth_Name
   ```

# Tutorial: Monitorando a umidade do solo com o AWS IoT Raspberry Pi
<a name="iot-moisture-tutorial"></a>

Este tutorial mostra como usar um [Raspberry Pi](https://www.raspberrypi.org/), um sensor de umidade, e AWS IoT monitorar o nível de umidade do solo de uma planta doméstica ou jardim. O Raspberry Pi executa um código que lê o nível de umidade e a temperatura do sensor e, em seguida, envia os dados para AWS IoT. Você cria uma regra AWS IoT que envia um e-mail para um endereço inscrito em um tópico do Amazon SNS quando o nível de umidade cai abaixo de um limite.

**nota**  
Este tutorial pode não estar atualizado. Algumas referências podem ter sido substituídas desde que este tópico foi publicado originalmente.

**Contents**
+ [Pré-requisitos](#iot-moisture-prereqs)
+ [Conf AWS IoT iguração](iot-moisture-setup.md)
  + [Etapa 1: criar a AWS IoT política](iot-moisture-policy.md)
  + [Etapa 2: criar a AWS IoT coisa, o certificado e a chave privada](iot-moisture-create-thing.md)
  + [Etapa 3: criar um tópico e uma assinatura do Amazon SNS](iot-moisture-create-sns-topic.md)
  + [Etapa 4: criar uma AWS IoT regra para enviar um e-mail](iot-moisture-create-rule.md)
+ [Configuração do Raspberry Pi e do sensor de umidade](iot-moisture-raspi-setup.md)

## Pré-requisitos
<a name="iot-moisture-prereqs"></a>

Para concluir este tutorial, é necessário:
+ Um Conta da AWS.
+ Um usuário do IAM com permissões de administrador.
+ Um computador de desenvolvimento que execute Windows, macOS, Linux ou Unix para acessar o [console do AWS IoT](https://console.aws.amazon.com/iot/home).
+ Um [Raspberry Pi 3B ou 4B](https://www.raspberrypi.com/products/) que execute a versão mais recente do [Raspberry Pi OS](https://www.raspberrypi.com/software/operating-systems/). Para acessar instruções de instalação, consulte [Install an operating system](https://www.raspberrypi.com/documentation/computers/getting-started.html#installing-the-operating-system) no site do Raspberry Pi. 
+ Um monitor, um teclado, um mouse e uma rede Wi-Fi ou conexão Ethernet para o Raspberry Pi.
+ Um sensor de umidade compatível com o Raspberry Pi. O sensor usado neste tutorial é um [Sensor capacitivo de umidade Adafruit STEMMA I2C](https://www.adafruit.com/product/4026) com um [JST de 4 pinos com conector de cabo de soquete fêmea](https://www.adafruit.com/product/3950). 

# Conf AWS IoT iguração
<a name="iot-moisture-setup"></a>

Para concluir este tutorial, é necessário criar os recursos a seguir. Para conectar um dispositivo AWS IoT, você cria uma coisa de IoT, um certificado de dispositivo e uma AWS IoT política. 
+ Qualquer AWS IoT coisa.

  Umo objeto representa um dispositivo físico (nesse caso, o Rasberry Pi) e contém metadados estáticos sobre o dispositivo. 
+ Um certificado de dispositivo.

  Todos os dispositivos devem ter um certificado de dispositivo para se conectar e autenticar com o AWS IoT.
+ Uma AWS IoT política.

  Cada certificado de dispositivo tem uma ou mais AWS IoT políticas associadas a ele. Essas políticas determinam quais AWS IoT recursos o dispositivo pode acessar. 
+ Um certificado CA AWS IoT raiz.

  Os dispositivos e outros clientes usam um certificado CA AWS IoT raiz para autenticar o AWS IoT servidor com o qual estão se comunicando. Para obter mais informações, consulte [Autenticação do servidor](server-authentication.md).
+ Uma AWS IoT regra.

  Uma regra contém uma consulta e uma ou mais ações de regra. A consulta extrai dados de mensagens do dispositivo para determinar se os dados da mensagem devem ser processados. A ação da regra especifica o que fazer se os dados corresponderem à consulta.
+ Uma assinatura e um tópico do Amazon SNS.

  A regra recebe dados de umidade do Raspberry Pi. Se o valor estiver abaixo de um limite, ele enviará uma mensagem ao tópico do Amazon SNS. O Amazon SNS envia essa mensagem para todos os endereços de e-mail assinantes do tópico.

 



# Etapa 1: criar a AWS IoT política
<a name="iot-moisture-policy"></a>

Crie uma AWS IoT política que permita que seu Raspberry Pi se conecte e envie mensagens para o. AWS IoT

1. No [console do AWS IoT](https://console.aws.amazon.com/iot), se um botão **Começar** for exibido, selecione-o. Caso contrário, no painel de navegação, expanda a opção **Proteger** e selecione a opção **Políticas**.

1. Se a caixa de diálogo **Você ainda não tem políticas**, selecione **Criar uma política**. Caso contrário, escolha a opção **Criar**.

1. Insira um nome para a AWS IoT política (por exemplo,**MoistureSensorPolicy**).

1. Na seção **Adicionar instruções**, substitua a política existente pelo JSON a seguir. *account*Substitua *region* e pelo seu Região da AWS Conta da AWS número e.  
****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "iot:Connect",
               "Resource": "arn:aws:iot:us-east-1:123456789012:client/RaspberryPi"
           },
           {
               "Effect": "Allow",
               "Action": "iot:Publish",
               "Resource": [
                   "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/update",
                   "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/delete",
                   "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/get"
               ]
           },
           {
               "Effect": "Allow",
               "Action": "iot:Receive",
               "Resource": [
                   "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/update/accepted",
                   "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/delete/accepted",
                   "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/get/accepted",
                   "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/update/rejected",
                   "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/RaspberryPi/shadow/delete/rejected"
               ]
           },
           {
               "Effect": "Allow",
               "Action": "iot:Subscribe",
               "Resource": [
                   "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/RaspberryPi/shadow/update/accepted",
                   "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/RaspberryPi/shadow/delete/accepted",
                   "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/RaspberryPi/shadow/get/accepted",
                   "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/RaspberryPi/shadow/update/rejected",
                   "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/RaspberryPi/shadow/delete/rejected"
               ]
           },
           {
               "Effect": "Allow",
               "Action": [
                   "iot:GetThingShadow",
                   "iot:UpdateThingShadow",
                   "iot:DeleteThingShadow"
               ],
               "Resource": "arn:aws:iot:us-east-1:123456789012:thing/RaspberryPi"
           }
       ]
   }
   ```

1. Escolha **Criar**.

# Etapa 2: criar a AWS IoT coisa, o certificado e a chave privada
<a name="iot-moisture-create-thing"></a>

Crie uma coisa no AWS IoT registro para representar seu Raspberry Pi.

1. No [console do AWS IoT](https://console.aws.amazon.com/iot/home), no painel de navegação, selecione **Gerenciar** e **Objetos**.

1. Se uma caixa de diálogo **Você ainda não tem objetos** for exibida, selecione a opção **Registrar um objeto**. Caso contrário, escolha **Criar**.

1. Na página **Criando AWS IoT coisas**, escolha **Criar uma única coisa**.

1. Na página **Adicionar o dispositivo ao registro do dispositivo**, insira um nome para o objeto de IoT (por exemplo, **RaspberryPi**) e selecione **Próximo**. Você não pode alterar o nome de um objeto depois de criá-lo. Para alterar o nome de um objeto, é necessário criar um objeto, fornecer o novo nome e, depois, excluir o objeto antiga.

1. Na página **Adicionar um certificado ao objeto**, escolha **Criar certificado**.

1. Escolha os links **Download** para fazer download do certificado, da chave privada e do certificado CA raiz.
**Importante**  
Esta é a única vez que você pode fazer download do certificado e da chave privada.

1. Para ativar o certificado, selecione a opção **Ativar**. O certificado deve estar ativo para que um dispositivo se conecte ao AWS IoT.

1. Selecione a opção **Anexar uma política**.

1. Em **Adicionar uma política para sua coisa**, escolha e **MoistureSensorPolicy**, em seguida, escolha **Registrar coisa**.

# Etapa 3: criar um tópico e uma assinatura do Amazon SNS
<a name="iot-moisture-create-sns-topic"></a>

Criar um tópico e uma assinatura do Amazon SNS.

1. No console SNS do [AWS](https://console.aws.amazon.com/sns/home), no painel de navegação, selecione **Tópicos** e, em seguida, selecione **Criar tópico**.

1. Escolha o tipo como **Padrão** e insira um nome para o tópico (por exemplo, **MoistureSensorTopic**).

1. Insira um nome de exibição para o tópico (por exemplo, **Moisture Sensor Topic**). Esse é o nome exibido para o tópico no console do Amazon SNS .

1. Escolha **Criar tópico**.

1. Na página de detalhes do tópico do Amazon SNS, selecione **Criar assinatura**.

1. Em **Protocolo**, escolha **Email**.

1. Para **Endpoint**, insira seu endereço de e-mail.

1. Selecione **Criar assinatura**.

1. Abra o cliente de e-mail e procure uma mensagem com o assunto **MoistureSensorTopic**. Abra o e-mail e clique no link **Confirmar assinatura**.
**Importante**  
Você não receberá nenhum alerta por e-mail deste tópico do Amazon SNS até confirmar a assinatura.

Você deve receber uma mensagem de e-mail com o texto digitado.

# Etapa 4: criar uma AWS IoT regra para enviar um e-mail
<a name="iot-moisture-create-rule"></a>

Uma AWS IoT regra define uma consulta e uma ou mais ações a serem tomadas quando uma mensagem é recebida de um dispositivo. O mecanismo de AWS IoT regras escuta as mensagens enviadas pelos dispositivos e usa os dados nas mensagens para determinar se alguma ação deve ser tomada. Para obter mais informações, consulte [Regras para AWS IoT](iot-rules.md). 

Neste tutorial, o Raspberry Pi publica mensagens no `aws/things/RaspberryPi/shadow/update`. Este é um tópico MQTT interno usado por dispositivos e pelo serviço Thing Shadow. O Raspberry Pi publica mensagens que têm o seguinte formato:

```
{
    "reported": {
        "moisture" : moisture-reading,
        "temp" : temperature-reading
    }
}
```

Você cria uma consulta que extrai os dados de umidade e temperatura da mensagem recebida. Você também cria uma ação do Amazon SNS que usa os dados e os envia aos assinantes do tópico do Amazon SNS se a leitura de umidade estiver abaixo de um valor limite.

**Criar uma regra do Amazon SNS**

1. No [AWS IoT console](https://console.aws.amazon.com/iot/home), escolha **Encaminhamento de mensagens** e, em seguida, escolha **Regras**. Se uma caixa de diálogo **Você ainda não tem regras**, selecione **Criar uma regra**. Caso contrário, selecione **Criar regra**.

1. Na página **Propriedades da regra**, insira um **nome de regra** como **MoistureSensorRule**, e forneça uma breve **descrição da regra**, como**Sends an alert when soil moisture level readings are too low**.

1. Escolha **Próximo** e configure sua instrução SQL. Escolha a **versão SQL** como **2016-03-23** e insira a seguinte AWS IoT instrução de consulta SQL:

   ```
   SELECT * FROM '$aws/things/RaspberryPi/shadow/update/accepted' WHERE state.reported.moisture < 400
   ```

   Essa instrução aciona a ação da regra quando a leitura de `moisture` é menor que `400`.
**nota**  
Talvez seja necessário usar um valor diferente. Depois de ter o código em execução no Raspberry Pi, você poderá ver os valores obtidos do sensor tocando no sensor, colocando-o na água ou colocando-o em um vaso. 

1. Escolha a opção **Próximo** e anexe ações de regra. Para a **Ação 1**, escolha **Serviço de Notificação Simples**. A descrição dessa ação de regra é **Enviar uma mensagem como uma notificação push do SNS**.

1. Para o **tópico SNS**, escolha o tópico que você criou em [Etapa 3: criar um tópico e uma assinatura do Amazon SNS](iot-moisture-create-sns-topic.md) **MoistureSensorTopic**, e deixe o **formato da mensagem** como **RAW**. Em **Perfil do IAM**, selecione **Criar uma nova função**. Insira um nome para a função, por exemplo, **LowMoistureTopicRole**, e escolha **Criar função**.

1. Escolha **Próximo** para revisar e, em seguida, escolha **Criar** para criar a regra.

# Configuração do Raspberry Pi e do sensor de umidade
<a name="iot-moisture-raspi-setup"></a>



Insira o cartão microSD no Raspberry Pi, conecte o monitor, o teclado, o mouse e, se você não estiver usando a rede Wi-Fi, o cabo Ethernet. Não conecte o cabo de alimentação ainda.

Conecte o cabo jumper JST ao sensor de umidade. O outro lado do jumper tem quatro cabos:
+ Verde: I2C SCL
+ Branco: I2C SDA
+ Vermelho: alimentação (3,5 V)
+ Preto: terra

Mantenha o Raspberry Pi com o conector Ethernet à direita. Nessa orientação, há duas linhas de pinos GPIO na parte superior. Conecte os cabos do sensor de umidade à linha inferior de pinos na ordem a seguir. A partir do pino mais à esquerda, conecte o vermelho (alimentação), o branco (SDA) e o verde (SCL). Ignore um pino e conecte o fio preto (terra). Para obter mais informações, consulte [Cabeamento de computador Python](https://learn.adafruit.com/adafruit-stemma-soil-sensor-i2c-capacitive-moisture-sensor/python-circuitpython-test).

Conecte o cabo de alimentação ao Raspberry Pi e conecte a outra extremidade a uma tomada para ligá-lo.

**Configurar o Raspberry Pi**

1. Em **Boas-vindas ao Raspberry Pi**, selecione **Próximo**.

1. Escolha o país, o idioma, o fuso horário e o layout do teclado. Escolha **Próximo**.

1. Insira uma senha para o Raspberry Pi e selecione **Próximo**.

1. Escolha a rede Wi-Fi e selecione **Próximo**. Se você não estiver usando uma rede Wi-Fi, selecione **Ignorar**.

1. Escolha **Próximo** para verificar se há atualizações de software. Quando as atualizações forem concluídas, selecione **Reiniciar** para reiniciar o Raspberry Pi.

Depois que o Raspberry Pi for iniciado, habilite a interface I2C.

1. No canto superior esquerdo da área de trabalho do Raspbian, clique no ícone do Raspberry, selecione **Preferências** e **Configuração do Raspberry Pi**.

1. Na guia **Interfaces** para **I2C**, selecione **Habilitar**.

1. Escolha **OK**.

As bibliotecas do sensor de umidade Adafruit STEMMA foram criadas para. CircuitPython Para executá-las em um Raspberry Pi, é necessário instalar a versão mais recente do Python 3.

1. Execute os seguintes comandos em um prompt de comando para atualizar o software do Raspberry Pi:

   `sudo apt-get update`

   `sudo apt-get upgrade`

1. Execute o seguinte comando para atualizar a instalação do Python 3:

   `sudo pip3 install --upgrade setuptools`

1. Execute o seguinte comando para instalar as bibliotecas GPIO do Raspberry Pi:

   `pip3 install RPI.GPIO`

1. Execute o seguinte comando para instalar as bibliotecas Adafruit Blinka:

   `pip3 install adafruit-blinka`

   Para obter mais informações, consulte [Instalando CircuitPython bibliotecas no Raspberry Pi](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/installing-circuitpython-on-raspberry-pi).

1. Execute o seguinte comando para instalar as bibliotecas Adafruit Seesaw:

   `sudo pip3 install adafruit-circuitpython-seesaw`

1. Execute o comando a seguir para instalar o AWS IoT Device SDK para Python:

   `pip3 install AWSIoTPythonSDK`

Agora o Raspberry Pi tem todas as bibliotecas necessárias. Crie um arquivo chamado **moistureSensor.py** e copie o seguinte código Python no arquivo:

```
from adafruit_seesaw.seesaw import Seesaw
from AWSIoTPythonSDK.MQTTLib import AWSIoTMQTTShadowClient
from board import SCL, SDA

import logging
import time
import json
import argparse
import busio

# Shadow JSON schema:
#
# {
#   "state": {
#       "desired":{
#           "moisture":<INT VALUE>,
#           "temp":<INT VALUE>            
#       }
#   }
# }

# Function called when a shadow is updated
def customShadowCallback_Update(payload, responseStatus, token):

    # Display status and data from update request
    if responseStatus == "timeout":
        print("Update request " + token + " time out!")

    if responseStatus == "accepted":
        payloadDict = json.loads(payload)
        print("~~~~~~~~~~~~~~~~~~~~~~~")
        print("Update request with token: " + token + " accepted!")
        print("moisture: " + str(payloadDict["state"]["reported"]["moisture"]))
        print("temperature: " + str(payloadDict["state"]["reported"]["temp"]))
        print("~~~~~~~~~~~~~~~~~~~~~~~\n\n")

    if responseStatus == "rejected":
        print("Update request " + token + " rejected!")

# Function called when a shadow is deleted
def customShadowCallback_Delete(payload, responseStatus, token):

     # Display status and data from delete request
    if responseStatus == "timeout":
        print("Delete request " + token + " time out!")

    if responseStatus == "accepted":
        print("~~~~~~~~~~~~~~~~~~~~~~~")
        print("Delete request with token: " + token + " accepted!")
        print("~~~~~~~~~~~~~~~~~~~~~~~\n\n")

    if responseStatus == "rejected":
        print("Delete request " + token + " rejected!")


# Read in command-line parameters
def parseArgs():

    parser = argparse.ArgumentParser()
    parser.add_argument("-e", "--endpoint", action="store", required=True, dest="host", help="Your device data endpoint")
    parser.add_argument("-r", "--rootCA", action="store", required=True, dest="rootCAPath", help="Root CA file path")
    parser.add_argument("-c", "--cert", action="store", dest="certificatePath", help="Certificate file path")
    parser.add_argument("-k", "--key", action="store", dest="privateKeyPath", help="Private key file path")
    parser.add_argument("-p", "--port", action="store", dest="port", type=int, help="Port number override")
    parser.add_argument("-n", "--thingName", action="store", dest="thingName", default="Bot", help="Targeted thing name")
    parser.add_argument("-id", "--clientId", action="store", dest="clientId", default="basicShadowUpdater", help="Targeted client id")

    args = parser.parse_args()
    return args


# Configure logging
# AWSIoTMQTTShadowClient writes data to the log
def configureLogging():

    logger = logging.getLogger("AWSIoTPythonSDK.core")
    logger.setLevel(logging.DEBUG)
    streamHandler = logging.StreamHandler()
    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
    streamHandler.setFormatter(formatter)
    logger.addHandler(streamHandler)


# Parse command line arguments
args = parseArgs()

if not args.certificatePath or not args.privateKeyPath:
    parser.error("Missing credentials for authentication.")
    exit(2)

# If no --port argument is passed, default to 8883
if not args.port: 
    args.port = 8883


# Init AWSIoTMQTTShadowClient
myAWSIoTMQTTShadowClient = None
myAWSIoTMQTTShadowClient = AWSIoTMQTTShadowClient(args.clientId)
myAWSIoTMQTTShadowClient.configureEndpoint(args.host, args.port)
myAWSIoTMQTTShadowClient.configureCredentials(args.rootCAPath, args.privateKeyPath, args.certificatePath)

# AWSIoTMQTTShadowClient connection configuration
myAWSIoTMQTTShadowClient.configureAutoReconnectBackoffTime(1, 32, 20)
myAWSIoTMQTTShadowClient.configureConnectDisconnectTimeout(10) # 10 sec
myAWSIoTMQTTShadowClient.configureMQTTOperationTimeout(5) # 5 sec

# Initialize Raspberry Pi's I2C interface
i2c_bus = busio.I2C(SCL, SDA)

# Intialize SeeSaw, Adafruit's Circuit Python library
ss = Seesaw(i2c_bus, addr=0x36)

# Connect to AWS IoT
myAWSIoTMQTTShadowClient.connect()

# Create a device shadow handler, use this to update and delete shadow document
deviceShadowHandler = myAWSIoTMQTTShadowClient.createShadowHandlerWithName(args.thingName, True)

# Delete current shadow JSON doc
deviceShadowHandler.shadowDelete(customShadowCallback_Delete, 5)

# Read data from moisture sensor and update shadow
while True:

    # read moisture level through capacitive touch pad
    moistureLevel = ss.moisture_read()

    # read temperature from the temperature sensor
    temp = ss.get_temp()

    # Display moisture and temp readings
    print("Moisture Level: {}".format(moistureLevel))
    print("Temperature: {}".format(temp))
    
    # Create message payload
    payload = {"state":{"reported":{"moisture":str(moistureLevel),"temp":str(temp)}}}

    # Update shadow
    deviceShadowHandler.shadowUpdate(json.dumps(payload), customShadowCallback_Update, 5)
    time.sleep(1)
```

Salve o arquivo em um local onde você possa encontrá-lo. Execute `moistureSensor.py` na linha de comando com os seguintes parâmetros:

endpoint  
Seu AWS IoT endpoint personalizado. Para obter mais informações, consulte [API REST da Sombra do Dispositivo](device-shadow-rest-api.md).

rootCA  
O caminho completo para seu certificado CA AWS IoT raiz.

cert  
O caminho completo para o certificado AWS IoT do seu dispositivo.

key  
O caminho completo para a chave privada AWS IoT do certificado do seu dispositivo.

thingName  
O nome do objeto (neste caso, `RaspberryPi`).

clientId  
O ID do cliente MQTT. Use `RaspberryPi`.

A linha de comando deve ser semelhante a esta:

`python3 moistureSensor.py --endpoint your-endpoint --rootCA ~/certs/AmazonRootCA1.pem --cert ~/certs/raspberrypi-certificate.pem.crt --key ~/certs/raspberrypi-private.pem.key --thingName RaspberryPi --clientId RaspberryPi`

Tente tocar no sensor, colocá-lo em um vaso ou em um copo de água para ver como o sensor responde a vários níveis de umidade. Se for necessário, você poderá alterar o valor limite no `MoistureSensorRule`. Quando a leitura do sensor de umidade fica abaixo do valor especificado na instrução de consulta SQL da sua regra, AWS IoT publica uma mensagem no tópico do Amazon SNS. Você deve receber uma mensagem de e-mail que contém os dados de umidade e temperatura.

Depois de verificar o recebimento de mensagens de e-mail do Amazon SNS, pressione **CTRL\$1C** para interromper o programa Python. É improvável que o programa Python envie mensagens suficientes para gerar cobranças, mas é uma prática recomendada interromper o programa ao concluir.