Condividi tramite

Come usare l'API REST di IoT Central per caricare un file

  • Articolo

IoT Central consente di caricare file multimediali e altri file dai dispositivi connessi all'archiviazione cloud. Configurare la funzionalità di caricamento dei file nell'applicazione IoT Central e quindi implementare i caricamenti di file nel codice del dispositivo. In questo articolo viene spiegato come:

  • Usare l'API REST per configurare la funzionalità di caricamento dei file nell'applicazione IoT Central.
  • Testare il caricamento del file eseguendo codice del dispositivo di esempio.

L'API REST di IoT Central consente di:

  • Aggiungere una configurazione dell'account di archiviazione per il caricamento di file
  • Aggiornare una configurazione dell'account di archiviazione per il caricamento di file
  • Ottenere la configurazione dell'account di archiviazione per il caricamento di file
  • Eliminare la configurazione dell'archiviazione di caricamento file

Ogni chiamata API REST di IoT Central richiede un'intestazione di autorizzazione. Per altre informazioni, vedere Come autenticare e autorizzare le chiamate API REST di IoT Central.

Per la documentazione di riferimento per l'API REST di IoT Central, vedere Informazioni di riferimento sull'API REST di Azure IoT Central.

Suggerimento

È possibile usare Postman per provare le chiamate API REST descritte in questo articolo. Scaricare la raccolta Postman di IoT Central e importarla in Postman. Nella raccolta sarà necessario impostare variabili come il sottodominio dell'app e il token di amministratore.

Per informazioni su come caricare file usando l'interfaccia utente di IoT Central, vedere Come configurare i caricamenti di file.

Prerequisiti

Per testare il caricamento del file, installare i prerequisiti seguenti nell'ambiente di sviluppo locale:

Aggiungere una configurazione dell'account di archiviazione per il caricamento di file

Per aggiungere una configurazione dell'account di archiviazione per il caricamento di file:

Creare un account di archiviazione

Per usare l'API REST Archiviazione di Azure, è necessario un token di connessione per la management.azure.com risorsa. Per ottenere un token di connessione, è possibile usare l'interfaccia della riga di comando di Azure:

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

Se non si ha un account di archiviazione per i BLOB, è possibile usare la richiesta seguente per crearne una nella sottoscrizione:

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

Le intestazioni della richiesta hanno i campi seguenti:

  • subscriptionId : ID della sottoscrizione di destinazione.
  • resourceGroupName: nome del gruppo di risorse nella sottoscrizione. Il nome non fa distinzione tra maiuscole e minuscole.
  • accountName : nome dell'account di archiviazione all'interno del gruppo di risorse specificato. I nomi degli account di archiviazione devono essere di lunghezza compresa tra 3 e 24 caratteri e utilizzare solo numeri e lettere minuscole.

Il corpo della richiesta include i campi obbligatori seguenti:

  • kind : tipo di account di archiviazione
  • location : posizione geografica in cui si trova la risorsa
  • sku: il nome dello SKU.
{
 "kind": "BlockBlobStorage",
 "location": "West US",
 "sku": "Premium_LRS"
}

Creazione di un contenitore

Usare la richiesta seguente per creare un contenitore denominato fileuploads nell'account di archiviazione per i BLOB:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/blobServices/default/containers/fileuploads?api-version=2021-09-01
  • containerName : i nomi dei contenitori BLOB devono avere una lunghezza compresa tra 3 e 63 caratteri e usare numeri, lettere minuscole e solo trattini (-). Ogni trattino (-) deve essere immediatamente preceduto e seguito da una lettera o un numero.

Inviare un corpo di richiesta vuoto con questa richiesta simile all'esempio seguente:

{
}

La risposta a questa richiesta è simile all'esempio seguente:

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

Ottenere le chiavi dell'account di archiviazione

Usare la richiesta seguente per recuperare le chiavi dell'account di archiviazione necessarie quando si configura il caricamento in IoT Central:

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

La risposta a questa richiesta è simile all'esempio seguente:

{
  "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"
    }
  ]
}

Creare la configurazione di caricamento

Usare la richiesta seguente per creare una configurazione dell'account di archiviazione BLOB di caricamento di file nell'applicazione IoT Central:

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

Il corpo della richiesta include i campi seguenti:

  • account: nome dell'account di archiviazione in cui caricare il file.
  • connectionString: stringa di connessione per connettersi all'account di archiviazione. Usare uno dei value valori della richiesta precedente listKeys come AccountKey valore.
  • container: nome del contenitore all'interno dell'account di archiviazione. Nell'esempio seguente viene usato il nome fileuploads.
  • etag: ETag per evitare conflitti con più caricamenti
  • sasTtl: standard di durata ISO 8601, quantità di tempo in cui la richiesta del dispositivo di caricare un file è valida prima della scadenza.
{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H"
}

La risposta a questa richiesta è simile all'esempio seguente:

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

}

Ottenere la configurazione dell'account di archiviazione per il caricamento di file

Usare la richiesta seguente per recuperare i dettagli di una configurazione dell'account di archiviazione BLOB di caricamento di file nell'applicazione IoT Central:

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

La risposta a questa richiesta è simile all'esempio seguente:

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

}

Aggiornare la configurazione dell'account di archiviazione per il caricamento del file

Usare la richiesta seguente per aggiornare un account di archiviazione BLOB di caricamento di file stringa di connessione nell'applicazione 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/"
}

La risposta a questa richiesta è simile all'esempio seguente:


{
  "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\""
}

Rimuovere la configurazione dell'account di archiviazione per il caricamento di file

Usare la richiesta seguente per eliminare una configurazione dell'account di archiviazione:

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

Test del caricamento di file

Dopo aver configurato i caricamenti di file nell'applicazione IoT Central, è possibile testarlo con il codice di esempio. Se il repository di esempio di caricamento del file non è già stato clonato, usare i comandi seguenti per clonarlo in un percorso appropriato nel computer locale e installare i pacchetti dipendenti:

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

Creare il modello di dispositivo e importare il modello

Per testare il caricamento del file, eseguire un'applicazione del dispositivo di esempio. Creare un modello di dispositivo per il dispositivo di esempio da usare.

  1. Aprire l'applicazione nell'interfaccia utente di IoT Central.

  2. Passare alla scheda Modelli di dispositivo nel riquadro sinistro, selezionare + Nuovo:

  3. Scegliere Dispositivo IoT come tipo di modello.

  4. Nella pagina Personalizza della procedura guidata immettere un nome, ad esempio File Upload Device Sample (Esempio di dispositivo di caricamento file) per il modello di dispositivo.

  5. Nella pagina Rivedi selezionare Crea.

  6. Selezionare Importa un modello e caricare il file di modello FileUploadDeviceDcm.json dalla cartella iotc-file-upload-device\setup nel repository scaricato in precedenza.

  7. Selezionare Pubblica per pubblicare il modello di dispositivo.

Aggiungere un dispositivo

Per aggiungere un dispositivo all'applicazione Azure IoT Central:

  1. Scegliere Dispositivi nel riquadro sinistro.

  2. Selezionare il modello di dispositivo File Upload Device Sample creato in precedenza.

  3. Selezionare + Nuovo e selezionare Crea.

  4. Selezionare il dispositivo creato e selezionare Connessione

Copiare i valori per ID scope, Device IDe Primary key. Questi valori vengono usati nel codice di esempio del dispositivo.

Eseguire il codice di esempio

Aprire il repository Git scaricato in VS Code. Creare un file ".env" nella radice del progetto e aggiungere i valori copiati in precedenza. Il file dovrebbe essere simile all'esempio seguente con i valori annotato in precedenza.

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

Aprire il repository Git scaricato in VS Code. Premere F5 per eseguire/eseguire il debug dell'esempio. Nella finestra del terminale si noterà che il dispositivo è registrato ed è connesso a 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
}

Il progetto di esempio viene fornito con un file di esempio denominato datafile.json. Questo file viene caricato quando si usa il comando Carica file nell'applicazione IoT Central.

Per testare il caricamento, aprire l'applicazione e selezionare il dispositivo creato. Selezionare la scheda Comando e viene visualizzato un pulsante denominato Esegui. Quando si seleziona il pulsante, l'app IoT Central chiama un metodo diretto nel dispositivo per caricare il file. È possibile visualizzare questo metodo diretto nel codice di esempio nel file /device.ts. Il metodo è denominato uploadFileCommand.

Selezionare la scheda Dati non elaborati per verificare lo stato di caricamento del file.

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

È anche possibile effettuare una chiamata API REST per verificare lo stato di caricamento del file nel contenitore di archiviazione.

Passaggi successivi

Dopo aver appreso come configurare i caricamenti di file con l'API REST, un passaggio successivo consigliato è Come creare modelli di dispositivo dall'interfaccia utente grafica di IoT Central.