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

  • Artigo

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 concluídas 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, irá aprender a:

  • Autorize a API REST.
  • Crie um aplicativo 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 neste tutorial, você precisa:

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

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

CLI do Azure

Você usa a CLI do Azure para gerar os tokens de portador que algumas das APIs REST usam para autorização.

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

    • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

Postman

Neste tutorial, você usa o Postman para fazer as chamadas da API REST. Se preferir não descarregar e instalar o Postman, pode usar a versão online. Você pode completar todas as etapas do tutorial usando a versão gratuita do Postman.

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

Importar a coleção do Postman

Para importar a coleção, abra o Postman e selecione Importar. Na caixa de diálogo Importar, selecione Vincular e cole no seguinte URL, selecione Continuar.

Seu espaço de trabalho agora contém a coleção de tutoriais REST do IoT Central. Esta coleção inclui todas as APIs que você usa no tutorial.

A coleção usa variáveis para parametrizar as chamadas da API REST. Para ver as variáveis, selecione o ... próximo ao tutorial REST do IoT Central e selecione Editar. Em seguida, selecione Variáveis. Muitas das variáveis são definidas automaticamente à medida que você faz as chamadas de 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 ao portador que autoriza o acesso ao https://management.azure.com. Você usa esse token de portador quando cria e exclui o aplicativo IoT Central. Um aplicativo do IoT Central é um recurso do Azure.
  • Um token ao portador que autoriza o acesso ao https://apps.azureiotcentral.com. Você usa esse token de portador para criar os tokens de API no aplicativo IoT Central.
  • Tokens de API de administrador e operador que autorizam o acesso a recursos em seu aplicativo IoT Central. Você usa esses tokens para a maioria das chamadas de 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 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

    Gorjeta

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

    Copie o accessToken valor para a coluna Valor atual para bearerToken nas variáveis de 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

    Gorjeta

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

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

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

Screenshot that shows the variables set manually in the Postman collection.

Certifique-se de salvar as alterações na coleção Postman.

Nota

Os tokens ao portador expiram após uma hora.

Criar uma aplicação

Use as solicitações do plano de controle para criar e gerenciar aplicativos centrais de IoT. Use a seguinte solicitação PUT para criar o aplicativo que você usa 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 REST do IoT Central e selecione Criar uma solicitação de aplicativo central do IoT.
  2. Selecione Enviar.
  3. Verifique se a solicitação foi bem-sucedida. Se falhar, verifique se você inseriu os valores das variáveis bearerToken e subscriptionId na coleção Postman.
  4. Selecione Visualizar para ver a URL do seu novo aplicativo IoT Central. Anote este URL, você precisa dele mais tarde neste tutorial.

Screenshot that shows the Visualize tab with the application URL in Postman.

Criar os tokens de API

Use as seguintes solicitações de plano de dados para criar os tokens de API do aplicativo em seu aplicativo 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 REST do IoT Central e selecione Criar uma solicitação de token de operador.
  2. Selecione Enviar.
  3. No Postman, abra a coleção de tutoriais REST do IoT Central e selecione Criar uma solicitação de token de administrador.
  4. Selecione Enviar.

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

Nota

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

Registar um dispositivo

Você deve registrar um dispositivo no IoT Central antes que ele possa se conectar. Use as seguintes solicitações para registrar seu dispositivo em seu aplicativo e recuperar as credenciais do dispositivo. A primeira solicitação cria um dispositivo com phone-001 como ID do dispositivo:

  1. No Postman, abra a coleção de tutoriais 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 REST do IoT Central e selecione a solicitação Obter credenciais do dispositivo.
  4. Selecione Enviar.
  5. A guia Visualizar mostra os valores de ID, Escopo e Chave primária que o dispositivo precisa para se conectar.

Provisionar e conectar um dispositivo

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

  1. Abra seu aplicativo IoT central usando a URL do aplicativo que você anotou anteriormente.
  2. No seu aplicativo IoT Central, navegue até Dispositivos > Meu aplicativo > de telefone Conecte o > código QR. Mantenha esta página aberta até que o dispositivo esteja ligado.

Screenshot that shows the QR code you use to connect the device.

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

Instale a aplicação no seu smartphone a partir de uma das lojas de aplicações:

Get the app for your Android phone on Google Play.Download the app for your phone from the App Store.

Para conectar o aplicativo IoT Plug and Play ao seu aplicativo Iot Central:

  1. Abra a aplicação IoT PnP no seu smartphone.

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

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

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

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

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

  1. No Postman, abra a coleção de tutoriais REST do IoT Central e selecione a solicitação Listar 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 um ID de modelo de dispositivo específico:

  1. No Postman, abra a coleção de tutoriais 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 REST do IoT Central e selecione Obter propriedades de uma solicitação de componente .
  2. Selecione Enviar.

Você pode usar a API REST para chamar comandos de 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 ligada com o aplicativo IoT Plug and Play visível:

  1. No Postman, abra a coleção de tutoriais REST do IoT Central e selecione a solicitação de comando Call.
  2. Selecione Enviar.

Exportar telemetria

Você pode usar a API REST para configurar e gerenciar seu aplicativo 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 é da Microsoft.

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

  1. Navegue até RequestBin.
  2. Selecione Criar um RequestBin.
  3. Inicie sessão com um dos métodos disponíveis.
  4. Copie o URL do seu ponto de extremidade RequestBin.
  5. No Postman, abra a coleção de tutoriais 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. Guarde as alterações.

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

  1. No Postman, abra a coleção de tutoriais 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 em seu aplicativo IoT Central usando a API REST:

  1. No Postman, abra a coleção de tutoriais 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.

Pode levar alguns minutos para que a exportação comece. Para verificar o status da exportação usando a API REST:

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

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

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

Clean up resources (Limpar recursos)

Se você tiver terminado com o aplicativo IoT Central usado neste tutorial, poderá usar a API REST para excluí-lo:

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

Gorjeta

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

Próximos passos

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

Criar um modelo de dispositivo de gateway