Azure Digital Twins API-k és SDK-k

Ez a cikk áttekintést nyújt a rendelkezésre álló Azure Digital Twins API-król és a velük való interakció módszereiről. Használhatja a REST API-kat közvetlenül a hozzájuk tartozó Swaggerekkel, vagy egy SDK-val.

Az Azure Digital Twins vezérlősík API-kkal, adatsík API-kkal és SDK-kkal rendelkezik a példány és elemei kezeléséhez.

• A vezérlősík API-k az Azure Resource Manager (ARM) API-k, és olyan erőforrás-kezelési műveleteket fednek le, mint a példány létrehozása és törlése.
• Az adatsík API-k Azure Digital Twins API-k, és olyan adatkezelési műveletekhez használhatók, mint a modellek, az ikerpéldányok és a gráfok kezelése.
• Az SDK-k kihasználják a meglévő API-kat, hogy megkönnyítsék az Azure Digital Twins használatát használó egyéni alkalmazások fejlesztését.

Vezérlősík áttekintése

A vezérlősík API-k az Azure Digital Twins-példány egészének kezelésére használt ARM API-k, így olyan műveleteket fednek le, mint a teljes példány létrehozása vagy törlése. Ezekkel az API-kkal végpontokat is létrehozhat és törölhet.

Az API-k közvetlen meghívásához hivatkozzon a Swagger vezérlősík adattárának legújabb Swagger mappájára. Ez a mappa egy példákat tartalmazó mappát is tartalmaz, amely a használatot mutatja.

Íme az Azure Digital Twins vezérlősík API-khoz jelenleg elérhető SDK-k.

A vezérlősík API-jait az Azure Digital Twins használatával is gyakorolhatja az Azure Portalon és a PARANCSSOR-on keresztül.

Adatsík áttekintése

Az adatsík API-k az Azure Digital Twins-példány elemeinek kezeléséhez használt Azure Digital Twins API-k. Ilyen műveletek például az útvonalak létrehozása, a modellek feltöltése, a kapcsolatok létrehozása és az ikerpéldányok kezelése, és széles körben a következő kategóriákba sorolhatók:

• DigitalTwinModels - A DigitalTwinModels kategória API-kat tartalmaz a modellek Azure Digital Twins-példányban való kezeléséhez. A felügyeleti tevékenységek közé tartozik a DTDL-ben létrehozott modellek feltöltése, érvényesítése, lekérése és törlése.
• DigitalTwins– A DigitalTwins kategória tartalmazza azokat az API-kat, amelyek lehetővé teszik a fejlesztők számára a digitális ikerpéldányok és azok kapcsolatainak létrehozását, módosítását és törlését egy Azure Digital Twins-példányban.
• Query – A Lekérdezés kategória lehetővé teszi a fejlesztők számára , hogy a kapcsolatok között digitális ikerpéldányokat találjanak az ikergráfban .
• Event Routes - Az Event Routes kategória api-kat tartalmaz az adatok a rendszeren és az alárendelt szolgáltatásokon keresztül történő átirányításához.
• Import Jobs– Az Import Jobs API lehetővé teszi egy hosszú ideig futó, aszinkron művelet kezelését modellek, ikerpéldányok és kapcsolatok tömeges importálásához.
• Delete Jobs– A Feladatok törlése API lehetővé teszi egy hosszú ideig futó, aszinkron művelet kezelését a példány összes modelljének, ikerpéldányának és kapcsolatának törléséhez.

Az API-k közvetlen meghívásához hivatkozzon a legújabb Swagger mappára az adatsík Swagger-adattárában. Ez a mappa egy példákat tartalmazó mappát is tartalmaz, amely a használatot mutatja. Megtekintheti az adatsík API referenciadokumentációját is.

Íme az Azure Digital Twins adatsík API-khoz jelenleg elérhető SDK-k.

Az adatsík API-jait az Azure Digital Twins parancssori felületén keresztül is használhatja.

Tömeges importálás a Feladatok importálása API-val

Az Import Jobs API egy adatsík API, amely lehetővé teszi modellek, ikerpéldányok és/vagy kapcsolatok importálását egyetlen API-hívásban. Az Importálási feladatok API-műveletek a CLI-parancsok és az adatsík SDK-k részét képezik. Az Import Jobs API használatához az Azure Blob Storage szükséges.

Engedélyek ellenőrzése

A Feladatok importálása API használatához engedélyeznie kell az ebben a szakaszban ismertetett engedélybeállításokat.

Először is szüksége lesz egy rendszer által hozzárendelt felügyelt identitásra az Azure Digital Twins-példányhoz. A példány rendszer által felügyelt identitásának beállítására vonatkozó utasításokat a példány felügyelt identitásának engedélyezése/letiltása című témakörben találja.

Írási engedélyekkel kell rendelkeznie az Azure Digital Twins-példányban a következő adatműveleti kategóriákhoz:

• Microsoft.DigitalTwins/jobs/*
• A Feladatok hívásba felvenni kívánt gráfelemek. Ilyen lehet például Microsoft.DigitalTwins/models/*a , Microsoft.DigitalTwins/digitaltwins/*és/vagy Microsoft.DigitalTwins/digitaltwins/relationships/*a .

Az összes engedélyt biztosító beépített szerepkör az Azure Digital Twins-adattulajdonos. Egyéni szerepkörrel részletes hozzáférést is biztosíthat csak a szükséges adattípusokhoz. Az Azure Digital Twins szerepköreivel kapcsolatos további információkért tekintse meg az Azure Digital Twins-megoldások biztonsági funkcióit.

A következő RBAC-engedélyeket is meg kell adnia az Azure Digital Twins-példány rendszer által hozzárendelt felügyelt identitásához, hogy hozzáférhessen az Azure Blob Storage-tároló bemeneti és kimeneti fájljaihoz:

• Storage Blob Data Reader az Azure Storage bemeneti blobtárolóhoz
• Storage Blob Data Közreműködő az Azure Storage kimeneti blobtárolóhoz

Végül hozzon létre egy tulajdonosi jogkivonatot, amely használható a Jobs API-ra irányuló kérelmekben. Útmutatásért lásd: Tulajdonosi jogkivonat hozzáadása.

Adatformázás

Az API gráfinformációs bemenetet fogad egy NDJSON-fájlból , amelyet fel kell tölteni egy Azure Blob Storage-tárolóba . A fájl egy Header szakaszsal kezdődik, majd a választható szakaszokModelsTwins, majd Relationshipsa . Nem kell mindhárom gráfadatot belefoglalnia a fájlba, de a jelen lévő szakaszoknak ezt a sorrendet kell követniük. Az API-val létrehozott ikerpéldányok és kapcsolatok opcionálisan magukban foglalhatják a tulajdonságaik inicializálását.

Íme egy minta bemeneti adatfájl az importálási API-hoz:

{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}

A fájl létrehozása után töltse fel egy blokkblobba az Azure Blob Storage-ban az előnyben részesített feltöltési módszerrel (néhány lehetőség az AzCopy parancs, az Azure CLI vagy az Azure Portal). Az NDJSON-fájl blobtároló URL-címét használja az Import Jobs API-hívás törzsében.

Az importálási feladat futtatása

Most folytathatja az Importálási feladatok API meghívását. A teljes gráf egyetlen API-hívásban való importálásával kapcsolatos részletes útmutatásért lásd : Modellek, ikerpéldányok és kapcsolatok tömeges feltöltése az Import Jobs API-val. A Feladatok importálása API-val egymástól függetlenül importálhatja az egyes erőforrástípusokat. A Feladatok importálása API egyéni erőforrástípusokkal való használatáról a Modellek, ikerpéldányok és kapcsolatok importálása API-utasítások című témakörben talál további információt.

Az API-hívás törzsében adja meg az NDJSON bemeneti fájl blobtároló URL-címét. Egy új blobtároló URL-címét is megadhatja, amely jelzi, hogy hol szeretné tárolni a kimeneti naplót a szolgáltatás létrehozása után.

Az importálási feladat végrehajtásakor a szolgáltatás létrehoz egy strukturált kimeneti naplót, amelyet új hozzáfűző blobként tárol a blobtárolóban, a kérelem kimeneti blobjához megadott URL-címen. Íme egy példa kimeneti napló a modellek, ikerpéldányok és kapcsolatok sikeres importálásához:

{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}

Ha a feladat befejeződött, a BulkOperationEntityCount metrika használatával láthatja a betöltött entitások teljes számát.

A futó importálási feladatokat az Importálási feladatok API Mégse műveletével is megszakíthatja. Miután a feladat megszakadt, és már nem fut, törölheti azt.

Korlátok és szempontok

Tartsa szem előtt az alábbi szempontokat az Import Jobs API használata során:

• Az importálási feladatok nem atomi műveletek. Hiba, részleges feladatvégzítés vagy a Mégse művelet használata esetén nincs visszaállítás.
• Egyszerre csak egy tömeges feladat támogatott egy Azure Digital Twins-példányon belül. Ezeket az információkat és a Feladatok API-k egyéb numerikus korlátait az Azure Digital Twins korlátai között tekintheti meg.

Tömeges törlés a Feladatok törlése API-val

A Feladatok törlése API egy adatsík API, amely lehetővé teszi az összes modell, ikerpéldány és kapcsolat törlését egyetlen API-hívással rendelkező példányban. A Delete Jobs API-műveletek parancssori felületi parancsként is elérhetők. A törlési feladat létrehozásához és állapotának ellenőrzéséhez tekintse meg az API dokumentációját.

Az összes elem törléséhez kövesse az alábbi javaslatokat a Feladatok törlése API használata során:

• Az API-kérések hitelesítéséhez szükséges tulajdonosi jogkivonatok létrehozására vonatkozó utasításokért lásd : Tulajdonosi jogkivonat hozzáadása.
• Ha a közelmúltban nagy számú entitást importált a gráfba, várjon egy ideig, és ellenőrizze, hogy a gráf minden eleme szinkronizálva van-e a törlési feladat megkezdése előtt.
• Állítsa le az összes műveletet a példányon, különösen a feltöltési műveleteket, amíg a törlési feladat be nem fejeződik.

A törölni kívánt gráf méretétől függően a törlési feladat akár néhány perctől akár több óráig is eltarthat.

A törlési feladatok alapértelmezett időtúllépési időtartama 12 óra, amely bármely 15 perc és 24 óra közötti értékre módosítható az API lekérdezési paraméterével. Ez az az idő, amíg a törlési feladat lefut, mielőtt túllépi az időkorlátot. Ekkor a szolgáltatás megpróbálja leállítani a feladatot, ha még nem fejeződött be.

Korlátok és egyéb szempontok

Tartsa szem előtt az alábbi szempontokat a Feladatok törlése API használata során:

• A törlési feladatok nem atomi műveletek. Hiba, részleges feladatvégzítés vagy a feladat időtúllépése esetén nincs visszaállítás.
• Egyszerre csak egy tömeges feladat támogatott egy Azure Digital Twins-példányon belül. Ezeket az információkat és a Feladatok API-k egyéb numerikus korlátait az Azure Digital Twins korlátai között tekintheti meg.

Használati és hitelesítési megjegyzések

Ez a szakasz részletesebb információkat tartalmaz az API-k és az SDK-k használatáról.

API-megjegyzések

Íme néhány általános információ az Azure Digital Twins API-k közvetlen meghívásáról.

• HTTP REST-teszteszköz használatával közvetlen hívásokat kezdeményezhet az Azure Digital Twins API-khoz. A folyamatról további információt az Azure Digital Twins API-k meghívása című témakörben talál.
• Az Azure Digital Twins jelenleg nem támogatja a forrásközi erőforrás-megosztást (CORS). A hatás- és megoldási stratégiákról további információt az Azure Digital Twins forrásközi erőforrás-megosztási (CORS) című témakörében talál.

Íme néhány további információ az API-kérések hitelesítéséről.

• Az Azure Digital Twins API-kérések tulajdonosi jogkivonatának létrehozásának egyik módja az az account get-access-token CLI parancs. Részletes útmutatásért lásd : Tulajdonosi jogkivonat hozzáadása.
• Az Azure Digital Twins API-khoz irányuló kérelmekhez olyan felhasználóra vagy szolgáltatásnévre van szükség, amely ugyanahhoz a Microsoft Entra ID-bérlőhöz tartozik, ahol az Azure Digital Twins-példány létezik. Az Azure Digital Twins-végpontok rosszindulatú vizsgálatának megakadályozása érdekében a rendszer "404 altartomány nem található" hibaüzenetet ad vissza az eredeti bérlőn kívüli hozzáférési jogkivonatokkal. Ez a hiba akkor is megjelenik, ha a felhasználó vagy a szolgáltatásnév Azure Digital Twins-adattulajdonosi vagy Azure Digital Twins-adatolvasói szerepkört kapott a Microsoft Entra B2B együttműködésével. További információ arról, hogyan érheti el a hozzáférést több bérlő között: Alkalmazáshitelesítési kód írása.

SDK-jegyzetek

Az Azure Digital Twins mögöttes SDK-ja a Azure.Core. Az SDK-infrastruktúrára és -típusokra vonatkozó hivatkozásért tekintse meg az Azure-névtér dokumentációját.

Íme néhány további információ az SDK-kkal való hitelesítésről.

• Kezdje az DigitalTwinsClient osztály példányosításával. A konstruktorhoz olyan hitelesítő adatok szükségesek, amelyek a csomag különböző hitelesítési módszereivel Azure.Identity kérhetők le. További információkért Azure.Identitytekintse meg a névtér dokumentációját.
• Az első lépések során hasznos lehetInteractiveBrowserCredential, de számos egyéb lehetőség is rendelkezésre áll, például a felügyelt identitás hitelesítő adatai, amelyek hasznosak lehetnek az MSI-vel beállított Azure-függvények Azure Digital Twins-hez való hitelesítéséhez. További információInteractiveBrowserCredential: osztálydokumentáció.

Íme néhány további információ a függvényekről és a visszaadott adatokról.

• Minden service API-hívás tagfüggvényként jelenik meg az DigitalTwinsClient osztályban.
• Minden szolgáltatásfüggvény szinkron és aszinkron verziókban létezik.
• Minden szolgáltatásfüggvény kivételt okoz a 400-ás vagy újabb visszatérési állapotok esetében. Győződjön meg arról, hogy a hívásokat egy try szakaszba csomagolja, és legalább RequestFailedExceptionselkapja. Az ilyen típusú kivételről további információt a referenciadokumentációban talál.
• A legtöbb szolgáltatásmetódus visszaadja Response<T> vagy (Task<Response<T>> az aszinkron hívások esetében) a T szolgáltatáshívás visszatérési objektumának osztályát. A Válasz osztály beágyazza a szolgáltatás visszatérését, és visszaadott értékeket jelenít meg a Value mezőjében.
• A lapszámozott eredményekkel rendelkező szolgáltatásmódszerek eredményként vagy AsyncPageable<T> eredményként adnak visszaPageable<T>. Az osztályról további információt a Pageable<T> referenciadokumentációjában talál. További információt AsyncPageable<T>a referenciadokumentációjában talál.
• A lapozott eredmények ismétlése hurok await foreach használatával történik. Erről a folyamatról a C# 8 Async Enumerables iterating with Async Enumerables (Async Enumerables) című szakaszában olvashat bővebben.
• A szolgáltatásmetódusok ahol csak lehetséges, erősen gépelt objektumokat ad vissza. Mivel azonban az Azure Digital Twins a felhasználó által a futásidőben egyénileg konfigurált modelleken alapul (a szolgáltatásba feltöltött DTDL-modelleken keresztül), számos szolgáltatás API JSON formátumban fogad és ad vissza ikeradatokat.

Szerializálási segédek a .NET (C#) SDK-ban

A szerializálási segédek a .NET (C#) SDK-n belül elérhető segédfüggvények, amelyekkel gyorsan létrehozhat vagy deszerializálhat ikeradatokat az alapvető információkhoz való hozzáférés érdekében. Mivel az alapvető SDK-metódusok alapértelmezés szerint JSON-ként adnak vissza ikeradatokat, hasznos lehet ezen segédosztályokkal tovább bontani az ikeradatokat.

A rendelkezésre álló segédosztályok a következők:

• BasicDigitalTwin: Általánosan egy digitális ikerpéldány alapadatait jelöli
• BasicDigitalTwinComponent: Általánosan egy összetevőt jelöl egy Contents adott elem tulajdonságaiban BasicDigitalTwin
• BasicRelationship: Általánosan egy kapcsolat alapadatait jelöli
• DigitalTwinsJsonPropertyName: Az egyéni digitális ikerpéldányok JSON-szerializálásához és deszerializálásához használható sztringállandókat tartalmazza

API-metrikák monitorozása

Az API-metrikákat, például a kéréseket, a késést és a hibaarányt az Azure Portalon tekintheti meg.

Az Azure Digital Twins-metrikák megtekintésével és kezelésével kapcsolatos információkért tekintse meg a példány monitorozását ismertető témakört. Az Azure Digital Twinshez elérhető API-metrikák teljes listájáért tekintse meg az Azure Digital Twins API kérésmetrikáit.

Következő lépések

Megtudhatja, hogyan kérhet közvetlen kéréseket az Azure Digital Twins API-khoz:

• Az Azure Digital Twins API-k meghívása

Vagy gyakorolja a .NET SDK használatát egy ügyfélalkalmazás létrehozásával az alábbi oktatóanyaggal:

• Ügyfélalkalmazás kódolása