Eksportowanie danych IoT do elementu webhook

W tym artykule opisano sposób konfigurowania eksportu danych w celu wysyłania danych do elementu webhook.

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 miejsca docelowego eksportu elementu webhook

W przypadku miejsc docelowych elementów webhook usługa IoT Central eksportuje dane niemal w czasie rzeczywistym. Dane w treści komunikatu mają taki sam format jak w przypadku usług Event Hubs i Service Bus.

Tworzenie miejsca docelowego elementu webhook

Dane można wyeksportować do publicznie dostępnego punktu końcowego elementu webhook HTTP. Możesz utworzyć testowy punkt końcowy elementu webhook przy użyciu metody RequestBin. Żądanie RequestBin ogranicza żądanie po osiągnięciu limitu żądań:

1. Przejdź do pozycji RequestBin.

2. Wybierz pozycję Utwórz element RequestBin.

3. Zaloguj się przy użyciu jednej z dostępnych metod.

4. Skopiuj adres URL elementu RequestBin Użyj tego adresu URL podczas testowania eksportu danych.

Aby utworzyć miejsce docelowe usługi Azure Data Explorer w usłudze IoT Central na stronie eksportowania danych:

1. Wybierz pozycję + Nowe miejsce docelowe.

2. Wybierz pozycję Element webhook jako typ docelowy.

3. Wklej adres URL wywołania zwrotnego dla punktu końcowego elementu webhook. Opcjonalnie możesz skonfigurować autoryzację elementu webhook i dodać nagłówki niestandardowe.

   • W przypadku protokołu OAuth2.0 obsługiwany jest tylko przepływ udzielania poświadczeń klienta. Po zapisaniu miejsca docelowego usługa IoT Central komunikuje się z dostawcą OAuth w celu pobrania tokenu autoryzacji. Ten token jest dołączony do nagłówka dla każdego komunikatu wysyłanego Authorization do tego miejsca docelowego.
   • W przypadku tokenu autoryzacji można określić wartość tokenu, która jest bezpośrednio dołączona do nagłówka dla każdego komunikatu wysyłanego Authorization do tego miejsca docelowego.

4. Wybierz pozycję Zapisz.

Przykładowa konfiguracja protokołu OAuth 2.0

W tym przykładzie pokazano, jak skonfigurować miejsce docelowe elementu webhook do korzystania z aplikacji funkcji platformy Azure chronionej przy użyciu logowania firmy Microsoft Entra:

Ustawienie	Przykład	Uwagi
Typ docelowy	Webhook
Adres URL wywołania zwrotnego	https://myapp.azurewebsites.net/api/HttpExample	Adres URL funkcji.
Autoryzacja	OAuth 2.0
Adres URL tokenu	https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token	Adres URL używany do pobierania tokenu. Tę wartość można znaleźć w aplikacji funkcji: Uwierzytelnianie > punktu końcowego tokenu dostawcy > > tożsamości firmy Microsoft OAuth 2.0 (wersja 2)
Client ID	your-client-id	Identyfikator klienta aplikacji funkcji. Tę wartość można znaleźć w aplikacji funkcji: Uwierzytelnianie > identyfikatora aplikacji dostawcy > tożsamości firmy Microsoft (klienta)
Klucz tajny klienta	your-client-secret	Wpis tajny klienta aplikacji funkcji. Tę wartość można znaleźć w aplikacji funkcji: Uwierzytelnianie > certyfikatów i wpisów tajnych dostawcy > tożsamości firmy Microsoft
Odbiorcy	Nie dotyczy	Puste, jeśli używasz aplikacji funkcji.
Scope	https://your-client-id/.default	Zakres tokenu. W przypadku aplikacji funkcji użyj wartości identyfikatora klienta.**
Typ zawartości żądania tokenu	Auto

Inne miejsca docelowe elementu webhook mogą wymagać różnych wartości dla tych ustawień.

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 z urządzenia do chmury.

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:16Z 2021-04-21T11:30:16-07:00 jest nieprawidłowy.

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 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.

Następne kroki

Teraz, gdy wiesz, jak wyeksportować do usługi Service Bus, sugerowanym następnym krokiem jest nauczenie się eksportowania do usługi Event Hubs.