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 fazer as chamadas de API REST e 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.

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 dois tipos de autorização:

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

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.

Anote o accessToken valor, você o usa mais adiante no tutorial.

Nota

Os tokens ao portador expiram após uma hora. Se eles expirarem, execute os mesmos comandos para gerar novos tokens de portador.

Criar um grupo de recursos

Use a cli do Azure para criar um grupo de recursos que contenha o aplicativo IoT Central criado neste tutorial:

az group create --name iot-central-rest-tutorial --location eastus

Criar uma aplicação de IoT Central

Use o seguinte comando para gerar um aplicativo IoT Central com um nome aleatório para usar neste tutorial:

appName=app-rest-$(date +%s)

az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName

Anote o nome do aplicativo, você o usará posteriormente 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:

Para criar um token de operador chamado operator-token usando a CLI do Azure, execute o seguinte comando. O GUID da função é a ID da função de operador em todos os aplicativos do IoT Central:

appName=<the app name generated previously>
bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/operator-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ae2c9854-393b-4f97-8c42-479d70ce626e"}]}'

Anote o token do operador que o comando retorna, você o usa mais adiante no tutorial. O token se parece com SharedAccessSignature sr=2....

Para criar um token de administrador chamado admin-token usando a CLI do Azure, execute o seguinte comando. O GUID da função é a ID da função de administrador em todos os aplicativos do IoT Central:

$appName=<the app name generated previously>
$bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/admin-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"}]}'

Anote o token de administrador que o comando retorna, você o usa mais tarde no tutorial. O token se parece com SharedAccessSignature sr=2....

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

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"displayName": "My phone app","simulated": false,"enabled": true}'

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/credentials?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Anote os valores e primaryKey que idScope o comando retorna, você os usa mais adiante no tutorial.

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.

Captura de ecrã que mostra o código QR que utiliza para ligar o dispositivo.

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:

Obtenha a aplicação para o seu telemóvel Android no Google Play.Transfira a aplicação para o seu telemóvel a partir da 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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Anote o valor que template o comando retorna, você o usa mais tarde no tutorial.

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
deviceTemplateId=<the device template Id you made a note of previously>
q1='{"query": "SELECT $id as ID, $ts as timestamp, sensors.accelerometer FROM '
q2=' WHERE WITHIN_WINDOW(P1D) AND sensors.accelerometer <> NULL"}'
query="$q1 $deviceTemplateId $q2"
echo $query

az rest --method post --uri https://$appName.azureiotcentral.com/api/query?api-version=2022-10-31-preview --headers Authorization="$operatorToken" "Content-Type=application/json" --body "$query"

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/components/device_info/properties?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method post --uri https://$appName.azureiotcentral.com/api/devices/phone-001/commands/lightOn?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"duration": 3, "delay": 1, "pulses": 2}'

Clean up resources (Limpar recursos)

Se você terminou de usar o aplicativo IoT Central neste tutorial, poderá excluí-lo:

appName=<the app name generated previously>

az iot central app delete --name $appName --resource-group iot-central-rest-tutorial