Tento prohlížeč se už nepodporuje.
Upgradujte na Microsoft Edge, abyste mohli využívat nejnovější funkce, aktualizace zabezpečení a technickou podporu.
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 buď použít přímo s přidruženými Swaggery, 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 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 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.
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.
Pokud chcete použít rozhraní API pro import úloh, musíte povolit nastavení oprávnění popsaná v této části.
Nejprve potřebujete spravovanou identitu přiřazenou systémem pro vaši instanci 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 musíte mít oprávnění k zápisu pro následující kategorie akcí dat:
Microsoft.DigitalTwins/jobs/*Microsoft.DigitalTwins/models/*, a Microsoft.DigitalTwins/digitaltwins/*/nebo Microsoft.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ů elementů je úspěšný pouze při importu modelů a dvojčat. Stav úlohy odráží selhání a zpráva indikuje, která oprávnění chybí.
Musíte také 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:
Nakonec vygenerujte nosný token, který můžete použít v požadavcích na rozhraní API úloh. Pokyny najdete v tématu Přidání nosné tokeny.
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 textu volání rozhraní API importu úloh použijete adresu URL úložiště objektů blob souboru NDJSON.
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.
Při práci s rozhraním API pro import úloh mějte na paměti následující skutečnosti:
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í:
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í časové období ú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. To je doba, po kterou se úloha odstranění spustí dříve, než vyprší časový limit, kdy se služba pokusí zastavit úlohu, pokud ještě nebyla dokončena.
Při práci s rozhraním API pro odstranění úloh mějte na paměti následující skutečnosti:
Tato část obsahuje podrobnější informace o používání rozhraní API a sad SDK.
Tady je několik obecných informací pro přímé volání rozhraní API služby Azure Digital Twins.
Tady je několik dalších informací o ověřování požadavků rozhraní API.
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.
DigitalTwinsClient třídy. Konstruktor vyžaduje přihlašovací údaje, které lze získat s různými druhy metod ověřování v Azure.Identity balíčku. Další informace Azure.Identitynajdete v dokumentaci k oboru názvů.InteractiveBrowserCredential Můž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é můžou být užitečné k ověřování funkcí Azure nastavených pomocí MSI v Azure Digital Twins. Další informace najdete v InteractiveBrowserCredentialdokumentaci ke své třídě.Tady je několik dalších informací o funkcích a vrácených datech.
DigitalTwinsClient .try a zachytit alespoň RequestFailedExceptions. Další informace o tomto typu výjimky najdete v referenční dokumentaci.Response<T> nebo (Task<Response<T>> pro asynchronní volání), kde T je třída návratového objektu pro volání služby.
Třída Response zapouzdřuje vrácenou službu a v poli Value zobrazí návratové hodnoty.Pageable<T> nebo AsyncPageable<T> jako výsledky. Další informace o třídě najdete v referenční dokumentaci. Další informace najdete AsyncPageable<T>v referenční dokumentaci.Pageable<T>await foreach . Další informace o tomto procesu najdete v tématu Iterace pomocí asynchronních výčtů v jazyce C# 8.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 komponentu Contents ve vlastnostech objektu BasicDigitalTwinBasicRelationship: 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.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.
Podívejte se, jak 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:
Školení
Postup výuky
Use advance techniques in canvas apps to perform custom updates and optimization - Training
Use advance techniques in canvas apps to perform custom updates and optimization
Certifikace
Microsoft Certified: Odborník pro vývojáře ve službě Azure Cosmos DB - Certifications
Vytvářejte efektivní dotazy, vytvářejte zásady indexování, spravujte a zřiďte prostředky v rozhraní SQL API a sadě SDK pomocí služby Microsoft Azure Cosmos DB.