Azure Digital Twins API-k és SDK-k

  • Cikk

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 (egy olyan eszközzel, mint a Postman), 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 API-k

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.

SDK language Csomaghivatkozás Reference documentation Forráskód
.NET (C#) Azure.ResourceManager.DigitalTwins a NuGeten Referencia a .NET-hez készült Azure DigitalTwins SDK-hoz A Microsoft Azure Digital Twins felügyeleti ügyféloldali kódtára a GitHubon futó .NET-hez
Java azure-resourcemanager-digitaltwins a Mavenen Referencia erőforrás-kezeléshez – Digital Twins Azure Resource Manager AzureDigitalTwins Java-ügyfélkódtár a GitHubon
JavaScript AzureDigitalTwinsManagement ügyfélkódtár JavaScripthez npm-en AzureDigitalTwinsManagement ügyfélkódtár JavaScripthez a GitHubon
Python azure-mgmt-digitaltwins a PyPI-n Microsoft Azure SDK for Python a GitHubon
Go azure-sdk-for-go/services/digitaltwins/mgmt Azure SDK for Go a GitHubon

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 API-k

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:

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.

SDK language Csomaghivatkozás Reference documentation Forráskód
.NET (C#) Azure.DigitalTwins.Core a NuGeten Referencia a .NET-hez készült Azure IoT Digital Twins ügyfélkódtárhoz Azure IoT Digital Twins ügyfélkódtár a GitHubon futó .NET-hez
Java com.azure:azure-digitaltwins-core on Maven Referencia a Java-hoz készült Azure Digital Twins SDK-hoz Azure IoT Digital Twins-ügyfélkódtár Java-hoz a GitHubon
JavaScript Azure Digital Twins Core-ügyfélkódtár JavaScripthez npm-en Reference for @azure/digital-twins-core Azure Digital Twins Core-ügyfélkódtár JavaScripthez a GitHubon
Python Azure Digital Twins Core ügyfélkódtár Pythonhoz a PyPI-n Az azure-digitaltwins-core referenciája Azure Digital Twins Core ügyfélkódtár Pythonhoz a GitHubon

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

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.

  • Egy HTTP REST-tesztelési eszköz, például a Postman 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 a Postmannel 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 lekérése.
  • 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 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, amelyeket valószínűleg az MSI-vel beállított Azure-függvények hitelesítésére fog használni az Azure Digital Twinsben. 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

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

Az Import Jobs 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.

Megjegyzés:

Ha megkísérl egy Importálási feladatok API-hívást, és hiányzik az importálásra használt gráfelem-típusok egyikének írási engedélye, a feladat kihagyja ezt a típust, és importálja a többit. Ha például írási hozzáféréssel rendelkezik a modellekhez és az ikerpéldányokhoz, de kapcsolatok nem, a három elem tömeges importálására tett kísérlet csak a modellek és az ikerpéldányok importálását fogja sikerülni. A feladat állapota hibát jelez, és az üzenet jelzi, hogy mely engedélyek hiányoznak.

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:

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 lekérése.

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}

Tipp.

A modelleket, ikerpéldányokat és kapcsolatokat az importálási API által támogatott NDJSON-ra konvertáló mintaprojektért lásd : Azure Digital Twins Bulk Import NDJSON Generator. A mintaprojekt a .NET-hez készült, és letölthető vagy módosítható, hogy segítsen saját importálási fájlok létrehozásában.

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 Importálási feladatok API-hívás törzsében az NDJSON-fájl blobtároló URL-címét fogja használni.

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 meg kell adnia az NDJSON bemeneti fájl blobtároló URL-címét. Egy új blobtároló URL-címét is meg kell adnia, amely jelzi, hogy hol szeretné tárolni a kimeneti naplót a szolgáltatás létrehozása után.

Fontos

Győződjön meg arról, hogy az Azure Digital Twins-példány rendszer által hozzárendelt felügyelt identitása rendelkezik az Engedélyek ellenőrzése szakaszban leírt tárblob RBAC-engedélyekkel.

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 beszerzése.
  • 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 megkísérli 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.

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.

További lépések

Megtudhatja, hogyan kérhet közvetlen kéréseket az Azure Digital Twins API-khoz a Postman használatával:

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