Eksportowanie danych IoT do usługi Service Bus
W tym artykule opisano sposób konfigurowania eksportu danych w celu wysyłania danych do usługi Service Bus.
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 usługi Service Bus
Kolejki i tematy są obsługiwane w przypadku miejsc docelowych usługi Azure Service Bus.
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-id
pola , iotcentral-application-id
, iotcentral-message-source
i iotcentral-message-type
, które mają te same wartości co odpowiednie pola w treści komunikatu.
Opcje połączenia
Miejsca docelowe usługi Service Bus 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 kolejki lub miejsca docelowego tematu usługi Service Bus
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 Service Bus 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 Service Bus i kolejkę. Następnie skrypt włącza tożsamość zarządzaną aplikacji usługi IoT Central i przypisuje rolę, która musi uzyskać dostęp do kolejki usługi Service Bus:
# Replace the Service Bus namespace name with your own unique value
SBNS=your-service-bus-namespace-$RANDOM
# Replace the IoT Central app name with the name of your
# IoT Central application.
CA=your-iot-central-app
SBQ=exportdata
RG=centralexportresources
LOCATION=eastus
RGID=$(az group create -n $RG --location $LOCATION --query "id" --output tsv)
az servicebus namespace create --name $SBNS --resource-group $RG -l $LOCATION
az servicebus queue create --name $SBQ --resource-group $RG --namespace-name $SBNS
# 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 Service Bus Data Sender" --scope $RGID
az role assignment list --assignee $PI --all -o table
echo "Host name: $SBNS.servicebus.windows.net"
echo "Queue: $SBQ"
Aby dodatkowo zabezpieczyć kolejkę lub temat 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 Service Bus w usłudze IoT Central na stronie Eksportowanie danych:
Wybierz pozycję + Nowe miejsce docelowe.
Wybierz pozycję Kolejka usługi Azure Service Bus lub Temat usługi Azure Service Bus jako typ docelowy.
Wybierz pozycję Tożsamość zarządzana przypisana przez system jako typ autoryzacji.
Wprowadź nazwę hosta zasobu usługi Service Bus. Następnie wprowadź nazwę kolejki lub tematu z uwzględnieniem wielkości liter. Nazwa hosta wygląda następująco:
contoso-waste.servicebus.windows.net
.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:
Zaloguj się do aplikacji usługi IoT Central.
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.
Wybierz pozycję + Nowy eksport.
Wprowadź nazwę wyświetlaną nowego eksportu i upewnij się, że eksport danych jest włączony.
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 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 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:
Wybierz pozycję + Miejsce docelowe , aby dodać miejsce docelowe, które zostało już utworzone, lub wybierz pozycję Utwórz nową.
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.
Wybierz pozycję + Miejsce docelowe , aby dodać do pięciu miejsc docelowych do jednego eksportu.
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ądzeniamessageProperties
: 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.
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
.messageType
cloudPropertyChange
: ,devicePropertyDesiredChange
lubdevicePropertyReportedChange
.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
.messageType
connected
: albo lubdisconnected
.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
, ,provisioned
deleted
,enabled
disabled
,displayNameChanged
ideviceTemplateChanged
.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
.messageType
created
: ,updated
lubdeleted
.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, gdymessageType
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 Service Bus usługa IoT Central eksportuje nowe dane komunikatów do kolejki lub tematu usługi Service Bus niemal w czasie rzeczywistym. We właściwościach użytkownika (nazywanych również właściwościami aplikacji) każdego komunikatu iotcentral-device-id
są automatycznie dołączane wartości , iotcentral-application-id
, iotcentral-message-source
i iotcentral-message-type
.
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.