Comment utiliser l’API REST IoT Central pour gérer les exportations de données

Article
10/22/2024

L’API REST IoT Central vous permet de développer des applications clientes qui s’intègrent à des applications IoT Central. Vous pouvez utiliser l’API REST pour créer et gérer les exportations de données dans votre application IoT Central.

Chaque appel d’API REST IoT Central nécessite un en-tête d’autorisation. Pour plus d’informations, consultez Comment authentifier et autoriser les appels d’API REST d’IoT Central.

Pour obtenir la documentation de référence sur l’API REST IoT Central, consultez Informations de référence sur l’API REST d’Azure IoT Central.

Pour savoir comment gérer l’exportation de données à l’aide de l’interface utilisateur IoT Central, consultez Exporter des données IoT vers le stockage Blob.

Exportation des données

Vous pouvez utiliser la fonctionnalité d’exportation de données IoT Central pour diffuser en continu les données de télémétrie, les modifications de propriété, les événements de connectivité des appareils, les événements de cycle de vie des appareils et les événements de cycle de vie du modèle d’appareil vers des destinations telles que Azure Event Hubs, Azure Service Bus, le Stockage Blob Azure et les points de terminaison webhook.

Chaque définition d’exportation de données peut envoyer des données à une ou plusieurs destinations. Créez les définitions de destination avant de créer la définition d’exportation.

Créer ou mettre à jour une destination

Pour créer ou mettre à jour une définition de destination, utilisez la requête suivante :

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

destinationId est un ID unique pour la destination.

L’exemple suivant montre un corps de demande qui crée une destination de stockage blob :

{
  "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data"
    }
}

Le corps de la demande contient des champs obligatoires :

displayName : afficher le nom de la destination.
type: type de l’objet de destination. Valeurs possibles : blobstorage@v1, dataexplorer@v1, eventhubs@v1, servicebusqueue@v1, servicebustopic@v1, webhook@v1.
authorization : détails de l’autorisation pour la destination. Les types d’autorisations pris en charge sont systemAssignedManagedIdentity et connectionString.

La réponse à cette demande ressemble à l’exemple suivant :

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

Obtenir une destination par ID

Utilisez la requête suivante pour récupérer les détails d’une destination à partir de votre application :

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Destinations des listes

Utilisez la requête suivante pour récupérer une liste de destinations à partir de votre application :

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Corriger une destination

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

Vous pouvez utiliser cet appel pour effectuer une mise à jour incrémentielle d’une exportation. L’exemple de corps de la demande ressemble à l’exemple suivant, qui met à jour la containerName d’une destination :

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Supprimer une destination

Pour supprimer une destination, utilisez la requête suivante :

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

Créer ou mettre à jour une définition d’exportation

Pour créer ou mettre à jour une définition d’exportation de données, utilisez la requête suivante :

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

L’exemple suivant montre un corps de la demande qui crée une définition d’exportation pour la télémétrie de l’appareil :

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

Le corps de la demande contient des champs obligatoires :

displayName : nom d’affichage de l’exportation.
enabled : basculer vers démarrer/arrêter une exportation à partir de l’envoi de données.
source : type de données à exporter.
destinations : liste des destinations auxquelles l’exportation doit envoyer des données. Les ID de destination doivent déjà exister dans l’application.

Il existe des champs facultatifs que vous pouvez utiliser pour ajouter plus de détails à l’exportation.

enrichments : informations en plus à inclure avec chaque message envoyé. Les données sont représentées sous la forme d’un ensemble de paires clé/valeur, où la clé est le nom de l’enrichissement qui apparaît dans le message de sortie et la valeur identifie les données à envoyer.
filter : requête définissant les événements de la source qui doivent être exportés.

La réponse à cette demande ressemble à l’exemple suivant :

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

Enrichissements

Il existe trois types d’enrichissement que vous pouvez ajouter à une exportation : des chaînes personnalisées, des propriétés système et des propriétés personnalisées :

L’exemple suivant montre comment utiliser le nœud enrichments pour ajouter une chaîne personnalisée au message sortant :

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

L’exemple suivant montre comment utiliser le nœud enrichments pour ajouter une propriété système au message sortant :

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

Vous pouvez ajouter les propriétés système suivantes :

Propriété	Description
`$enabled`	L’appareil est-il activé ?
`$displayName`	Le nom de l'appareil.
`$templateDisplayName`	Le nom du modèle d’appareil.
`$organizations`	Les organisations auxquelles appartient l’appareil.
`$provisioned`	L’appareil est-il approvisionné ?
`$simulated`	L’appareil est-il simulé ?

L’exemple suivant montre comment utiliser le nœud enrichments pour ajouter une propriété personnalisée au message sortant. Les propriétés personnalisées sont définies dans le modèle d’appareil auquel l’appareil est associé :

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

Filtres

Vous pouvez filtrer les messages exportés en fonction des valeurs de télémétrie ou de propriété.

L’exemple suivant montre comment utiliser le champ filter pour exporter uniquement les messages où la valeur de télémétrie accéléromètre-X est supérieure à 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’exemple suivant montre comment utiliser le champ filter pour exporter uniquement les messages où la valeur de télémétrie temperature est supérieure à la propriété 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"
}

Récupérer une exportation par ID

Utilisez la requête suivante pour récupérer les détails d’une définition d’exportation à partir de votre application :

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Répertorier les définitions d’exportation

Utilisez la requête suivante pour récupérer une liste de définitions d’exportation à partir de votre application :

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Corriger une définition d’exportation

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

Vous pouvez utiliser cet appel pour effectuer une mise à jour incrémentielle d’une exportation. L’exemple de corps de la demande ressemble à l’exemple suivant, qui met à jour enrichments vers une exportation :

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

La réponse à cette demande ressemble à l’exemple suivant :

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

Supprimer une définition d’exportation

Pour supprimer une définition d’exportation, utilisez la requête suivante :

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

Étapes suivantes

Maintenant que vous savez comment gérer l’exportation des données dans l’API REST, nous vous suggérons d’apprendre comment utiliser l’API REST IoT Central pour gérer les modèles d’appareils.

Partager via

Comment utiliser l’API REST IoT Central pour gérer les exportations de données

Exportation des données

Créer ou mettre à jour une destination

Obtenir une destination par ID

Destinations des listes

Corriger une destination

Supprimer une destination

Créer ou mettre à jour une définition d’exportation

Enrichissements

Filtres

Récupérer une exportation par ID

Répertorier les définitions d’exportation

Corriger une définition d’exportation

Supprimer une définition d’exportation

Étapes suivantes

Commentaires

Ressources supplémentaires