Udostępnij za pośrednictwem

Jak używać interfejsów API zarządzania usługi Azure Digital Twins

  • Artykuł

Ważne

Wydano nową wersję usługi Azure Digital Twins. W świetle rozszerzonych możliwości nowej usługi oryginalna usługa Azure Digital Twins (opisana w tym zestawie dokumentacji) została wycofana.

Aby wyświetlić dokumentację nowej usługi, odwiedź aktywną dokumentację usługi Azure Digital Twins.

Interfejsy API zarządzania usługą Azure Digital Twins zapewniają zaawansowane funkcje dla aplikacji IoT. W tym artykule pokazano, jak nawigować po strukturze interfejsu API.

Podsumowanie interfejsu API

Na poniższej liście przedstawiono składniki interfejsów API usługi Digital Twins.

  • /spaces: te interfejsy API współdziałają z lokalizacjami fizycznymi w konfiguracji. Pomagają one tworzyć, usuwać i zarządzać mapowaniami cyfrowymi lokalizacji fizycznych w postaci grafu przestrzennego.

  • /devices: te interfejsy API współdziałają z urządzeniami w konfiguracji. Te urządzenia mogą zarządzać co najmniej jednym czujnikiem. Na przykład urządzenie może być telefonem lub zasobnikem czujnika Raspberry Pi lub bramą Lora itd.

  • /sensors: te interfejsy API ułatwiają komunikację z czujnikami skojarzonymi z urządzeniami i lokalizacjami fizycznymi. Czujniki rejestrują i wysyłają wartości otoczenia, których następnie można użyć do manipulowania środowiskiem przestrzennym.

  • /resources: te interfejsy API ułatwiają konfigurowanie zasobów, takich jak centrum IoT, dla wystąpienia usługi Digital Twins.

  • /types: Te interfejsy API umożliwiają kojarzenie typów rozszerzonych z obiektami usługi Digital Twins w celu dodania określonych cech do tych obiektów. Te typy umożliwiają łatwe filtrowanie i grupowanie obiektów w interfejsie użytkownika oraz funkcji niestandardowych, które przetwarzają dane telemetryczne. Przykłady typów rozszerzonych to DeviceType, SensorType, SensorDataType, SpaceType, SpaceSubType, SpaceBlobType, SpaceResourceType itd.

  • /ontologies: te interfejsy API ułatwiają zarządzanie dziennikami, które są kolekcjami typów rozszerzonych. Nalogie zawierają nazwy typów obiektów zgodnie z przestrzenią fizyczną, którą reprezentują. Na przykład ontologia BACnet zawiera określone nazwy typów czujników, typówdanych, typów danych, podtypów danych i typów danych. Dzienniki są zarządzane i tworzone przez usługę. Użytkownicy mogą ładować i zwalniać dzienniki. Po załadowaniu ontologii wszystkie skojarzone nazwy typów są włączone i gotowe do aprowizacji na wykresie przestrzennym.

  • /propertyKeys: możesz użyć tych interfejsów API do tworzenia niestandardowych właściwości dla przestrzeni, urządzeń, użytkowników i czujników. Te właściwości są tworzone jako pary klucz/wartość. Typ danych dla tych właściwości można zdefiniować, ustawiając typ danych PrimitiveDataType. Można na przykład zdefiniować właściwość o nazwie BasicTemperatureDeltaProcessingRefreshTime typu uint dla czujników, a następnie przypisać wartość dla tej właściwości dla każdego z czujników. Można również dodać ograniczenia dla tych wartości podczas tworzenia właściwości, takiej jak zakresy Min i Max , a także dozwolone wartości jako ValidationData.

  • /matchers: te interfejsy API umożliwiają określenie warunków, które mają zostać ocenione z danych przychodzących urządzeń. Więcej informacji zawiera ten artykuł.

  • /userDefinedFunctions: te interfejsy API umożliwiają tworzenie, usuwanie lub aktualizowanie funkcji niestandardowej, która będzie wykonywana po wystąpieniu warunków zdefiniowanych przez matchers w celu przetwarzania danych pochodzących z konfiguracji. Zobacz ten artykuł , aby uzyskać więcej informacji na temat tych funkcji niestandardowych, nazywanych również funkcjami zdefiniowanymi przez użytkownika.

  • /endpoints: te interfejsy API umożliwiają tworzenie punktów końcowych, dzięki czemu rozwiązanie Digital Twins może komunikować się z innymi usługami platformy Azure na potrzeby magazynowania i analizy danych. Przeczytaj ten artykuł , aby uzyskać więcej informacji.

  • /keyStores: te interfejsy API umożliwiają zarządzanie magazynami kluczy zabezpieczeń dla przestrzeni. Te magazyny mogą przechowywać kolekcję kluczy zabezpieczeń i umożliwiają łatwe pobieranie najnowszych prawidłowych kluczy.

  • /users: te interfejsy API umożliwiają kojarzenie użytkowników z przestrzeniami w celu zlokalizowania tych osób w razie potrzeby.

  • /system: Te interfejsy API umożliwiają zarządzanie ustawieniami całego systemu, takimi jak domyślne typy spacji i czujników.

  • /roleAssignments: te interfejsy API umożliwiają kojarzenie ról z jednostkami, takimi jak identyfikator użytkownika, identyfikator funkcji zdefiniowanej przez użytkownika itp. Każde przypisanie roli zawiera identyfikator jednostki do skojarzenia, typ jednostki, identyfikator roli do skojarzenia, identyfikator dzierżawy i ścieżkę definiującą górny limit zasobu, do którego jednostka może uzyskiwać dostęp za pomocą tego skojarzenia. Przeczytaj ten artykuł , aby uzyskać więcej informacji.

Nawigacja interfejsu API

Interfejsy API usługi Digital Twins obsługują filtrowanie i nawigację na wykresie przestrzennym przy użyciu następujących parametrów:

  • spaceId: interfejs API będzie filtrować wyniki według podanego identyfikatora miejsca. Ponadto flaga logiczna useParentSpace ma zastosowanie do interfejsów API /spaces , co wskazuje, że dany identyfikator przestrzeni odwołuje się do przestrzeni nadrzędnej zamiast bieżącego miejsca.

  • minLevel i maxLevel: Przestrzenie główne są uważane za poziom 1. Spacje z spacją nadrzędną na poziomie n są na poziomie n+1. Za pomocą tych wartości można filtrować wyniki na określonych poziomach. Są to wartości inkluzywne po ustawieniu. Urządzenia, czujniki i inne obiekty są uważane za na tym samym poziomie co ich najbliższa przestrzeń. Aby uzyskać wszystkie obiekty na danym poziomie, ustaw wartość minLevel i maxLevel na tę samą wartość.

  • minRelative i maxRelative: po podaniu tych filtrów odpowiedni poziom jest względny do poziomu podanego identyfikatora miejsca:

    • Poziom względny 0 jest taki sam jak podany identyfikator miejsca.
    • Poziom względny 1 reprezentuje spacje na tym samym poziomie co elementy podrzędne danego identyfikatora przestrzeni. Poziom względny n reprezentuje spacje niższe niż określona przestrzeń według n poziomów.
    • Poziom względny -1 reprezentuje spacje na tym samym poziomie co przestrzeń nadrzędna określonego miejsca.

  • przechodzenie: umożliwia przechodzenie w obu kierunkach z danego identyfikatora przestrzeni zgodnie z następującymi wartościami.

    • Brak: ta wartość domyślna filtruje do danego identyfikatora miejsca.
    • W dół: powoduje to filtrowanie według podanego identyfikatora przestrzeni i jego elementów podrzędnych.
    • W górę: to filtruje według podanego identyfikatora przestrzeni i jego elementów nadrzędnych.
    • Zakres: Powoduje to filtrowanie poziomej części grafu przestrzennego na tym samym poziomie co dany identyfikator przestrzeni. Wymaga to wartości minRelative lub maxRelative , aby ustawić wartość true.

Przykłady

Na poniższej liście przedstawiono kilka przykładów nawigacji za pośrednictwem interfejsów API /devices . Należy pamiętać, że symbol zastępczy YOUR_MANAGEMENT_API_URL odwołuje się do identyfikatora URI interfejsów API usługi Digital Twins w formacie https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0/, gdzie YOUR_INSTANCE_NAME jest nazwą wystąpienia usługi Azure Digital Twins i YOUR_LOCATION regionem, w którym jest hostowane wystąpienie.

  • YOUR_MANAGEMENT_API_URL/devices?maxLevel=1 zwraca wszystkie urządzenia dołączone do przestrzeni głównych.
  • YOUR_MANAGEMENT_API_URL/devices?minLevel=2&maxLevel=4 Zwraca wszystkie urządzenia dołączone do spacji poziomów 2, 3 lub 4.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId zwraca wszystkie urządzenia bezpośrednio dołączone do identyfikatora mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down zwraca wszystkie urządzenia dołączone do identyfikatora mySpaceId lub jednego z jego elementów podrzędnych.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true zwraca wszystkie urządzenia dołączone do elementów podrzędnych mySpaceId z wyłączeniem identyfikatora mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true&maxLevel=1&maxRelative=true zwraca wszystkie urządzenia dołączone do natychmiastowych elementów podrzędnych mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Up&maxLevel=-1&maxRelative=true zwraca wszystkie urządzenia dołączone do jednego z elementów głównych mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&maxLevel=5 zwraca wszystkie urządzenia dołączone do elementów podrzędnych mySpaceId, które są na poziomie mniejszym lub równym 5.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Span&minLevel=0&minRelative=true&maxLevel=0&maxRelative=true zwraca wszystkie urządzenia dołączone do spacji, które znajdują się na tym samym poziomie co mySpaceId.

Obsługa OData

Większość interfejsów API, które zwracają kolekcje, takie jak wywołanie GET /spaces, obsługuje następujący podzestaw ogólnych opcji zapytania systemu OData :

  • $filter
  • $orderby
  • $top
  • $skip — jeśli zamierzasz wyświetlić całą kolekcję, należy zażądać jej jako całego zestawu w jednym wywołaniu, a następnie wykonać stronicowanie w aplikacji.

Uwaga

Niektóre opcje OData (takie jak opcje zapytań $count, $expand i $search) nie są obecnie obsługiwane.

Przykłady

Poniższa lista przedstawia kilka zapytań z prawidłową składnią 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)

Następne kroki

Aby dowiedzieć się więcej o typowych wzorcach zapytań interfejsu API, przeczytaj Artykuł Jak wykonywać zapytania dotyczące interfejsów API usługi Azure Digital Twins pod kątem typowych zadań.

Aby dowiedzieć się więcej na temat punktów końcowych interfejsu API, przeczytaj How to use Digital Twins Swagger (Jak używać struktury Swagger usługi Digital Twins).

Aby przejrzeć składnię OData i dostępne operatory porównania, przeczytaj operatory porównania OData w Azure Cognitive Search.