Rozhraní API služby Azure Digital Twins a sady SDK
Tento článek poskytuje přehled dostupných rozhraní API služby Azure Digital Twins a metod pro interakci s nimi. Rozhraní REST API můžete použít přímo s přidruženými Swaggery (prostřednictvím nástroje, jako je Postman), nebo prostřednictvím sady SDK.
Azure Digital Twins je vybavená rozhraními API řídicí roviny, rozhraními API roviny dat a sadami SDK pro správu instance a jejích prvků.
- Rozhraní API řídicí roviny jsou rozhraní API Azure Resource Manageru (ARM) a pokrývají operace správy prostředků, jako je vytvoření a odstranění vaší instance.
- Rozhraní API roviny dat jsou rozhraní API služby Azure Digital Twins a používají se pro operace správy dat, jako je správa modelů, dvojčat a graf.
- Sady SDK využívají stávající rozhraní API, aby bylo možné snadno vyvíjet vlastní aplikace využívající Službu Azure Digital Twins.
Rozhraní API řídicí roviny
Rozhraní API řídicí roviny jsou rozhraní API ARM, která slouží ke správě vaší instance Služby Azure Digital Twins jako celku, takže pokrývají operace, jako je vytvoření nebo odstranění celé instance. Tato rozhraní API také použijete k vytváření a odstraňování koncových bodů.
Pokud chcete rozhraní API volat přímo, odkazujte na nejnovější složku Swaggeru v úložišti Swagger řídicí roviny. Tato složka obsahuje také složku příkladů, které ukazují využití.
Tady jsou sady SDK, které jsou aktuálně k dispozici pro rozhraní API řídicí roviny služby Azure Digital Twins.
Rozhraní API řídicí roviny můžete také využít při interakci s Azure Digital Twins prostřednictvím webu Azure Portal a rozhraní příkazového řádku.
Rozhraní API roviny dat
Rozhraní API roviny dat jsou rozhraní API služby Azure Digital Twins, která slouží ke správě prvků v instanci služby Azure Digital Twins. Patří mezi ně operace, jako je vytváření tras, nahrávání modelů, vytváření relací a správa dvojčat, a dají se obecně rozdělit do následujících kategorií:
DigitalTwinModels– Kategorie DigitalTwinModels obsahuje rozhraní API pro správu modelů v instanci Azure Digital Twins. Aktivity správy zahrnují nahrávání, ověřování, načítání a odstraňování modelů vytvořených v DTDL.DigitalTwins– Kategorie DigitalTwins obsahuje rozhraní API, která vývojářům umožňují vytvářet, upravovat a odstraňovat digitální dvojčata a jejich vztahy v instanci Azure Digital Twins.Query– Kategorie Dotaz umožňuje vývojářům najít sady digitálních dvojčat v grafu dvojčat napříč relacemi.Event Routes– Kategorie Trasy událostí obsahuje rozhraní API pro směrování dat prostřednictvím systému a podřízených služeb.Import Jobs– Rozhraní API pro úlohy importu umožňuje spravovat dlouhotrvající asynchronní akci pro hromadný import modelů, dvojčat a relací.Delete Jobs– Rozhraní API pro odstranění úloh umožňuje spravovat dlouhotrvající asynchronní akci pro odstranění všech modelů, dvojčat a relací v instanci.
Pokud chcete rozhraní API volat přímo, odkazujte na nejnovější složku Swaggeru v úložišti Swagger roviny dat. Tato složka obsahuje také složku příkladů, které ukazují využití. Můžete si také prohlédnout referenční dokumentaci k rozhraní API roviny dat.
Tady jsou sady SDK, které jsou aktuálně k dispozici pro rozhraní API roviny dat Azure Digital Twins.
Rozhraní API roviny dat můžete také uplatnit pomocí interakce s Azure Digital Twins prostřednictvím rozhraní příkazového řádku.
Poznámky k používání a ověřování
Tato část obsahuje podrobnější informace o používání rozhraní API a sad SDK.
Poznámky k rozhraní API
Tady je několik obecných informací pro přímé volání rozhraní API služby Azure Digital Twins.
- Pomocí nástroje HTTP REST testing, jako je Postman, můžete provádět přímá volání rozhraní API služby Azure Digital Twins. Další informace o tomto procesu najdete v tématu Volání rozhraní API služby Azure Digital Twins pomocí nástroje Postman.
- Azure Digital Twins v současné době nepodporuje sdílení prostředků mezi zdroji (CORS). Další informace o strategiích dopadu a řešení najdete v tématu Sdílení prostředků mezi zdroji (CORS) pro Azure Digital Twins.
Tady je několik dalších informací o ověřování požadavků rozhraní API.
- Jedním ze způsobů, jak vygenerovat nosný token pro požadavky rozhraní API služby Azure Digital Twins, je příkaz az account get-access-token CLI. Podrobné pokyny najdete v tématu Získání nosné tokeny.
- Požadavky na rozhraní API služby Azure Digital Twins vyžadují uživatele nebo instanční objekt, který je součástí stejného tenanta Microsoft Entra ID , ve kterém existuje instance Azure Digital Twins. Aby se zabránilo škodlivé kontrole koncových bodů služby Azure Digital Twins, budou žádosti s přístupovými tokeny mimo původního tenanta vráceny chybovou zprávou "404 Sub-Domain not found" (Nenalezena poddoména 404). Tato chyba se vrátí i v případě, že uživateli nebo instančnímu objektu byla udělena role vlastníka dat Azure Digital Twins nebo role Čtenář dat Azure Digital Twins prostřednictvím spolupráce Microsoft Entra B2B . Informace o tom, jak dosáhnout přístupu napříč více tenanty, najdete v tématu Psaní ověřovacího kódu aplikace.
Poznámky k sadě SDK
Podkladová sada SDK pro Azure Digital Twins je Azure.Core. Referenční informace o infrastruktuře a typech sady SDK najdete v dokumentaci k oboru názvů Azure.
Tady je několik dalších informací o ověřování pomocí sad SDK.
- Začněte vytvořením instance
DigitalTwinsClienttřídy. Konstruktor vyžaduje přihlašovací údaje, které lze získat s různými druhy metod ověřování vAzure.Identitybalíčku. Další informaceAzure.Identitynajdete v dokumentaci k oboru názvů. InteractiveBrowserCredentialMůže být užitečné při zahájení práce, ale existuje několik dalších možností, včetně přihlašovacích údajů pro spravovanou identitu, které pravděpodobně použijete k ověření funkcí Azure nastavených pomocí MSI v Azure Digital Twins. Další informace najdete vInteractiveBrowserCredentialdokumentaci ke své třídě.
Tady je několik dalších informací o funkcích a vrácených datech.
- Všechna volání rozhraní API služby jsou ve třídě zpřístupněna jako členské funkce
DigitalTwinsClient. - Všechny funkce služby existují v synchronních a asynchronních verzích.
- Všechny funkce služby volají výjimku pro jakýkoli návratový stav 400 nebo vyšší. Nezapomeňte zabalit volání do oddílu
trya zachytit alespoňRequestFailedExceptions. Další informace o tomto typu výjimky najdete v referenční dokumentaci. - Většina metod služby vrací
Response<T>nebo (Task<Response<T>>pro asynchronní volání), kdeTje třída návratového objektu pro volání služby. Třída Response zapouzdřuje vrácenou službu a v poliValuezobrazí návratové hodnoty. - Metody služby s stránkovanými výsledky se vrátí
Pageable<T>neboAsyncPageable<T>jako výsledky. Další informace o třídě najdete v referenční dokumentaci. Další informace najdeteAsyncPageable<T>v referenční dokumentaci.Pageable<T> - Stránkované výsledky můžete iterovat pomocí smyčky
await foreach. Další informace o tomto procesu najdete v tématu Iterace pomocí asynchronních výčtů v jazyce C# 8. - Metody služby vracejí objekty silného typu, kdykoli je to možné. Vzhledem k tomu, že služba Azure Digital Twins je založená na modelech nakonfigurovaných uživatelem za běhu (prostřednictvím modelů DTDL nahraných do služby), mnoho rozhraní API služby bere a vrací data dvojčat ve formátu JSON.
Pomocné rutiny serializace v sadě .NET (C#) SDK
Pomocné rutiny serializace jsou pomocné funkce dostupné v sadě .NET (C#) SDK pro rychlé vytváření nebo deserializaci dat dvojčat pro přístup k základním informacím. Vzhledem k tomu, že základní metody sady SDK ve výchozím nastavení vracejí data dvojčat jako JSON, může být užitečné použít tyto pomocné třídy k dalšímu rozdělení dat dvojčete.
Dostupné pomocné třídy jsou:
BasicDigitalTwin: Obecně představuje základní data digitálního dvojčete.BasicDigitalTwinComponent: Obecně představuje komponentuContentsve vlastnostech objektuBasicDigitalTwinBasicRelationship: Obecně představuje základní data relace.DigitalTwinsJsonPropertyName: Obsahuje řetězcové konstanty pro použití v serializaci JSON a deserializaci pro vlastní typy digitálních dvojčat.
Hromadný import pomocí rozhraní API pro import úloh
Rozhraní API pro úlohy importu je rozhraní API roviny dat, které umožňuje importovat sadu modelů, dvojčat a relací v jednom volání rozhraní API. Operace rozhraní API pro úlohy importu jsou také součástí příkazů rozhraní příkazového řádku a sad SDK roviny dat. Použití rozhraní API pro úlohy importu vyžaduje použití služby Azure Blob Storage.
Ověření oprávnění
Pokud chcete použít rozhraní API pro import úloh, musíte povolit nastavení oprávnění popsaná v této části.
Nejprve budete potřebovat spravovanou identitu přiřazenou systémem pro vaši instanci Služby Azure Digital Twins. Pokyny k nastavení identity spravované systémem pro instanci najdete v tématu Povolení nebo zakázání spravované identity pro instanci.
V instanci Azure Digital Twins budete muset mít oprávnění k zápisu pro následující kategorie akcí dat:
Microsoft.DigitalTwins/jobs/*- Všechny prvky grafu, které chcete zahrnout do volání Úlohy. To může zahrnovat
Microsoft.DigitalTwins/models/*, aMicrosoft.DigitalTwins/digitaltwins/*/neboMicrosoft.DigitalTwins/digitaltwins/relationships/*.
Předdefinovaná role, která poskytuje všechna tato oprávnění, je vlastníkem dat Azure Digital Twins. Vlastní roli můžete použít také k udělení podrobného přístupu jenom k datovým typům, které potřebujete. Další informace o rolích ve službě Azure Digital Twins najdete v tématu Zabezpečení pro řešení Azure Digital Twins.
Poznámka:
Pokud se pokusíte o volání rozhraní API pro import úloh a chybí oprávnění k zápisu do některého z typů prvků grafu, které se pokoušíte importovat, úloha tento typ přeskočí a naimportuje ostatní. Pokud máte například přístup k zápisu k modelům a dvojčatům, ale ne k relacím, pokus o hromadný import všech tří typů elementu bude úspěšný pouze při importu modelů a dvojčat. Stav úlohy bude odrážet selhání a zpráva bude indikovat, která oprávnění chybí.
Také budete muset udělit následující oprávnění RBAC spravované identitě přiřazené systémem vaší instance Azure Digital Twins, aby mohl přistupovat ke vstupním a výstupním souborům v kontejneru Azure Blob Storage:
- Čtenář dat objektů blob služby Storage pro kontejner vstupních objektů blob služby Azure Storage
- Přispěvatel dat objektů blob úložiště pro výstupní kontejner objektů blob služby Azure Storage
Nakonec vygenerujte nosný token, který můžete použít v požadavcích na rozhraní API úloh. Pokyny najdete v tématu Získání nosné tokeny.
Formátování dat
Rozhraní API přijímá vstup s informacemi o grafu ze souboru NDJSON , který se musí nahrát do kontejneru úložiště objektů blob v Azure. Soubor začíná oddílem Header následovaným volitelnými oddíly Models, Twinsa Relationships. Do souboru nemusíte zahrnout všechny tři typy dat grafu, ale všechny oddíly, které jsou k dispozici, musí postupovat podle tohoto pořadí. Dvojčata a relace vytvořené pomocí tohoto rozhraní API můžou volitelně zahrnovat inicializaci jejich vlastností.
Tady je ukázkový vstupní datový soubor pro rozhraní API pro import:
{"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}
Tip
Ukázkový projekt, který převádí modely, dvojčata a relace na NDJSON podporované rozhraním API pro import, najdete v tématu Generátor hromadného importu NDJSON služby Azure Digital Twins. Ukázkový projekt je napsaný pro .NET a můžete si ho stáhnout nebo přizpůsobit, abyste mohli vytvářet vlastní soubory importu.
Po vytvoření souboru ho nahrajte do objektu blob bloku ve službě Azure Blob Storage pomocí preferované metody nahrání (některé možnosti jsou příkaz AzCopy, Azure CLI nebo Azure Portal). V těle volání rozhraní API importu úloh použijete adresu URL úložiště objektů blob souboru NDJSON.
Spuštění úlohy importu
Teď můžete pokračovat voláním rozhraní API pro import úloh. Podrobné pokyny k importu celého grafu v jednom volání rozhraní API najdete v tématu Hromadné nahrávání modelů, dvojčat a relací pomocí rozhraní API importu úloh. K nezávislému importu jednotlivých typů prostředků můžete také použít rozhraní API pro import úloh. Další informace o použití rozhraní API pro import úloh s jednotlivými typy prostředků najdete v pokynech k rozhraní API importu úloh pro modely, dvojčata a relace.
V těle volání rozhraní API zadáte adresu URL úložiště objektů blob vstupního souboru NDJSON. Zadáte také novou adresu URL úložiště objektů blob, která bude indikovat, kam se má výstupní protokol uložit, jakmile ji služba vytvoří.
Důležité
Ujistěte se, že spravovaná identita přiřazená systémem instance Azure Digital Twins má oprávnění RBAC objektu blob úložiště popsaná v části Kontrola oprávnění.
Při spuštění úlohy importu služba vygeneruje strukturovaný výstupní protokol a uloží se ve vašem kontejneru objektů blob jako nový doplňovací objekt blob v umístění adresy URL, které jste zadali pro výstupní objekt blob v požadavku. Tady je ukázkový výstupní protokol pro úspěšný import modelů, dvojčat a relací:
{"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"}}
Po dokončení úlohy uvidíte celkový počet přijatých entit pomocí metriky BulkOperationEntityCount.
Je také možné zrušit spuštěnou úlohu importu pomocí operace Zrušit z rozhraní API importu úloh. Jakmile je úloha zrušena a už není spuštěná, můžete ji odstranit.
Omezení a důležité informace
Při práci s rozhraním API pro import úloh mějte na paměti následující skutečnosti:
- Úlohy importu nejsou atomické operace. V případě selhání, částečného dokončení úlohy nebo použití operace Zrušení neexistuje vrácení zpět.
- V instanci Azure Digital Twins se podporuje jenom jedna hromadná úloha. Tyto informace a další číselné limity rozhraní API úloh můžete zobrazit v limitech služby Azure Digital Twins.
Hromadné odstranění pomocí rozhraní API pro odstranění úloh
Rozhraní API pro odstranění úloh je rozhraní API roviny dat, které umožňuje odstranit všechny modely, dvojčata a relace v instanci s jedním voláním rozhraní API. Operace rozhraní API pro odstranění úloh jsou také k dispozici jako příkazy rozhraní příkazového řádku. Navštivte dokumentaci k rozhraní API, kde najdete podrobnosti žádosti o vytvoření úlohy odstranění a kontrolu jejího stavu.
Pokud chcete zajistit odstranění všech prvků, při používání rozhraní API pro odstranění úloh postupujte podle těchto doporučení:
- Pokyny k vygenerování nosný token pro ověřování požadavků rozhraní API najdete v tématu Získání nosné tokenu.
- Pokud jste do grafu nedávno naimportovali velký počet entit, chvíli počkejte a před zahájením úlohy odstranění ověřte, že se všechny prvky v grafu synchronizují.
- Zastavte všechny operace v instanci, zejména operace nahrávání, dokud úloha odstranění nebude dokončena.
V závislosti na velikosti odstraněného grafu může úloha odstranění trvat od několika minut do několika hodin.
Výchozí období časového limitu úlohy odstranění je 12 hodin, které je možné upravit na libovolnou hodnotu mezi 15 minutami a 24 hodin pomocí parametru dotazu v rozhraní API. Doba, po kterou se úloha odstranění spustí, než vyprší časový limit, se služba pokusí zastavit úlohu, pokud ještě nebyla dokončena.
Omezení a další aspekty
Při práci s rozhraním API pro odstranění úloh mějte na paměti následující skutečnosti:
- Odstranit úlohy nejsou atomické operace. V případě selhání, částečného dokončení úlohy nebo vypršení časového limitu úlohy neexistuje vrácení zpět.
- V instanci Azure Digital Twins se podporuje jenom jedna hromadná úloha. Tyto informace a další číselné limity rozhraní API úloh můžete zobrazit v limitech služby Azure Digital Twins.
Monitorování metrik rozhraní API
Metriky rozhraní API, jako jsou požadavky, latence a míra selhání, se dají zobrazit na webu Azure Portal.
Informace o zobrazení a správě metrik Služby Azure Digital Twins najdete v tématu Monitorování vaší instance. Úplný seznam metrik rozhraní API dostupných pro Azure Digital Twins najdete v tématu Metriky požadavků rozhraní API služby Azure Digital Twins.
Další kroky
Zjistěte, jak pomocí Nástroje Postman provádět přímé požadavky na rozhraní API služby Azure Digital Twins:
Nebo si procvičte použití sady .NET SDK vytvořením klientské aplikace v tomto kurzu: