Interfejsy API i zestawy SDK usługi Azure Digital Twins
Ten artykuł zawiera omówienie dostępnych interfejsów API usługi Azure Digital Twins oraz metod interakcji z nimi. Interfejsy API REST można używać bezpośrednio ze skojarzonymi z nimi narzędziami Swagger lub za pośrednictwem zestawu SDK.
Usługa Azure Digital Twins jest wyposażona w interfejsy API płaszczyzny sterowania, interfejsy API płaszczyzny danych i zestawy SDK do zarządzania wystąpieniem i jego elementami.
- Interfejsy API płaszczyzny sterowania to interfejsy API usługi Azure Resource Manager (ARM) i obejmują operacje zarządzania zasobami, takie jak tworzenie i usuwanie wystąpienia.
- Interfejsy API płaszczyzny danych to interfejsy API usługi Azure Digital Twins i są używane do operacji zarządzania danymi, takich jak zarządzanie modelami, reprezentacjami bliźniaczymi i grafem.
- Zestawy SDK korzystają z istniejących interfejsów API, aby ułatwić tworzenie niestandardowych aplikacji korzystających z usługi Azure Digital Twins.
Interfejsy API płaszczyzny sterowania
Interfejsy API płaszczyzny sterowania to interfejsy API usługi ARM używane do zarządzania wystąpieniem usługi Azure Digital Twins jako całości, więc obejmują operacje takie jak tworzenie lub usuwanie całego wystąpienia. Te interfejsy API będą również używane do tworzenia i usuwania punktów końcowych.
Aby bezpośrednio wywołać interfejsy API, odwołaj się do najnowszego folderu struktury Swagger w repozytorium struktury Swagger płaszczyzny sterowania. Ten folder zawiera również folder przykładów pokazujący użycie.
Poniżej przedstawiono zestawy SDK dostępne obecnie dla interfejsów API płaszczyzny sterowania usługi Azure Digital Twins.
Interfejsy API płaszczyzny sterowania można również wykonywać, korzystając z usługi Azure Digital Twins za pośrednictwem witryny Azure Portal i interfejsu wiersza polecenia.
Interfejsy API płaszczyzny danych
Interfejsy API płaszczyzny danych to interfejsy API usługi Azure Digital Twins używane do zarządzania elementami w wystąpieniu usługi Azure Digital Twins. Obejmują one operacje, takie jak tworzenie tras, przekazywanie modeli, tworzenie relacji i zarządzanie bliźniaczymi reprezentacjami, i mogą być szeroko podzielone na następujące kategorie:
DigitalTwinModels— Kategoria DigitalTwinModels zawiera interfejsy API do zarządzania modelami w wystąpieniu usługi Azure Digital Twins. Działania związane z zarządzaniem obejmują przekazywanie, walidację, pobieranie i usuwanie modeli utworzonych w języku DTDL.DigitalTwins— Kategoria DigitalTwins zawiera interfejsy API, które umożliwiają deweloperom tworzenie, modyfikowanie i usuwanie cyfrowych reprezentacji bliźniaczych oraz ich relacji w wystąpieniu usługi Azure Digital Twins.Query— Kategoria Zapytanie umożliwia deweloperom znajdowanie zestawów cyfrowych reprezentacji bliźniaczych w grafie bliźniaczej reprezentacji między relacjami.Event Routes— Kategoria Trasy zdarzeń zawiera interfejsy API do kierowania danych za pośrednictwem systemu i do usług podrzędnych.Import Jobs— Interfejs API importu zadań umożliwia zarządzanie długotrwałą, asynchroniczną akcją importowania modeli, reprezentacji bliźniaczych i relacji zbiorczo.Delete Jobs— Interfejs API usuwania zadań umożliwia zarządzanie długotrwałą akcją asynchroniczną w celu usunięcia wszystkich modeli, reprezentacji bliźniaczych i relacji w wystąpieniu.
Aby bezpośrednio wywołać interfejsy API, odwołaj się do najnowszego folderu struktury Swagger w repozytorium struktury Swagger płaszczyzny danych. Ten folder zawiera również folder przykładów pokazujący użycie. Możesz również wyświetlić dokumentację referencyjną interfejsu API płaszczyzny danych.
Poniżej przedstawiono zestawy SDK dostępne obecnie dla interfejsów API płaszczyzny danych usługi Azure Digital Twins.
Możesz również ćwiczyć interfejsy API płaszczyzny danych, korzystając z usługi Azure Digital Twins za pośrednictwem interfejsu wiersza polecenia.
Uwagi dotyczące użycia i uwierzytelniania
Ta sekcja zawiera bardziej szczegółowe informacje na temat korzystania z interfejsów API i zestawów SDK.
Uwagi dotyczące interfejsu API
Poniżej przedstawiono ogólne informacje dotyczące bezpośredniego wywoływania interfejsów API usługi Azure Digital Twins.
- Możesz użyć narzędzia do testowania REST PROTOKOŁU HTTP, aby wykonywać bezpośrednie wywołania interfejsów API usługi Azure Digital Twins. Aby uzyskać więcej informacji na temat tego procesu, zobacz Wywoływanie interfejsów API usługi Azure Digital Twins.
- Usługa Azure Digital Twins obecnie nie obsługuje udostępniania zasobów między źródłami (CORS). Aby uzyskać więcej informacji na temat strategii wpływu i rozwiązywania problemów, zobacz Współużytkowanie zasobów między źródłami (CORS) dla usługi Azure Digital Twins.
Oto kilka dodatkowych informacji na temat uwierzytelniania żądań interfejsu API.
- Jednym ze sposobów wygenerowania tokenu elementu nośnego dla żądań interfejsu API usługi Azure Digital Twins jest użycie polecenia az account get-access-token CLI. Aby uzyskać szczegółowe instrukcje, zobacz Dodawanie tokenu elementu nośnego.
- Żądania do interfejsów API usługi Azure Digital Twins wymagają użytkownika lub jednostki usługi będącej częścią tej samej dzierżawy identyfikatora Entra firmy Microsoft, w której istnieje wystąpienie usługi Azure Digital Twins. Aby zapobiec złośliwemu skanowaniu punktów końcowych usługi Azure Digital Twins, żądania z tokenami dostępu spoza dzierżawy źródłowej zostaną zwrócone komunikat o błędzie "Nie znaleziono domeny podrzędnej 404". Ten błąd zostanie zwrócony, nawet jeśli użytkownik lub jednostka usługi otrzymał rolę właściciela danych usługi Azure Digital Twins lub czytelnika danych usługi Azure Digital Twins za pośrednictwem współpracy firmy Microsoft Entra B2B . Aby uzyskać informacje na temat uzyskiwania dostępu w wielu dzierżawach, zobacz Pisanie kodu uwierzytelniania aplikacji.
Uwagi dotyczące zestawu SDK
Podstawowym zestawem SDK dla usługi Azure Digital Twins jest Azure.Core. Zapoznaj się z dokumentacją przestrzeni nazw platformy Azure, aby uzyskać informacje na temat infrastruktury i typów zestawu SDK.
Oto kilka dodatkowych informacji na temat uwierzytelniania za pomocą zestawów SDK.
- Zacznij od utworzenia
DigitalTwinsClientwystąpienia klasy. Konstruktor wymaga poświadczeń, które można uzyskać przy użyciu różnych rodzajów metod uwierzytelniania w pakiecieAzure.Identity. Aby uzyskać więcej informacji na ten tematAzure.Identity, zobacz dokumentację przestrzeni nazw. - Przydatne podczas rozpoczynania pracy może okazać się
InteractiveBrowserCredentialprzydatne, ale istnieje kilka innych opcji, w tym poświadczeń tożsamości zarządzanej, które prawdopodobnie będą używane do uwierzytelniania funkcji platformy Azure skonfigurowanych przy użyciu tożsamości usługi zarządzanej w usłudze Azure Digital Twins. Aby uzyskać więcej informacji na tematInteractiveBrowserCredentialprogramu , zobacz dokumentację klasy.
Oto kilka dodatkowych informacji na temat funkcji i zwracanych danych.
- Wszystkie wywołania interfejsu API usługi są uwidocznione jako funkcje składowe w
DigitalTwinsClientklasie . - Wszystkie funkcje usługi istnieją w wersjach synchronicznych i asynchronicznych.
- Wszystkie funkcje usługi zgłaszają wyjątek dla dowolnego stanu zwrotu 400 lub nowszego. Upewnij się, że zawijasz wywołania do
trysekcji i przechwyć co najmniejRequestFailedExceptions. Aby uzyskać więcej informacji na temat tego typu wyjątku, zobacz dokumentację referencyjną. - Większość metod usługi zwraca
Response<T>lub (Task<Response<T>>dla wywołań asynchronicznych), gdzieTjest klasą obiektu zwracanego dla wywołania usługi. Klasa Response hermetyzuje zwracanie usługi i przedstawia wartości zwracane w jegoValuepolu. - Metody usługi ze stronicowanym wynikiem są zwracane
Pageable<T>lubAsyncPageable<T>jako wyniki. Aby uzyskać więcej informacji na tematPageable<T>klasy, zobacz jej dokumentację referencyjną. Aby uzyskać więcej informacji na tematAsyncPageable<T>, zobacz dokumentację referencyjną. - Można iterować po stronicowanych wynikach przy użyciu
await foreachpętli. Aby uzyskać więcej informacji na temat tego procesu, zobacz Iterating with Async Enumerables in C# 8 (Iterating with Async Enumerables in C# 8( Iterating with Async Enumerables in C# 8 (Iterating with Async Enumerables in C# - Metody usługi zwracają silnie typizowane obiekty wszędzie tam, gdzie to możliwe. Jednak ponieważ usługa Azure Digital Twins jest oparta na modelach niestandardowych skonfigurowanych przez użytkownika w czasie wykonywania (za pośrednictwem modeli DTDL przekazanych do usługi), wiele interfejsów API usługi bierze i zwraca dane bliźniaczych reprezentacji w formacie JSON.
Pomocnicy serializacji w zestawie SDK platformy .NET (C#)
Pomocnicy serializacji to funkcje pomocnicze dostępne w zestawie .NET (C#) SDK umożliwiające szybkie tworzenie lub deserializowanie danych bliźniaczych reprezentacji w celu uzyskania dostępu do podstawowych informacji. Ponieważ podstawowe metody zestawu SDK zwracają dane bliźniaczej reprezentacji jako dane JSON domyślnie, warto użyć tych klas pomocnika, aby dalej podzielić dane bliźniaczej reprezentacji.
Dostępne klasy pomocnika to:
BasicDigitalTwin: Ogólnie reprezentuje podstawowe dane cyfrowej reprezentacji bliźniaczejBasicDigitalTwinComponent: Typowo reprezentuje składnik weContentswłaściwościach obiektuBasicDigitalTwinBasicRelationship: Ogólnie reprezentuje podstawowe dane relacjiDigitalTwinsJsonPropertyName: zawiera stałe ciągów do użycia w serializacji JSON i deserializacji niestandardowych typów cyfrowych reprezentacji bliźniaczych
Importowanie zbiorcze za pomocą interfejsu API importowania zadań
Interfejs API importu zadań to interfejs API płaszczyzny danych, który umożliwia importowanie zestawu modeli, reprezentacji bliźniaczych i/lub relacji w jednym wywołaniu interfejsu API. Operacje interfejsu API importowania zadań są również dołączone do poleceń interfejsu wiersza polecenia i zestawów SDK płaszczyzny danych. Korzystanie z interfejsu API zadań importu wymaga użycia usługi Azure Blob Storage.
Sprawdzanie uprawnień
Aby użyć interfejsu API importu zadań, należy włączyć ustawienia uprawnień opisane w tej sekcji.
Najpierw musisz mieć tożsamość zarządzaną przypisaną przez system dla wystąpienia usługi Azure Digital Twins. Aby uzyskać instrukcje dotyczące konfigurowania tożsamości zarządzanej przez system dla wystąpienia, zobacz Włączanie/wyłączanie tożsamości zarządzanej dla wystąpienia.
Musisz mieć uprawnienia do zapisu w wystąpieniu usługi Azure Digital Twins dla następujących kategorii akcji danych:
Microsoft.DigitalTwins/jobs/*- Wszystkie elementy grafu, które mają zostać uwzględnione w wywołaniu Zadania. Może to obejmować
Microsoft.DigitalTwins/models/*,Microsoft.DigitalTwins/digitaltwins/*i/lubMicrosoft.DigitalTwins/digitaltwins/relationships/*.
Wbudowana rola, która zapewnia wszystkie te uprawnienia, to właściciel danych usługi Azure Digital Twins. Możesz również użyć roli niestandardowej, aby udzielić szczegółowego dostępu tylko do potrzebnych typów danych. Aby uzyskać więcej informacji na temat ról w usłudze Azure Digital Twins, zobacz Security for Azure Digital Twins solutions (Zabezpieczenia dla rozwiązań usługi Azure Digital Twins).
Uwaga
Jeśli spróbujesz wywołać interfejs API zadań importu i brakuje uprawnień do zapisu do jednego z typów elementów grafu, które próbujesz zaimportować, zadanie pominie ten typ i zaimportuje inne. Jeśli na przykład masz dostęp do zapisu do modeli i reprezentacji bliźniaczych, ale nie do relacji, próba zbiorczego zaimportowania wszystkich trzech typów elementów powiedzie się tylko podczas importowania modeli i reprezentacji bliźniaczych. Stan zadania będzie odzwierciedlać błąd, a komunikat będzie wskazywać, których uprawnień brakuje.
Należy również udzielić następujących uprawnień kontroli dostępu opartej na rolach do przypisanej przez system tożsamości zarządzanej wystąpienia usługi Azure Digital Twins, aby mógł uzyskać dostęp do plików wejściowych i wyjściowych w kontenerze usługi Azure Blob Storage:
- Czytelnik danych obiektu blob usługi Storage dla wejściowego kontenera obiektów blob usługi Azure Storage
- Współautor danych obiektu blob usługi Storage dla wyjściowego kontenera obiektów blob usługi Azure Storage
Na koniec wygeneruj token elementu nośnego, który może być używany w żądaniach do interfejsu API zadań. Aby uzyskać instrukcje, zobacz Dodawanie tokenu elementu nośnego.
Formatowanie danych
Interfejs API akceptuje dane wejściowe informacji o grafie z pliku NDJSON , który musi zostać przekazany do kontenera usługi Azure Blob Storage . Plik rozpoczyna się od Header sekcji, a następnie opcjonalnych sekcji Models, Twinsi Relationships. Nie musisz uwzględniać wszystkich trzech typów danych grafu w pliku, ale wszystkie obecne sekcje muszą być zgodne z kolejnością. Bliźniacze i relacje utworzone za pomocą tego interfejsu API mogą opcjonalnie obejmować inicjowanie ich właściwości.
Oto przykładowy plik danych wejściowych dla interfejsu API importu:
{"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}
Napiwek
Przykładowy projekt, który konwertuje modele, reprezentacje bliźniacze i relacje na format NDJSON obsługiwany przez interfejs API importu, zobacz Azure Digital Twins Bulk Import NDJSON Generator. Przykładowy projekt jest napisany dla platformy .NET i można go pobrać lub dostosować, aby ułatwić tworzenie własnych plików importu.
Po utworzeniu pliku przekaż go do blokowego obiektu blob w usłudze Azure Blob Storage przy użyciu preferowanej metody przekazywania (niektóre opcje to polecenie AzCopy, interfejs wiersza polecenia platformy Azure lub witryna Azure Portal). Użyjesz adresu URL magazynu obiektów blob pliku NDJSON w treści wywołania interfejsu API importu zadań.
Uruchamianie zadania importu
Teraz możesz kontynuować wywoływanie interfejsu API importu zadań. Aby uzyskać szczegółowe instrukcje dotyczące importowania pełnego grafu w jednym wywołaniu interfejsu API, zobacz Przekazywanie modeli, reprezentacji bliźniaczych i relacji zbiorczo za pomocą interfejsu API importowania zadań. Możesz również użyć interfejsu API importu zadań, aby zaimportować każdy typ zasobu niezależnie. Aby uzyskać więcej informacji na temat korzystania z interfejsu API importowania zadań z poszczególnymi typami zasobów, zobacz Instrukcje interfejsu API importowania zadań dla modeli, reprezentacji bliźniaczych i relacji.
W treści wywołania interfejsu API podasz adres URL magazynu obiektów blob pliku wejściowego NDJSON. Udostępnisz również nowy adres URL magazynu obiektów blob, aby wskazać, gdzie ma być przechowywany dziennik danych wyjściowych po jego utworzeniu.
Ważne
Upewnij się, że tożsamość zarządzana przypisana przez system wystąpienia usługi Azure Digital Twins ma uprawnienia kontroli dostępu opartej na rolach obiektu blob magazynu opisane w sekcji Sprawdzanie uprawnień.
W miarę wykonywania zadania importowania ustrukturyzowany dziennik danych wyjściowych jest generowany przez usługę i przechowywany jako nowy uzupełnilny obiekt blob w kontenerze obiektów blob, w lokalizacji adresu URL określonej dla wyjściowego obiektu blob w żądaniu. Oto przykładowy dziennik danych wyjściowych pomyślnego importowania modeli, reprezentacji bliźniaczych i relacji:
{"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 zakończeniu zadania można zobaczyć łączną liczbę pozyskanych jednostek przy użyciu metryki BulkOperationEntityCount.
Istnieje również możliwość anulowania uruchomionego zadania importu za pomocą operacji Anuluj z interfejsu API importu zadań. Gdy zadanie zostało anulowane i nie jest już uruchomione, możesz go usunąć.
Limity i zagadnienia
Podczas pracy z interfejsem API importu zadań należy wziąć pod uwagę następujące zagadnienia:
- Zadania importu nie są operacjami niepodzielnych. Nie ma wycofywania w przypadku awarii, częściowego ukończenia zadania lub użycia operacji Anuluj.
- W ramach wystąpienia usługi Azure Digital Twins jest obsługiwane tylko jedno zadanie zbiorcze. Te informacje i inne limity liczbowe interfejsów API zadań można wyświetlić w limitach usługi Azure Digital Twins.
Zbiorcze usuwanie za pomocą interfejsu API usuwania zadań
Interfejs API usuwania zadań to interfejs API płaszczyzny danych, który umożliwia usuwanie wszystkich modeli, reprezentacji bliźniaczych i relacji w wystąpieniu za pomocą jednego wywołania interfejsu API. Operacje interfejsu API usuwania zadań są również dostępne jako polecenia interfejsu wiersza polecenia. Zapoznaj się z dokumentacją interfejsu API, aby wyświetlić szczegóły żądania dotyczące tworzenia zadania usuwania i sprawdzania jego stanu.
Aby upewnić się, że wszystkie elementy zostały usunięte, postępuj zgodnie z tymi zaleceniami podczas korzystania z interfejsu API usuwania zadań:
- Aby uzyskać instrukcje dotyczące generowania tokenu elementu nośnego w celu uwierzytelniania żądań interfejsu API, zobacz Dodawanie tokenu elementu nośnego.
- Jeśli ostatnio zaimportowano dużą liczbę jednostek do grafu, poczekaj chwilę i sprawdź, czy wszystkie elementy są zsynchronizowane na grafie przed rozpoczęciem zadania usuwania.
- Zatrzymaj wszystkie operacje na wystąpieniu, zwłaszcza operacje przekazywania, dopóki zadanie usuwania nie zostanie ukończone.
W zależności od rozmiaru usuniętego grafu zadanie usuwania może potrwać od kilku minut do wielu godzin.
Domyślny limit czasu zadania usuwania to 12 godzin, które można dostosować do dowolnej wartości z zakresu od 15 minut do 24 godzin przy użyciu parametru zapytania w interfejsie API. Jest to czas, przez jaki zadanie usuwania zostanie uruchomione przed przekroczeniem limitu czasu, w którym usługa podejmie próbę zatrzymania zadania, jeśli zadanie nie zostało jeszcze ukończone.
Limity i inne zagadnienia
Podczas pracy z interfejsem API usuwania zadań należy pamiętać o następujących kwestiach:
- Zadania usuwania nie są operacjami niepodzielnych. Brak wycofywania w przypadku niepowodzenia, częściowego zakończenia zadania lub przekroczenia limitu czasu zadania.
- W ramach wystąpienia usługi Azure Digital Twins jest obsługiwane tylko jedno zadanie zbiorcze. Te informacje i inne limity liczbowe interfejsów API zadań można wyświetlić w limitach usługi Azure Digital Twins.
Monitorowanie metryk interfejsu API
Metryki interfejsu API, takie jak żądania, opóźnienia i współczynnik niepowodzeń, można wyświetlić w witrynie Azure Portal.
Aby uzyskać informacje na temat wyświetlania metryk usługi Azure Digital Twins i zarządzania nimi, zobacz Monitorowanie wystąpienia. Aby uzyskać pełną listę metryk interfejsu API dostępnych dla usługi Azure Digital Twins, zobacz Metryki żądań interfejsu API usługi Azure Digital Twins.
Następne kroki
Zobacz, jak wysyłać bezpośrednie żądania do interfejsów API usługi Azure Digital Twins:
Możesz też przećwiczyć korzystanie z zestawu SDK platformy .NET, tworząc aplikację kliencką w ramach tego samouczka: