IoT-gegevens exporteren naar Event Hubs

In dit artikel wordt beschreven hoe u gegevensexport configureert om gegevens naar de Event Hubs 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 Event Hubs-exportbestemming instellen

IoT Central exporteert gegevens in bijna realtime. De gegevens bevinden zich in de berichttekst en hebben een JSON-indeling die is gecodeerd als UTF-8.

De aantekeningen of systeemeigenschappen van het bericht bevatten de iotcentral-device-id, iotcentral-application-iden iotcentral-message-sourceiotcentral-message-type velden met dezelfde waarden als de bijbehorende velden in de berichttekst.

Verbindingsopties

Met Event Hubs-bestemmingen kunt u de verbinding configureren met een verbindingsreeks of een beheerde identiteit.

Beheerde identiteiten zijn veiliger omdat:

• U slaat de referenties voor uw resource niet op in een verbindingsreeks in uw IoT Central-toepassing.
• De referenties worden automatisch gekoppeld aan de levensduur van uw IoT Central-toepassing.
• Beheerde identiteiten draaien hun beveiligingssleutels automatisch regelmatig.

IoT Central maakt momenteel gebruik van door het systeem toegewezen beheerde identiteiten.

Wanneer u een beheerde identiteit configureert, bevat de configuratie een bereik en een rol:

• Het bereik definieert waar u de beheerde identiteit kunt gebruiken. U kunt bijvoorbeeld een Azure-resourcegroep gebruiken als bereik. In dit geval moeten zowel de IoT Central-toepassing als de bestemming zich in dezelfde resourcegroep bevinden.
• De rol bepaalt welke machtigingen de IoT Central-toepassing wordt verleend in de doelservice. Voor een IoT Central-toepassing voor het verzenden van gegevens naar een Event Hub heeft de beheerde identiteit bijvoorbeeld de roltoewijzing Azure Event Hubs-gegevenszender nodig.

De volgende video bevat meer informatie over door het systeem toegewezen beheerde identiteiten:

Let op

Als u wilt exporteren naar blobopslag, gebruikt u de bijdrager voor het opslagaccount niet, zoals wordt weergegeven in de video. Gebruik in plaats daarvan de rol Inzender voor opslagblobgegevens.

Een Event Hubs-bestemming maken

Beheerde identiteit

In dit artikel wordt beschreven hoe u een beheerde identiteit maakt met behulp van de Azure CLI. U kunt azure Portal ook gebruiken om een beheerde identiteit te maken.

Als u geen bestaande Event Hubs-naamruimte hebt waarnaar u wilt exporteren, voert u het volgende script uit in de Azure Cloud Shell bash-omgeving. Met het script maakt u een resourcegroep, Event Hubs-naamruimte en Event Hub. Met het script wordt vervolgens de beheerde identiteit voor uw IoT Central-toepassing ingeschakeld en wordt de rol toegewezen die nodig is voor toegang tot uw Event Hub:

# Replace the Event Hubs namespace name with your own unique value
EHNS=your-event-hubs-namespace-$RANDOM

# Replace the IoT Central app name with the name of your
# IoT Central application.
CA=your-iot-central-app

EH=exportdata
RG=centralexportresources
LOCATION=eastus

RGID=$(az group create -n $RG --location $LOCATION --query "id" --output tsv)
az eventhubs namespace create --name $EHNS --resource-group $RG -l $LOCATION
az eventhubs eventhub create --name $EH --resource-group $RG --namespace-name $EHNS

# This assumes your IoT Central application is in the 
# default `IOTC` resource group.
az iot central app identity assign --name $CA --resource-group IOTC --system-assigned
PI=$(az iot central app identity show --name $CA --resource-group IOTC --query "principalId" --output tsv)

az role assignment create --assignee $PI --role "Azure Event Hubs Data Sender" --scope $RGID

az role assignment list --assignee $PI --all -o table

echo "Host name: $EHNS.servicebus.windows.net"
echo "Event Hub: $EH"

Zie Gegevens exporteren naar een veilige bestemming in een virtueel Azure-netwerk om uw Event Hub verder te beveiligen en alleen toegang toe te staan vanuit vertrouwde services met beheerde identiteiten.

De Event Hubs-bestemming maken in IoT Central op de pagina Gegevensexport :

1. Selecteer + Nieuwe bestemming.

2. Selecteer Azure Event Hubs als het doeltype.

3. Selecteer Door het systeem toegewezen beheerde identiteit als autorisatietype.

4. Voer de hostnaam van uw Event Hubs-resource in. Voer vervolgens de naam van de hoofdlettergevoelige Event Hub in. Een hostnaam ziet er als volgt uit: contoso-waste.servicebus.windows.net.

5. Selecteer Opslaan.

Als u geen gegevens ziet die binnenkomen in uw doelservice, raadpleegt u Problemen met gegevensexports vanuit uw Azure IoT Central-toepassing oplossen.

Verbindingsreeks

Als u geen bestaande Event Hubs-naamruimte hebt waarnaar u wilt exporteren, voert u het volgende script uit in de Azure Cloud Shell bash-omgeving. Met het script maakt u een resourcegroep, Event Hubs-naamruimte en Event Hub. Vervolgens wordt het verbindingsreeks afgedrukt dat moet worden gebruikt wanneer u de gegevensexport in IoT Central configureert:

# Replace the Event Hubs namespace name with your own unique value
EHNS=your-event-hubs-namespace-$RANDOM
EH=exportdata
RG=centralexportresources
LOCATION=eastus

az group create -n $RG --location $LOCATION
az eventhubs namespace create --name $EHNS --resource-group $RG -l $LOCATION
az eventhubs eventhub create --name $EH --resource-group $RG --namespace-name $EHNS
az eventhubs eventhub authorization-rule create --eventhub-name $EH --resource-group $RG --namespace-name $EHNS --name SendRule --rights Send

CS=$(az eventhubs eventhub authorization-rule keys list --eventhub-name $EH --resource-group $RG --namespace-name $EHNS --name SendRule --query "primaryConnectionString" -o tsv)

echo "Event hub connection string: $CS"

De Event Hubs-bestemming maken in IoT Central op de pagina Gegevensexport :

1. Selecteer + Nieuwe bestemming.

2. Selecteer Azure Event Hubs als het doeltype.

3. Selecteer De verbindingsreeks als het autorisatietype.

4. Plak de verbindingsreeks voor uw Event Hubs-resource en voer indien nodig de naam van de hoofdlettergevoelige Event Hub in.

5. Selecteer Opslaan.

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 IoT Hub-berichten in de apparaat-naar-cloud 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 connected disconnected.
• 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.

Voor Event Hubs exporteert IoT Central in bijna realtime nieuwe berichtengegevens naar uw Event Hub. In de gebruikerseigenschappen (ook wel toepassingseigenschappen genoemd) van elk bericht, worden de iotcentral-device-id, iotcentral-application-iden iotcentral-message-sourceautomatisch iotcentral-message-type opgenomen.

Volgende stappen

Nu u weet hoe u naar Event Hubs exporteert, is een voorgestelde volgende stap het leren exporteren naar Azure Data Explorer.