Tutorial: Usar a API REST para gerenciar um aplicativo do Azure IoT Central

Este tutorial mostra como usar a API REST do Azure IoT Central para criar e interagir com um aplicativo do IoT Central. Este tutorial usa a API REST para concluir muitas das etapas que você concluiu usando a interface do usuário da Web nos inícios rápidos. Essas etapas incluem o uso de um aplicativo em seu smartphone como um dispositivo IoT que se conecta ao IoT Central.

Neste tutorial, você aprenderá como:

• Autorize a API REST.
• Crie um aplicativo do IoT Central.
• Adicione um dispositivo ao seu aplicativo.
• Consulte e controle o dispositivo.
• Configure a exportação de dados.
• Excluir um aplicativo.

Pré-requisitos

Para concluir as etapas deste tutorial, você precisará do seguinte:

• Uma assinatura ativa do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

• Um smartphone Android ou iOS no qual você posa instalar um aplicativo gratuito de uma das lojas de aplicativos oficiais.

CLI do Azure

A CLI do Azure é usada para gerar os tokens de portador que algumas APIs REST usam para autorização.

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.

  • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

postman

Neste tutorial, você usará o Postman para fazer as chamadas à API REST. Se preferir não baixar e instalar o Postman, você poderá usar a versão online. É possível concluir todas as etapas no tutorial usando a versão gratuita do Postman.

O tutorial usa uma coleção predefinida do Postman que inclui alguns scripts para ajudá-lo a concluir as etapas.

Importar a coleção Postman

Para importar a coleção, abra o Postman e selecione Importar. No diálogo Importar, selecione Link e cole noURL a seguir; selecione Continuar.

O workspace agora contém a coleção de Tutoriais do REST do IoT Central. Esta coleção inclui todas as APIs usadas no tutorial.

A coleção usa variáveis para parametrizar as chamadas à API REST. Para ver as variáveis, selecione ... ao lado de Tutorial do REST do IoT Central e selecione Editar. Em seguida, selecione Variáveis. Muitas variáveis são definidas automaticamente à medida que você faz as chamadas à API ou têm valores predefinidos.

Autorizar a API REST

Antes de usar a API REST, você deve configurar a autorização. As chamadas à API REST neste tutorial usam um dos três tipos de autorização:

• Um token de portador que autoriza o acesso ao https://management.azure.com. Você usa esse token de portador ao criar e excluir o aplicativo do IoT Central. Um aplicativo do IoT Central é um recurso do Azure.
• Um token de portador que autoriza o acesso ao https://apps.azureiotcentral.com. Esse token de portador é usado para criar os tokens de API no aplicativo do IoT Central.
• Tokens de API de administrador e operador que autorizam o acesso aos recursos no aplicativo do IoT Central. Esses tokens são usados para a maioria das chamadas à API neste tutorial. Esses tokens só autorizam o acesso a um aplicativo específico do IoT Central.

Atribua valores às seguintes variáveis na coleção do Postman:

• bearerToken: execute os seguintes comandos da CLI do Azure para gerar um token de portador que autorize o acesso a https://management.azure.com:

  az login
  az account get-access-token --resource https://management.azure.com
  

  Dica

  Talvez seja necessário executar az login mesmo se estiver usando o Cloud Shell.

  Copie o valor de accessToken na coluna Valor atual para bearerToken nas variáveis da coleção.

• bearerTokenApp: execute os seguintes comandos da CLI do Azure para gerar um token de portador que autorize o acesso a https://apps.azureiotcentral.com:

  az account get-access-token --resource https://apps.azureiotcentral.com
  

  Dica

  Se você iniciou uma nova instância do shell, execute az login novamente.

  Copie o valor de accessToken na coluna Valor atual para bearerTokenApp nas variáveis da coleção.

• subscriptionId: a ID da assinatura foi incluída na saída dos dois comandos anteriores. Copie o valor de subscription na coluna Valor atual para subscriptionId nas variáveis da coleção.

Salve as alterações na coleção do Postman.

Observação

Os tokens de portador expiram após uma hora.

Criar um aplicativo

Use as solicitações do painel de controle para criar e gerenciar aplicativos do IoT Central. Use a solicitação PUT a seguir para criar o aplicativo usado neste tutorial. A solicitação usa um token de portador para autorizar e gera um nome de aplicativo aleatório.

1. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Criar um aplicativo do IoT Central.
2. Selecione Enviar.
3. Verifique se a solicitação teve êxito. Se falhar, verifique se você inseriu os valores de variável bearerToken e subscriptionId na coleção do Postman.
4. Selecione Visualizar para ver a URL do novo aplicativo do IoT Central. Anote o nome dessa URL. Você precisará dela mais tarde neste tutorial.

Criar os tokens de API

Use as solicitações do plano de dados a seguir para criar os tokens de API no aplicativo do IoT Central. Algumas das solicitações neste tutorial exigem um token de API com permissões de administrador, mas a maioria pode usar permissões de operador:

1. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Criar um token de operador.
2. Selecione Enviar.
3. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Criar um token de administrador.
4. Selecione Enviar.

Se você quiser ver esses tokens no aplicativo do IoT Central, abra o aplicativo e navegue até Segurança > Permissões > Tokens de API.

Observação

Um script no Postman adiciona automaticamente esses tokens de API à lista de variáveis de coleção para você.

Registrar um dispositivo

É necessário registrar um dispositivo no IoT Central antes de conectá-lo. Use as solicitações a seguir para registrar o dispositivo no aplicativo e recuperar as credenciais do dispositivo. A primeira solicitação cria um dispositivo com phone-001 como a ID do dispositivo:

1. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Adicionar um dispositivo.
2. Selecione Enviar. Na resposta, observe que o dispositivo não está provisionado.
3. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Obter credenciais do dispositivo.
4. Selecione Enviar.
5. A guia Visualizar mostra os valores Escopo da ID e Chave primária que o dispositivo precisa para poder se conectar.

Provisionar e conectar um dispositivo

Para evitar a necessidade de inserir as credenciais do dispositivo manualmente no smartphone, você pode usar um código QR gerado pelo IoT Central. O código QR codifica a ID do dispositivo, o escopo da ID e a chave primária. Para exibir o código QR:

1. Abra seu aplicativo do IoT Central usando a URL do aplicativo anotada anteriormente.
2. No aplicativo IoT Central, navegue até Dispositivos > Meu aplicativo de telefone > Conectar > Código QR. Mantenha esta página aberta até que o dispositivo esteja conectado.

Para simplificar a configuração, este artigo usa o aplicativo de smartphone IoT Plug and Play como um dispositivo do IoT. O aplicativo envia os dados telemétricos coletados dos sensores do smartphone, responde aos comandos invocados do IoT Central e relata valores de propriedade para o IoT Central.

Instale o aplicativo em seu smartphone de uma das lojas de aplicativos:

Para conectar o aplicativo IoT Plug and Play ao aplicativo do IoT Central:

1. Abra o aplicativo PnP do IoT em seu smartphone.

2. Na página de boas-vindas, selecione Verificar código QR. Aponte a câmera do smartphone para o código QR. Em seguida, aguarde alguns segundos enquanto a conexão é estabelecida.

3. Na página de telemetria do aplicativo, você poderá ver os dados que o aplicativo está enviando para o IoT Central. Na página de logs, é possível ver o dispositivo se conectando e várias mensagens de inicialização.

Para verificar se o dispositivo está provisionado, você pode usar a API REST:

1. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Obter um dispositivo.
2. Selecione Enviar. Na resposta, observe que agora o dispositivo está provisionado. O IoT Central também atribuiu um modelo de dispositivo ao dispositivo com base na ID do modelo enviada pelo dispositivo.

Você pode usar a API REST para gerenciar modelos de dispositivos no aplicativo. Por exemplo, para exibir os modelos de dispositivo no aplicativo:

1. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Listar os modelos de dispositivo.
2. Selecione Enviar.

Consultar e controlar o dispositivo

Você pode usar a API REST para consultar a telemetria de seus dispositivos. A solicitação a seguir retorna os dados do acelerômetro de todos os dispositivos que compartilham uma ID de modelo de dispositivo específica:

1. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Executar uma consulta.
2. Selecione Enviar.

Você pode usar a API REST para ler e definir as propriedades do dispositivo. A solicitação a seguir retorna todos os valores de propriedade do componente Informações do dispositivo que o dispositivo implementa:

1. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Obter propriedades de um componente.
2. Selecione Enviar.

Você pode usar a API REST para chamar comandos do dispositivo. A solicitação a seguir chama um comando que liga a luz do smartphone duas vezes por três segundos. Para que o comando seja executado, a tela do smartphone deve estar ativada com o aplicativo IoT Plug and Play visível:

1. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Comando de chamada.
2. Selecione Enviar.

Exportar telemetria

Você pode usar a API REST para configurar e gerenciar o aplicativo do IoT Central. As etapas a seguir mostram como configurar a exportação de dados para enviar valores de telemetria para um webhook. Para simplificar a configuração, este artigo usa um webhook RequestBin como destino. RequestBin é um serviço que não pertence à Microsoft.

Para criar o ponto de extremidade de teste para o destino de exportação de dados:

1. Navegue até RequestBin.
2. Selecione Criar um RequestBin.
3. Entre usando um dos métodos disponíveis.
4. Copie a URL do ponto de extremidade RequestBin.
5. No Postman, abra a coleção de Tutoriais do REST do IoT Central e navegue até as variáveis de coleção.
6. Cole a URL do ponto de extremidade RequestBin na coluna Valor atual para webHookURL nas variáveis de coleção.
7. Salve as alterações.

Para configurar o destino de exportação em seu aplicativo do IoT Central usando a API REST:

1. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Criar um destino de exportação de webhook.
2. Selecione Enviar.

Para configurar a definição de exportação no aplicativo do IoT Central usando a API REST:

1. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Criar uma definição de exportação de telemetria.
2. Selecione Enviar. Observe que o status é Não iniciado.

A exportação pode demorar alguns minutos para iniciar. Para verificar o status da exportação usando a API REST:

1. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Obter uma exportação pela ID.
2. Selecione Enviar. Quando o status é íntegro, o IoT Central está enviando a telemetria para o webhook.

O aplicativo no smartphone não envia telemetria, a menos que a tela esteja ativada e o aplicativo IoT Plug and Play esteja visível.

Quando o aplicativo de smartphone estiver enviando telemetria, navegue até RequestBin para exibir a telemetria exportada.

Limpar os recursos

Ao finalizar o aplicativo IoT Central usado neste tutorial, a API REST poderá ser utilizada para excluí-lo:

1. No Postman, abra a coleção de Tutoriais do REST do IoT Central e selecione a solicitação Excluir um aplicativo do IoT Central.
2. Selecione Enviar.

Dica

Essa solicitação usa um token de portador gerado no início do tutorial. Os tokens de portador expiram após uma hora. Talvez seja necessário gerar um novo token de portador que autorize o acesso ao https://apps.azureiotcentral.com.

Próximas etapas

Se você preferir continuar com o conjunto de tutoriais do IoT Central e saber mais sobre como criar uma solução de IoT Central, confira:

Criar um modelo de dispositivo de gateway