Como usar a API REST do IoT Central para carregar um arquivo

  • Artigo

O IoT Central permite carregar mídia e outros arquivos de dispositivos conectados para o armazenamento em nuvem. Configure a capacidade de carregamento de ficheiros na aplicação IoT Central e, em seguida, implemente carregamentos de ficheiros no código do dispositivo. Neste artigo, saiba como:

  • Use a API REST para configurar o recurso de carregamento de arquivos em seu aplicativo IoT Central.
  • Teste o upload do arquivo executando algum código de dispositivo de exemplo.

A API REST do IoT Central permite:

  • Adicionar uma configuração de conta de armazenamento de upload de arquivo
  • Atualizar uma configuração de conta de armazenamento de upload de arquivo
  • Obter a configuração da conta de armazenamento de upload de arquivos
  • Excluir a configuração de armazenamento de upload de arquivo

Cada chamada à API REST do IoT Central requer um cabeçalho de autorização. Para saber mais, consulte Como autenticar e autorizar chamadas de API REST do IoT Central.

Para obter a documentação de referência da API REST do IoT Central, consulte Referência da API REST do Azure IoT Central.

Gorjeta

Você pode usar o Postman para experimentar as chamadas de API REST descritas neste artigo. Faça o download da coleção IoT Central Postman e importe-a para o Postman. Na coleção, você precisará definir variáveis como o subdomínio do aplicativo e o token de administrador.

Para saber como carregar arquivos usando a interface do usuário do IoT Central, consulte Como configurar carregamentos de arquivos.

Pré-requisitos

Para testar o upload do arquivo, instale os seguintes pré-requisitos em seu ambiente de desenvolvimento local:

Adicionar uma configuração de conta de armazenamento de upload de arquivo

Para adicionar uma configuração de conta de armazenamento de upload de arquivo:

Criar uma conta de armazenamento

Para usar a API REST do Armazenamento do Azure, você precisa de um token de portador para o management.azure.com recurso. Para obter um token de portador, você pode usar a CLI do Azure:

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

Se você não tiver uma conta de armazenamento para seus blobs, poderá usar a seguinte solicitação para criar uma em sua assinatura:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}?api-version=2021-09-01

Os cabeçalhos de solicitação têm os seguintes campos:

  • subscriptionId : A ID da assinatura de destino.
  • resourceGroupName: O nome do grupo de recursos na sua subscrição. O nome não diferencia maiúsculas de minúsculas.
  • accountName : O nome da conta de armazenamento dentro do grupo de recursos especificado. O nome da conta de armazenamento tem de ter entre 3 e 24 carateres de comprimento e conter apenas números e letras minúsculas.

O corpo da solicitação tem os seguintes campos obrigatórios:

  • kind : Tipo de conta de armazenamento
  • location : A geolocalização onde o recurso vive
  • sku: O nome SKU.
{
 "kind": "BlockBlobStorage",
 "location": "West US",
 "sku": "Premium_LRS"
}

Criar um contentor

Use a seguinte solicitação para criar um contêiner chamado fileuploads em sua conta de armazenamento para seus blobs:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/blobServices/default/containers/fileuploads?api-version=2021-09-01
  • containerName : Os nomes dos contêineres de blob devem ter entre 3 e 63 caracteres e usar apenas números, letras minúsculas e traço (-). Cada caractere de traço (-) deve ser imediatamente precedido e seguido por uma letra ou número.

Envie um corpo de solicitação vazio com essa solicitação semelhante ao exemplo a seguir:

{
}

A resposta a essa solicitação se parece com o exemplo a seguir:

{
  "id": "/subscriptions/your-subscription-id/resourceGroups/yourResourceGroupName/providers/Microsoft.Storage/storageAccounts/yourAccountName/blobServices/default/containers/fileuploads",
  "name": "fileuploads",
  "type": "Microsoft.Storage/storageAccounts/blobServices/containers"
}

Obter as chaves da conta de armazenamento

Use a seguinte solicitação para recuperar as chaves de conta de armazenamento necessárias ao configurar o carregamento no IoT Central:

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/listKeys?api-version=2021-09-01

A resposta a essa solicitação se parece com o exemplo a seguir:

{
  "keys": [
    {
      "creationTime": "2022-05-19T19:22:40.9132287Z",
      "keyName": "key1",
      "value": "j3UTm**************==",
      "permissions": "FULL"
    },
    {
      "creationTime": "2022-05-19T19:22:40.9132287Z",
      "keyName": "key2",
      "value": "Nbs3W**************==",
      "permissions": "FULL"
    }
  ]
}

Criar a configuração de carregamento

Use a seguinte solicitação para criar uma configuração de conta de armazenamento de blob de upload de arquivo em seu aplicativo IoT Central:

PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

O corpo da solicitação tem os seguintes campos:

  • account: O nome da conta de armazenamento para onde carregar o arquivo.
  • connectionString: A cadeia de conexão para se conectar à conta de armazenamento. Use um dos value valores da solicitação anterior listKeys como o AccountKey valor.
  • container: O nome do contêiner dentro da conta de armazenamento. O exemplo a seguir usa o nome fileuploads.
  • etag: ETag para evitar conflitos com vários uploads
  • sasTtl: ISO 8601 padrão de duração, A quantidade de tempo que a solicitação do dispositivo para carregar um arquivo é válida antes que ele expire.
{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H"
}

A resposta a essa solicitação se parece com o exemplo a seguir:

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H",
  "state": "pending",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""

}

Obter a configuração da conta de armazenamento de upload de arquivos

Use a seguinte solicitação para recuperar detalhes de uma configuração de conta de armazenamento de blob de upload de arquivo em seu aplicativo IoT Central:

GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

A resposta a essa solicitação se parece com o exemplo a seguir:

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "yourContainerName",
  "state": "succeeded",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""

}

Atualizar a configuração da conta de armazenamento de upload de arquivo

Use a seguinte solicitação para atualizar uma cadeia de conexão de conta de armazenamento de blob de upload de arquivo em seu aplicativo IoT Central:

PATCH https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

{
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/"
}

A resposta a essa solicitação se parece com o exemplo a seguir:


{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "yourContainerName",
  "sasTtl": "PT1H",
  "state": "succeeded",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}

Remover a configuração da conta de armazenamento de upload de arquivo

Use a seguinte solicitação para excluir uma configuração de conta de armazenamento:

DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

Upload de arquivo de teste

Depois de configurar os carregamentos de arquivos em seu aplicativo IoT Central, você pode testá-lo com o código de exemplo. Se você ainda não clonou o repositório de exemplo de upload de arquivos, use os seguintes comandos para cloná-lo para um local adequado em sua máquina local e instalar os pacotes dependentes:

git clone https://github.com/azure-Samples/iot-central-file-upload-device
cd iotc-file-upload-device
npm i
npm build

Criar o modelo de dispositivo e importar o modelo

Para testar o carregamento do arquivo, execute um aplicativo de dispositivo de exemplo. Crie um modelo de dispositivo para o dispositivo de exemplo a ser usado.

  1. Abra seu aplicativo na interface do usuário do IoT Central.

  2. Navegue até a guia Modelos de dispositivo no painel esquerdo, selecione + Novo:

  3. Escolha Dispositivo IoT como o tipo de modelo.

  4. Na página Personalizar do assistente, insira um nome como Exemplo de dispositivo de carregamento de arquivo para o modelo de dispositivo.

  5. Na página Revisão, selecione Criar.

  6. Selecione Importar um modelo e carregue o arquivo de modelo FileUploadDeviceDcm.json da pasta iotc-file-upload-device\setup no repositório que você baixou anteriormente.

  7. Selecione Publicar para publicar o modelo de dispositivo.

Adicionar um dispositivo

Para adicionar um dispositivo ao seu aplicativo do Azure IoT Central:

  1. Escolha Dispositivos no painel esquerdo.

  2. Selecione o modelo de dispositivo de Exemplo de Dispositivo de Carregamento de Arquivo que você criou anteriormente.

  3. Selecione + Novo e selecione Criar.

  4. Selecione o dispositivo que criou e selecione Ligar

Copie os valores de ID scope, Device IDe Primary key. Use esses valores no código de exemplo do dispositivo.

Execute o código de exemplo

Abra o repositório git que você baixou no VS Code. Crie um arquivo ".env" na raiz do seu projeto e adicione os valores copiados anteriormente. O arquivo deve se parecer com o exemplo a seguir com os valores que você anotou anteriormente.

scopeId=<YOUR_SCOPE_ID>
deviceId=<YOUR_DEVICE_ID>
deviceKey=<YOUR_PRIMARY_KEY>
modelId=dtmi:IoTCentral:IotCentralFileUploadDevice;1

Abra o repositório git que você baixou no VS Code. Pressione F5 para executar/depurar o exemplo. Na janela do terminal, você vê que o dispositivo está registrado e conectado ao IoT Central:

Starting IoT Central device...
 > Machine: Windows_NT, 8 core, freemem=6674mb, totalmem=16157mb
Starting device registration...
DPS registration succeeded
Connecting the device...
IoT Central successfully connected device: 7z1xo26yd8
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}

O projeto de exemplo vem com um arquivo de exemplo chamado datafile.json. Esse arquivo é carregado quando você usa o comando Carregar arquivo em seu aplicativo IoT Central.

Para testar o upload, abra seu aplicativo e selecione o dispositivo que você criou. Selecione a guia Comando e você verá um botão chamado Executar. Quando você seleciona esse botão, o aplicativo IoT Central chama um método direto em seu dispositivo para carregar o arquivo. Você pode ver esse método direto no código de exemplo no arquivo /device.ts. O método é chamado uploadFileCommand.

Selecione a guia Dados brutos para verificar o status de carregamento do arquivo.

Screenshot showing the U I of how to verify a file upload.

Você também pode fazer uma chamada à API REST para verificar o status de carregamento do arquivo no contêiner de armazenamento.

Próximos passos

Agora que você aprendeu como configurar carregamentos de arquivos com a API REST, uma próxima etapa sugerida é Como criar modelos de dispositivo a partir da GUI do IoT Central.