Share via

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

  • Artigo

O IoT Central permite que você carregue mídia e outros arquivos dos dispositivos conectados no armazenamento em nuvem. Você configura a capacidade de upload de arquivos no seu aplicativo IoT Central e, então, implementa os uploads de arquivo no código do seu dispositivo. Neste artigo, aprenda a:

  • Use a API REST para configurar a capacidade de upload de arquivos em seu aplicativo IoT Central.
  • Teste o upload de arquivos executando uma amostra de um código de dispositivo.

A API REST do IoT Central permite:

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

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

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

Dica

Você pode usar o Postman para experimentar as chamadas à API REST descritas neste artigo. Baixe a coleção do Postman do IoT Central 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 uploads de arquivo.

Pré-requisitos

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

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

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

Criar uma conta de armazenamento

Para usar a API REST do Armazenamento do Microsoft Azure, você precisa de um token de portador para o recurso management.azure.com. 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 em sua assinatura. O nome diferencia maiúsculas de minúsculas.
  • accountName : o nome da conta de armazenamento no grupo de recursos especificado. Os nomes da conta de armazenamento devem ter entre 3 e 24 caracteres, usar números e apenas letras minúsculas.

O corpo da solicitação possui os seguintes campos necessários:

  • kind : tipo de conta de armazenamento
  • location : a localização geográfica em que o recurso reside
  • sku: o nome do SKU.
{
 "kind": "BlockBlobStorage",
 "location": "West US",
 "sku": "Premium_LRS"
}

Criar um contêiner

Use a seguinte solicitação para criar um contêiner chamado fileuploads em sua conta de armazenamento para os 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 do contêiner de blob devem ter entre 3 e 63 caracteres, usar números, apenas letras minúsculas e traço (-). Todo caractere de traço (-) precisa ser precedido e seguido imediatamente por uma letra ou um número.

Envie um corpo da solicitação vazio com esta solicitação semelhante ao exemplo a seguir:

{
}

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "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 da conta de armazenamento necessárias ao configurar o upload 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 é parecida com o seguinte exemplo:

{
  "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 upload

Use a seguinte solicitação para criar uma configuração de conta de armazenamento de blobs de upload de arquivos no aplicativo IoT Central:

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

O corpo da solicitação tem os campos a seguir:

  • account: o nome da conta de armazenamento onde o arquivo será carregado.
  • connectionString: a cadeia de conexão a ser conectada à conta de armazenamento. Use um dos valores value da solicitação anterior listKeys como o valor AccountKey.
  • container: o nome do contêiner na conta de armazenamento. O seguinte exemplo usa o nome fileuploads.
  • etag: ETag para evitar conflitos com vários uploads
  • sasTtl: padrão de duração ISO 8601. O prazo de validade da solicitação do dispositivo para carregar um arquivo antes de expirar.
{
  "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 é parecida com o seguinte exemplo:

{
  "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 arquivo

Use a seguinte solicitação para recuperar os detalhes de uma configuração de conta de armazenamento de blobs de upload de arquivos no aplicativo IoT Central:

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

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "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 solicitação a seguir para atualizar uma cadeia de conexão de conta de armazenamento de blob de carregamento 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 é parecida com o seguinte exemplo:


{
  "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 solicitação a seguir para excluir uma configuração de conta de armazenamento:

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

Testar o upload de arquivos

Depois de configurar o upload de arquivos no aplicativo IoT Central, você pode testá-lo com o código de exemplo. Caso ainda não tenha clonado o repositório de exemplo do upload de arquivos, use o seguinte comando para cloná-lo em uma localização adequada no computador 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 Amostra de dispositivo de upload de arquivos para o modelo de dispositivo.

  5. Na página Examinar, 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 baixado anteriormente.

  7. Escolha Publicar para publicar o modelo de dispositivo.

Adicionar um dispositivo

Para adicionar um dispositivo ao aplicativo Azure IoT Central:

  1. Escolha Dispositivos no painel esquerdo.

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

  3. Selecione + Novo e, em seguida, Criar.

  4. Selecione o dispositivo que você criou e selecione Conectar

Copie os valores de ID scope, Device ID e 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ê verá 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 o aplicativo e selecione o dispositivo que você criou. Selecione a guia Comando e um botão chamado Executar será exibido. Ao selecionar esse botão, o aplicativo IoT Central chama um método direto em seu dispositivo para carregar o arquivo. Esse método direto será exibido no código de exemplo no arquivo /device.ts. O método é chamado uploadFileCommand.

Selecione a guia Dados brutos para verificar o status de upload 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 upload do arquivo no contêiner de armazenamento.

Próximas etapas

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