IoT-gegevens exporteren naar webhook

In dit artikel wordt beschreven hoe u gegevensexport configureert om gegevens naar de webhook te verzenden.

Gebruik deze functie om gefilterde en verrijkte IoT-gegevens continu te exporteren uit uw IoT Central-toepassing. Gegevensexport pusht wijzigingen in bijna realtime naar andere onderdelen van uw cloudoplossing voor inzichten, analyses en opslag op warm pad.

U kunt bijvoorbeeld:

• Continu telemetrie exporteren, eigenschappenwijzigingen, apparaatconnectiviteit, apparaatlevenscyclus, levenscyclus van apparaatsjablonen en auditlogboekgegevens in JSON-indeling in bijna realtime.
• Filter de gegevensstromen om gegevens te exporteren die overeenkomen met aangepaste voorwaarden.
• Verrijk de gegevensstromen met aangepaste waarden en eigenschapswaarden van het apparaat.
• Transformeer de gegevensstromen om hun vorm en inhoud te wijzigen.

Tip

Wanneer u gegevensexport inschakelt, krijgt u alleen de gegevens vanaf dat moment. Als u meer historische gegevens wilt behouden, schakelt u gegevensexport vroeg in. Als u gegevens handmatig wilt exporteren vanaf tijdstippen waarop gegevensexport is uitgeschakeld, raadpleegt u Hoe u de Rest API van IoT Central gebruikt om query's uit te voeren op apparaten.

Notitie

In sommige gevallen kan het tot 60 seconden duren voordat de berichten worden geëxporteerd. Deze tijd wordt gemeten vanaf wanneer IoT Central het bericht van de onderliggende IoT-hub ontvangt tot wanneer het bericht wordt bezorgd bij het doeleindpunt.

Vereisten

Als u functies voor gegevensexport wilt gebruiken, moet u beschikken over de machtiging Gegevensexport .

Een webhook-exportbestemming instellen

Voor Webhook-bestemmingen exporteert IoT Central gegevens in bijna realtime. De gegevens in de berichttekst hebben dezelfde indeling als voor Event Hubs en Service Bus.

Een webhookbestemming maken

U kunt gegevens exporteren naar een openbaar beschikbaar HTTP Webhook-eindpunt. U kunt een testwebhookeindpunt maken met behulp van RequestBin. RequestBin beperkt de aanvraag wanneer de aanvraaglimiet is bereikt:

1. Navigeer naar RequestBin.

2. Selecteer Een RequestBin maken.

3. Meld u aan met een van de beschikbare methoden.

4. Kopieer de URL van uw RequestBin U gebruikt deze URL wanneer u de gegevensexport test.

De Azure Data Explorer-bestemming maken in IoT Central op de pagina Gegevensexport :

1. Selecteer + Nieuwe bestemming.

2. Selecteer Webhook als doeltype.

3. Plak de callback-URL voor uw Webhook-eindpunt. U kunt desgewenst webhookautorisatie configureren en aangepaste headers toevoegen.

   • Voor OAuth2.0 wordt alleen de stroom voor het verlenen van clientreferenties ondersteund. Wanneer u de bestemming opslaat, communiceert IoT Central met uw OAuth-provider om een autorisatietoken op te halen. Dit token is gekoppeld aan de Authorization koptekst voor elk bericht dat naar deze bestemming wordt verzonden.
   • Voor autorisatietoken kunt u een tokenwaarde opgeven die rechtstreeks is gekoppeld aan de Authorization koptekst voor elk bericht dat naar deze bestemming wordt verzonden.

4. Selecteer Opslaan.

Voorbeeld van OAuth 2.0-configuratie

In dit voorbeeld ziet u hoe u een webhookbestemming configureert voor het gebruik van een Azure Function-app die wordt beveiligd met behulp van microsoft Entra-aanmelding:

Instelling	Opmerking	Opmerkingen
Doeltype	Webhook
URL voor aanroep	https://myapp.azurewebsites.net/api/HttpExample	De functie-URL.
Autorisatie	OAuth 2.0
Token-URL	https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token	De URL die moet worden gebruikt om een token op te halen. U vindt deze waarde in uw functie-app: Verificatie > van het OAuth 2.0-tokeneindpunt van uw Microsoft Identity Provider >> (v2)
Client ID	your-client-id	De client-id van uw functie-app. U vindt deze waarde in uw functie-app: Verificatie > van uw Microsoft Identity Provider > Application -id (client)-id
Clientgeheim	your-client-secret	Het clientgeheim van uw functie-app. U vindt deze waarde in uw functie-app: Verificatie > van certificaten en geheimen van uw Microsoft Identity Provider >
Doelgroep	N.v.t.	Leeg als u een functie-app gebruikt.
Bereik	https://your-client-id/.default	Het bereik van het token. Gebruik de waarde van de client-id voor een functie-app.**
Inhoudstype tokenaanvraag	Auto

Voor andere webhookbestemmingen zijn mogelijk andere waarden vereist voor deze instellingen.

Een gegevensexport instellen

Nu u een bestemming hebt om uw gegevens naar te exporteren, stelt u de gegevensexport in uw IoT Central-toepassing in:

1. Meld u aan bij uw IoT Central-toepassing.

2. Selecteer Gegevensexport in het linkerdeelvenster.

   Tip

   Als u gegevensexport niet ziet in het linkerdeelvenster, hebt u geen machtigingen om gegevensexport in uw app te configureren. Neem contact op met een beheerder om gegevensexport in te stellen.

3. Selecteer + Nieuwe export.

4. Voer een weergavenaam in voor de nieuwe export en zorg ervoor dat de gegevensexport is ingeschakeld.

5. Kies het type gegevens dat u wilt exporteren. De volgende tabel bevat de ondersteunde typen gegevensexport:

   Gegevenstype	Beschrijving	Gegevensopmaak
   Telemetrie	Telemetrieberichten exporteren van apparaten in bijna realtime. Elk geëxporteerd bericht bevat de volledige inhoud van het oorspronkelijke apparaatbericht, genormaliseerd.	Telemetrieberichtindeling
   Eigenschapswijzigingen	Exporteer wijzigingen in apparaat- en cloudeigenschappen in bijna realtime. Voor alleen-lezen apparaateigenschappen worden wijzigingen in de gerapporteerde waarden geëxporteerd. Voor eigenschappen voor lezen/schrijven worden zowel gerapporteerde als gewenste waarden geëxporteerd.	Berichtindeling wijzigen van eigenschap
   Connectiviteit van apparaten	Verbonden en verbroken gebeurtenissen van het apparaat exporteren.	Berichtindeling voor apparaatconnectiviteit
   Levenscyclus van apparaat	Exporteer apparaat geregistreerd, verwijderd, ingericht, ingeschakeld, uitgeschakeld, displayNameChanged en deviceTemplateChanged-gebeurtenissen.	Berichtindeling van apparaatlevenscyclus wordt gewijzigd
   Levenscyclus van apparaatsjabloon	Gepubliceerde apparaatsjabloonwijzigingen exporteren, waaronder gemaakt, bijgewerkt en verwijderd.	De levenscyclus van apparaatsjablonen verandert de berichtindeling
   Auditlogboeken	Logboeken van door de gebruiker geïnitieerde updates voor entiteiten in de toepassing. Zie Auditlogboeken gebruiken om activiteiten in uw IoT Central-toepassing bij te houden voor meer informatie	Berichtindeling auditlogboek

6. Voeg eventueel filters toe om de hoeveelheid geëxporteerde gegevens te verminderen. Er zijn verschillende typen filters beschikbaar voor elk type gegevensexport:

   Type gegevens	Beschikbare filters
   Telemetrie	Filteren op apparaatnaam, apparaat-id, apparaatsjabloon en of het apparaat is gesimuleerd Filterstroom om alleen telemetrie te bevatten die voldoet aan de filtervoorwaarden Filterstroom zodat deze alleen telemetrie van apparaten bevat met eigenschappen die overeenkomen met de filtervoorwaarden Filterstroom zodat deze alleen telemetrie bevat met berichteigenschappen die voldoen aan de filtervoorwaarde. Berichteigenschappen (ook wel toepassingseigenschappen genoemd) worden verzonden in een zak sleutel-waardeparen op elk telemetriebericht. Als u een berichteigenschapsfilter wilt maken, voert u de eigenschapssleutel van het bericht in die u zoekt en geeft u een voorwaarde op. Alleen telemetrieberichten met eigenschappen die overeenkomen met de opgegeven filtervoorwaarde worden geëxporteerd. Meer informatie over toepassingseigenschappen uit IoT Hub-documenten
   Eigenschapswijzigingen	Filteren op apparaatnaam, apparaat-id, apparaatsjabloon en of het apparaat is gesimuleerd Filterstroom om alleen eigenschapswijzigingen te bevatten die voldoen aan de filtervoorwaarden
   Connectiviteit van apparaten	Filteren op apparaatnaam, apparaat-id, apparaatsjabloon, organisaties en of het apparaat is gesimuleerd Filterstroom zodat deze alleen wijzigingen van apparaten bevat met eigenschappen die overeenkomen met de filtervoorwaarden
   Levenscyclus van apparaat	Filteren op apparaatnaam, apparaat-id, apparaatsjabloon en of het apparaat is ingericht, ingeschakeld of gesimuleerd Filterstroom zodat deze alleen wijzigingen van apparaten bevat met eigenschappen die overeenkomen met de filtervoorwaarden
   Levenscyclus van apparaatsjabloon	Filteren op apparaatsjabloon
   Auditlogboeken	N.v.t.

7. Verrijk eventueel geëxporteerde berichten met extra metagegevens van sleutel-waardepaar. De volgende verrijkingen zijn beschikbaar voor de telemetrie, eigenschappenwijzigingen, apparaatconnectiviteit en gegevensexporttypen voor de levenscyclus van apparaten:

   • Aangepaste tekenreeks: voegt een aangepaste statische tekenreeks toe aan elk bericht. Voer een willekeurige sleutel in en voer een tekenreekswaarde in.
   • Eigenschap, die aan elk bericht wordt toegevoegd:
     • Metagegevens van apparaten, zoals apparaatnaam, apparaatsjabloonnaam, ingeschakeld, organisaties, ingericht en gesimuleerd.
     • De gerapporteerde eigenschap of cloudeigenschapswaarde van het huidige apparaat voor elk bericht. Als het geëxporteerde bericht afkomstig is van een apparaat dat niet de opgegeven eigenschap heeft, krijgt het geëxporteerde bericht de verrijking niet.

Configureer de exportbestemming:

1. Selecteer + Bestemming om een bestemming toe te voegen die u al hebt gemaakt of selecteer Een nieuwe maken.

2. Als u uw gegevens wilt transformeren voordat deze worden geëxporteerd, selecteert u + Transformeren. Zie Gegevens transformeren in uw IoT Central-toepassing voor export voor meer informatie.

3. Selecteer + Bestemming om maximaal vijf bestemmingen toe te voegen aan één export.

4. Wanneer u klaar bent met het instellen van de export, selecteert u Opslaan. Na een paar minuten worden uw gegevens weergegeven in uw bestemmingen.

Uw export bewaken

Op de pagina Gegevensexport in IoT Central kunt u de status van uw exports controleren. U kunt Ook Azure Monitor gebruiken om te zien hoeveel gegevens u exporteert en eventuele exportfouten. U hebt toegang tot metrische gegevens over export- en apparaatstatus in grafieken in Azure Portal met behulp van de REST API, query's in PowerShell of de Azure CLI. Op dit moment kunt u de volgende metrische gegevens voor gegevensexport bewaken in Azure Monitor:

• Aantal berichten dat binnenkomt om te exporteren voordat filters worden toegepast.
• Aantal berichten dat filters doorgeeft.
• Het aantal berichten dat naar bestemmingen is geëxporteerd.
• Aantal gevonden fouten.

Zie Toepassingsstatus bewaken voor meer informatie.

Bestandsindelingen

In de volgende secties worden de indelingen van de geëxporteerde gegevens beschreven:

Telemetrie-indeling

Elk geëxporteerd bericht bevat een genormaliseerde vorm van het volledige bericht dat het apparaat in de hoofdtekst van het bericht heeft verzonden. Het bericht heeft de JSON-indeling en is gecodeerd als UTF-8. Informatie in elk bericht bevat:

• applicationId: De id van de IoT Central-toepassing.
• messageSource: De bron voor het bericht - telemetry.
• deviceId: De id van het apparaat dat het telemetriebericht heeft verzonden.
• schema: de naam en versie van het nettoladingschema.
• templateId: De id van de apparaatsjabloon die is toegewezen aan het apparaat.
• enqueuedTime: Het tijdstip waarop IoT Central dit bericht heeft ontvangen.
• enrichments: Alle verrijkingen die voor de export zijn ingesteld.
• module: De IoT Edge-module die dit bericht heeft verzonden. Dit veld wordt alleen weergegeven als het bericht afkomstig is van een IoT Edge-module.
• component: het onderdeel dat dit bericht heeft verzonden. Dit veld wordt alleen weergegeven als de mogelijkheden die in het bericht zijn verzonden, zijn gemodelleerd als onderdeel in de apparaatsjabloon
• messageProperties: Andere eigenschappen die het apparaat met het bericht heeft verzonden. Deze eigenschappen worden soms toepassingseigenschappen genoemd. Meer informatie vindt u in IoT Hub-documenten.

Berichteigenschappen

Telemetrieberichten hebben eigenschappen voor metagegevens en de nettolading van telemetrie. In het vorige fragment ziet u voorbeelden van systeemberichten zoals deviceId en enqueuedTime. Zie Systeemeigenschappen van D2C IoT Hub-berichten voor meer informatie over de eigenschappen van systeemberichten.

U kunt eigenschappen toevoegen aan telemetrieberichten als u aangepaste metagegevens wilt toevoegen aan uw telemetrieberichten. U moet bijvoorbeeld een tijdstempel toevoegen wanneer het apparaat het bericht maakt.

In het volgende codefragment ziet u hoe u de iothub-creation-time-utc eigenschap aan het bericht toevoegt wanneer u het op het apparaat maakt:

Belangrijk

De notatie van deze tijdstempel moet UTC zijn zonder tijdzonegegevens. Is bijvoorbeeld 2021-04-21T11:30:16Z geldig, 2021-04-21T11:30:16-07:00 is ongeldig.

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)

Opmaak van eigenschapswijzigingen

Elk bericht of elke record vertegenwoordigt wijzigingen in apparaat- en cloudeigenschappen. Informatie in het geëxporteerde bericht bevat:

• applicationId: De id van de IoT Central-toepassing.
• messageSource: De bron voor het bericht - properties.
• messageType: Ofwel cloudPropertyChange, devicePropertyDesiredChangeof devicePropertyReportedChange.
• deviceId: De id van het apparaat dat het telemetriebericht heeft verzonden.
• schema: de naam en versie van het nettoladingschema.
• enqueuedTime: Het tijdstip waarop IoT Central deze wijziging heeft gedetecteerd.
• templateId: De id van de apparaatsjabloon die is toegewezen aan het apparaat.
• properties: Een matrix met eigenschappen die zijn gewijzigd, inclusief de namen van de eigenschappen en waarden die zijn gewijzigd. De onderdeel- en modulegegevens worden opgenomen als de eigenschap is gemodelleerd binnen een onderdeel of een IoT Edge-module.
• enrichments: Alle verrijkingen die voor de export zijn ingesteld.

Indeling van apparaatverbindingswijzigingen

Elk bericht of elke record vertegenwoordigt een connectiviteitsgebeurtenis van één apparaat. Informatie in het geëxporteerde bericht bevat:

• applicationId: De id van de IoT Central-toepassing.
• messageSource: De bron voor het bericht - deviceConnectivity.
• messageType: Of connecteddisconnected.
• deviceId: De id van het apparaat dat is gewijzigd.
• schema: de naam en versie van het nettoladingschema.
• templateId: De id van de apparaatsjabloon die is toegewezen aan het apparaat.
• enqueuedTime: Het tijdstip waarop deze wijziging heeft plaatsgevonden in IoT Central.
• enrichments: Alle verrijkingen die voor de export zijn ingesteld.

Indeling voor wijzigingen in de levenscyclus van apparaten

Elk bericht of elke record vertegenwoordigt één wijziging in één apparaat. Informatie in het geëxporteerde bericht bevat:

• applicationId: De id van de IoT Central-toepassing.
• messageSource: De bron voor het bericht - deviceLifecycle.
• messageType: Het type wijziging dat is opgetreden. Een van: registered, , deleted, provisioned, enabled, , disabled, , en displayNameChangeddeviceTemplateChanged.
• deviceId: De id van het apparaat dat is gewijzigd.
• schema: de naam en versie van het nettoladingschema.
• templateId: De id van de apparaatsjabloon die is toegewezen aan het apparaat.
• enqueuedTime: Het tijdstip waarop deze wijziging heeft plaatsgevonden in IoT Central.
• enrichments: Alle verrijkingen die voor de export zijn ingesteld.

Indeling voor levenscycluswijzigingen van apparaatsjablonen

Elk bericht of elke record vertegenwoordigt één wijziging in één gepubliceerde apparaatsjabloon. Informatie in het geëxporteerde bericht bevat:

• applicationId: De id van de IoT Central-toepassing.
• messageSource: De bron voor het bericht - deviceTemplateLifecycle.
• messageType: Ofwel created, updatedof deleted.
• schema: de naam en versie van het nettoladingschema.
• templateId: De id van de apparaatsjabloon die is toegewezen aan het apparaat.
• enqueuedTime: Het tijdstip waarop deze wijziging heeft plaatsgevonden in IoT Central.
• enrichments: Alle verrijkingen die voor de export zijn ingesteld.

Indeling van auditlogboek

Elk auditlogboekbericht vertegenwoordigt een door de gebruiker geïnitieerde wijziging in een controleerbare entiteit in de IoT Central-toepassing. Informatie in het geëxporteerde bericht bevat:

• actor: Informatie over de gebruiker die de entiteit heeft gewijzigd.
• applicationId: De id van de IoT Central-toepassing.
• messageSource: De bron voor het bericht - audit.
• messageType: Het type wijziging dat is opgetreden. Een van: updated, created, deleted.
• updated: Alleen aanwezig als messageType dat het is updated. Biedt meer informatie over de update.
• resource: Details van de gewijzigde entiteit.
• schema: de naam en versie van het nettoladingschema.
• deviceId: De id van het apparaat dat is gewijzigd.
• enqueuedTime: Het tijdstip waarop deze wijziging heeft plaatsgevonden in IoT Central.
• enrichments: Alle verrijkingen die voor de export zijn ingesteld.

Volgende stappen

Nu u weet hoe u kunt exporteren naar Service Bus, is een voorgestelde volgende stap het leren exporteren naar Event Hubs.