Come usare l'API REST IoT Central per gestire le esportazioni di dati

Articolo
07/25/2023

L'API REST di IoT Central consente di sviluppare applicazioni client integrate con le applicazioni IoT Central. È possibile usare l'API REST per creare e gestire le esportazioni di dati nell'applicazione IoT Central.

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

Per la documentazione di riferimento per l'API REST 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 l'insieme IoT Central Postman e importarlo in Postman. Nella raccolta sarà necessario impostare variabili come il sottodominio dell'app e il token di amministrazione.

Per informazioni su come gestire l'esportazione dei dati usando l'interfaccia utente di IoT Central, vedere Esportare i dati IoT nell'archiviazione BLOB.

Esportazione dei dati

È possibile usare la funzionalità di esportazione dei dati IoT Central per trasmettere dati di telemetria, modifiche alle proprietà, eventi di connettività del dispositivo, eventi del ciclo di vita del dispositivo e eventi del ciclo di vita dei dispositivi alle destinazioni, ad esempio Hub eventi di Azure, bus di servizio di Azure, Archiviazione BLOB di Azure e endpoint webhook.

Ogni definizione di esportazione dati può inviare dati a una o più destinazioni. Creare le definizioni di destinazione prima di creare la definizione di esportazione.

Creare o aggiornare una destinazione

Usare la richiesta seguente per creare o aggiornare una definizione di destinazione:

PUT https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

destinationId è un ID univoco per la destinazione.

Nell'esempio seguente viene illustrato un corpo della richiesta che crea una destinazione di archiviazione BLOB:

{
  "displayName": "Blob Storage Destination",
  "type": "blobstorage@v1",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
  "containerName": "central-data"
}

Il corpo della richiesta include alcuni campi obbligatori:

displayName: nome visualizzato della destinazione.
type: tipo di oggetto di destinazione. Uno di: blobstorage@v1, dataexplorer@v1webhook@v1eventhubs@v1servicebusqueue@v1servicebustopic@v1.
connectionString: stringa di connessione per l'accesso alla risorsa di destinazione.
containerName: per una destinazione di archiviazione BLOB, il nome del contenitore in cui devono essere scritti i dati.

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

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Ottenere una destinazione in base all'ID

Usare la richiesta seguente per recuperare i dettagli di una destinazione dall'applicazione:

GET https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

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

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Elencare le destinazioni

Usare la richiesta seguente per recuperare un elenco di destinazioni dall'applicazione:

GET https://{your app subdomain}/api/dataExport/destinations?api-version=2022-10-31-preview

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

{
    "value": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
            "displayName": "Blob Storage Destination",
            "type": "blobstorage@v1",
            "authorization": {
                "type": "connectionString",
                "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
                "containerName": "central-data"
            },
            "status": "waiting"
        },
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9",
            "displayName": "Webhook destination",
            "type": "webhook@v1",
            "url": "https://eofnjsh68jdytan.m.pipedream.net",
            "headerCustomizations": {},
            "status": "error"
        }
    ]
}

Applicare una patch a una destinazione

PATCH https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

È possibile usare questa chiamata per eseguire un aggiornamento incrementale in un'esportazione. Il corpo della richiesta di esempio è simile all'esempio seguente che aggiorna l'oggetto connectionString di una destinazione:

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

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

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Eliminare una destinazione

Usare la richiesta seguente per eliminare una destinazione:

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Creare o aggiornare una definizione di esportazione

Usare la richiesta seguente per creare o aggiornare una definizione di esportazione dati:

PUT https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

Nell'esempio seguente viene illustrato un corpo della richiesta che crea una definizione di esportazione per i dati di telemetria del dispositivo:

{
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150"
        }
    ]
}

Il corpo della richiesta include alcuni campi obbligatori:

displayName: nome visualizzato dell'esportazione.
enabled: attiva/arresta l'esportazione dall'invio di dati.
source: tipo di dati da esportare.
destinations: elenco di destinazioni a cui l'esportazione deve inviare dati. Gli ID di destinazione devono già esistere nell'applicazione.

Esistono alcuni campi facoltativi che è possibile usare per aggiungere altri dettagli all'esportazione.

enrichments: parti aggiuntive di informazioni da includere con ogni messaggio inviato. I dati vengono rappresentati come set di coppie chiave/valore, in cui la chiave è il nome dell'arricchimento visualizzato nel messaggio di output e il valore identifica i dati da inviare.
filter: query che definisce gli eventi dell'origine da esportare.

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

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "starting"
}

Arricchimenti

Esistono tre tipi di arricchimento che è possibile aggiungere a un'esportazione: stringhe personalizzate, proprietà di sistema e proprietà personalizzate:

Nell'esempio seguente viene illustrato come usare il enrichments nodo per aggiungere una stringa personalizzata al messaggio in uscita:

"enrichments": {
  "My custom string": {
    "value": "My value"
  },
  //...
}

Nell'esempio seguente viene illustrato come usare il enrichments nodo per aggiungere una proprietà di sistema al messaggio in uscita:

"enrichments": {
  "Device template": {
    "path": "$templateDisplayName"
  },
  //...
}

È possibile aggiungere le proprietà di sistema seguenti:

Proprietà	Descrizione
`$enabled`	Il dispositivo è abilitato?
`$displayName`	Nome del dispositivo.
`$templateDisplayName`	Nome del modello di dispositivo.
`$organizations`	Le organizzazioni a cui appartiene il dispositivo.
`$provisioned`	Il dispositivo viene effettuato il provisioning?
`$simulated`	Il dispositivo è simulato?

Nell'esempio seguente viene illustrato come usare il enrichments nodo per aggiungere una proprietà personalizzata al messaggio in uscita. Le proprietà personalizzate sono proprietà definite nel modello di dispositivo a cui il dispositivo è associato:

"enrichments": {
  "Device model": {
    "target": "dtmi:azure:DeviceManagement:DeviceInformation;1",
    "path": "model"
  },
  //...
}

Filtri

È possibile filtrare i messaggi esportati in base ai valori di telemetria o proprietà.

Nell'esempio seguente viene illustrato come usare il filter campo per esportare solo i messaggi in cui il valore di telemetria accelerometro-X è maggiore di 0:

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 WHERE accelerometerX > 0",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

Nell'esempio seguente viene illustrato come usare il filter campo per esportare solo i messaggi in cui il temperature valore di telemetria è maggiore della targetTemperature proprietà:

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 AS A, dtmi:contoso:Thermostat;1 WHERE A.temperature > targetTemperature",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

Ottenere un'esportazione in base all'ID

Usare la richiesta seguente per recuperare i dettagli di una definizione di esportazione dall'applicazione:

GET https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

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

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage Destination",
    "type": "blobstorage@v1",
    "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
    "containerName": "central-data",
    "status": "waiting"
}

Elencare le definizioni di esportazione

Usare la richiesta seguente per recuperare un elenco di definizioni di esportazione dall'applicazione:

GET https://{your app subdomain}/api/dataExport/exports?api-version=2022-10-31-preview

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

{
  "value": [
    {
      "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "starting"
    },
    {
      "id": "802894c4-33bc-4f1e-ad64-e886f315cece",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "healthy"
    }
  ]
}

Applicare una patch a una definizione di esportazione

PATCH https://{your app subdomain}/dataExport/exports/{exportId}?api-version=2022-10-31-preview

{
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    }
}

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

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "healthy"
}

Eliminare una definizione di esportazione

Usare la richiesta seguente per eliminare una definizione di esportazione:

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Passaggi successivi

Dopo aver appreso come gestire l'esportazione dei dati con l'API REST, un passaggio successivo consigliato consiste nell'usare l'API REST IoT Central per gestire i modelli di dispositivo.

Come usare l'API REST IoT Central per gestire le esportazioni di dati

Esportazione dei dati

Creare o aggiornare una destinazione

Ottenere una destinazione in base all'ID

Elencare le destinazioni

Applicare una patch a una destinazione

Eliminare una destinazione

Creare o aggiornare una definizione di esportazione

Arricchimenti

Filtri

Ottenere un'esportazione in base all'ID

Elencare le definizioni di esportazione

Applicare una patch a una definizione di esportazione

Eliminare una definizione di esportazione

Passaggi successivi

Risorse aggiuntive