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

Artigo
11/11/2024

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

Você usa a CLI do Azure para fazer chamadas à API e 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.

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

Execute os seguintes comandos da CLI do Azure para gerar um token de portador que autorize o acesso ao 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.

Anote o valor de accessToken e use-o posteriormente no tutorial.

Observação

Os tokens de 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 que você cria neste tutorial:

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

Criar um aplicativo IoT Central

Use o seguinte comando para gerar um aplicativo do IoT Central com um nome aleatório a ser usado 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á mais adiante 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:

Para criar um token de operador chamado operator-token usando a CLI do Azure, execute o comando a seguir. O GUID de 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 usará 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 comando a seguir. O GUID de 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 usará posteriormente no tutorial. O token se parece com SharedAccessSignature sr=2....

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

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:

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 de idScope e primaryKey que o comando retorna, você os usará mais adiante no tutorial.

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:

Abra seu aplicativo do IoT Central usando a URL do aplicativo anotada anteriormente.
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.

Captura de tela que mostra o código QR usado para conectar o dispositivo.

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:

Abra o aplicativo PnP do IoT em seu smartphone.
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.
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:

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 de template que o comando retorna, você o usará mais adiante no tutorial.

Você pode usar a API REST para gerenciar modelos de dispositivos 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 uma ID de modelo de dispositivo específica:

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

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}'

Limpar os recursos

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

appName=<the app name generated previously>

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

Compartilhar via