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 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.
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.
- No Postman, abra a coleção de tutoriais REST do IoT Central e selecione Criar uma solicitação de aplicativo central do IoT.
- Selecione Enviar.
- 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.
- Selecione Visualizar para ver a URL do seu novo aplicativo IoT Central. Anote este URL, você precisa dele mais tarde neste tutorial.
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:
- No Postman, abra a coleção de tutoriais REST do IoT Central e selecione Criar uma solicitação de token de operador.
- Selecione Enviar.
- No Postman, abra a coleção de tutoriais REST do IoT Central e selecione Criar uma solicitação de token de administrador.
- 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:
- No Postman, abra a coleção de tutoriais REST do IoT Central e selecione a solicitação Adicionar um dispositivo.
- Selecione Enviar. Na resposta, observe que o dispositivo não está provisionado.
- No Postman, abra a coleção de tutoriais REST do IoT Central e selecione a solicitação Obter credenciais do dispositivo.
- Selecione Enviar.
- 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:
- Abra seu aplicativo IoT central usando a URL do aplicativo que você anotou anteriormente.
- 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.
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:
Para conectar o aplicativo IoT Plug and Play ao seu aplicativo Iot Central:
Abra a aplicação IoT PnP no seu smartphone.
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.
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:
- No Postman, abra a coleção de tutoriais REST do IoT Central e selecione a solicitação Obter um dispositivo.
- 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:
- No Postman, abra a coleção de tutoriais REST do IoT Central e selecione a solicitação Listar modelos de dispositivo.
- 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:
- No Postman, abra a coleção de tutoriais REST do IoT Central e selecione a solicitação Executar uma consulta.
- 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:
- No Postman, abra a coleção de tutoriais REST do IoT Central e selecione Obter propriedades de uma solicitação de componente .
- 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:
- No Postman, abra a coleção de tutoriais REST do IoT Central e selecione a solicitação de comando Call.
- 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:
- Navegue até RequestBin.
- Selecione Criar um RequestBin.
- Inicie sessão com um dos métodos disponíveis.
- Copie o URL do seu ponto de extremidade RequestBin.
- No Postman, abra a coleção de tutoriais REST do IoT Central e navegue até as variáveis de coleção.
- Cole a URL do ponto de extremidade RequestBin na coluna Valor atual para webHookURL nas variáveis de coleção.
- Guarde as alterações.
Para configurar o destino de exportação em seu aplicativo IoT Central usando a API REST:
- 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.
- Selecione Enviar.
Para configurar a definição de exportação em seu aplicativo IoT Central usando a API REST:
- 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.
- 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:
- No Postman, abra a coleção de tutoriais REST do IoT Central e selecione a solicitação Obter uma exportação por ID.
- 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:
- No Postman, abra a coleção de tutoriais REST do IoT Central e selecione Excluir uma solicitação de aplicativo central do IoT.
- 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: