Share via

Jak wysyłać żądania do interfejsów API usługi Azure Digital Twins przy użyciu narzędzia Postman

  • Artykuł

Postman to narzędzie do testowania REST, które zapewnia kluczowe funkcje żądań HTTP w graficznym interfejsie użytkownika na pulpicie i wtyczki. Służy do tworzenia żądań HTTP i przesyłania ich do interfejsów API REST usługi Azure Digital Twins. W tym artykule opisano sposób konfigurowania klienta REST postman do interakcji z interfejsami API usługi Azure Digital Twins. Te informacje są specyficzne dla usługi Azure Digital Twins.

Ten artykuł zawiera informacje o następujących krokach:

  1. Użyj interfejsu wiersza polecenia platformy Azure, aby uzyskać token elementu nośnego, który będzie używany do tworzenia żądań interfejsu API w narzędziu Postman.
  2. Skonfiguruj kolekcję Postman i skonfiguruj klienta REST narzędzia Postman do uwierzytelniania przy użyciu tokenu elementu nośnego. Podczas konfigurowania kolekcji możesz wybrać jedną z następujących opcji:
    1. Zaimportuj wstępnie utworzoną kolekcję żądań interfejsu API usługi Azure Digital Twins.
    2. Utwórz własną kolekcję od podstaw.
  3. Dodaj żądania do skonfigurowanej kolekcji i wyślij je do interfejsów API usługi Azure Digital Twins.

Usługa Azure Digital Twins ma dwa zestawy interfejsów API, z którymi można pracować: płaszczyzna danych i płaszczyzna sterowania. Aby uzyskać więcej informacji na temat różnic między tymi zestawami interfejsów API, zobacz Interfejsy API usługi Azure Digital Twins i zestawy SDK. Ten artykuł zawiera informacje dotyczące obu zestawów interfejsów API.

Wymagania wstępne

Aby kontynuować korzystanie z narzędzia Postman w celu uzyskania dostępu do interfejsów API usługi Azure Digital Twins, należy skonfigurować wystąpienie usługi Azure Digital Twins i pobrać narzędzie Postman. W pozostałej części tej sekcji przedstawiono te kroki.

Konfigurowanie wystąpienia usługi Azure Digital Twins

Aby pracować z usługą Azure Digital Twins w tym artykule, musisz mieć wystąpienie usługi Azure Digital Twins i wymagane uprawnienia do korzystania z niego. Jeśli masz już skonfigurowane wystąpienie usługi Azure Digital Twins, możesz użyć tego wystąpienia i przejść do następnej sekcji. W przeciwnym razie postępuj zgodnie z instrukcjami w temacie Konfigurowanie wystąpienia i uwierzytelniania. Instrukcje zawierają informacje ułatwiające sprawdzenie, czy każdy krok został ukończony pomyślnie.

Po skonfigurowaniu wystąpienia zanotuj nazwę hosta wystąpienia. Nazwę hosta można znaleźć w witrynie Azure Portal.

Pobierz narzędzie Postman

Następnie pobierz wersję klasyczną klienta Postman.

Uzyskiwanie tokenu elementu nośnego

Po skonfigurowaniu narzędzia Postman i wystąpienia usługi Azure Digital Twins należy uzyskać token elementu nośnego, którego żądania Postman mogą używać do autoryzacji względem interfejsów API usługi Azure Digital Twins.

Istnieje kilka możliwych sposobów uzyskania tego tokenu. W tym artykule użyto interfejsu wiersza polecenia platformy Azure do zalogowania się na koncie platformy Azure i uzyskania tokenu.

Jeśli masz zainstalowany lokalnie interfejs wiersza polecenia platformy Azure, możesz uruchomić wiersz polecenia na maszynie, aby uruchomić następujące polecenia. W przeciwnym razie możesz otworzyć okno usługi Azure Cloud Shell w przeglądarce i uruchomić tam polecenia.

  1. Najpierw upewnij się, że zalogowano się na platformie Azure przy użyciu odpowiednich poświadczeń, uruchamiając następujące polecenie:

    az login

  2. Następnie użyj polecenia az account get-access-token , aby uzyskać token elementu nośnego z dostępem do usługi Azure Digital Twins. W tym poleceniu przekażesz identyfikator zasobu punktu końcowego usługi Azure Digital Twins, aby uzyskać token dostępu, który może uzyskać dostęp do zasobów usługi Azure Digital Twins.

    Wymagany kontekst tokenu zależy od używanego zestawu interfejsów API, dlatego użyj poniższych kart, aby wybrać między płaszczyzną danych a interfejsami API płaszczyzny sterowania.

    Aby uzyskać token do użycia z interfejsami API płaszczyzny danych, użyj następującej wartości statycznej dla kontekstu tokenu: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0. Ta wartość to identyfikator zasobu punktu końcowego usługi Azure Digital Twins.

    az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

    Uwaga

    Jeśli musisz uzyskać dostęp do wystąpienia usługi Azure Digital Twins przy użyciu jednostki usługi lub konta użytkownika należącego do innej dzierżawy usługi Microsoft Entra z wystąpienia, musisz zażądać tokenu z dzierżawy "macierzystej" wystąpienia usługi Azure Digital Twins. Aby uzyskać więcej informacji na temat tego procesu, zobacz Pisanie kodu uwierzytelniania aplikacji.

  3. Skopiuj wartość accessToken w wyniku i zapisz ją, aby użyć jej w następnej sekcji. Ta wartość to wartość tokenu, którą należy podać do narzędzia Postman w celu autoryzowania żądań.

    Screenshot of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted.

Napiwek

Ten token jest ważny przez co najmniej pięć minut i maksymalnie 60 minut. Jeśli zabraknie czasu przydzielonego dla bieżącego tokenu, możesz powtórzyć kroki opisane w tej sekcji, aby uzyskać nowy.

Następnie skonfigurujesz narzędzie Postman, aby używać tego tokenu do tworzenia żądań interfejsu API do usługi Azure Digital Twins.

Informacje o kolekcjach Postman

Żądania w narzędziu Postman są zapisywane w kolekcjach (grupach żądań). Podczas tworzenia kolekcji w celu grupowania żądań można stosować wspólne ustawienia do wielu żądań jednocześnie. Typowe ustawienia mogą znacznie uprościć autoryzację, jeśli planujesz utworzyć więcej niż jedno żądanie względem interfejsów API usługi Azure Digital Twins, ponieważ musisz skonfigurować te szczegóły tylko raz dla całej kolekcji.

Podczas pracy z usługą Azure Digital Twins możesz rozpocząć, importując wstępnie utworzoną kolekcję wszystkich żądań usługi Azure Digital Twins. Możesz zaimportować tę kolekcję, jeśli eksplorujesz interfejsy API i chcesz szybko skonfigurować projekt z przykładami żądań.

Alternatywnie możesz również zacząć od podstaw, tworząc własną pustą kolekcję i wypełniając ją pojedynczymi żądaniami wywołującymi tylko potrzebne interfejsy API.

W poniższych sekcjach opisano oba te procesy. Pozostała część artykułu odbywa się w lokalnej aplikacji Postman, więc przejdź do przodu i otwórz aplikację Postman na komputerze teraz.

Importowanie kolekcji interfejsów API usługi Azure Digital Twins

Szybkim sposobem rozpoczęcia pracy z usługą Azure Digital Twins w narzędziu Postman jest zaimportowanie wstępnie utworzonej kolekcji żądań dla interfejsów API. Wykonaj poniższe kroki, aby zaimportować kolekcję popularnych żądań interfejsu API płaszczyzny danych usługi Azure Digital Twins zawierających przykładowe dane żądania.

  1. W głównym oknie Postman wybierz przycisk Importuj. Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. W wyświetlonym oknie Importowanie wybierz pozycję Połącz i wprowadź następujący adres URL: https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json. Następnie wybierz pozycję Importuj , aby potwierdzić.

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

Nowo zaimportowana kolekcja jest teraz widoczna w widoku głównym narzędzia Postman na karcie Kolekcje.

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

Napiwek

Aby zaimportować pełny zestaw wywołań interfejsu API dla określonej wersji interfejsów API usługi Azure Digital Twins (w tym płaszczyzny sterowania lub płaszczyzny danych), możesz również zaimportować pliki struktury Swagger jako kolekcje. Aby uzyskać linki do plików struktury Swagger dla interfejsów API płaszczyzny sterowania i płaszczyzny danych, zobacz Interfejsy API i zestawy SDK usługi Azure Digital Twins.

Następnie przejdź do następnej sekcji, aby dodać token elementu nośnego do kolekcji na potrzeby autoryzacji i połączyć go z wystąpieniem usługi Azure Digital Twins.

Konfigurowanie autoryzacji

Następnie zmodyfikuj utworzoną kolekcję, aby skonfigurować szczegóły dostępu. Wyróżnij utworzoną kolekcję i wybierz ikonę Wyświetl więcej akcji , aby wyświetlić opcje akcji. Zaznacz Edytuj.

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

Wykonaj następujące kroki, aby dodać token elementu nośnego do kolekcji na potrzeby autoryzacji. Użyj wartości tokenu zebranej w sekcji Uzyskiwanie tokenu elementu nośnego, aby użyć jej dla wszystkich żądań interfejsu API w kolekcji.

  1. W oknie dialogowym edycji kolekcji upewnij się, że jesteś na karcie Autoryzacja .

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Ustaw wartość Typ na OAuth 2.0 i wklej token dostępu w polu Token dostępu. Musisz użyć poprawnego tokenu dla typu używanego interfejsu API, ponieważ istnieją różne tokeny dla interfejsów API płaszczyzny danych i interfejsów API płaszczyzny sterowania. Wybierz pozycję Zapisz.

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

    Napiwek

    Możesz włączyć udostępnianie tokenów, jeśli chcesz przechowywać token z żądaniem w chmurze Postman, a potencjalnie udostępnić token innym osobom.

Inna konfiguracja

Kolekcję można łatwo połączyć z zasobami usługi Azure Digital Twins, ustawiając niektóre zmienne dostarczone z kolekcją. Jeśli wiele żądań w kolekcji wymaga tej samej wartości (takiej jak nazwa hosta wystąpienia usługi Azure Digital Twins), można przechowywać wartość w zmiennej, która ma zastosowanie do każdego żądania w kolekcji. Kolekcja usługi Azure Digital Twins zawiera wstępnie utworzone zmienne, które można ustawić na poziomie kolekcji.

  1. Nadal w oknie dialogowym edycji kolekcji przejdź do karty Zmienne .

  2. Użyj poniższej tabeli, aby ustawić wartości zmiennych w kolekcji:

    Zmienna Zestaw interfejsów API opis
    digitaltwins-hostname Płaszczyzna danych Nazwa hosta wystąpienia usługi Azure Digital Twins. Tę wartość można znaleźć na stronie przeglądu wystąpienia w portalu.
    subscriptionId Płaszczyzna sterowania Identyfikator subskrypcji platformy Azure.
    digitalTwinInstance Płaszczyzna sterowania Nazwa wystąpienia usługi Azure Digital Twins.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

  3. Jeśli kolekcja ma dodatkowe zmienne, wypełnij i zapisz te wartości.

  4. Wybierz pozycję Zapisz.

Po wykonaniu powyższych kroków skonfigurujesz kolekcję. Jeśli chcesz, możesz zamknąć kartę edycji kolekcji.

Eksplorowanie żądań

Następnie zapoznaj się z żądaniami w kolekcji interfejsu API usługi Azure Digital Twins. Możesz rozwinąć kolekcję, aby wyświetlić wstępnie utworzone żądania (posortowane według kategorii operacji).

Różne żądania wymagają różnych informacji o wystąpieniu i jego danych. Aby wyświetlić wszystkie informacje wymagane do utworzenia określonego żądania, wyszukaj szczegóły żądania w dokumentacji interfejsu API REST usługi Azure Digital Twins.

Szczegóły żądania można edytować w kolekcji Postman, wykonując następujące kroki:

  1. Wybierz ją z listy, aby ściągnąć jego edytowalne szczegóły.

  2. Większość żądań w kolekcji przykładowej jest wstępnie skonfigurowana do uruchamiania bez wprowadzania dalszych zmian.

  3. Poniższy zrzut ekranu przedstawia interfejs API Dodawania modelu DigitalTwinModels. Na karcie Treść można zobaczyć ładunek JSON, który definiuje nowy model do dodania:

  4. Wypełnij wartości zmiennych wymienionych na karcie Params w obszarze Zmienne ścieżki.

    Screenshot of Postman. The collection is expanded to show the body tab of a request.

  5. Aby uruchomić żądanie, użyj przycisku Wyślij .

Możesz również dodać własne żądania do kolekcji, korzystając z procesu opisanego w sekcji Dodawanie pojedynczego żądania .

Tworzenie własnej kolekcji

Zamiast importować istniejącą kolekcję interfejsów API usługi Azure Digital Twins, możesz również utworzyć własną kolekcję od podstaw. Następnie możesz wypełnić je pojedynczymi żądaniami przy użyciu dokumentacji interfejsu API REST usługi Azure Digital Twins.

Tworzenie kolekcji w usłudze Postman

  1. Aby utworzyć kolekcję, wybierz przycisk Nowy w głównym oknie Postman.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Wybierz typ kolekcji.

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  2. Zostanie otwarta karta. Wypełnij szczegóły nowej kolekcji. Wybierz ikonę Edytuj obok domyślnej nazwy kolekcji (Nowa kolekcja), aby zastąpić ją własną nazwą.

    Screenshot of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

Następnie przejdź do następnej sekcji, aby dodać token elementu nośnego do kolekcji na potrzeby autoryzacji.

Konfigurowanie autoryzacji

Wykonaj następujące kroki, aby dodać token elementu nośnego do kolekcji na potrzeby autoryzacji. Użyj wartości tokenu zebranej w sekcji Uzyskiwanie tokenu elementu nośnego, aby użyć jej dla wszystkich żądań interfejsu API w kolekcji.

  1. W oknie dialogowym edycji nowej kolekcji przejdź do karty Autoryzacja .

    Screenshot of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Ustaw wartość Typ na OAuth 2.0, wklej token dostępu w polu Token dostępu, a następnie wybierz pozycję Zapisz.

    Screenshot of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

Po wykonaniu powyższych kroków skonfigurujesz kolekcję. Jeśli chcesz, możesz zamknąć kartę edycji nowej kolekcji.

Nowa kolekcja jest widoczna w widoku głównym narzędzia Postman na karcie Kolekcje.

Screenshot of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

Dodawanie pojedynczego żądania

Po skonfigurowaniu kolekcji możesz dodać własne żądania do interfejsów API usługi Azure Digital Twin.

  1. Aby utworzyć żądanie, ponownie użyj przycisku Nowy .

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Wybierz typ żądania.

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

  2. Ta akcja powoduje otwarcie okna ZAPISZ ŻĄDANIE, w którym można wprowadzić nazwę żądania, podać mu opcjonalny opis i wybrać kolekcję, której jest ona częścią. Wypełnij szczegóły i zapisz żądanie w utworzonej wcześniej kolekcji.

Screenshot of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

Teraz możesz wyświetlić żądanie w kolekcji i wybrać je, aby ściągnąć jego edytowalne szczegóły.

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

Ustawianie szczegółów żądania

Aby wysłać żądanie Postman do jednego z interfejsów API usługi Azure Digital Twins, potrzebny będzie adres URL interfejsu API i informacje o tym, jakich szczegółów wymaga. Te informacje można znaleźć w dokumentacji interfejsu API REST usługi Azure Digital Twins.

Aby kontynuować przykładowe zapytanie, w tym artykule użyto interfejsu API zapytań usługi Azure Digital Twins do wykonywania zapytań dotyczących wszystkich cyfrowych reprezentacji bliźniaczych w wystąpieniu.

  1. Pobierz adres URL żądania i wpisz go z dokumentacji referencyjnej. W przypadku interfejsu API zapytań jest to obecnie posthttps://digitaltwins-host-name/query?api-version=2020-10-31.

  2. W narzędziu Postman ustaw typ żądania i wprowadź adres URL żądania, wypełniając symbole zastępcze w adresie URL zgodnie z potrzebami. Użyj nazwy hosta wystąpienia w sekcji Wymagania wstępne.

    Screenshot of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  3. Sprawdź, czy parametry wyświetlane dla żądania na karcie Params są zgodne z parametrami opisanymi w dokumentacji referencyjnej. W przypadku tego żądania w narzędziu api-version Postman parametr został wypełniony automatycznie po wprowadzeniu adresu URL żądania w poprzednim kroku. W przypadku interfejsu API zapytań jest to jedyny wymagany parametr, więc ten krok jest wykonywany.

  4. Na karcie Autoryzacja ustaw wartość Typ na Dziedzicz uwierzytelnianie po elemecie nadrzędnym. Oznacza to, że to żądanie będzie używać autoryzacji skonfigurowanej wcześniej dla całej kolekcji.

  5. Sprawdź, czy nagłówki wyświetlane dla żądania na karcie Nagłówki są zgodne z nagłówkami opisanymi w dokumentacji referencyjnej. W przypadku tego żądania wypełniono automatycznie kilka nagłówków. W przypadku interfejsu API zapytań żadna z opcji nagłówka nie jest wymagana, więc ten krok jest wykonywany.

  6. Sprawdź, czy treść wyświetlana dla żądania na karcie Treść odpowiada potrzebom opisanym w dokumentacji referencyjnej. W przypadku interfejsu API zapytań do podania tekstu zapytania jest wymagana treść JSON. Oto przykładowa treść tego żądania, która wysyła zapytanie do wszystkich cyfrowych reprezentacji bliźniaczych w wystąpieniu:

    Screenshot of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of 'SELECT * FROM DIGITALTWINS'.

    Aby uzyskać więcej informacji na temat tworzenia zapytań usługi Azure Digital Twins, zobacz Query the twin graph (Wykonywanie zapytań względem grafu bliźniaczej reprezentacji).

  7. Zapoznaj się z dokumentacją referencyjną dla innych pól, które mogą być wymagane dla danego typu żądania. W przypadku interfejsu API zapytań wszystkie wymagania zostały spełnione w żądaniu Postman, więc ten krok zostanie wykonany.

  8. Użyj przycisku Wyślij, aby wysłać ukończone żądanie. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

Po wysłaniu żądania szczegóły odpowiedzi zostaną wyświetlone w oknie Postman poniżej żądania. Możesz wyświetlić kod stanu odpowiedzi i dowolny tekst treści.

Screenshot of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

Możesz również porównać odpowiedź z oczekiwaną odpowiedzią podaną w dokumentacji referencyjnej, aby zweryfikować wynik lub dowiedzieć się więcej o wszelkich pojawiających się błędach.

Następne kroki

Aby dowiedzieć się więcej na temat interfejsów API usługi Digital Twins, przeczytaj artykuł Interfejsy API i zestawy SDK usługi Azure Digital Twins lub zapoznaj się z dokumentacją referencyjną interfejsów API REST.