Eksportowanie danych IoT do usługi Event Hubs

W tym artykule opisano sposób konfigurowania eksportu danych w celu wysyłania danych do usługi Event Hubs.

Ta funkcja służy do ciągłego eksportowania filtrowanych i wzbogaconych danych IoT z aplikacji usługi IoT Central. Eksport danych wypycha zmiany niemal w czasie rzeczywistym do innych części rozwiązania w chmurze w celu uzyskania szczegółowych informacji o ciepłej ścieżce, analizy i magazynu.

Można na przykład:

  • Stale eksportuj dane telemetryczne, zmiany właściwości, łączność urządzenia, cykl życia urządzenia, cykl życia szablonu urządzenia i dane dziennika inspekcji w formacie JSON niemal w czasie rzeczywistym.
  • Przefiltruj strumienie danych, aby wyeksportować dane zgodne z warunkami niestandardowymi.
  • Wzbogacanie strumieni danych przy użyciu wartości niestandardowych i wartości właściwości z urządzenia.
  • Przekształć strumienie danych , aby zmodyfikować ich kształt i zawartość.

Napiwek

Po włączeniu eksportu danych uzyskasz tylko dane od tej chwili. Aby zachować więcej danych historycznych, włącz wczesne eksportowanie danych. Aby ręcznie wyeksportować dane od czasu wyłączenia eksportu danych, zobacz Jak używać interfejsu API REST usługi IoT Central do wykonywania zapytań dotyczących urządzeń.

Uwaga

W niektórych sytuacjach eksportowanie komunikatów może potrwać do 60 sekund. Ten czas jest mierzony od momentu odebrania komunikatu z bazowego centrum IoT Do momentu dostarczenia komunikatu do docelowego punktu końcowego.

Wymagania wstępne

Aby korzystać z funkcji eksportowania danych, musisz mieć uprawnienie do eksportowania danych.

Konfigurowanie lokalizacji docelowej eksportu usługi Event Hubs

Usługa IoT Central eksportuje dane niemal w czasie rzeczywistym. Dane są w treści komunikatu i są w formacie JSON zakodowanym jako UTF-8.

Adnotacje lub torby właściwości systemu komunikatu zawierają iotcentral-device-idpola , iotcentral-application-id, iotcentral-message-sourcei iotcentral-message-type , które mają te same wartości co odpowiednie pola w treści komunikatu.

Opcje Połączenie ion

Miejsca docelowe usługi Event Hubs umożliwiają skonfigurowanie połączenia z parametry połączenia lub tożsamością zarządzaną.

Tożsamości zarządzane są bezpieczniejsze, ponieważ:

  • Poświadczenia zasobu nie są przechowywane w parametry połączenia w aplikacji usługi IoT Central.
  • Poświadczenia są automatycznie powiązane z okresem istnienia aplikacji usługi IoT Central.
  • Tożsamości zarządzane automatycznie obracają swoje klucze zabezpieczeń regularnie.

Usługa IoT Central obecnie używa tożsamości zarządzanych przypisanych przez system.

Podczas konfigurowania tożsamości zarządzanej konfiguracja obejmuje zakres i rolę:

  • Zakres określa, gdzie można użyć tożsamości zarządzanej. Na przykład możesz użyć grupy zasobów platformy Azure jako zakresu. W takim przypadku zarówno aplikacja usługi IoT Central, jak i miejsce docelowe muszą znajdować się w tej samej grupie zasobów.
  • Rola określa, jakie uprawnienia ma aplikacja usługi IoT Central w usłudze docelowej. Na przykład w przypadku aplikacji usługi IoT Central do wysyłania danych do centrum zdarzeń tożsamość zarządzana wymaga przypisania roli Nadawca danych usługi Azure Event Hubs.

Poniższy film wideo zawiera więcej informacji na temat tożsamości zarządzanych przypisanych przez system:

Uwaga

Aby wyeksportować do magazynu obiektów blob, nie używaj współautora konta magazynu, jak pokazano w filmie wideo. Zamiast tego użyj roli Współautor danych obiektu blob usługi Storage.

Tworzenie miejsca docelowego usługi Event Hubs

W tym artykule pokazano, jak utworzyć tożsamość zarządzaną przy użyciu interfejsu wiersza polecenia platformy Azure. Możesz również użyć witryny Azure Portal, aby utworzyć tożsamość manged.

Jeśli nie masz istniejącej przestrzeni nazw usługi Event Hubs do wyeksportowania, uruchom następujący skrypt w środowisku powłoki bash usługi Azure Cloud Shell. Skrypt tworzy grupę zasobów, przestrzeń nazw usługi Event Hubs i centrum zdarzeń. Następnie skrypt włącza tożsamość zarządzaną dla aplikacji usługi IoT Central i przypisuje rolę, która musi uzyskać dostęp do centrum zdarzeń:

# 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"

Aby dodatkowo zabezpieczyć centrum zdarzeń i zezwolić na dostęp tylko z zaufanych usług za pomocą tożsamości zarządzanych, zobacz Eksportowanie danych do bezpiecznego miejsca docelowego w usłudze Azure Virtual Network.

Aby utworzyć miejsce docelowe usługi Event Hubs w usłudze IoT Central na stronie eksportowania danych:

  1. Wybierz pozycję + Nowe miejsce docelowe.

  2. Wybierz pozycję Azure Event Hubs jako typ docelowy.

  3. Wybierz pozycję Tożsamość zarządzana przypisana przez system jako typ autoryzacji.

  4. Wprowadź nazwę hosta zasobu usługi Event Hubs. Następnie wprowadź nazwę centrum zdarzeń uwzględniającą wielkość liter. Nazwa hosta wygląda następująco: contoso-waste.servicebus.windows.net.

  5. Wybierz pozycję Zapisz.

Jeśli nie widzisz danych przybywających do usługi docelowej, zobacz Rozwiązywanie problemów z eksportami danych z aplikacji usługi Azure IoT Central.

Konfigurowanie eksportu danych

Teraz, gdy masz miejsce docelowe do wyeksportowania danych, skonfiguruj eksport danych w aplikacji usługi IoT Central:

  1. Zaloguj się do aplikacji usługi IoT Central.

  2. W okienku po lewej stronie wybierz pozycję Eksport danych.

    Napiwek

    Jeśli nie widzisz opcji Eksportowanie danych w okienku po lewej stronie, nie masz uprawnień do konfigurowania eksportu danych w aplikacji. Skontaktuj się z administratorem, aby skonfigurować eksportowanie danych.

  3. Wybierz pozycję + Nowy eksport.

  4. Wprowadź nazwę wyświetlaną nowego eksportu i upewnij się, że eksport danych jest włączony.

  5. Wybierz typ danych do wyeksportowania. W poniższej tabeli wymieniono obsługiwane typy eksportu danych:

    Typ danych opis Format danych
    Telemetria Eksportowanie komunikatów telemetrycznych z urządzeń w czasie niemal rzeczywistym. Każdy wyeksportowany komunikat zawiera pełną zawartość oryginalnego komunikatu urządzenia, znormalizowany. Format komunikatu telemetrii
    Zmiany właściwości Wyeksportuj zmiany do właściwości urządzenia i chmury w czasie niemal rzeczywistym. W przypadku właściwości urządzenia tylko do odczytu są eksportowane zmiany w raportowanych wartościach. W przypadku właściwości odczytu i zapisu eksportowane są zarówno zgłoszone, jak i żądane wartości. Format komunikatu zmiany właściwości
    Łączność urządzeń Eksportowanie zdarzeń połączonych i odłączonych urządzeń. Format komunikatu łączności urządzenia
    Cykl życia urządzenia Eksportuj zarejestrowane, usunięte, aprowizowane, włączone, wyłączone, displayNameChanged i zdarzenia deviceTemplateChanged. Format komunikatu zmiany cyklu życia urządzenia
    Cykl życia szablonu urządzenia Wyeksportuj opublikowane zmiany szablonu urządzenia, w tym utworzone, zaktualizowane i usunięte. Format komunikatu zmienia cykl życia szablonu urządzenia
    Dzienniki inspekcji Dzienniki aktualizacji inicjowanych przez użytkownika do jednostek w aplikacji. Aby dowiedzieć się więcej, zobacz Używanie dzienników inspekcji do śledzenia aktywności w aplikacji usługi IoT Central Format komunikatu dziennika inspekcji
  6. Opcjonalnie dodaj filtry, aby zmniejszyć ilość eksportowanych danych. Dla każdego typu eksportu danych dostępne są różne typy filtrów:

    Typ danych Dostępne filtry
    Telemetria
    • Filtruj według nazwy urządzenia, identyfikatora urządzenia, szablonu urządzenia i jeśli urządzenie jest symulowane
    • Filtruj strumień tak, aby zawierał tylko dane telemetryczne spełniające warunki filtrowania
    • Filtruj strumień tak, aby zawierał tylko dane telemetryczne z urządzeń z właściwościami zgodnymi z warunkami filtrowania
    • Filtruj strumień tak, aby zawierał tylko dane telemetryczne zawierające właściwości komunikatu spełniające warunek filtru. Właściwości komunikatu (nazywane również właściwościami aplikacji) są wysyłane w torbie par klucz-wartość dla każdego komunikatu telemetrii. Aby utworzyć filtr właściwości komunikatu, wprowadź klucz właściwości komunikatu, którego szukasz, i określ warunek. Eksportowane są tylko komunikaty telemetryczne z właściwościami zgodnymi z określonym warunkiem filtru. Dowiedz się więcej o właściwościach aplikacji z dokumentacji usługi IoT Hub
    Zmiany właściwości
    • Filtruj według nazwy urządzenia, identyfikatora urządzenia, szablonu urządzenia i jeśli urządzenie jest symulowane
    • Filtruj strumień tak, aby zawierał tylko zmiany właściwości spełniające warunki filtrowania
    Łączność urządzeń
    • Filtruj według nazwy urządzenia, identyfikatora urządzenia, szablonu urządzenia, organizacji i jeśli urządzenie jest symulowane
    • Filtruj strumień tak, aby zawierał tylko zmiany z urządzeń z właściwościami pasującymi do warunków filtrowania
    Cykl życia urządzenia
    • Filtruj według nazwy urządzenia, identyfikatora urządzenia, szablonu urządzenia oraz jeśli urządzenie jest aprowizowane, włączone lub symulowane
    • Filtruj strumień tak, aby zawierał tylko zmiany z urządzeń z właściwościami pasującymi do warunków filtrowania
    Cykl życia szablonu urządzenia
    • Filtrowanie według szablonu urządzenia
    Dzienniki inspekcji Nie dotyczy
  7. Opcjonalnie możesz wzbogacić wyeksportowane komunikaty o dodatkowe metadane pary klucz-wartość. Następujące wzbogacania są dostępne dla danych telemetrycznych, zmian właściwości, łączności urządzeń i typów eksportu danych cyklu życia urządzenia:

    • Ciąg niestandardowy: dodaje niestandardowy ciąg statyczny do każdego komunikatu. Wprowadź dowolny klucz i wprowadź dowolną wartość ciągu.
    • Właściwość, która dodaje do każdego komunikatu:
      • Metadane urządzenia, takie jak nazwa urządzenia, nazwa szablonu urządzenia, włączone, organizacje, aprowizowane i symulowane.
      • Bieżąca właściwość zgłoszona przez urządzenie lub wartość właściwości chmury do każdego komunikatu. Jeśli wyeksportowany komunikat pochodzi z urządzenia, które nie ma określonej właściwości, wyeksportowany komunikat nie pobiera wzbogacania.

Skonfiguruj miejsce docelowe eksportu:

  1. Wybierz pozycję + Miejsce docelowe , aby dodać miejsce docelowe, które zostało już utworzone, lub wybierz pozycję Utwórz nową.

  2. Aby przekształcić dane przed ich wyeksportowanie, wybierz pozycję + Przekształć. Aby dowiedzieć się więcej, zobacz Przekształcanie danych wewnątrz aplikacji usługi IoT Central do eksportowania.

  3. Wybierz pozycję + Miejsce docelowe , aby dodać do pięciu miejsc docelowych do jednego eksportu.

  4. Po zakończeniu konfigurowania eksportu wybierz pozycję Zapisz. Po kilku minutach dane pojawią się w miejscach docelowych.

Monitorowanie eksportu

W usłudze IoT Central strona Eksportowanie danych umożliwia sprawdzenie stanu eksportów. Możesz również użyć usługi Azure Monitor , aby zobaczyć, ile danych eksportujesz i jakiekolwiek błędy eksportu. Dostęp do metryk eksportu i kondycji urządzenia można uzyskać w wykresach w witrynie Azure Portal przy użyciu interfejsu API REST, zapytań w programie PowerShell lub interfejsu wiersza polecenia platformy Azure. Obecnie można monitorować następujące metryki eksportu danych w usłudze Azure Monitor:

  • Liczba komunikatów przychodzących do eksportu przed zastosowaniem filtrów.
  • Liczba komunikatów przekazywanych przez filtry.
  • Liczba komunikatów pomyślnie wyeksportowanych do miejsc docelowych.
  • Liczba znalezionych błędów.

Aby dowiedzieć się więcej, zobacz Monitorowanie kondycji aplikacji.

Formaty danych

W poniższych sekcjach opisano formaty wyeksportowanych danych:

Format telemetrii

Każdy wyeksportowany komunikat zawiera znormalizowaną formę pełnego komunikatu wysyłanego przez urządzenie w treści wiadomości. Komunikat jest w formacie JSON i zakodowany jako UTF-8. Informacje w każdym komunikacie obejmują:

  • applicationId: identyfikator aplikacji usługi IoT Central.
  • messageSource: źródło komunikatu — telemetry.
  • deviceId: identyfikator urządzenia, które wysłało komunikat telemetrii.
  • schema: nazwa i wersja schematu ładunku.
  • templateId: identyfikator szablonu urządzenia przypisanego do urządzenia.
  • enqueuedTime: czas, w którym usługa IoT Central otrzymała tę wiadomość.
  • enrichments: wszelkie wzbogacania skonfigurowane w eksporcie.
  • module: moduł usługi IoT Edge, który wysłał tę wiadomość. To pole jest wyświetlane tylko wtedy, gdy komunikat pochodzi z modułu usługi IoT Edge.
  • component: składnik, który wysłał ten komunikat. To pole jest wyświetlane tylko wtedy, gdy możliwości wysłane w komunikacie zostały modelowane jako składnik w szablonie urządzenia
  • messageProperties: inne właściwości wysyłane przez urządzenie z komunikatem. Te właściwości są czasami określane jako właściwości aplikacji. Dowiedz się więcej z dokumentacji usługi IoT Hub.

Właściwości komunikatu

Komunikaty telemetryczne mają właściwości metadanych, a także ładunek telemetrii. W poprzednim fragmencie kodu przedstawiono przykłady komunikatów systemowych, takich jak deviceId i enqueuedTime. Aby dowiedzieć się więcej o właściwościach komunikatów systemowych, zobacz Właściwości systemu komunikatów usługi IoT Hub D2C.

Jeśli chcesz dodać niestandardowe metadane do komunikatów telemetrycznych, możesz dodać właściwości do komunikatów telemetrycznych. Na przykład należy dodać znacznik czasu podczas tworzenia komunikatu przez urządzenie.

Poniższy fragment kodu pokazuje, jak dodać iothub-creation-time-utc właściwość do komunikatu podczas jego tworzenia na urządzeniu:

Ważne

Format tego znacznika czasu musi być utc bez informacji o strefie czasowej. Na przykład jest prawidłowy, 2021-04-21T11:30:16Z2021-04-21T11:30:16-07:00 jest nieprawidłowy.

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

Format zmiany właściwości

Każdy komunikat lub rekord reprezentuje zmiany właściwości urządzenia i chmury. Informacje w wyeksportowanym komunikacie obejmują:

  • applicationId: identyfikator aplikacji usługi IoT Central.
  • messageSource: źródło komunikatu — properties.
  • messageTypecloudPropertyChange: , devicePropertyDesiredChangelub devicePropertyReportedChange.
  • deviceId: identyfikator urządzenia, które wysłało komunikat telemetrii.
  • schema: nazwa i wersja schematu ładunku.
  • enqueuedTime: czas, w którym usługa IoT Central wykryła tę zmianę.
  • templateId: identyfikator szablonu urządzenia przypisanego do urządzenia.
  • properties: tablica właściwości, które uległy zmianie, w tym nazwy właściwości i wartości, które uległy zmianie. Informacje o składniku i module są uwzględniane, jeśli właściwość jest modelowana w składniku lub module usługi IoT Edge.
  • enrichments: wszelkie wzbogacania skonfigurowane w eksporcie.

Format zmiany łączności urządzenia

Każdy komunikat lub rekord reprezentuje zdarzenie łączności z jednego urządzenia. Informacje w wyeksportowanym komunikacie obejmują:

  • applicationId: identyfikator aplikacji usługi IoT Central.
  • messageSource: źródło komunikatu — deviceConnectivity.
  • messageTypeconnected: albo lub disconnected.
  • deviceId: identyfikator zmienionego urządzenia.
  • schema: nazwa i wersja schematu ładunku.
  • templateId: identyfikator szablonu urządzenia przypisanego do urządzenia.
  • enqueuedTime: czas wystąpienia tej zmiany w usłudze IoT Central.
  • enrichments: wszelkie wzbogacania skonfigurowane w eksporcie.

Format zmian cyklu życia urządzenia

Każdy komunikat lub rekord reprezentuje jedną zmianę jednego urządzenia. Informacje w wyeksportowanym komunikacie obejmują:

  • applicationId: identyfikator aplikacji usługi IoT Central.
  • messageSource: źródło komunikatu — deviceLifecycle.
  • messageType: typ zmiany, która wystąpiła. Jeden z: registered, , provisioneddeleted, enableddisabled, displayNameChangedi deviceTemplateChanged.
  • deviceId: identyfikator zmienionego urządzenia.
  • schema: nazwa i wersja schematu ładunku.
  • templateId: identyfikator szablonu urządzenia przypisanego do urządzenia.
  • enqueuedTime: czas wystąpienia tej zmiany w usłudze IoT Central.
  • enrichments: wszelkie wzbogacania skonfigurowane w eksporcie.

Format cyklu życia szablonu urządzenia

Każdy komunikat lub rekord reprezentuje jedną zmianę w jednym opublikowanym szablonie urządzenia. Informacje w wyeksportowanym komunikacie obejmują:

  • applicationId: identyfikator aplikacji usługi IoT Central.
  • messageSource: źródło komunikatu — deviceTemplateLifecycle.
  • messageTypecreated: , updatedlub deleted.
  • schema: nazwa i wersja schematu ładunku.
  • templateId: identyfikator szablonu urządzenia przypisanego do urządzenia.
  • enqueuedTime: czas wystąpienia tej zmiany w usłudze IoT Central.
  • enrichments: wszelkie wzbogacania skonfigurowane w eksporcie.

Format dziennika inspekcji

Każdy komunikat dziennika inspekcji reprezentuje zainicjowaną przez użytkownika zmianę jednostki z możliwością inspekcji wewnątrz aplikacji usługi IoT Central. Informacje w wyeksportowanym komunikacie obejmują:

  • actor: informacje o użytkowniku, który zmodyfikował jednostkę.
  • applicationId: identyfikator aplikacji usługi IoT Central.
  • messageSource: źródło komunikatu — audit.
  • messageType: typ zmiany, która wystąpiła. Jeden z: updated, created, deleted.
  • updated: występuje tylko wtedy, gdy messageType ma wartość updated. Zawiera więcej szczegółów dotyczących aktualizacji.
  • resource: szczegóły zmodyfikowanej jednostki.
  • schema: nazwa i wersja schematu ładunku.
  • deviceId: identyfikator zmienionego urządzenia.
  • enqueuedTime: czas wystąpienia tej zmiany w usłudze IoT Central.
  • enrichments: wszelkie wzbogacania skonfigurowane w eksporcie.

W przypadku usługi Event Hubs usługa IoT Central eksportuje nowe dane komunikatów do centrum zdarzeń niemal w czasie rzeczywistym. We właściwościach użytkownika (nazywanych również właściwościami aplikacji) każdego komunikatu iotcentral-device-idsą automatycznie dołączane wartości , iotcentral-application-id, iotcentral-message-sourcei iotcentral-message-type .

Następne kroki

Teraz, gdy wiesz, jak eksportować do usługi Event Hubs, sugerowanym następnym krokiem jest nauczenie się eksportowania do usługi Azure Data Explorer.