IoT-adatok exportálása a Service Busba

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

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.

Service Bus-exportálási célhely beállítása

Az Azure Service Bus-célhelyek esetében az üzenetsorok és a témakörök egyaránt támogatottak.

Az IoT Central közel valós időben exportálja az adatokat. Az adatok az üzenet törzsében vannak, és JSON formátumban vannak kódolva UTF-8 formátumban.

Az üzenet széljegyzetei vagy rendszertulajdonság-zsákja tartalmazza azokat a iotcentral-device-id, iotcentral-application-id, iotcentral-message-sourceés iotcentral-message-type mezőket, amelyek értékei megegyeznek az üzenet törzsének megfelelő mezőivel.

Csatlakozás ion beállításai

A Service Bus-célhelyek lehetővé teszik a kapcsolat konfigurálását egy kapcsolati sztring vagy egy felügyelt identitással.

A felügyelt identitások biztonságosabbak, mert:

• Nem tárolja az erőforrás hitelesítő adatait egy kapcsolati sztring az IoT Central-alkalmazásban.
• A hitelesítő adatok automatikusan az IoT Central-alkalmazás élettartamához vannak kötve.
• A felügyelt identitások rendszeresen automatikusan elforgatják a biztonsági kulcsokat.

Az IoT Central jelenleg rendszer által hozzárendelt felügyelt identitásokat használ.

Felügyelt identitás konfigurálásakor a konfiguráció hatókört és szerepkört tartalmaz:

• A hatókör határozza meg, hogy hol használhatja a felügyelt identitást. Használhat például egy Azure-erőforráscsoportot hatókörként. Ebben az esetben az IoT Central-alkalmazásnak és a célnak ugyanabban az erőforráscsoportban kell lennie.
• A szerepkör határozza meg, hogy az IoT Central-alkalmazás milyen engedélyeket kap a célszolgáltatásban. Például ahhoz, hogy egy IoT Central-alkalmazás adatokat küldjön egy eseményközpontba, a felügyelt identitásnak szüksége van az Azure Event Hubs Adatküldő szerepkör-hozzárendelésére.

Az alábbi videó további információt nyújt a rendszer által hozzárendelt felügyelt identitásokról:

Figyelemfelhívás

A Blob Storage-ba való exportáláshoz ne használja a tárfiók-közreműködőt a videóban látható módon. Használja inkább a Storage Blob Data Közreműködő szerepkört.

Service Bus-üzenetsor vagy témakör célhelyének létrehozása

Kezelt identitás

Ez a cikk bemutatja, hogyan hozhat létre felügyelt identitást az Azure CLI használatával. Az Azure Portallal is létrehozhat egy rugalmas identitást.

Ha nem rendelkezik meglévő Service Bus-névtérrel, futtassa a következő szkriptet az Azure Cloud Shell bash-környezetben. A szkript létrehoz egy erőforráscsoportot, Egy Service Bus-névteret és egy üzenetsort. A szkript ezután engedélyezi az IoT Central-alkalmazás felügyelt identitását, és hozzárendeli a Service Bus-üzenetsor eléréséhez szükséges szerepkört:

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

Ha tovább szeretné biztonságossá tenni az üzenetsort vagy a témakört, és csak felügyelt identitásokkal rendelkező megbízható szolgáltatásokból szeretne hozzáférést engedélyezni, tekintse meg az Adatok exportálása biztonságos helyre egy Azure-beli virtuális hálózaton című témakört.

A Service Bus-cél létrehozása az IoT Centralban az Adatexportálási oldalon:

1. Válassza az + Új cél lehetőséget.

2. Válassza az Azure Service Bus-üzenetsort vagy az Azure Service Bus-témakört céltípusként.

3. Válassza ki a rendszer által hozzárendelt felügyelt identitást engedélyezési típusként.

4. Adja meg a Service Bus-erőforrás állomásnevét. Ezután adja meg a kis- és nagybetűkre érzékeny üzenetsort vagy témakörnevet. A gazdagép neve így néz ki: contoso-waste.servicebus.windows.net.

5. Válassza a Mentés lehetőséget.

Ha nem látja a célszolgáltatásba érkező adatokat, tekintse meg az Azure IoT Central-alkalmazásból származó adatexportálással kapcsolatos problémák elhárítása című témakört.

Kapcsolati sztring

Ha nem rendelkezik meglévő Service Bus-névtérrel, futtassa a következő szkriptet az Azure Cloud Shell bash-környezetben. A szkript létrehoz egy erőforráscsoportot, Egy Service Bus-névteret és egy üzenetsort. Ezután kinyomtatja a kapcsolati sztring, amelyet az IoT Centralban való adatexportálás konfigurálásakor használ:

# Replace the Service Bus namespace name with your own unique value
SBNS=your-service-bus-namespace-$RANDOM
SBQ=exportdata
RG=centralexportresources
LOCATION=eastus

az group create -n $RG --location $LOCATION
az servicebus namespace create --name $SBNS --resource-group $RG -l $LOCATION

# This example uses a Service Bus queue. You can use a Service Bus topic.
az servicebus queue create --name $SBQ --resource-group $RG --namespace-name $SBNS
az servicebus queue authorization-rule create --queue-name $SBQ --resource-group $RG --namespace-name $SBNS --name SendRule --rights Send

CS=$(az servicebus queue authorization-rule keys list --queue-name $SBQ --resource-group $RG --namespace-name $SBNS --name SendRule --query "primaryConnectionString" -o tsv)

echo "Service bus connection string: $CS"

A Service Bus-cél létrehozása az IoT Centralban az Adatexportálási oldalon:

1. Válassza az + Új cél lehetőséget.

2. Válassza az Azure Service Bus-üzenetsort vagy az Azure Service Bus-témakört céltípusként.

3. Engedélyezési típusként válassza a Csatlakozás ion sztringet.

4. Illessze be a Service Bus-erőforrás kapcsolati sztring, és szükség esetén adja meg a kis- és nagybetűknek megfelelő üzenetsort vagy témakörnevet.

5. Válassza a Mentés lehetőséget.

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:

1. Jelentkezzen be az IoT Central-alkalmazásba.

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

3. Válassza az + Új exportálás lehetőséget.

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

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

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

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

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

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

3. A + Cél lehetőséget választva legfeljebb öt célhelyet adhat hozzá egyetlen exportáláshoz.

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

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)

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.

A Service Bus esetében az IoT Central közel valós időben exportálja az új üzenetek adatait a Service Bus-üzenetsorba vagy -témakörbe. Az egyes üzenetek felhasználói tulajdonságaiban (más néven alkalmazástulajdonságok) a iotcentral-device-id, iotcentral-application-id, iotcentral-message-sourceés iotcentral-message-type automatikusan szerepelnek.

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.