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

Articolo
10/22/2024

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 di 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 di IoT Central, vedere Informazioni di riferimento sull'API REST di Azure IoT Central.

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 di IoT Central per riprodurre in streaming dati di telemetria, modifiche alle proprietà, eventi di connettività dei dispositivi, eventi del ciclo di vita del dispositivo ed eventi del ciclo di vita dei dispositivi a destinazioni come Hub eventi di Azure, bus di servizio di Azure, Archiviazione BLOB di Azure ed endpoint webhook.

Ogni definizione di esportazione dei 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.

L'esempio seguente mostra un corpo della richiesta che crea una destinazione di archiviazione BLOB:

{
  "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.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 dei valori possibili: blobstorage@v1, dataexplorer@v1, eventhubs@v1, servicebusqueue@v1, servicebustopic@v1, webhook@v1.
authorization: dettagli dell'autorizzazione per la destinazione. I tipi di autorizzazione supportati sono systemAssignedManagedIdentity e connectionString.

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

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.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": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.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": "systemAssignedManagedIdentity",
              "endpointUri": "https://yourapplication.blob.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 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 a un'esportazione. Il corpo della richiesta di esempio è simile all'esempio seguente che aggiorna containerName di una destinazione:

{
  "containerName": "central-data-analysis"
}

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

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data-analysis"
    },
    "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

L'esempio seguente mostra 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/disattiva l'avvio/arresto di un'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: informazioni aggiuntive da includere con ogni messaggio inviato. I dati vengono rappresentati come un set di coppie chiave/valore, in cui la chiave è il nome dell'arricchimento da visualizzare 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 nodo enrichments per aggiungere una stringa personalizzata al messaggio in uscita:

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

Nell'esempio seguente viene illustrato come usare il nodo enrichments 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`	Viene effettuato il provisioning del dispositivo?
`$simulated`	Il dispositivo è simulato?

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

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

Filtri

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

L'esempio seguente illustra come usare il campo filter per esportare solo i messaggi in cui il valore di telemetria accelerometer-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"
}

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

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

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

Ora che si è appreso come gestire l'esportazione dei dati con l'API REST, un passaggio successivo consigliato è Come usare l'API REST di IoT Central per gestire i modelli di dispositivo.

Condividi tramite

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 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 patch a una definizione di esportazione

Eliminare una definizione di esportazione

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive