Exporter des données IoT vers le webhook

Cet article explique comment configurer l’exportation de données pour envoyer des données au webhook.

Utilisez cette fonctionnalité pour une exportation continue des données IoT filtrées et enrichies à partir de votre application IoT Central. La fonctionnalité d'exportation de données envoie (push) les modifications en quasi-temps réel vers d'autres parties de votre solution cloud pour vous fournir des insights, des analyses et un stockage à chaud.

Par exemple, vous pouvez :

• Exportez en continu des données de télémétrie, de modifications des propriétés, de connectivité des appareils, de cycle de vie des appareils, de cycle de vie de modèle d’appareil et de journal d’audit au format JSON en quasi-temps réel.
• filtrer les flux de données pour exporter des données qui remplissent des conditions personnalisées ;
• enrichir les flux de données avec des valeurs personnalisées et des valeurs de propriété à partir de l'appareil ;
• Transformer les flux de données pour modifier leur forme et leur contenu.

Conseil

Quand vous activez l’exportation de données, vous obtenez seulement les données à partir de ce moment. Pour conserver un historique des données plus étendu, activez l’exportation de données au plus tôt. Pour exporter manuellement des données générées lorsque l’exportation des données était désactivée, consultez Comment utiliser l’API REST IoT Central pour interroger des appareils.

Remarque

Dans certains cas, l’exportation des messages peut prendre jusqu’à 60 secondes. Cette durée est mesurée à partir du moment où IoT Central reçoit le message du hub IoT sous-jacent jusqu’au moment où le message est remis au point de terminaison de destination.

Prérequis

Pour utiliser les fonctionnalités d’exportation de données, vous devez disposer d’une autorisation d’exportation de données.

Configurer une destination d’exportation de webhook

Pour les destinations de webhook, IoT Central exporte des données en quasi-temps réel. Les données contenues dans le corps du message sont au même format que pour Event Hubs et Service Bus.

Créer une destination de webhook

Vous pouvez exporter des données vers un point de terminaison de webhook HTTP disponible publiquement. Vous pouvez créer un point de terminaison de webhook test à l’aide de RequestBin. RequestBin limite la requête lorsque le nombre maximal de requêtes est atteint :

1. Accédez à RequestBin.

2. Sélectionnez Créer un RequestBin.

3. Connectez-vous avec l’une des méthodes disponibles.

4. Copiez l’URL de votre RequestBin Vous utilisez cette URL quand vous testez votre exportation de données.

Pour créer la destination Azure Data Explorer dans IoT Central sur la page Exportation de données :

1. Sélectionnez + Nouvelle destination.

2. Sélectionnez Webhook comme type de destination.

3. Collez l’URL de rappel de votre point de terminaison de webhook. Vous pouvez aussi configurer l’autorisation du webhook et ajouter des en-têtes personnalisés.

   • Pour OAuth 2.0, seul le flux d’approbation des informations d’identification du client est pris en charge. Quand vous enregistrez la destination, IoT Central communique avec votre fournisseur OAuth pour récupérer un jeton d’autorisation. Ce jeton est joint à l’en-tête Authorization pour chaque message envoyé à cette destination.
   • Pour Jeton d’autorisation, vous pouvez spécifier une valeur de jeton qui est directement jointe à l’en-tête Authorization pour chaque message envoyé à cette destination.

4. Sélectionnez Enregistrer.

Exemple de configuration OAuth 2.0

Cet exemple explique comment configurer une destination de Webhook pour utiliser une application de fonction Azure protégée à l’aide de la connexion Microsoft Entra :

Setting	Exemple	Notes
Type de destination	webhook
Callback URL (URL de rappel)	https://myapp.azurewebsites.net/api/HttpExample	URL de la fonction
Autorisation	OAuth 2.0
URL du jeton	https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token	URL à utiliser pour récupérer un jeton. Vous trouverez cette valeur dans votre application de fonction : Authentification > Votre fournisseur d’identité Microsoft > Points de terminaison > Point de terminaison de jeton OAuth 2.0 (v2)
ID client	your-client-id	ID de client de votre application de fonction. Vous trouverez cette valeur dans votre application de fonction : Authentification > Votre fournisseur d’identité Microsoft > ID (client) de l’application
Clé secrète client	your-client-secret	Clé secrète client de votre application de fonction. Vous trouverez cette valeur dans votre application de fonction : Authentification > Votre fournisseur d’identité Microsoft > Certificats et secrets
Audience	S/O	Vide si vous utilisez une application de fonction.
Étendue	https://your-client-id/.default	Étendue du jeton. Pour une application de fonction, utilisez la valeur de l’ID de client.**
Type de contenu de la requête de jeton	Automatique

D’autres destinations de Webhook peuvent nécessiter des valeurs différentes pour ces paramètres.

Configurer une exportation de données

Maintenant que vous disposez d'une destination vers laquelle exporter vos données, configurez la fonctionnalité d'exportation de données dans votre application IoT Central :

1. Connectez-vous à votre application IoT Central.

2. Dans le volet gauche, sélectionnez Exportation de données.

   Conseil

   Si vous ne voyez pas Exportation de données dans le volet gauche, cela signifie que vous n’avez pas les autorisations nécessaires pour configurer l’exportation de données dans votre application. Contactez un administrateur pour configurer l’exportation de données.

3. Sélectionnez + Nouvelle exportation.

4. Entrez un nom d'affichage pour votre nouvelle exportation et assurez-vous que l'exportation de données est activée.

5. Choisissez le type de données à exporter. Le tableau suivant répertorie les types d'exportation de données pris en charge :

   Type de données	Description	Format de données
   Télémétrie	Exportez des messages de télémétrie à partir d’appareils en quasi-temps réel. Chaque message exporté contient le contenu complet du message d'origine de l'appareil, normalisé.	Format du message de télémétrie
   Modifications de la propriété	Exportez les modifications apportées aux propriétés de l’appareil et du cloud en quasi-temps réel. Pour les propriétés en lecture seule de l'appareil, les modifications apportées aux valeurs signalées sont exportées. Pour les propriétés en lecture-écriture, les valeurs signalées et souhaitées sont exportées.	Format du message de modification de la propriété
   Connectivité des appareils	Exportez les événements connectés et déconnectés des appareils.	Format de message de connectivité des appareils
   Cycle de vie des appareils	Exportez les événements enregistrés, supprimés, approvisionnés, activés, désactivés, displayNameChanged et deviceTemplateChanged de l’appareil.	Format du message relatif aux changements de cycle de vie d’appareil
   Cycle de vie de modèle d’appareil	Exportez les changements de modèle d’appareil publiés, dont les créations, les mises à jour et les suppressions.	Format de message relatif aux changements de cycle de vie d’appareil
   Journaux d’audit	Journaux des mises à jour lancées par l’utilisateur et apportées à des entités dans l’application. Pour plus d’informations, consultez Utiliser des journaux d’audit pour suivre l’activité dans votre application IoT Central	Format de message de journal d’audit

6. Vous pouvez également ajouter des filtres pour réduire la quantité de données exportées. Différents types de filtres sont disponibles pour chaque type d’exportation de données :

   Type de données	Filtres disponibles
   Télémétrie	Filtrer par nom d’appareil, identité d'appareil et modèle d’appareil et indiquez si l’appareil est simulé Filtrer le flux de façon à ce qu’il contienne uniquement la télémétrie correspondant aux conditions de filtre Filtrer le flux de façon à ce qu’il contienne uniquement la télémétrie des appareils dont les propriétés correspondent aux conditions de filtre Filtrer le flux de façon à ce qu’il contienne uniquement la télémétrie avec des propriétés de message correspondant à la condition de filtre. Les propriétés de message (également appelées propriétés d’application) sont envoyées dans un ensemble de paires clé-valeur sur chaque message de télémétrie. Pour créer un filtre de propriété de message, entrez la clé de la propriété de message que vous recherchez, et spécifiez une condition. Seuls les messages de télémétrie dont les propriétés correspondent à la condition de filtre spécifiée sont exportés. En savoir plus sur les propriétés d’application dans des documents IoT Hub
   Modifications de la propriété	Filtrer par nom d’appareil, identité d'appareil et modèle d’appareil et indiquez si l’appareil est simulé Filtrer le flux de façon à ce qu’il contienne uniquement les changements de propriété correspondant aux conditions de filtre
   Connectivité des appareils	Filtrer par nom d’appareil, ID d’appareil, modèle d’appareil, organisations et indiquer si l’appareil est simulé Filtrer le flux de façon à ce qu’il contienne uniquement les changements des appareils dont les propriétés correspondent aux conditions de filtre
   Cycle de vie des appareils	Filtrer par nom d’appareil, identité d’appareil, modèle d’appareil et indiquez si l’appareil est approvisionné, activé ou simulé Filtrer le flux de façon à ce qu’il contienne uniquement les changements des appareils dont les propriétés correspondent aux conditions de filtre
   Cycle de vie de modèle d’appareil	Filtrer par modèle d’appareil
   Journaux d’audit	S/O

7. Si vous le souhaitez, vous pouvez également enrichir les messages exportés avec des métadonnées supplémentaires dans les paires clé-valeur. Les enrichissements suivants sont disponibles pour les types d’exportation de données de télémétrie, de modification des propriétés, de connectivité des appareils et de cycle de vie des appareils :

   • Chaîne personnalisée : ajoute une chaîne statique personnalisée à chaque message. Entrez n’importe quelle clé, puis entrez une valeur de chaîne.
   • Propriété, qui ajoute à chaque message ce qui suit :
     • Métadonnées d’appareil, par exemple nom de l’appareil, nom du modèle d’appareil, informations relatives à l’activation, aux organisations, au provisionnement et à la simulation.
     • Valeur actuelle de la propriété rapportée d’appareil ou de la propriété de cloud à chaque message. Si le message exporté provient d'un appareil qui ne dispose pas de la propriété spécifiée, l'enrichissement ne s'applique pas à ce message.

Configurez la destination de l’exportation :

1. Sélectionnez + Destination pour ajouter une destination que vous avez déjà créée ou sélectionnez Créer nouveau.

2. Pour transformer vos données avant leur exportation, sélectionnez + Transformer. Pour plus d’informations, consultez Transformer des données dans votre application IoT Central pour les exporter.

3. Sélectionnez + Destination pour ajouter jusqu’à cinq destinations à une même exportation.

4. Une fois la configuration de votre exportation terminée, sélectionnez Enregistrer. Au bout de quelques minutes, vos données apparaissent dans vos destinations.

Superviser votre exportation

Dans IoT Central, la page Exportation de données vous permet de vérifier l’état de vos exportations. Vous pouvez également utiliser Azure Monitor pour connaître la quantité de données que vous exportez et voir les erreurs d’exportation. Vous pouvez accéder aux métriques d’intégrité des appareils et des exportations dans les graphiques du portail Azure en utilisant l’API REST, des requêtes dans PowerShell ou Azure CLI. Vous pouvez superviser les métriques d’exportation de données suivantes dans Azure Monitor :

• Nombre de messages entrants à exporter avant l’application de filtres.
• Nombre de messages qui passent par des filtres.
• Nombre de messages correctement exportés vers les destinations.
• Nombre d’erreurs trouvées.

Pour en savoir plus, consultez Superviser l’intégrité de l’application.

Formats de données

Les sections suivantes décrivent les formats des données exportées :

Format des données de télémétrie.

Chaque message exporté contient un formulaire normalisé du message complet que l'appareil a envoyé dans le corps du message. Le message est au format JSON et encodé en UTF-8. Chaque message contient les informations suivantes :

• applicationId : ID de l’application IoT Central.
• messageSource : source du message - telemetry.
• deviceId : ID de l’appareil qui a envoyé le message de télémétrie.
• schema : nom et version du schéma de charge utile.
• templateId : ID du modèle d’appareil affecté à l’appareil.
• enqueuedTime : heure à laquelle IoT Central a reçu ce message.
• enrichments : enrichissements configurés lors de l’exportation.
• module : module IoT Edge qui a envoyé ce message. Ce champ apparaît uniquement si le message provient d’un module IoT Edge.
• component : composant qui a envoyé ce message. Ce champ apparaît uniquement si les capacités envoyées dans le message ont été modélisées en tant que composant dans le modèle d’appareil.
• messageProperties : autres propriétés envoyées par l’appareil avec le message. Ces propriétés sont parfois appelées propriétés d'application. Pour en savoir plus, consultez la documentation d'IoT Hub.

Propriétés de message

Les messages de télémétrie ont des propriétés pour les métadonnées ainsi que pour la charge utile de télémétrie. L’extrait de code précédent montre des exemples de messages système tels que deviceId et enqueuedTime. Pour en savoir plus sur les propriétés des messages système, consultez Propriétés système des messages IoT Hub D2C.

Vous pouvez ajouter des propriétés aux messages de télémétrie si vous devez ajouter des métadonnées personnalisées à ces derniers. Par exemple, vous devez ajouter un horodatage quand l’appareil crée le message.

L’extrait de code suivant montre comment ajouter la propriété iothub-creation-time-utc au message quand vous le créez sur l’appareil :

Important

Le format de cet horodatage doit être UTC sans informations de fuseau horaire. Par exemple, 2021-04-21T11:30:16Z est valide, 2021-04-21T11:30:16-07:00 non.

JavaScript

async function sendTelemetry(deviceClient, index) {
  console.log('Sending telemetry message %d...', index);
  const msg = new Message(
    JSON.stringify(
      deviceTemperatureSensor.updateSensor().getCurrentTemperatureObject()
    )
  );
  msg.properties.add("iothub-creation-time-utc", new Date().toISOString());
  msg.contentType = 'application/json';
  msg.contentEncoding = 'utf-8';
  await deviceClient.sendEvent(msg);
}

Java

private static void sendTemperatureTelemetry() {
  String telemetryName = "temperature";
  String telemetryPayload = String.format("{\"%s\": %f}", telemetryName, temperature);

  Message message = new Message(telemetryPayload);
  message.setContentEncoding(StandardCharsets.UTF_8.name());
  message.setContentTypeFinal("application/json");
  message.setProperty("iothub-creation-time-utc", Instant.now().toString());

  deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
  log.debug("My Telemetry: Sent - {\"{}\": {}°C} with message Id {}.", telemetryName, temperature, message.getMessageId());
  temperatureReadings.put(new Date(), temperature);
}

C#

private async Task SendTemperatureTelemetryAsync()
{
  const string telemetryName = "temperature";

  string telemetryPayload = $"{{ \"{telemetryName}\": {_temperature} }}";
  using var message = new Message(Encoding.UTF8.GetBytes(telemetryPayload))
  {
      ContentEncoding = "utf-8",
      ContentType = "application/json",
  };
  message.Properties.Add("iothub-creation-time-utc", DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"));
  await _deviceClient.SendEventAsync(message);
  _logger.LogDebug($"Telemetry: Sent - {{ \"{telemetryName}\": {_temperature}°C }}.");
}

Python

async def send_telemetry_from_thermostat(device_client, telemetry_msg):
    msg = Message(json.dumps(telemetry_msg))
    msg.custom_properties["iothub-creation-time-utc"] = datetime.now(timezone.utc).isoformat()
    msg.content_encoding = "utf-8"
    msg.content_type = "application/json"
    print("Sent message")
    await device_client.send_message(msg)

Format des modifications de propriétés

Chaque message ou enregistrement représente les modifications apportées aux propriétés de l’appareil et du cloud. Les informations incluses dans le message exporté sont les suivantes :

• applicationId : ID de l’application IoT Central.
• messageSource : source du message - properties.
• messageType : cloudPropertyChange, devicePropertyDesiredChange ou devicePropertyReportedChange.
• deviceId : ID de l’appareil qui a envoyé le message de télémétrie.
• schema : nom et version du schéma de charge utile.
• enqueuedTime : heure à laquelle IoT Central a détecté cette modification.
• templateId : ID du modèle d’appareil affecté à l’appareil.
• properties : Tableau des propriétés qui ont été modifiées, y compris les noms des propriétés et les valeurs qui ont été modifiés. Les informations sur le composant et le module sont incluses si la propriété est modélisée dans un composant ou un module IoT Edge.
• enrichments : enrichissements configurés lors de l’exportation.

Format des modifications de la connectivité des appareils

Chaque message ou enregistrement représente un événement de connectivité provenant d’un seul appareil. Les informations incluses dans le message exporté sont les suivantes :

• applicationId : ID de l’application IoT Central.
• messageSource : source du message - deviceConnectivity.
• messageType : connected ou disconnected.
• deviceId : ID de l’appareil modifié.
• schema : nom et version du schéma de charge utile.
• templateId : ID du modèle d’appareil affecté à l’appareil.
• enqueuedTime : Heure à laquelle cette modification est intervenue dans IoT Central.
• enrichments : enrichissements configurés lors de l’exportation.

Format des changements du cycle de vie d’appareil

Chaque message ou enregistrement représente une modification apportée à un appareil. Les informations incluses dans le message exporté sont les suivantes :

• applicationId : ID de l’application IoT Central.
• messageSource : source du message - deviceLifecycle.
• messageType : type de la modification effectuée. Il s’agit de l’un des éléments suivants : registered, deleted, provisioned, enabled, disabled, displayNameChanged et deviceTemplateChanged.
• deviceId : ID de l’appareil modifié.
• schema : nom et version du schéma de charge utile.
• templateId : ID du modèle d’appareil affecté à l’appareil.
• enqueuedTime : Heure à laquelle cette modification est intervenue dans IoT Central.
• enrichments : enrichissements configurés lors de l’exportation.

Format des changements de cycle de vie d’appareil

Chaque message ou enregistrement représente une modification apportée à un modèle d’appareil publié. Les informations incluses dans le message exporté sont les suivantes :

• applicationId : ID de l’application IoT Central.
• messageSource : source du message - deviceTemplateLifecycle.
• messageType : created, updated ou deleted.
• schema : nom et version du schéma de charge utile.
• templateId : ID du modèle d’appareil affecté à l’appareil.
• enqueuedTime : Heure à laquelle cette modification est intervenue dans IoT Central.
• enrichments : enrichissements configurés lors de l’exportation.

Format du journal d’audit

Chaque message de journal d’audit représente un changement à l’initiative de l’utilisateur apporté à une entité pouvant être auditée dans l’application IoT Central. Les informations incluses dans le message exporté sont les suivantes :

• actor : informations sur l’utilisateur qui a modifié l’entité.
• applicationId : ID de l’application IoT Central.
• messageSource : source du message - audit.
• messageType : type de la modification effectuée. Valeurs possibles : updated, created, deleted.
• updated : présent uniquement si messageType a la valeur updated. Fournit plus de détails sur la mise à jour.
• resource : détails de l’entité modifiée.
• schema : nom et version du schéma de charge utile.
• deviceId : ID de l’appareil modifié.
• enqueuedTime : Heure à laquelle cette modification est intervenue dans IoT Central.
• enrichments : enrichissements configurés lors de l’exportation.

Étapes suivantes

Maintenant que vous savez comment exporter vers Service Bus, une étape suivante suggérée consiste à apprendre à exporter vers Event Hubs.