Dokumentacja referencyjna usługi Azure Digital Twins Swagger

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.

Każde aprowizowane wystąpienie usługi Azure Digital Twins zawiera własną automatycznie wygenerowaną dokumentację referencyjną struktury Swagger.

Struktura Swagger lub OpenAPI łączy złożone informacje o interfejsie API w interaktywny i niezależny od języka zasób referencyjny. Struktura Swagger udostępnia krytyczne materiały referencyjne dotyczące ładunków JSON, metod HTTP i określonych punktów końcowych używanych do wykonywania operacji względem interfejsu API.

Podsumowanie struktury Swagger

Struktura Swagger udostępnia interaktywne podsumowanie interfejsu API, w tym:

• Informacje o interfejsie API i modelu obiektów.
• Punkty końcowe interfejsu API REST, które określają wymagane ładunki żądań, nagłówki, parametry, ścieżki kontekstowe i metody HTTP.
• Testowanie funkcji interfejsu API.
• Przykładowe informacje odpowiedzi używane do weryfikowania i potwierdzania odpowiedzi HTTP.
• Informacje o kodzie błędu.

Swagger to wygodne narzędzie ułatwiające tworzenie i testowanie wywołań do interfejsów API zarządzania usługą Azure Digital Twins.

Porada

Dostępna jest wersja zapoznawcza programu Swagger w celu zademonstrowania zestawu funkcji interfejsu API. Jest on hostowany w docs.westcentralus.azuresmartspaces.net/management/swagger.

Dostęp do własnej wygenerowanej dokumentacji programu Swagger interfejsu API zarządzania można uzyskać pod adresem:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger

Nazwa	Zamień na
YOUR_INSTANCE_NAME	Nazwa wystąpienia usługi Azure Digital Twins
YOUR_LOCATION	Region serwera, w którym jest hostowane używane wystąpienie

Materiał referencyjny

Automatycznie wygenerowany materiał referencyjny struktury Swagger zawiera krótkie omówienie ważnych pojęć, dostępnych punktów końcowych interfejsu API zarządzania oraz opis każdego modelu obiektów ułatwiającego programowanie i testowanie.

Zwięzłe podsumowanie opisuje interfejs API.

Zostaną również wyświetlone modele obiektów interfejsu API zarządzania.

Dla bardziej szczegółowego podsumowania kluczowych atrybutów można wybrać każdy z wymienionych modeli obiektów.

Wygenerowane modele obiektów struktury Swagger są wygodne do odczytywania wszystkich dostępnych obiektów i interfejsów API usługi Azure Digital Twins. Deweloperzy mogą używać tego zasobu podczas tworzenia rozwiązań w usłudze Azure Digital Twins.

Podsumowanie punktu końcowego

Program Swagger zawiera również szczegółowe omówienie wszystkich punktów końcowych tworzących interfejsy API zarządzania.

Każdy wymieniony punkt końcowy zawiera również wymagane informacje o żądaniu, takie jak:

• Wymagane parametry.
• Wymagane typy danych parametrów.
• Metoda HTTP umożliwiająca dostęp do zasobu.

Wybierz każdy zasób, aby wyświetlić ich dodatkową zawartość, aby uzyskać bardziej szczegółowe omówienie.

Testowanie punktów końcowych za pomocą programu Swagger

Jedną z zaawansowanych funkcji programu Swagger jest możliwość testowania punktu końcowego interfejsu API bezpośrednio za pośrednictwem interfejsu użytkownika dokumentacji.

Po wybraniu określonego punktu końcowego zostanie wyświetlony przycisk Wypróbuj .

Rozwiń tę sekcję, aby wyświetlić pola wejściowe dla każdego wymaganego i opcjonalnego parametru. Wprowadź poprawne wartości, a następnie wybierz pozycję Wykonaj.

Po wykonaniu testu możesz zweryfikować dane odpowiedzi.

Dane odpowiedzi struktury Swagger

Każdy wymieniony punkt końcowy zawiera również dane treści odpowiedzi w celu zweryfikowania programowania i testów. Te przykłady obejmują kody stanu i kod JSON dla pomyślnych żądań HTTP.

Przykłady obejmują również kody błędów ułatwiające debugowanie lub ulepszanie testów zakończonych niepowodzeniem.

Autoryzacja programu Swagger OAuth 2.0

Uwaga

• Jednostka użytkownika, która utworzyła zasób usługi Azure Digital Twins, będzie miała przypisanie roli Administrator obszaru i będzie mogła tworzyć dodatkowe przypisania ról dla innych użytkowników. Ci użytkownicy i ich role mogą być autoryzowani do wywoływania interfejsów API.

1. Wykonaj kroki opisane w przewodniku Szybki start, aby utworzyć i skonfigurować aplikację usługi Azure Active Directory. Alternatywnie możesz ponownie użyć istniejącej rejestracji aplikacji.

2. Dodaj następujący identyfikator URI przekierowania do rejestracji aplikacji usługi Azure Active Directory:

   

   https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html
   

   Nazwa	Zamień na	Przykład
   YOUR_SWAGGER_URL	Adres URL dokumentacji interfejsu API REST zarządzania znaleziony w portalu	https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger

3. Zaznacz pole wyboru Niejawne udzielanie>tokenów dostępu , aby zezwolić na używanie niejawnego przepływu przyznawania OAuth 2.0. Wybierz pozycję Konfiguruj, a następnie pozycję Zapisz.

4. Skopiuj identyfikator klienta aplikacji usługi Azure Active Directory.

Po zakończeniu rejestracji w usłudze Azure Active Directory:

1. Wybierz przycisk Autoryzuj na stronie struktury Swagger.

   

2. Wklej identyfikator aplikacji w polu client_id .

   

3. Nastąpi przekierowanie do następującego modalnego powodzenia.

   

Aby dowiedzieć się więcej na temat interakcyjnych żądań testowania chronionych przez protokół OAuth 2.0, przeczytaj oficjalną dokumentację.

Następne kroki

• Aby dowiedzieć się więcej o modelach obiektów usługi Azure Digital Twins i wykresie analizy przestrzennej, przeczytaj Omówienie modeli obiektów usługi Azure Digital Twins.

• Aby dowiedzieć się, jak uwierzytelniać się za pomocą interfejsu API zarządzania, przeczytaj Uwierzytelnianie za pomocą interfejsów API.