IoT-adatok exportálása Webhookba

Cikk
12/09/2023

Ez a cikk azt ismerteti, hogyan konfigurálhatja az adatexportálást úgy, hogy adatokat küldjön a Webhooknak.

Ezzel a funkcióval folyamatosan exportálhat szűrt és bővített IoT-adatokat az IoT Central-alkalmazásból. Az adatexportálás közel valós időben küldi el a változásokat a felhőalapú megoldás más részeire a melegúti elemzések, elemzések és tárolás érdekében.

Lehetőség van például a következőkre:

A telemetriai adatok, a tulajdonságváltozások, az eszközkapcsolatok, az eszköz életciklusa, az eszközsablonok életciklusa és a naplóadatok JSON formátumban történő folyamatos exportálása közel valós időben.
Szűrje az adatfolyamokat az egyéni feltételeknek megfelelő adatok exportálására.
Az adatfolyamok bővítése az eszközről származó egyéni értékekkel és tulajdonságértékekkel.
Alakítsa át az adatfolyamokat az alakzat és a tartalom módosításához.

Tipp.

Amikor bekapcsolja az adatexportálást, attól a pillanattól kezdve csak az adatokat kapja meg. Az előzményadatok megőrzéséhez kapcsolja be az adatexportálást korán. Ha manuálisan szeretne adatokat exportálni az adatexportálás kikapcsolt állapotából, olvassa el az IoT Central REST API használata az eszközök lekérdezéséhez című témakört.

Feljegyzés

Bizonyos körülmények között akár 60 másodpercet is igénybe vehet az üzenetek exportálása. Ez az idő attól számítható ki, hogy az IoT Central mikor kapja meg az üzenetet a mögöttes IoT Hubtól a célvégpontra való kézbesítés időpontjáig.

Előfeltételek

Az adatexportálási funkciók használatához adatexportálási engedéllyel kell rendelkeznie.

Webhook exportálási célhelyének beállítása

Webhook-célhelyek esetén az IoT Central közel valós időben exportálja az adatokat. Az üzenet törzsében lévő adatok az Event Hubs és a Service Bus formátumával megegyező formátumúak.

Webhook-célhely létrehozása

Adatokat exportálhat egy nyilvánosan elérhető HTTP Webhook-végpontra. A RequestBin használatával létrehozhat egy teszt Webhook-végpontot. A RequestBin szabályozza a kérést a kérelemkorlát elérésekor:

Lépjen a RequestBinre.
Válassza a RequestBin létrehozása lehetőséget.
Jelentkezzen be az elérhető módszerek egyikével.
Másolja ki a RequestBin URL-címét. Ezt az URL-címet használja az adatexportálás tesztelése során.

Az Azure Data Explorer célhelyének létrehozása az IoT Centralban az Adatexportálási oldalon:

Válassza az + Új cél lehetőséget.
Válassza a Webhook lehetőséget céltípusként.
Illessze be a Webhook-végpont visszahívási URL-címét. Igény szerint konfigurálhatja a Webhook-engedélyezést, és egyéni fejléceket adhat hozzá.
- Az OAuth2.0 esetében csak az ügyfél hitelesítő adatainak megadása támogatott. A cél mentésekor az IoT Central kommunikál az OAuth-szolgáltatóval egy engedélyezési jogkivonat lekéréséhez. Ez a jogkivonat a Authorization célhelyre küldött összes üzenet fejlécéhez van csatolva.
- Az engedélyezési jogkivonat esetében megadhat egy olyan jogkivonatértéket, amely közvetlenül a fejléchez van csatolva az erre a Authorization célhelyre küldött összes üzenethez.
Válassza a Mentés lehetőséget.

Példa OAuth 2.0-konfigurációra

Ez a példa bemutatja, hogyan konfigurálhat webhook-célhelyet egy Microsoft Entra-bejelentkezéssel védett Azure-függvényalkalmazás használatára:

Beállítás	Példa	Jegyzetek
Céltípus	Webhook
Visszahívási URL-cím	`https://myapp.azurewebsites.net/api/HttpExample`	A függvény URL-címe.
Engedélyezés	OAuth 2.0
Jogkivonat URL-címe	`https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token`	A jogkivonat lekéréséhez használandó URL-cím. Ezt az értéket a függvényalkalmazásban találja: A Microsoft Identity Provider > Endpoints > OAuth 2.0 tokenvégpont hitelesítése > (v2)
Ügyfél azonosítója	`your-client-id`	A függvényalkalmazás ügyfélazonosítója. Ezt az értéket a függvényalkalmazásban találja: A Microsoft Identity Provider-alkalmazás > (ügyfél) azonosítójának hitelesítése >
Titkos ügyfélkód	`your-client-secret`	A függvényalkalmazás ügyféltitkára. Ezt az értéket a függvényalkalmazásban találja: A Microsoft Identitásszolgáltató > tanúsítványainak és titkos kulcsainak hitelesítése >
Célközönség	n/a	Függvényalkalmazás használata esetén üres.
Hatókör	`https://your-client-id/.default`	A jogkivonat hatóköre. Függvényalkalmazás esetén használja az ügyfél-azonosító értékét.**
Jogkivonat-kérelem tartalomtípusa	Auto

Előfordulhat, hogy más webhook-célhelyek eltérő értékeket igényelnek ezekhez a beállításokhoz.

Adatexportálás beállítása

Most, hogy már van egy célhely az adatok exportálásához, állítsa be az adatexportálást az IoT Central-alkalmazásban:

Jelentkezzen be az IoT Central-alkalmazásba.
A bal oldali panelen válassza az Adatexportálás lehetőséget.

Tipp.

Ha nem látja az adatexportálást a bal oldali panelen, akkor nincs engedélye az adatok exportálásának konfigurálására az alkalmazásban. Az adatexportálás beállításához forduljon egy rendszergazdához.
Válassza az + Új exportálás lehetőséget.
Adja meg az új exportálás megjelenítendő nevét, és győződjön meg arról, hogy az adatexportálás engedélyezve van.

Válassza ki az exportálni kívánt adatok típusát. Az alábbi táblázat a támogatott adatexportálási típusokat sorolja fel:

Adattípus	Leírás	Adatformátum
Telemetria	Telemetriaüzenetek exportálása közel valós időben az eszközökről. Minden exportált üzenet tartalmazza az eredeti, normalizált eszközüzenet teljes tartalmát.	Telemetriai üzenet formátuma
Tulajdonságváltozások	Az eszköz- és felhőtulajdonságok változásainak exportálása közel valós időben. Írásvédett eszköztulajdonságok esetén a rendszer exportálja a jelentett értékek módosításait. Az olvasási-írási tulajdonságok esetében a jelentett és a kívánt értékek is exportálva lesznek.	Tulajdonságmódosítás üzenetformátuma
Eszközkapcsolatok	Csatlakoztatott és leválasztott események exportálása.	Eszközkapcsolati üzenet formátuma
Az eszközök életciklusa	Exportálja a regisztrált, törölt, kiépített, engedélyezett, letiltott, displayNameChanged és deviceTemplateChanged eseményeket.	Az eszköz életciklusának változásai üzenetformátuma
Eszközsablon életciklusa	Exportálja a közzétett eszközsablon módosításait, beleértve a létrehozott, frissített és törölt módosításokat.	Az eszközsablon életciklusa módosítja az üzenet formátumát
Naplók	Az alkalmazás entitásainak felhasználó által kezdeményezett frissítéseinek naplói. További információ: Naplók használata az IoT Central-alkalmazásban végzett tevékenységek nyomon követéséhez	Naplóüzenet formátuma

Szükség esetén szűrőket is hozzáadhat az exportált adatok mennyiségének csökkentéséhez. Az egyes adatexportálási típusokhoz különböző szűrőtípusok érhetők el:

Adatok típusa	Elérhető szűrők
Telemetria	Szűrés eszköznév, eszközazonosító, eszközsablon alapján, és ha az eszköz szimulálva van A stream szűrése csak olyan telemetriát tartalmaz, amely megfelel a szűrési feltételeknek Stream szűrése a szűrőfeltételeknek megfelelő tulajdonságokkal rendelkező eszközök telemetriai adatainak szűréséhez A stream szűrése csak olyan telemetriát tartalmaz, amelynek üzenettulajdonságai megfelelnek a szűrőfeltételnek. Az üzenettulajdonságok (más néven alkalmazástulajdonságok) minden telemetriai üzenetben kulcs-érték párokban jelennek meg. Üzenettulajdonság-szűrő létrehozásához írja be a keresett üzenettulajdonság-kulcsot, és adjon meg egy feltételt. Csak a megadott szűrőfeltételnek megfelelő tulajdonságokkal rendelkező telemetriai üzenetek lesznek exportálva. További információ az IoT Hub-dokumentumok alkalmazástulajdonságairól
Tulajdonságváltozások	Szűrés eszköznév, eszközazonosító, eszközsablon alapján, és ha az eszköz szimulálva van A stream szűrése csak a szűrési feltételeknek megfelelő tulajdonságmódosításokat tartalmazza
Eszközkapcsolatok	Szűrés eszköznév, eszközazonosító, eszközsablon, szervezetek és az eszköz szimulálása alapján A stream szűrése, hogy csak a szűrőfeltételeknek megfelelő tulajdonságokkal rendelkező eszközök módosításait tartalmazza
Az eszközök életciklusa	Szűrés eszköznév, eszközazonosító, eszközsablon alapján, és ha az eszköz ki van építve, engedélyezve vagy szimulálva A stream szűrése, hogy csak a szűrőfeltételeknek megfelelő tulajdonságokkal rendelkező eszközök módosításait tartalmazza
Eszközsablon életciklusa	Szűrés eszközsablon alapján
Naplók	n/a

Igény szerint bővítse az exportált üzeneteket további kulcs-érték pár metaadatokkal. A telemetria, a tulajdonságváltozások, az eszközkapcsolatok és az eszköz életciklusának adatexportálási típusaihoz a következő bővítések érhetők el:
- Egyéni sztring: Minden üzenethez hozzáad egy egyéni statikus sztringet. Adjon meg bármilyen kulcsot, és adjon meg bármilyen sztringértéket.
- Tulajdonság, amely hozzáadja az egyes üzeneteket:
  - Eszköz metaadatai, például eszköznév, eszközsablon neve, engedélyezve, szervezetek, kiépített és szimulált.
  - Az eszköz aktuálisan jelentett tulajdonsága vagy felhőtulajdonság-értéke minden üzenethez. Ha az exportált üzenet olyan eszközről származik, amely nem rendelkezik a megadott tulajdonságokkal, az exportált üzenet nem kapja meg a bővítést.

Az exportálási cél konfigurálása:

Válassza a + Cél lehetőséget egy már létrehozott célhely hozzáadásához, vagy válassza az Új létrehozása lehetőséget.
Az adatok exportálás előtti átalakításához válassza az + Átalakítás lehetőséget. További információ: Adatok átalakítása az IoT Central-alkalmazásban exportáláshoz.
A + Cél lehetőséget választva legfeljebb öt célhelyet adhat hozzá egyetlen exportáláshoz.
Amikor befejezte az exportálás beállítását, válassza a Mentés lehetőséget. Néhány perc elteltével az adatok megjelennek a célhelyeken.

Az exportálás figyelése

Az IoT Central Adatexportálási lapján ellenőrizheti az exportálások állapotát. Az Azure Monitor használatával azt is megtekintheti, hogy mennyi adatot exportál, és milyen exportálási hibákat tapasztal. Az exportálási és az eszközállapot-metrikákat az Azure Portal diagramjaiban a REST API, a PowerShell-lekérdezések vagy az Azure CLI használatával érheti el. Jelenleg a következő adatexportálási metrikákat figyelheti az Azure Monitorban:

Az exportálandó üzenetek száma a szűrők alkalmazása előtt.
A szűrőkön áthaladó üzenetek száma.
A célhelyekre sikeresen exportált üzenetek száma.
A talált hibák száma.

További információ: Alkalmazás állapotának figyelése.

Adatformátumok

Az alábbi szakaszok az exportált adatok formátumát ismertetik:

Telemetriai formátum

Minden exportált üzenet az eszköz által az üzenet törzsében küldött teljes üzenet normalizált formáját tartalmazza. Az üzenet JSON formátumban van, és UTF-8 formátumban van kódolva. Az egyes üzenetek információi a következők:

applicationId: Az IoT Central-alkalmazás azonosítója.
messageSource: Az üzenet forrása – telemetry.
deviceId: A telemetriai üzenetet küldő eszköz azonosítója.
schema: A hasznos adatséma neve és verziója.
templateId: Az eszközhöz rendelt eszközsablon azonosítója.
enqueuedTime: Az az időpont, amikor az IoT Central megkapta ezt az üzenetet.
enrichments: Az exportáláson beállított összes bővítés.
module: Az üzenetet küldő IoT Edge-modul. Ez a mező csak akkor jelenik meg, ha az üzenet egy IoT Edge-modulból származik.
component: Az üzenetet küldő összetevő. Ez a mező csak akkor jelenik meg, ha az üzenetben küldött képességeket az eszközsablon összetevőjeként modellezték
messageProperties: Egyéb tulajdonságok, amelyeket az eszköz küldött az üzenettel. Ezeket a tulajdonságokat néha alkalmazástulajdonságoknak is nevezik. További információ az IoT Hub-dokumentumokból.

Üzenet tulajdonságai

A telemetriai üzenetek a metaadatokhoz és a telemetriai hasznos adatokhoz is rendelkeznek tulajdonságokkal. Az előző kódrészlet példákat mutat be a rendszerüzenetekre, például deviceId és enqueuedTime. A rendszerüzenetek tulajdonságaival kapcsolatos további információkért lásd a D2C IoT Hub-üzenetek rendszertulajdonságait.

Ha egyéni metaadatokat szeretne hozzáadni a telemetriai üzenetekhez, tulajdonságokat adhat hozzá a telemetriai üzenetekhez. Ha például az eszköz létrehozza az üzenetet, időbélyeget kell hozzáadnia.

Az alábbi kódrészlet bemutatja, hogyan adhatja hozzá a iothub-creation-time-utc tulajdonságot az üzenethez, amikor létrehozza az eszközön:

Fontos

Az időbélyeg formátumának utc-nek kell lennie, és nincs időzónára vonatkozó információ. Például 2021-04-21T11:30:16Z érvényes, 2021-04-21T11:30:16-07:00 érvénytelen.

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)

Tulajdonságmódosítások formátuma

Minden üzenet vagy rekord az eszköz- és felhőtulajdonságok változásait jelöli. Az exportált üzenet tartalma:

applicationId: Az IoT Central-alkalmazás azonosítója.
messageSource: Az üzenet forrása – properties.
messageType: Vagy cloudPropertyChange, devicePropertyDesiredChangevagy devicePropertyReportedChange.
deviceId: A telemetriai üzenetet küldő eszköz azonosítója.
schema: A hasznos adatséma neve és verziója.
enqueuedTime: Az az időpont, amikor az IoT Central észlelte ezt a változást.
templateId: Az eszközhöz rendelt eszközsablon azonosítója.
properties: Megváltozott tulajdonságok tömbje, beleértve a módosított tulajdonságok és értékek nevét. Az összetevő és a modul adatai akkor jelennek meg, ha a tulajdonság egy összetevőben vagy egy IoT Edge-modulban van modellelve.
enrichments: Az exportáláson beállított összes bővítés.

Eszközkapcsolat-módosítások formátuma

Minden üzenet vagy rekord egyetlen eszköz kapcsolati eseményét jelöli. Az exportált üzenet tartalma:

applicationId: Az IoT Central-alkalmazás azonosítója.
messageSource: Az üzenet forrása – deviceConnectivity.
messageType: Vagy connected .disconnected
deviceId: A módosított eszköz azonosítója.
schema: A hasznos adatséma neve és verziója.
templateId: Az eszközhöz rendelt eszközsablon azonosítója.
enqueuedTime: A változás időpontja az IoT Centralban.
enrichments: Az exportáláson beállított összes bővítés.

Az eszköz életciklusának változásai formátuma

Minden üzenet vagy rekord egyetlen eszközre történő módosítást jelöl. Az exportált üzenet tartalma:

applicationId: Az IoT Central-alkalmazás azonosítója.
messageSource: Az üzenet forrása – deviceLifecycle.
messageType: A bekövetkezett változás típusa. Az alábbiak egyike: registered, deleted, provisioned, enabled, disabled, displayNameChangedés deviceTemplateChanged.
deviceId: A módosított eszköz azonosítója.
schema: A hasznos adatséma neve és verziója.
templateId: Az eszközhöz rendelt eszközsablon azonosítója.
enqueuedTime: A változás időpontja az IoT Centralban.
enrichments: Az exportáláson beállított összes bővítés.

Az eszközsablon életciklusának változásainak formátuma

Minden üzenet vagy rekord egyetlen közzétett eszközsablonra való módosítást jelöl. Az exportált üzenet tartalma:

applicationId: Az IoT Central-alkalmazás azonosítója.
messageSource: Az üzenet forrása – deviceTemplateLifecycle.
messageType: Vagy created, updatedvagy deleted.
schema: A hasznos adatséma neve és verziója.
templateId: Az eszközhöz rendelt eszközsablon azonosítója.
enqueuedTime: A változás időpontja az IoT Centralban.
enrichments: Az exportáláson beállított összes bővítés.

Auditnapló formátuma

Minden auditnapló-üzenet egy felhasználó által kezdeményezett módosítást jelöl az IoT Central-alkalmazáson belül egy naplózható entitáson. Az exportált üzenet tartalma:

actor: Az entitást módosító felhasználó adatai.
applicationId: Az IoT Central-alkalmazás azonosítója.
messageSource: Az üzenet forrása – audit.
messageType: A bekövetkezett változás típusa. Az egyik: updated, created, deleted.
updated: Csak akkor jelen van, ha messageType van updated. További részleteket tartalmaz a frissítésről.
resource: A módosított entitás részletei.
schema: A hasznos adatséma neve és verziója.
deviceId: A módosított eszköz azonosítója.
enqueuedTime: A változás időpontja az IoT Centralban.
enrichments: Az exportáláson beállított összes bővítés.

Következő lépések

Most, hogy már tudja, hogyan exportálhat a Service Busba, javasolt következő lépés az Exportálás az Event Hubsba című cikk.

Megosztás a következőn keresztül: