Exportera IoT-data till Webhook

Den här artikeln beskriver hur du konfigurerar dataexport för att skicka data till Webhook.

Använd den här funktionen för att kontinuerligt exportera filtrerade och berikade IoT-data från ditt IoT Central-program. Dataexport skickar ändringar i nära realtid till andra delar av din molnlösning för analyser av varma dataflöden, insikter och lagring.

Du kan till exempel:

• Exportera kontinuerligt telemetri, egenskapsändringar, enhetsanslutning, enhetens livscykel, livscykel för enhetsmallar och granskningsloggdata i JSON-format nästan i realtid.
• Filtrera dataströmmarna för att exportera data som matchar anpassade villkor.
• Utöka dataströmmarna med anpassade värden och egenskapsvärden från enheten.
• Transformera dataströmmarna för att ändra form och innehåll.

Förutsättningar

Om du vill använda dataexportfunktioner måste du ha behörigheten Dataexport .

Konfigurera ett Webhook-exportmål

För Webhook-mål exporterar IoT Central data nästan i realtid. Data i meddelandetexten är i samma format som för Event Hubs och Service Bus.

HTTPS-slutpunkts- och TLS-krav

Om du vill exportera data på ett säkert sätt konfigurerar du webhooksslutpunkten så att den använder HTTPS. Webhook-klienten för IoT Central-dataexport verifierar servercertifikatet som slutpunkten presenterar under TLS-handskakningen.

Följande krav gäller:

• Slutpunkten måste kunna nås från det offentliga Internet. IoT Central kan inte leverera till slutpunkter som bara kan nås från ett privat nätverk eller som kräver ett VPN.
• Servercertifikatet måste signeras av en offentligt betrodd certifikatutfärdare (CA). IoT Central accepterar inte självsignerade certifikat eller certifikat som utfärdats av en privat certifikatutfärdare, och det finns inget alternativ för att ladda upp ett anpassat CA-paket eller en förtroendelista till ditt IoT Central-program.
• Certifikatets ämne eller alternativt namn på certifikatmottagare (SAN) måste matcha värdnamnet i motringnings-URL:en och certifikatet får inte ha upphört att gälla.

Om slutpunkten visar ett certifikat som IoT Central webhook-klienten inte kan verifiera misslyckas målet med felet "Det gick inte att nå webhooken. Kontrollera att webhooken är online och tillgänglig." när du sparar den.

Skapa ett Webhook-mål

Du kan exportera data till en offentligt tillgänglig HTTP Webhook-slutpunkt. Du kan skapa en Webhook-testslutpunkt med RequestBin. RequestBin begränsar begäran när gränsen för begäran har nåtts:

1. Gå till RequestBin.

2. Välj Skapa en RequestBin.

3. Logga in med någon av de tillgängliga metoderna.

4. Kopiera URL:en för din RequestBin Du använder den här URL:en när du testar dataexporten.

Så här skapar du Azure Data Explorer-målet i IoT Central på sidan Dataexport :

1. Välj + Nytt mål.

2. Välj Webhook som måltyp.

3. Klistra in återkopplings-URL:en för webhook-slutpunkten. Du kan också konfigurera Webhook-auktorisering och lägga till anpassade rubriker.

   • För OAuth2.0 stöds endast flödet för beviljande av klientautentiseringsuppgifter. När du sparar målet kommunicerar IoT Central med din OAuth-provider för att hämta en auktoriseringstoken. Den här tokenen är kopplad till Authorization-huvudet för varje meddelande som skickas till den här destinationen.
   • För auktoriseringstoken kan du ange ett tokenvärde som är direkt kopplat till Authorization rubriken för varje meddelande som skickas till det här målet.

4. Välj Spara.

Exempel på OAuth 2.0-konfiguration

Det här exemplet visar hur du konfigurerar ett Webhook-mål för att använda en Azure-funktionsapp som skyddas med hjälp av Microsoft Entra-inloggning:

Andra webhooksdestinationer kan kräva olika värden för de här inställningarna.

Konfigurera en dataexport

Nu när du har ett mål att exportera dina data till konfigurerar du dataexport i ditt IoT Central-program:

1. Logga in på ditt IoT Central-program.

2. I den vänstra rutan väljer du Dataexport.

   Tips

   Om du inte ser dataexport i den vänstra rutan har du inte behörighet att konfigurera dataexport i din app. Prata med en administratör för att konfigurera dataexport.

3. Välj + Ny export.

4. Ange ett visningsnamn för den nya exporten och kontrollera att dataexporten är Aktiverad.

5. Välj vilken typ av data som ska exporteras. I följande tabell visas de dataexporttyper som stöds:

   Datatyp	beskrivning	Dataformat
   Telemetri	Exportera telemetrimeddelanden från enheter nästan i realtid. Varje exporterat meddelande innehåller det fullständiga innehållet i det ursprungliga enhetsmeddelandet, normaliserat.	Telemetriformat
   Egenskapsändringar	Exportera ändringar av enhets- och molnegenskaper nästan i realtid. För endast läsbara enhetsegenskaper exporteras ändringar av de rapporterade värdena. För läs- och skrivbara egenskaper exporteras både rapporterade och önskade värden.	Format för egenskapsändringar
   Enhetsanslutning	Exportera enhetsanslutna och frånkopplade händelser.	Ändringar i format för enhetsanslutning
   Enhetens livscykel	Exportera händelser för enhet som är registrerad, borttagen, etablerad, aktiverad, inaktiverad, namnändrad och enhetsmalländrad.	Enhetens livscykelförändringar format
   Livscykel för enhetsmall	Exportera publicerade enhetsmalländringar, inklusive skapade, uppdaterade och borttagna.	Ändringsformat för enhetsmallens livscykel
   Granskningsloggar	Loggar över användarinitierade uppdateringar av entiteter i programmet. Mer information finns i Använda granskningsloggar för att spåra aktivitet i ditt IoT Central-program	Granskningsloggformat

6. Du kan också lägga till filter för att minska mängden data som exporteras. Det finns olika typer av filter för varje dataexporttyp:

   Typ av data	Tillgängliga filter
   Telemetri	Filtrera efter enhetsnamn, enhets-ID, enhetsmall och om enheten simuleras Filterströmmen får endast innehålla telemetri som uppfyller filtervillkoren Filtrera dataström så att den endast innehåller telemetri från enheter med egenskaper som matchar filtervillkoren Filtrera dataström så att den endast innehåller telemetri som har meddelandeegenskaper som uppfyller filtervillkoret. Meddelandeegenskaper (även kallade programegenskaper) skickas i en påse nyckel/värde-par på varje telemetrimeddelande. Om du vill skapa ett filter för meddelandeegenskap anger du den meddelandeegenskapsnyckel som du letar efter och anger ett villkor. Endast telemetrimeddelanden med egenskaper som matchar det angivna filtervillkoret exporteras. Mer information om programegenskaper finns i IoT Hub-dokumentationen.
   Egenskapsändringar	Filtrera efter enhetsnamn, enhets-ID, enhetsmall och om enheten simuleras Filtrera strömmen så att den endast innehåller egenskapsändringar som uppfyller filtervillkoren
   Enhetsanslutning	Filtrera efter enhetsnamn, enhets-ID, enhetsmall, organisationer och om enheten simuleras Filtrera dataström så att den endast innehåller ändringar från enheter med egenskaper som matchar filtervillkoren
   Enhetens livscykel	Filtrera efter enhetsnamn, enhets-ID, enhetsmall och om enheten har etablerats, aktiverats eller simulerats Filtrera dataström så att den endast innehåller ändringar från enheter med egenskaper som matchar filtervillkoren
   Livscykel för enhetsmall	Filtrera efter enhetsmall
   Granskningsloggar	Ej tillämpligt

7. Du kan också utöka exporterade meddelanden med extra nyckel/värde-parmetadata. Följande berikanden är tillgängliga för dataexporttyperna telemetri, egenskapsändringar, enhetsanslutning och enhetslivscykel:

   • Anpassad sträng: Lägger till en anpassad statisk sträng i varje meddelande. Ange valfri nyckel och ange valfritt strängvärde.
   • Egenskap som läggs till i varje meddelande:
     • Enhetsmetadata som: enhetsnamn, enhetsmallnamn, aktiverade, organisationer, tilldelade och simulerade.
     • Den aktuella enheten rapporterade egenskaps- eller molnegenskapsvärdet för varje meddelande. Om det exporterade meddelandet kommer från en enhet som inte har den angivna egenskapen får det exporterade meddelandet inte berikningen.

Konfigurera exportmålet:

1. Välj + Mål för att lägga till ett mål som du redan har skapat eller välj Skapa ett nytt.

2. Om du vill transformera dina data innan de exporteras väljer du + Transformera. Mer information finns i Transformera data i ditt IoT Central-program för export.

3. Välj + Mål för att lägga till upp till fem mål för en enskild export.

4. När du har konfigurerat exporten väljer du Spara. Efter några minuter visas dina data i dina destinationer.

Övervaka exporten

På sidan Dataexport i IoT Central kan du kontrollera statusen för dina exporter. Du kan också använda Azure Monitor för att se hur mycket data du exporterar och eventuella exportfel. Du kan komma åt export- och enhetshälsomått i diagram i Azure Portal med hjälp av REST-API:et, frågor i PowerShell eller Azure CLI. För närvarande kan du övervaka följande dataexportmått i Azure Monitor:

• Antal meddelanden som ska exporteras innan filter tillämpas.
• Antal meddelanden som passerar genom filter.
• Antal meddelanden som framgångsrikt har exporterats till destinationer.
• Antal fel som hittades.

Mer information finns i Övervaka programmets hälsa.

Dataformat

I följande avsnitt beskrivs formaten för exporterade data:

Telemetriformat

Varje exporterat meddelande innehåller en normaliserad form av det fullständiga meddelandet som enheten skickade i meddelandetexten. Meddelandet är i JSON-format och kodat som UTF-8. Information i varje meddelande innehåller:

• applicationId: ID för IoT Central-programmet.
• messageSource: Källan för meddelandet – telemetry.
• deviceId: ID för enheten som skickade telemetrimeddelandet.
• schema: Namnet och versionen av nyttolastschemat.
• templateId: ID för enhetsmallen som tilldelats enheten.
• enqueuedTime: Den tidpunkt då IoT Central tog emot det här meddelandet.
• enrichments: Alla berikningar som har konfigurerats vid exporten.
• module: IoT Edge-modulen som skickade det här meddelandet. Det här fältet visas bara om meddelandet kom från en IoT Edge-modul.
• component: Komponenten som skickade det här meddelandet. Det här fältet visas bara om funktionerna som skickades i meddelandet modellerades som en komponent i enhetsmallen
• messageProperties: Andra egenskaper som enheten skickade med meddelandet. Dessa egenskaper kallas ibland för programegenskaper. Mer information finns i IoT Hub-dokumentationen.

Meddelandeegenskaper

Telemetrimeddelanden har egenskaper för metadata och telemetrinyttolasten. Föregående kodfragment visar exempel på systemmeddelanden som deviceId och enqueuedTime. Mer information om systemmeddelandeegenskaperna finns i Systemegenskaper för meddelanden från enhet till moln.

Du kan lägga till egenskaper i telemetrimeddelanden om du behöver lägga till anpassade metadata i dina telemetrimeddelanden. Du måste till exempel lägga till en tidsstämpel när enheten skapar meddelandet.

Följande kodfragment visar hur du lägger iothub-creation-time-utc till egenskapen i meddelandet när du skapar den på enheten:

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);
}

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);
}

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 }}.");
}

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 för egenskapsändringar

Varje meddelande eller post representerar ändringar i enhets- och molnegenskaper. Informationen i det exporterade meddelandet innehåller:

• applicationId: ID för IoT Central-programmet.
• messageSource: Källan för meddelandet – properties.
• messageType: Antingen cloudPropertyChange, devicePropertyDesiredChangeeller devicePropertyReportedChange.
• deviceId: ID för enheten som skickade telemetrimeddelandet.
• schema: Namnet och versionen av nyttolastschemat.
• enqueuedTime: Den tidpunkt då IoT Central identifierade den här ändringen.
• templateId: ID för enhetsmallen som tilldelats enheten.
• properties: En matris med egenskaper som har ändrats, inklusive namnen på de egenskaper och värden som har ändrats. Komponent- och modulinformationen ingår om egenskapen modelleras inom en komponent eller en IoT Edge-modul.
• enrichments: Alla berikningar som har konfigurerats vid exporten.

Ändringar i formatet för enhetsanslutningar

Varje meddelande eller post representerar en anslutningshändelse från en enda enhet. Informationen i det exporterade meddelandet innehåller:

• applicationId: ID för IoT Central-programmet.
• messageSource: Källan för meddelandet – deviceConnectivity.
• messageType: Antingen connected eller disconnected.
• deviceId: ID:t för enheten som ändrades.
• schema: Namnet och versionen av nyttolastschemat.
• templateId: ID för enhetsmallen som tilldelats enheten.
• enqueuedTime: Den tidpunkt då den här ändringen inträffade i IoT Central.
• enrichments: Alla berikningar som har konfigurerats vid exporten.

Livscykeln för enheten ändrar format

Varje meddelande eller post representerar en ändring av en enskild enhet. Informationen i det exporterade meddelandet innehåller:

• applicationId: ID för IoT Central-programmet.
• messageSource: Källan för meddelandet – deviceLifecycle.
• messageType: Den typ av ändring som inträffade. En av: registered, deleted, provisioned, enabled, disabled, displayNameChangedoch deviceTemplateChanged.
• deviceId: ID:t för enheten som ändrades.
• schema: Namnet och versionen av nyttolastschemat.
• templateId: ID för enhetsmallen som tilldelats enheten.
• enqueuedTime: Den tidpunkt då den här ändringen inträffade i IoT Central.
• enrichments: Alla berikningar som har konfigurerats vid exporten.

Ändringsformat för enhetsmallens livscykel

Varje meddelande eller post representerar en ändring i en enda publicerad enhetsmall. Informationen i det exporterade meddelandet innehåller:

• applicationId: ID för IoT Central-programmet.
• messageSource: Källan för meddelandet – deviceTemplateLifecycle.
• messageType: Antingen created, updatedeller deleted.
• schema: Namnet och versionen av nyttolastschemat.
• templateId: ID för enhetsmallen som tilldelats enheten.
• enqueuedTime: Den tidpunkt då den här ändringen inträffade i IoT Central.
• enrichments: Alla berikningar som har konfigurerats vid exporten.

Format för granskningsloggar

Varje granskningsloggmeddelande representerar en användarinitierad ändring av en granskningsbar entitet i IoT Central-programmet. Informationen i det exporterade meddelandet innehåller:

• actor: Information om användaren som ändrade entiteten.
• applicationId: ID för IoT Central-programmet.
• messageSource: Källan för meddelandet – audit.
• messageType: Den typ av ändring som inträffade. En av: updated, created, deleted.
• updated: Endast om messageType är updated. Innehåller mer information om uppdateringen.
• resource: Information om den ändrade entiteten.
• schema: Namnet och versionen av nyttolastschemat.
• deviceId: ID:t för enheten som ändrades.
• enqueuedTime: Den tidpunkt då den här ändringen inträffade i IoT Central.
• enrichments: Alla berikningar som har konfigurerats vid exporten.

Nästa steg

Nu när du vet hur du exporterar till Service Bus rekommenderas det som nästa steg att lära dig Exportera till Event Hubs.