Jak používat rozhraní API pro správu služby Azure Digital Twins

Důležité

Byla vydána nová verze služby Azure Digital Twins. Vzhledem k rozšířeným funkcím nové služby se původní služba Azure Digital Twins (popsaná v této sadě dokumentace) vyřadila z provozu.

Pokud chcete zobrazit dokumentaci k nové službě, navštivte aktivní dokumentaci ke službě Azure Digital Twins.

Rozhraní API pro správu Služby Azure Digital Twins poskytují výkonné funkce pro vaše aplikace IoT. V tomto článku se dozvíte, jak procházet strukturu rozhraní API.

Souhrn rozhraní API

Následující seznam ukazuje komponenty rozhraní API služby Digital Twins.

• /spaces: Tato rozhraní API komunikují s fyzickými umístěními ve vašem systému. Ty vám pomůžou vytvářet, odstraňovat a spravovat digitální mapování fyzických umístění ve formě prostorového grafu.

• /devices: Tato rozhraní API komunikují se zařízeními ve vaší konfiguraci. Tato zařízení můžou spravovat jeden nebo více senzorů. Například zařízení může být váš telefon, senzorový modul Raspberry Pi, brána Lora a tak dále.

• /sensors: Tato rozhraní API pomáhají komunikovat se snímači přidruženými k vašim zařízením a fyzickým umístěním. Senzory zaznamenávají a odesílají okolní hodnoty, které se pak dají použít k manipulaci s prostorovými prostředími.

• /resources: Tato rozhraní API vám pomůžou nastavit prostředky, jako je centrum IoT, pro vaši instanci služby Digital Twins.

• /types: Tato rozhraní API umožňují přidružit rozšířené typy k objektům Služby Digital Twins, abyste těmto objektům přidali specifické vlastnosti. Tyto typy umožňují snadné filtrování a seskupení objektů v uživatelském rozhraní a vlastní funkce, které zpracovávají vaše telemetrická data. Mezi příklady rozšířených typů patří DeviceType, SensorType, SensorDataType, SpaceType, SpaceSubType, SpaceBlobType, SpaceResourceType atd.

• /ontologie: Tato rozhraní API pomáhají spravovat ontologie, což jsou kolekce rozšířených typů. Ontologie poskytují názvy pro typy objektů podle fyzického prostoru, který představují. Například ontologie BACnet poskytuje konkrétní názvy pro typy snímačů, datové typy, datové typy, datové podtypy a typy dat. Ontologie se spravují a vytvářejí službou. Uživatelé mohou načíst a uvolnit ontologie. Při načtení ontologie jsou všechny jeho přidružené názvy typů povolené a připravené ke zřízení v prostorovém grafu.

• /propertyKeys: Pomocí těchto rozhraní API můžete vytvářet vlastní vlastnosti pro prostory, zařízení, uživatele a senzory. Tyto vlastnosti se vytvoří jako páry klíč/hodnota. Datový typ pro tyto vlastnosti můžete definovat nastavením jejich PrimitiveDataType. Můžete například definovat vlastnost s názvem BasicTemperatureDeltaProcessingRefreshTime typu uint pro vaše senzory a pak přiřadit hodnotu pro tuto vlastnost pro každou z vašich senzorů. Při vytváření vlastnosti, jako jsou minimální a maximální rozsahy, a také povolené hodnoty jako ValidationData, můžete také přidat omezení pro tyto hodnoty.

• /matchers: Tato rozhraní API umožňují určit podmínky, které chcete vyhodnotit z příchozích dat zařízení. Další informace najdete v tomto článku.

• /userDefinedFunctions: Tato rozhraní API umožňují vytvořit, odstranit nebo aktualizovat vlastní funkci, která se spustí, když dojde k podmínkám definovaným shodovači , aby zpracovávala data přicházející z vašeho nastavení. Další informace o těchto vlastních funkcích, označovaných také jako uživatelem definované funkce, najdete v tomto článku.

• /endpoints: Tato rozhraní API umožňují vytvářet koncové body, aby vaše řešení Digital Twins mohlo komunikovat s dalšími službami Azure pro ukládání a analýzu dat. Další informace najdete v tomto článku .

• /keyStores: Tato rozhraní API umožňují spravovat úložiště klíčů zabezpečení pro vaše prostory. Tato úložiště můžou obsahovat kolekci klíčů zabezpečení a umožňují snadno načíst nejnovější platné klíče.

• /users: Tato rozhraní API umožňují přidružit uživatele k vašim prostorům a vyhledat tyto osoby v případě potřeby.

• /system: Tato rozhraní API umožňují spravovat nastavení pro celý systém, jako jsou výchozí typy prostorů a senzorů.

• /roleAssignments: Tato rozhraní API umožňují přidružit role k entitám, jako je ID uživatele, ID uživatelem definované funkce atd. Každé přiřazení role zahrnuje ID entity, která se má přidružit, typ entity, ID role pro přidružení, ID tenanta a cestu, která definuje horní limit prostředku, ke kterému má entita přístup s tímto přidružením. Další informace najdete v tomto článku .

Navigace v rozhraní API

Rozhraní API služby Digital Twins podporují filtrování a navigaci v celém prostorovém grafu pomocí následujících parametrů:

• spaceId: Rozhraní API vyfiltruje výsledky podle zadaného ID prostoru. Kromě toho je logický příznak useParentSpace použitelný pro /spaces API, což znamená, že uvedené ID prostoru odkazuje na nadřazený prostor namísto aktuálního prostoru.

• minLevel a maxLevel: Kořenové mezery se považují za úroveň 1. Mezery, které mají nadřazený prostor na úrovni n, jsou na úrovni n+1. Pomocí těchto hodnot můžete filtrovat výsledky na konkrétních úrovních. Jedná se o inkluzivní hodnoty při nastavení. Zařízení, senzory a další objekty se považují za stejnou úroveň jako jejich nejbližší prostor. Pokud chcete získat všechny objekty na dané úrovni, nastavte minLevel i maxLevel na stejnou hodnotu.

• minRelative a maxRelative: Pokud jsou tyto filtry zadané, odpovídající úroveň je relativní k úrovni daného ID mezery:

  • Relativní úroveň 0 je stejná jako dané ID mezery.
  • Relativní úroveň 1 představuje prostory na stejné úrovni jako podřízené položky daného ID prostoru. Relativní úroveň n představuje mezery nižší než zadaná mezera na n úrovních.
  • Relativní úroveň -1 představuje mezery na stejné úrovni jako nadřazený prostor zadaného prostoru.

• procházení: Umožňuje procházet v obou směrech z daného ID prostoru, jak je určeno následujícími hodnotami.

  • Žádný: Tato výchozí hodnota filtruje pro dané ID prostoru.
  • Dolů: Filtruje podle daného ID prostoru a jeho potomků.
  • Nahoru: Tím se vyfiltruje dané ID prostoru a jeho nadřazené objekty.
  • Span: Tím se vyfiltruje vodorovná část prostorového grafu na stejné úrovni jako dané ID prostoru. To vyžaduje, aby hodnota minRelative nebo maxRelative byla nastavena na hodnotu true.

Příklady

Následující seznam ukazuje některé příklady navigace prostřednictvím rozhraní API /devices . Všimněte si, že zástupný symbol YOUR_MANAGEMENT_API_URL odkazuje na identifikátor URI rozhraní API služby Digital Twins ve formátu https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0/, kde YOUR_INSTANCE_NAME je název vaší instance služby Azure Digital Twins a YOUR_LOCATION je oblast, ve které je vaše instance hostovaná.

• YOUR_MANAGEMENT_API_URL/devices?maxLevel=1 vrátí všechna zařízení připojená k primárním prostorům.
• YOUR_MANAGEMENT_API_URL/devices?minLevel=2&maxLevel=4 vrátí všechna zařízení připojená k prostorům úrovně 2, 3 nebo 4.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId vrátí všechna zařízení přímo připojená k mySpaceId.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down vrátí všechna zařízení připojená k mySpaceId nebo některému z jejích potomků.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true vrátí všechna zařízení připojená k potomkům mySpaceId s výjimkou mySpaceId.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true&maxLevel=1&maxRelative=true vrátí všechna zařízení připojená k bezprostředním podřízeným položkám mySpaceId.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Up&maxLevel=-1&maxRelative=true vrátí všechna zařízení připojená k jednomu z předků mySpaceId.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&maxLevel=5 vrátí všechna zařízení připojená k potomkům mySpaceId, která jsou na úrovni menší nebo rovna 5.
• YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Span&minLevel=0&minRelative=true&maxLevel=0&maxRelative=true vrátí všechna zařízení připojená k prostorům, které se nacházejí na stejné úrovni jako mySpaceId.

Podpora OData

Většina rozhraní API, která vracejí kolekce, jako je volání GET pro /spaces, podporují následující podmnožinu obecných možností systémového dotazu OData :

• $filter
• $orderby
• $top
• $skip – Pokud máte v úmyslu zobrazit celou kolekci, měli byste si ji vyžádat jako celou sadu najednou během jediného volání a provést stránkování v aplikaci.

Poznámka:

Některé možnosti OData (například možnosti dotazu $count, $expand a $search) nejsou momentálně podporované.

Příklady

Následující seznam znázorňuje několik dotazů s platnou syntaxí OData:

• YOUR_MANAGEMENT_API_URL/devices?$top=3&$orderby=Name desc
• YOUR_MANAGEMENT_API_URL/keystores?$filter=endswith(Description,'space')
• YOUR_MANAGEMENT_API_URL/devices?$filter=TypeId eq 2
• YOUR_MANAGEMENT_API_URL/resources?$filter=StatusId ne 1
• YOUR_MANAGEMENT_API_URL/users?$top=4&$filter=endswith(LastName,'k')&$orderby=LastName
• YOUR_MANAGEMENT_API_URL/spaces?$orderby=Name desc&$top=3&$filter=substringof('Floor',Name)

Další kroky

Pokud se chcete seznámit s některými běžnými vzory dotazů rozhraní API, přečtěte si, jak dotazovat rozhraní API služby Azure Digital Twins pro běžné úlohy.

Další informace o koncových bodech rozhraní API najdete v tématu Použití služby Digital Twins Swagger.

Pokud chcete zkontrolovat syntaxi OData a dostupné relační operátory, přečtěte si relační operátory OData ve službě Azure Cognitive Search.