Végpontok létrehozása az Azure Digital Twinsben

Cikk
10/27/2023

Ez a cikk bemutatja, hogyan hozhat létre végpontot az Azure Digital Twin-eseményekhez az Azure Portal vagy az Azure CLI használatával. A végpontokat a DigitalTwinsEndpoint vezérlősík API-kkal is kezelheti.

Az Eseményértesítések átirányítása az Azure Digital Twinsből az alsóbb rétegbeli szolgáltatásokhoz vagy a csatlakoztatott számítási erőforrásokhoz kétlépéses folyamat: végpontok létrehozása, majd eseményútvonalak létrehozása az adatoknak a végpontokra való küldéséhez. Ez a cikk az első lépésről, az események fogadására képes végpontok beállításával foglalkozik. Később létrehozhat olyan eseményútvonalakat, amelyek meghatározzák , hogy az Azure Digital Twins által létrehozott események mely végpontokra érkeznek.

Előfeltételek

Szüksége lesz egy Azure-fiókra, amely ingyenesen beállítható
Szüksége lesz egy Azure Digital Twins-példányra az Azure-előfizetésében. Ha még nincs példánya, létrehozhat egyet a példány és a hitelesítés beállításának lépéseivel. A cikk későbbi részében a következő értékeket használhatja a beállítástól kezdve:
- Példány neve
- Erőforráscsoport
Ezeket a részleteket az Azure Portalon találja a példány beállítása után.

Ezután kövesse az alábbi utasításokat, ha az Azure CLI-t szeretné használni az útmutató követésével.

A környezet előkészítése az Azure CLI-hez

Használja a Bash-környezetet az Azure Cloud Shellben. További információ: A Bash rövid útmutatója az Azure Cloud Shellben.
Ha inkább helyi cli-referenciaparancsokat szeretne futtatni, telepítse az Azure CLI-t. Ha Windows vagy macOS rendszert használ, fontolja meg az Azure CLI Docker-tárolóban való futtatását. További információ: Az Azure CLI futtatása Docker-tárolóban.
- Ha helyi telepítést használ, jelentkezzen be az Azure CLI-be az az login parancs futtatásával. A hitelesítési folyamat befejezéséhez kövesse a terminálon megjelenő lépéseket. További bejelentkezési lehetőségekért lásd : Bejelentkezés az Azure CLI-vel.
- Amikor a rendszer kéri, először telepítse az Azure CLI-bővítményt. További információ a bővítményekről: Bővítmények használata az Azure CLI-vel.
- Futtassa az az version parancsot a telepített verzió és a függő kódtárak megkereséséhez. A legújabb verzióra az az upgrade paranccsal frissíthet.

A szükséges erőforrások létrehozása

Ezek a szolgáltatások a példányhoz létrehozható végpontok támogatott típusai:

Event Grid-témakör
- Az Event Grid-végpontok esetében csak az Event Grid-témakörök támogatottak. Az Event Grid-tartományok nem támogatottak végpontként.
Event Hubs Hub
Service Bus-témakör

Ahhoz, hogy egy végpontot az Azure Digital Twinshez csatoljon, a végponthoz használt Event Grid-témakörnek, eseményközpontnak vagy Service Bus-témakörnek már léteznie kell.

Az alábbi diagramon megtekintheti, hogy milyen erőforrásokat kell beállítani a végpont létrehozása előtt.

Végpont típusa	Szükséges erőforrások (létrehozási utasításokhoz csatolva)
Event Grid-végpont	Event Grid-témakör *az eseménysémának Event Grid-sémának vagy felhőbeli eseményséma 1.0-s verziójának kell lennie
Event Hubs-végpont	Event Hubs-névtér event hub (Nem kötelező) kulcsalapú hitelesítés engedélyezési szabálya
Service Bus-végpont	Service Bus-névtér Service Bus-témakör (Nem kötelező) kulcsalapú hitelesítés engedélyezési szabálya

A végpont létrehozása

Miután létrehozta a végponterőforrásokat, használhatja őket egy Azure Digital Twins-végponthoz.

Portál
Parancssori felület

Új végpont létrehozásához lépjen a példány lapjára az Azure Portalon (a példányt a portál keresősávjába beírva találhatja meg).

A példány menüjében válassza a Végpontok lehetőséget. Ezután az alábbi Végpontok lapon válassza a + Végpont létrehozása lehetőséget. Ezzel megnyitja a Végpont létrehozása lapot, ahol a következő lépésekben kitölti a mezőket.
Adja meg a végpont nevét, és válassza ki a végpont típusát.
Töltse ki a végponttípushoz szükséges egyéb részleteket, beleértve az előfizetését és a korábban ismertetett végponterőforrásokat.
1. Csak Event Hubs- és Service Bus-végpontok esetén ki kell választania egy hitelesítési típust. Kulcsalapú hitelesítést használhat előre létrehozott engedélyezési szabálysal, vagy rendszer által hozzárendelt vagy felhasználó által hozzárendelt felügyelt identitással. Az identitás-hitelesítési beállítások használatáról további információt a Végpont beállításai: Identitásalapú hitelesítés című témakörben talál.
Fejezze be a végpont létrehozását a Mentés gombra kattintva.

A végpont létrehozása után ellenőrizheti, hogy a végpont sikeresen létrejött-e a felső Azure Portal-sáv értesítésikonjának ellenőrzésével:

Képernyőkép a végpont azure portalon való létrehozásának ellenőrzésére szolgáló értesítésről.

Ha a végpont létrehozása sikertelen, figyelje meg a hibaüzenetet, és próbálkozzon újra néhány perc múlva.

Az Azure Digital Twins-példány Végpontok lapján létrehozott végpontot is megtekintheti.

Az Event Grid-témakör, az eseményközpont vagy a Service Bus-témakör mostantól végpontként érhető el az Azure Digital Twinsben a végponthoz választott név alatt. Általában ezt a nevet fogja használni egy eseményútvonal céljaként, amelyet útvonalak és szűrők létrehozásakor hozhat létre.

Az alábbi példák bemutatják, hogyan hozhat létre végpontokat az Az dt endpoint create paranccsal az Azure Digital Twins CLI-hez. Cserélje le a parancsok helyőrzőit a saját erőforrásai részleteire.

Event Grid-végpont létrehozása:

az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

Event Hubs-végpont létrehozása (kulcsalapú hitelesítés):

az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Service Bus-témakörvégpont létrehozása (kulcsalapú hitelesítés):

az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

A parancsok sikeres futtatása után az Event Grid-témakör, az event hub vagy a Service Bus-témakör végpontként lesz elérhető az Azure Digital Twinsben az --endpoint-name argumentumhoz megadott név alatt. Általában ezt a nevet fogja használni egy eseményútvonal céljaként, amelyet útvonalak és szűrők létrehozásakor hozhat létre.

Végpontbeállítások: Identitásalapú hitelesítés

Ez a szakasz azt ismerteti, hogyan használhat felügyelt identitást egy Azure Digital Twins-példányhoz , amikor eseményeket továbbít a támogatott útválasztási célhelyekre. A felügyelt identitás beállítása nem szükséges az útválasztáshoz, de segíthet a példánynak a Microsoft Entra által védett egyéb erőforrások, például az Event Hubs, a Service Bus-célhelyek és az Azure Storage-tárolók egyszerű elérésében. A felügyelt identitások rendszerhez vagy felhasználóhoz rendelhetők.

A szakasz további része egy felügyelt identitással rendelkező végpont beállításának három lépését ismerteti.

1. Felügyelt identitás engedélyezése a példányhoz

Az alábbi fülek segítségével az ön által előnyben részesített felületnek megfelelő utasításokat talál.

Portál
Parancssori felület

Először győződjön meg arról, hogy engedélyezte a felügyelt identitást az Azure Digital Twins-példányhoz.

Emellett győződjön meg arról, hogy rendelkezik Azure Digital Twins-adattulajdonosi szerepkörökkel a példányon. A felhasználói hozzáférési engedélyek beállítása című témakörben talál útmutatást.

2. Azure-szerepkörök hozzárendelése az identitáshoz

Miután létrehozott egy felügyelt identitást az Azure Digital Twins-példányhoz, hozzá kell rendelnie a megfelelő szerepköröket a különböző típusú végpontokkal való hitelesítéshez, hogy az eseményeket a támogatott célhelyekre irányíthassa. Ez a szakasz a szerepkör-beállításokat és azok felügyelt identitáshoz való hozzárendelését ismerteti.

Fontos

Mindenképpen végezze el ezt a lépést. Nélküle az identitás nem fog tudni hozzáférni a végpontokhoz, és az események nem lesznek kézbesítve.

Az alábbiakban bemutatjuk, hogy az Azure Digital Twins-identitásnak milyen minimális szerepkörökre van szüksége egy végpont eléréséhez a cél típusától függően. A magasabb engedélyekkel (például adattulajdonosi szerepkörökkel) rendelkező szerepkörök is működni fognak.

Cél	Azure-szerepkör
Azure-eseményközpontok	Azure Event Hubs-adatküldő
Azure Service Bus	Azure Service Bus-adatfeladó
Azure Storage-tároló	Storage blobadat-közreműködő

Az alábbi lapok segítségével rendelje hozzá a szerepkört az előnyben részesített felülettel.

Portál
Parancssori felület

Ha szerepkört szeretne hozzárendelni az identitáshoz, először nyissa meg az Azure Portalt egy böngészőben.

A portál keresősávjában keresse meg a végponterőforrást (az eseményközpontot, a Service Bus-témakört vagy a tárolót).
Válassza a Hozzáférés-vezérlés (IAM) lehetőséget.
Kattintson a Hozzáadás>Szerepkör-hozzárendelés hozzáadása lehetőségre a Szerepkör-hozzárendelés hozzáadása oldal megnyitásához.

Rendelje hozzá a kívánt szerepkört az Azure Digital Twins-példány felügyelt identitásához az alábbi információk alapján. A részletes lépésekért tekintse meg az Azure-szerepköröknek az Azure Portalon történő hozzárendelését ismertető cikket.

Beállítás	Érték
Szerepkör	Válassza ki a kívánt szerepkört a beállítások közül.
Hozzáférés hozzárendelése a következőhöz:	Kezelt identitás
Tagok	Válassza ki a szerepkörhöz hozzárendelt Azure Digital Twins-példány felhasználó által hozzárendelt vagy rendszer által hozzárendelt felügyelt identitását. A felhasználó által hozzárendelt identitások neve az identitás létrehozásakor lesz kiválasztva, a rendszer által hozzárendelt identitás pedig az Azure Digital Twins-példány nevével egyező névvel fog rendelkezni.

A paramétert hozzáadhatja a --scopesaz dt create parancshoz, és hozzárendelheti az identitást egy vagy több megadott szerepkörrel rendelkező hatókörhöz. Az ezzel a paraméterrel rendelkező parancs a példány első létrehozásakor vagy később is használható egy már létező példány nevére való átadással.

Íme egy példa, amely létrehoz egy példányt egy rendszer által hozzárendelt felügyelt identitással, és hozzárendeli az identitást egy eseményközpontban hívott MyCustomRole egyéni szerepkörhöz.

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned --scopes "/subscriptions/<subscription ID>/resourceGroups/<resource-group>/providers/Microsoft.EventHub/namespaces/<Event-Hubs-namespace>/eventhubs/<event-hub-name>" --role MyCustomRole

A paranccsal történő szerepkör-hozzárendelésekre további példákat az az dt create referenciadokumentációban talál.

A szerepkörök létrehozásához és kezeléséhez az az szerepkör-hozzárendelési parancscsoportot is használhatja. Ez a parancs más olyan forgatókönyvek támogatására is használható, ahol nem szeretné csoportosítani a szerepkör-hozzárendelést a létrehozási paranccsal.

3. A végpont létrehozása identitásalapú hitelesítéssel

Miután beállított egy felügyelt identitást az Azure Digital Twins-példányhoz, és hozzárendelte a megfelelő szerepkör(ek)hez, létrehozhatja az identitást hitelesítésre használó végpontokat. Ez a beállítás csak az Event Hubs és a Service Bus típusú végpontok esetében érhető el (az Event Grid esetében ez nem támogatott).

Feljegyzés

Nem szerkesztheti a kulcsalapú identitással már létrehozott végpontot, hogy identitásalapú hitelesítésre váltson. A végpont első létrehozásakor ki kell választania a hitelesítési típust.

Az alábbi lapfülekkel hozza létre a végpontot az előnyben részesített felülettel.

Portál
Parancssori felület

Az Azure Digital Twins-végpont létrehozásához kövesse az általános utasításokat.

Amikor a végponttípushoz szükséges adatok elvégzésének lépéséhez ér, válassza ki a rendszer által hozzárendelt vagy a felhasználó által hozzárendelt (előzetes verzió) hitelesítéstípust.

Fejezze be a végpont beállítását, és válassza a Mentés lehetőséget.

A rendszer a végponthoz hozzáadja a felügyelt identitásokat úgy, hogy paramétereket ad hozzá a az dt endpoint create végpont létrehozásához használt parancshoz. (A parancsról további információt a referenciadokumentációban vagy az Azure Digital Twins-végpont létrehozásához szükséges általános utasításokban talál.)

Használja az alábbi CLI-parancsot a választott felügyelt identitástípushoz.

Rendszer által hozzárendelt identitásparancs

A rendszer által hozzárendelt hitelesítést használó végpont létrehozásához adja meg a IdentityBased hitelesítési típust a --auth-type paraméterrel. Az alábbi példa egy Event Hubs-végpont funkcióját szemlélteti.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --auth-type IdentityBased

Felhasználó által hozzárendelt identitásparancs

Felhasználó által hozzárendelt identitáshitelesítést használó végpont létrehozásához adja meg a felhasználó által hozzárendelt identitáserőforrás-azonosítót a --user paraméterrel. Az alábbi példa egy Event Hubs-végpont funkcióját szemlélteti.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --user <user-assigned-identity-resource-ID>

Megfontolandó szempontok a felügyelt identitások letiltására

Mivel az identitások kezelése külön történik az azt használó végpontoktól, fontos figyelembe venni, hogy az identitás vagy szerepköreinek változásai milyen hatással lehetnek az Azure Digital Twins-példány végpontjaira. Ha az identitás le van tiltva, vagy eltávolít egy végponthoz szükséges szerepkört, a végpont elérhetetlenné válhat, és az események folyamata megszakad.

Ha továbbra is használni kíván egy végpontot, amelynek a felügyelt identitása le lett tiltva, törölnie kell a végpontot, és ismét létre kell hoznia egy másik hitelesítési típussal. A módosítás után akár egy óra is eltelhet, mire újból megindul az események kézbesítése a végpont felé.

Végpontbeállítások: Holt betűs

Ha egy végpont egy adott időszakon belül nem tud eseményt kézbesíteni, vagy ha bizonyos számú alkalommal próbálja kézbesíteni az eseményt, a nem kézbesített eseményt elküldheti egy tárfiókba. Ezt a folyamatot holtbetűsnek nevezzük.

A szükséges tárolási erőforrásokat az Azure Portalon vagy az Azure Digital Twins parancssori felületén állíthatja be. Ha azonban engedélyezve van a holtbetűs végpont létrehozása, az Azure Digital Twins CLI-t vagy a vezérlősík API-jait kell használnia.

Ha többet szeretne megtudni a holtbetűsítésről, tekintse meg a végpontokat és az eseményútvonalakat. A végpont holt betűs beállításával kapcsolatos útmutatásért folytassa a szakasz további részében.

Tárolási erőforrások beállítása

A kézbesíthetetlen levelek helyének beállítása előtt rendelkeznie kell egy tárolóval rendelkező tárfiókkal az Azure-fiókjában.

A végpont későbbi létrehozásakor meg kell adnia a tároló URI-ját. A holtbetűs hely sas-jogkivonattal rendelkező tároló URI-ként lesz megadva a végpont számára. A jogkivonatnak engedélyre van szüksége write a tárfiókon belüli céltárolóhoz. A teljesen formázott SAS URI holt betű a következő formátumban lesz: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Az alábbi lépéseket követve állítsa be ezeket a tárolási erőforrásokat az Azure-fiókjában, hogy előkészítse a végpontkapcsolat beállítását a következő szakaszban.

Kövesse a Tárfiók létrehozása című témakörben leírt lépéseket egy tárfiók Azure-előfizetésben való létrehozásához. Jegyezze fel a tárfiók nevét, hogy később használhassa.
Az új tárfiókon belüli tároló létrehozásához kövesse a Tároló létrehozása című témakörben leírt lépéseket. Jegyezze fel a tároló nevét, hogy később használhassa.

SAS-jogkivonat létrehozása

Ezután hozzon létre egy SAS-jogkivonatot a tárfiókhoz, amelyet a végpont használhat a hozzáféréshez.

Portál
Parancssori felület

Első lépésként navigáljon a tárfiókhoz az Azure Portalon (a portál keresősávjával név szerint megtalálhatja).
A tárfiók lapján válassza a megosztott hozzáférésű jogosultságkód hivatkozását a bal oldali navigációs sávon az SAS-jogkivonat beállításának megkezdéséhez.
A Megosztott hozzáférés aláírása lapon, az Engedélyezett szolgáltatások és az Engedélyezett erőforrástípusok területen válassza ki a kívánt beállításokat. Minden kategóriában legalább egy mezőt ki kell jelölnie. Az Engedélyezett engedélyek területen válassza az Írás lehetőséget (igény szerint más engedélyeket is kiválaszthat).
Állítsa be a többi beállításhoz szükséges értékeket.
Ha végzett, válassza az SAS létrehozása és kapcsolati sztring gombot az SAS-jogkivonat létrehozásához.
Ha így tesz, több SAS- és kapcsolati sztring értéket hoz létre ugyanazon lap alján, a beállítási beállítások alatt. Görgessen le az értékek megtekintéséhez, és a Másolás vágólapra ikonnal másolja az SAS-jogkivonat értékét. Mentse a későbbi használatra.

Kérje le a tárfiók kulcsait az alábbi paranccsal, és másolja ki az egyik kulcs értékét:
```
az storage account keys list --account-name <storage-account-name>
```
Válasszon ki egy lejárati dátumot, és hozza létre a tárfiók SAS-jogkivonatát a következő paranccsal:
```
az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions w
```
Ennek a parancsnak a kimenete az SAS-jogkivonat. Másolja ki az SAS-jogkivonat értékét későbbi használatra.

Feljegyzés

Ez a parancs tartalmazza a "blob", "file", "queue" és "table" szolgáltatásokat; egy "object" erőforrástípust; és engedélyezi a "write" engedélyeket.

A parancsról és annak az storage account generate-sas paramétereiről az Azure CLI-referencia nyújt további információt.

A kézbesíthetetlen levelek végpontjának létrehozása

Portál
Parancssori felület

Ha olyan végpontot szeretne létrehozni, amely engedélyezve van a holt betűvel, a parancssori felület parancsait vagy vezérlősík API-jait kell használnia a végpont létrehozásához az Azure Portal helyett.

Az ilyen típusú végpont azure CLI-vel való létrehozásáról szóló útmutatásért váltson a szakasz PARANCSSOR lapjára.

Ha olyan végpontot szeretne létrehozni, amelyen engedélyezve van a holtbetűsítés, adja hozzá a --deadletter-sas-uri paramétert az az dt endpoint create parancshoz, amely létrehoz egy végpontot.

A paraméter értéke az előző szakaszban összegyűjtött tárfióknévből, tárolónévből és SAS-jogkivonatból álló SAS URI holt betű. Ez a paraméter kulcsalapú hitelesítéssel hozza létre a végpontot. Így néz ki a paraméter:

--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

Tipp.

Ha identitásalapú hitelesítéssel szeretne holtbetűs végpontot létrehozni, adja hozzá az ebből a szakaszból származó holtbetű paramétert és a megfelelő felügyelt identitásparamétert ugyanahhoz a parancshoz.

A parancssori felület helyett az Azure Digital Twins vezérlősík API-kkal is létrehozhat halottbetűvégpontokat. Ehhez tekintse meg a DigitalTwinsEndpoint dokumentációját , amelyből megtudhatja, hogyan strukturálhatja a kérést, és hogyan adhat hozzá halottbetűs paramétereket.

Üzenettároló séma

A kézbesítetlen levelek végpontjának beállítása után a rendszer a következő formátumban tárolja a kézbesítetlen üzeneteket a tárfiókban:

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

A kézbesítetlen üzenetek megegyeznek az eredeti esemény sémájának, amelyet az eredeti végpontra kívántak kézbesíteni.

Íme egy példa az ikerpéldány-létrehozási értesítés kézbesíthetetlen üzenetére:

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

Következő lépések

Ahhoz, hogy adatokat küldjön az Azure Digital Twinsből egy végpontnak, meg kell határoznia egy eseményútvonalat. Ezek az útvonalak lehetővé teszik a fejlesztők számára az eseményfolyamatok továbbítását a teljes rendszerben és az alsóbb rétegbeli szolgáltatásokban. Egyetlen útvonal több értesítés és eseménytípus kijelölését is lehetővé teheti. Folytassa az eseményútvonal létrehozását a végponthoz az Útvonalak és szűrők létrehozása területen.

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