Azure Digital Twins rozhraní API a sdk

  • Článek
  • 7 min ke čtení

Tento článek poskytuje přehled dostupných Azure Digital Twins rozhraní API a metody pro interakci s nimi. Rozhraní REST API můžete použít buď 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 sdk pro správu vaší instance a jejích prvků.

  • Rozhraní API řídicí roviny Azure Resource Manager rozhraní API (ARM) a pokrývají operace správy prostředků, jako je vytvoření a odstranění instance.
  • Rozhraní API roviny dat Azure Digital Twins rozhraní API a používají se pro operace správy dat, jako je správa modelů, dvojčat a grafu.
  • Tyto sdk využívají stávající rozhraní API, aby umožnily snadný vývoj vlastních aplikací, které využívají Azure Digital Twins. V rozhraní .NET (C#) a Javějsou k dispozici verze SDK řídicí roviny a v .NET (C#), Javě, JavaScriptua Pythonujsou k dispozici i tyto rovině dat.

Přehled: Rozhraní API řídicí roviny

Rozhraní API řídicí roviny jsou rozhraní ARM API, která slouží ke správě Azure Digital Twins instance jako celku, takže pokrývají operace, jako je vytvoření nebo odstranění celé instance. Tato rozhraní API použijete také k vytváření a odstraňování koncových bodů.

Nejnovější verzí rozhraní API roviny řízení je 2020-12-01.

Použití rozhraní API řídicí roviny:

Rozhraní API roviny řízení můžete také procvičit interakcí s Azure Digital Twins prostřednictvím rozhraní Azure Portal a rozhraní příkazového řádku.

Přehled: Rozhraní API roviny dat

Rozhraní API roviny dat jsou Azure Digital Twins API používaná ke správě prvků v rámci Azure Digital Twins instance. Zahrnují operace, jako je vytváření tras, nahrávání modelů, vytváření relací a správa dvojčat, a lze je obecně rozdělit do následujících kategorií:

  • DigitalTwinModels – Kategorie DigitalTwinModels obsahuje rozhraní API pro správu modelů v Azure Digital Twins instanci. Aktivity správy zahrnují nahrávání, ověřování, načítání a odstraňování modelů autorovaný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 Azure Digital Twins instanci.
  • Dotaz – kategorie Dotaz umožňuje vývojářům najít sady digitálních dvojčat v grafu dvojčat napříč relacemi.
  • Trasy událostí – Kategorie Trasy událostí obsahuje rozhraní API pro směrování dat,přes systém a do služeb pro příjem dat.

Nejnovější verze rozhraní API roviny dat je 2020-10-31.

Použití rozhraní API roviny dat:

Rozhraní API roviny dat můžete také procvičit interakcí s Azure Digital Twins prostřednictvím rozhraní příkazového řádku.

.NET (C#) SDK (rovina dat)

Sada Azure Digital Twins .NET (C#) SDK je součástí sady Azure SDK pro .NET. Je open source a je založená na rozhraních API Azure Digital Twins roviny dat.

Poznámka

Další informace o návrhu sady SDK najdete v obecných principech návrhu sad Azure SDK a v konkrétních pokynech pro návrh rozhraní .NET.

Pokud chcete tuto sadu SDK použít, NuGet do svého projektu balíček Azure.DigitalTwins.Core. Budete také potřebovat nejnovější verzi balíčku Azure.Identity. V Visual Studio můžete tyto balíčky přidat pomocí NuGet Správce balíčků (přístup k nim najdete v části Nástroje > NuGet Správce balíčků > Správa balíčků NuGet pro řešení). K přidání těchto balíčků do projektu můžete použít také nástroj příkazového řádku .NET s příkazy NuGet odkazy na balíček:

Podrobný návod k používání rozhraní API v praxi najdete v tématu Kód klientské aplikace.

Pomocná sestavení serializace

Pomocníki serializace jsou pomocná funkce, které jsou k dispozici v rámci sady SDK pro rychlé vytvoření nebo deserializaci dat dvojčete pro přístup k základní informace. Vzhledem k tomu, že základní metody sady SDK ve výchozím nastavení vrací data dvojčat ve formátu JSON, může být užitečné použít tyto třídy pomocné metody k dalšímu přerušení dat dvojčat.

K dispozici jsou tyto třídy pomocně:

  • BasicDigitalTwin: Obecně představuje základní data digitálního dvojčete.
  • BasicDigitalTwinComponent: Obecně představuje komponentu ve Contents vlastnostech objektu . BasicDigitalTwin
  • BasicRelationship: Obecně představuje základní data relace.
  • DigitalTwinsJsonPropertyName: Obsahuje řetězcové konstanty pro použití v serializaci a deserializaci JSON pro vlastní typy digitálních dvojčat.

Obecné poznámky k používání rozhraní API nebo sady SDK

Poznámka

Upozorňujeme, 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 části Sdílení prostředků mezi zdroji (CORS) tématu Koncepty: Zabezpečení pro Azure Digital Twins řešení.

Následující seznam obsahuje podrobnější a obecné pokyny pro používání rozhraní API a sdk.

  • Pomocí testovacího nástroje HTTP REST, jako je Postman, můžete provádět přímá volání rozhraní API Azure Digital Twins rozhraní API. Další informace o tomto procesu najdete v tématu Vytváření požadavků rozhraní API pomocí postman.
  • Pokud chcete použít sadu SDK, vytvořte instanci DigitalTwinsClient třídy . Konstruktor vyžaduje přihlašovací údaje, které lze získat pomocí různých druhů metod ověřování v Azure.Identity balíčku. Další informace o najdete Azure.Identity v dokumentaci k oboru názvů .
  • To 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é budete pravděpodobně používat k ověřování funkcí Azure nastavených pomocí MSI proti InteractiveBrowserCredential Azure Digital Twins. Další informace o najdete InteractiveBrowserCredential v dokumentaci třídy.
  • Požadavky na rozhraní AZURE DIGITAL TWINS API vyžadují uživatele nebo objekt služby, který je součástí stejného tenanta Azure Active Directory (Azure AD), ve kterém Azure Digital Twins instance služby. Aby se zabránilo škodlivé kontrole koncových Azure Digital Twins koncových bodů, vrátí se žádostem s přístupovými tokeny mimo původního tenanta chybová zpráva 404 Sub-Domain se nenašla. Tato chyba se vrátí i v případě, že uživateli nebo objektu služby byla prostřednictvím spolupráce Azure AD B2B Azure Digital Twins Data Owner nebo Azure Digital Twins Data Reader. Informace o tom, jak dosáhnout přístupu mezi více tenanty, najdete v tématu Psaní ověřovacího kódu aplikace.
  • Všechna volání rozhraní API služby jsou vystavena jako členské funkce ve DigitalTwinsClient třídě .
  • Všechny funkce služby existují v synchronních a asynchronních verzích.
  • Všechny funkce služby vyvracejí výjimku pro jakýkoli návratový stav 400 nebo vyšší. Nezapomeňte zabalit volání do oddílu a try zachytit alespoň RequestFailedExceptions . Další informace o tomto typu výjimky najdete v referenční dokumentaci.
  • Většina metod služby vrací nebo ( pro asynchronní volání), kde je třída návratového objektu Response<T> pro Task<Response<T>> volání T služby. Třída Response zapouzdřuje vrácenou službu a v poli prezentuje návratové Value hodnoty.
  • Metody služby se stránkované výsledky vrátí Pageable<T> nebo AsyncPageable<T> jako výsledky. Další informace o třídě najdete v referenční dokumentaci . Další informace o najdete Pageable<T> v její referenční AsyncPageable<T> dokumentaci.
  • Stránkované výsledky můžete iterovat pomocí await foreach smyčky . Další informace o tomto procesu najdete v příslušné dokumentaci.
  • Základní sada SDK je Azure.Core . Referenční informace o infrastruktuře a typech sady SDK najdete v dokumentaci k oboru názvů Azure.

Metody služby vracejí objekty silného typu, kdykoli je to možné. Protože je Azure Digital Twins založená na modelech, které uživatel nakonfiguroval za běhu (prostřednictvím modelů DTDL nahraných do služby), mnoho rozhraní API služeb přijímá a vrací data dvojčat ve formátu JSON.

Monitorování metrik rozhraní API

Metriky rozhraní API, jako jsou požadavky, latence a míra selhání, je možné zobrazit v Azure Portal.

Na domovské stránce portálu vyhledejte svou instanci Azure Digital Twins a stáhněte si její podrobnosti. V nabídce instance Azure Digital Twins možnost Metriky. Zobrazí se stránka Metriky.

Snímek obrazovky zobrazující stránku metrik pro Azure Digital Twins

Tady můžete zobrazit metriky pro vaši instanci a vytvořit vlastní zobrazení.

Další kroky

Podívejte se, jak provádět přímé požadavky na rozhraní API pomocí nástroje Postman:

Nebo si procvičte použití sady .NET SDK vytvořením klientské aplikace v tomto kurzu: