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

Article
07/25/2023

L’API REST IoT Central vous permet de développer des applications clientes qui s’intègrent aux 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.

Conseil

Vous pouvez utiliser Postman pour tester les appels d’API REST décrits dans cet article. Téléchargez la collection IoT Central Postman et importez-la dans Postman. Dans la collection, vous devez définir des variables telles que votre sous-domaine d’application et le jeton d’administrateur.

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 de 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 Destination",
  "type": "blobstorage@v1",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=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.
connectionString : chaîne de connexion pour accéder à la ressource de destination.
containerName : pour une destination de stockage blob, nom du conteneur dans lequel les données doivent être écrites.

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

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

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": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=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": "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"
        }
    ]
}

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. Le corps de l’exemple de requête ressemble à l’exemple suivant qui met à jour le connectionString d’une destination :

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

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

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

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îtra 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 : chaînes personnalisées, propriétés système et propriétés personnalisées :

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

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

L’exemple suivant montre comment utiliser le enrichments nœud 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`	Nom du modèle d’appareil.
`$organizations`	Organisations à laquelle appartient l’appareil.
`$provisioned`	L’appareil est-il approvisionné ?
`$simulated`	L’appareil est-il simulé ?

L’exemple suivant montre comment utiliser le enrichments nœud pour ajouter une propriété personnalisée au message sortant. Les propriétés personnalisées sont des propriétés définies dans le modèle d’appareil à lequel 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 filter champ pour exporter uniquement les messages dont 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 filter champ pour exporter uniquement les messages dont la temperature valeur de télémétrie est supérieure à la targetTemperature propriété :

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

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.

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

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

Ressources supplémentaires