Jak wysyłać żądania do interfejsów API usługi Azure Digital Twins przy użyciu programu Visual Studio

Program Visual Studio 2022 obsługuje .http pliki, które mogą służyć do tworzenia struktury, przechowywania i bezpośredniego wysyłania żądań HTTP z aplikacji. Użycie tej funkcji programu Visual Studio jest jednym ze sposobów tworzenia żądań HTTP i przesyłania ich do interfejsów API REST usługi Azure Digital Twins. W tym artykule opisano sposób konfigurowania .http pliku w programie Visual Studio, który może być interfejsem z interfejsami API usługi Azure Digital Twins.

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

1. Skonfiguruj projekt i .http plik programu Visual Studio ze zmiennymi reprezentującymi wystąpienie usługi Azure Digital Twins.
2. Użyj interfejsu wiersza polecenia platformy Azure, aby uzyskać token elementu nośnego, którego można użyć do tworzenia żądań interfejsu API w programie Visual Studio.
3. Skorzystaj z dokumentacji interfejsu API REST usługi Azure Digital Twins jako zasobu, aby utworzyć żądania w .http pliku i wysłać 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 instrukcje dotyczące obu zestawów interfejsów API.

Aby uzyskać więcej informacji na temat .http obsługi plików w programie Visual Studio, zobacz Use .http files in Visual Studio 2022 (Używanie plików http w programie Visual Studio 2022).

Wymagania wstępne

Aby wysyłać żądania do interfejsów API usługi Azure Digital Twins przy użyciu programu Visual Studio, musisz skonfigurować wystąpienie usługi Azure Digital Twins i pobrać program Visual Studio 2022. Ta sekcja dotyczy tych kroków.

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 program Visual Studio 2022

Następnie pobierz program Visual Studio 2022. Pamiętaj o dołączeniu obciążenia ASP.NET i tworzenia aplikacji internetowych w instalacji.

Konfigurowanie projektu programu Visual Studio

W tej sekcji skonfigurujesz projekt w programie Visual Studio, który będzie używany do tworzenia żądań HTTP.

Otwórz program Visual Studio na maszynie i utwórz nowy projekt. Użyj szablonu projektu ASP.NET Core Empty .

Postępuj zgodnie z instrukcjami w temacie Tworzenie pliku HTTP, aby utworzyć nowy .http plik w projekcie.

Dodaj zmienne

Następnie dodaj kilka zmiennych w górnej części .http pliku, które będą używane do nawiązywania połączenia z zasobem usługi Azure Digital Twins.

Zestaw potrzebnych zmiennych zależy od używanego zestawu interfejsów API, dlatego użyj poniższych kart, aby wybrać interfejsy API płaszczyzny danych i płaszczyzny sterowania.

Płaszczyzna danych

Dodaj następujące zmienne dla żądań płaszczyzny danych. Istnieje jeden symbol zastępczy nazwy hosta wystąpienia usługi Azure Digital Twins (kończy się digitaltwins.azure.net).

@hostName=<host-name-of-your-Azure-Digital-Twins-instance>
@DPversion=2023-10-31

Płaszczyzna sterowania

Dodaj następujące zmienne dla żądań płaszczyzny sterowania. Zawierają symbole zastępcze dla wartości zasobów.

@instance=<name-of-your-Azure-Digital-Twins-instance>
@subscription=<ID-of-your-Azure-subscription>
@resourceGroup=<resource-group>
@CPversion=2023-01-31

Dodawanie tokenu elementu nośnego

Po skonfigurowaniu wystąpienia usługi Azure Digital Twins i projektu programu Visual Studio musisz uzyskać token elementu nośnego, którego żądania HTTP mogą używać do autoryzacji względem interfejsów API usługi Azure Digital Twins.

Istnieje wiele sposobów uzyskania tego tokenu. W tym artykule użyto interfejsu wiersza polecenia platformy Azure do zalogowania się do konta platformy Azure i uzyskania tokenu w ten sposób.

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ć interfejsy API płaszczyzny danych i płaszczyzny sterowania.

   Płaszczyzna danych

   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
   

   Płaszczyzna sterowania

   Aby uzyskać token do użycia z interfejsami API płaszczyzny sterowania, użyj następującej wartości dla kontekstu tokenu: https://management.azure.com/.

   az account get-access-token --resource https://management.azure.com/
   

   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. Ta wartość to wartość tokenu, która zostanie wklejona do programu Visual Studio, aby autoryzować żądania.

   

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.

Dodawanie tokenu do .http pliku

.http W pliku w programie Visual Studio dodaj kolejną zmienną, która przechowuje wartość tokenu.

Płaszczyzna danych

@token=<paste-data-plane-token>

Zmienne powinny teraz wyglądać mniej więcej tak:

Płaszczyzna sterowania

@token=<paste-control-plane-token>

Zmienne powinny teraz wyglądać mniej więcej tak:

Dodawanie żądań

Teraz, po skonfigurowaniu .http pliku, możesz dodać żądania do interfejsów API usługi Azure Digital Twin.

Zacznij od otwarcia dokumentacji interfejsu API REST usługi Azure Digital Twins. Ta dokumentacja zawiera szczegółowe informacje o wszystkich operacjach objętych interfejsami API. Przejdź do strony referencyjnej żądania, które chcesz uruchomić.

W tym artykule jako przykład użyjemy interfejsu API aktualizacji DigitalTwins z płaszczyzny danych.

1. Dodaj szablon żądania: skopiuj żądanie HTTP pokazane w dokumentacji referencyjnej.

   

   W programie Visual Studio wklej żądanie w nowym wierszu poniżej zmiennych w .http pliku.

2. Dodaj parametry: zapoznaj się z sekcją Parametry identyfikatora URI w dokumentacji referencyjnej, aby sprawdzić, które wartości parametrów są wymagane przez żądanie. Możesz zastąpić niektóre z utworzonych wcześniej zmiennych i wypełnić inne wartości parametrów zgodnie z potrzebami. Aby odwołać się do zmiennej, umieść nazwę zmiennej w podwójnych nawiasach klamrowych, takich jak {{variable}}. Aby uzyskać więcej informacji, zobacz Zmienne.

   Uwaga

   W przypadku żądań digitaltwins-hostname płaszczyzny danych jest również parametrem. Zastąp {{hostName}} wartość , aby użyć wartości zmiennej nazwy hosta.

   Oto jak ten krok wygląda w przykładowym żądaniu:

   

3. Dodaj autoryzację: Dodaj następujący wiersz (dokładnie tak jak napisany) bezpośrednio pod żądaniem, aby określić uwierzytelnianie za pomocą zmiennej tokenu elementu nośnego.

   Authorization: Bearer {{token}}
   

   Oto jak ten krok wygląda w przykładowym żądaniu:

   

4. Dodaj dodatkowe nagłówki: zapoznaj się z sekcją Nagłówek żądania w dokumentacji referencyjnej, aby zobaczyć, które wartości nagłówka mogą towarzyszyć żądaniu. Możesz również uwzględnić tradycyjne nagłówki HTTP, takie jak Content-Type. Dodaj każdy nagłówek we własnym wierszu w formacie HeaderName: Value. Aby uzyskać więcej informacji, zobacz Nagłówki żądań.

   Oto jak ten krok wygląda w przykładowym żądaniu:

   

5. Dodaj treść: zapoznaj się z sekcją Treść żądania w dokumentacji referencyjnej, aby zobaczyć, jakie informacje o treści mogą być potrzebne przez żądanie. Dodaj treść żądania po pustym wierszu. Aby uzyskać więcej informacji, zobacz Treść żądania.

   Oto jak ten krok wygląda w przykładowym żądaniu:

6. Gdy żądanie jest gotowe, wybierz pozycję Wyślij żądanie powyżej żądania, aby je wysłać.

   

Program Visual Studio powoduje wyświetlenie okienka ze szczegółami odpowiedzi. Zapoznaj się z sekcją Odpowiedzi w dokumentacji referencyjnej, aby zinterpretować kod stanu i wszystkie dane w treści odpowiedzi.

Dodawanie dodatkowych żądań

Aby dodać więcej żądań do .http pliku, rozdziel je ### ogranicznikiem.

Następne kroki

Aby uzyskać więcej informacji na temat wysyłania żądań z plikami .http w programie Visual Studio, w tym szczegółów składni i zaawansowanych scenariuszy, zobacz Use .http files in Visual Studio 2022 (Używanie plików http w programie Visual Studio 2022).

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.