Dokumentacja interfejsu API REST platformy Azure

Artykuł
07/19/2023

Dokumentacja interfejsu API REST platformy Azure — Zapraszamy!

Interfejsy API rest (Representational State Transfer) to punkty końcowe usługi, które obsługują zestawy operacji HTTP (metod), które umożliwiają tworzenie/pobieranie/aktualizowanie/usuwanie dostępu do zasobów usługi. Poniższe sekcje przeprowadzą Cię przez następujące kroki:

Podstawowe składniki pary żądań/odpowiedzi interfejsu API REST
Jak zarejestrować aplikację kliencą w usłudze Azure Active Directory (Azure AD), aby zabezpieczyć żądania REST
Omówienie tworzenia i wysyłania żądania REST oraz obsługi odpowiedzi

Uwaga

Większość interfejsów API REST usługi platformy Azure ma odpowiednią bibliotekę zestawu SDK klienta, która obsługuje większość kodu klienta. Zobacz:

Zestaw Azure .NET SDK
Zestaw Azure Java SDK
Zestaw SDK interfejsu wiersza polecenia platformy Azure 2.0

Składniki żądania/odpowiedzi interfejsu API REST

Parę żądań/odpowiedzi interfejsu API REST można podzielić na 5 składników:

Identyfikator URI żądania, który składa się z następujących elementów: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Należy pamiętać, że wywołujemy to osobno w tym miejscu, ponieważ większość języków/struktur wymaga przekazania go oddzielnie od komunikatu żądania, ale jest faktycznie zawarta w nagłówku komunikatu żądania.
- Schemat identyfikatora URI: wskazuje protokół używany do przesyłania żądania. Na przykład: http lub https.
- Host identyfikatora URI: nazwa domeny lub adres IP serwera, na którym jest hostowany punkt końcowy usługi REST, na przykład graph.microsoft.com
- Ścieżka zasobu: określa zasób lub kolekcję zasobów, która może zawierać wiele segmentów używanych przez usługę podczas określania wyboru tych zasobów. Na przykład: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners może służyć do wykonywania zapytań dotyczących listy właścicieli określonej aplikacji w kolekcji aplikacji.
- Ciąg zapytania (opcjonalnie): służy do udostępniania dodatkowych prostych parametrów, takich jak wersja interfejsu API, kryteria wyboru zasobów itp.
Pola nagłówka komunikatu żądania HTTP
- Wymagana metoda HTTP (nazywana również operacją lub zleceniem), która informuje usługę o żądanym typie operacji. Interfejsy API REST platformy Azure obsługują metody GET, HEAD, PUT, POST i PATCH.
- Opcjonalne dodatkowe pola nagłówka wymagane przez określony identyfikator URI i metodę HTTP. Na przykład nagłówek autoryzacji, który dostarcza token elementu nośnego zawierający informacje o autoryzacji klienta dla żądania.
Opcjonalne pola treści komunikatu żądania HTTP umożliwiające obsługę identyfikatora URI i działania protokołu HTTP. Na przykład operacje POST zawierają obiekty zakodowane w formacie MIME przekazywane jako parametry złożone. Typ kodowania MIME dla treści należy również określić w nagłówku Content-type żądania dla operacji POST/PUT. Należy pamiętać, że niektóre usługi wymagają użycia określonego typu MIME, takiego jak application/json.
Pola nagłówka komunikatu odpowiedzi HTTP
- Kod stanu HTTP, od kodów powodzenia 2xx do kodów błędów 4xx/5xx. Można także zwracać kod stanu zdefiniowany przez usługę zgodnie z informacjami podanymi w dokumentacji interfejsu API.
- Opcjonalne dodatkowe pola nagłówka wymagane do obsługi odpowiedzi żądania, takie jak Content-type nagłówek odpowiedzi.
Opcjonalne pola treści komunikatu odpowiedzi HTTP
- Obiekty odpowiedzi zakodowane za pomocą protokołu MIME mogą być zwracane w treści odpowiedzi HTTP, takie jak odpowiedź z metody GET, która zwraca dane. Zazwyczaj będą one zwracane w formacie ustrukturyzowanym jako JSON lub XML, zgodnie z nagłówkiem Content-type odpowiedzi. Na przykład podczas żądania tokenu dostępu z Azure AD zostanie on zwrócony w treści odpowiedzi jako access_token element — jeden z kilku sparowanych obiektów nazwy/wartości w kolekcji danych. W tym przykładzie zostanie również dołączony nagłówek Content-Type: application/json odpowiedzi.

Rejestrowanie aplikacji klienckiej w usłudze Azure AD

Większość usług platformy Azure (takich jak dostawcy usługi Azure Resource Manager i klasyczne interfejsy API zarządzania usługami) wymaga od klienta uwierzytelnienia przy użyciu prawidłowych poświadczeń, zanim będzie można wywołać interfejs API usługi. Uwierzytelnianie jest koordynowane między różnymi aktorami przez Azure AD, co zapewnia klientowi token dostępu jako dowód uwierzytelniania/autoryzacji. Token jest następnie wysyłany do usługi platformy Azure w nagłówku autoryzacji HTTP wszystkich kolejnych żądań interfejsu API REST. Oświadczenia tokenu udostępniają również informacje do usługi, umożliwiając jej zweryfikowanie klienta i wykonanie dowolnej wymaganej autoryzacji.

Jeśli używasz interfejsu API REST, który nie używa zintegrowanego uwierzytelniania Azure AD lub masz już zarejestrowanego klienta, możesz przejść do sekcji Tworzenie żądania.

Wymagania wstępne

Aplikacja kliencka musi sprawić, że konfiguracja tożsamości będzie znana Azure AD przed uruchomieniem, rejestrując ją w dzierżawie Azure AD. Poniżej znajduje się lista elementów, które należy wziąć pod uwagę przed zarejestrowaniem klienta w Azure AD:

Jeśli nie masz jeszcze dzierżawy Azure AD, zobacz Jak uzyskać dzierżawę usługi Azure Active Directory.
Na strukturę autoryzacji OAuth2 Azure AD obsługuje 2 typy klientów. Zrozumienie każdego z nich pomoże Ci zdecydować, który z nich jest najbardziej odpowiedni dla danego scenariusza:
- klienci internetowi/poufne (działa na serwerze internetowym) mogą uzyskiwać dostęp do zasobów w ramach własnej tożsamości (tj. usługi/demona) lub uzyskać delegowane autoryzację dostępu do zasobów w ramach tożsamości zalogowanego użytkownika (tj. aplikacji internetowej). Tylko klient internetowy ma możliwość bezpiecznego utrzymywania i prezentowania własnych poświadczeń podczas uwierzytelniania Azure AD w celu uzyskania tokenu dostępu.
- natywni/publiczni klienci (zainstalowani/uruchomienia na urządzeniu) mogą uzyskiwać dostęp tylko do zasobów w ramach autoryzacji delegowanej przy użyciu tożsamości zalogowanego użytkownika w celu uzyskania tokenu dostępu w imieniu użytkownika.
Proces rejestracji spowoduje utworzenie 2 powiązanych obiektów w dzierżawie Azure AD, w której zarejestrowano aplikację: obiekt aplikacji i obiekt jednostki usługi. Aby uzyskać więcej informacji na temat tych składników i sposobu ich użycia w czasie wykonywania, zapoznaj się z tematem Application and service principal objects in Azure Active Directory (Obiekty aplikacji i jednostki usługi w usłudze Azure Active Directory).

Teraz możemy zarejestrować aplikację kliencą w usłudze Azure AD.

Rejestracja klienta

Aby zarejestrować klienta, który będzie uzyskiwać dostęp do interfejsu API REST usługi Azure Resource Manager, zobacz Tworzenie aplikacji usługi Active Directory i jednostki usługi, która może uzyskiwać dostęp do zasobów, aby uzyskać instrukcje rejestracji krok po kroku. W tym artykule (dostępnym również w programie PowerShell i wersjach interfejsu wiersza polecenia do automatyzacji rejestracji) pokazano, jak wykonać następujące czynności:

rejestrowanie aplikacji klienckiej w usłudze Azure AD
ustawianie żądań uprawnień, aby umożliwić klientowi dostęp do interfejsu API usługi Azure Resource Manager
Konfigurowanie ustawień Access Control opartych na rolach (RBAC) usługi Azure Resource Manager w celu autoryzowania klienta

W przypadku wszystkich innych klientów zapoznaj się z tematem Integrowanie aplikacji z usługą Azure Active Directory. W tym artykule pokazano, jak wykonać następujące działania:

rejestrowanie aplikacji klienckiej przy użyciu Azure AD w sekcji "Dodawanie aplikacji"
tworzenie klucza tajnego (jeśli rejestrujesz klienta internetowego) w sekcji "Aktualizowanie aplikacji"
dodawanie żądań uprawnień zgodnie z wymaganiami interfejsu API w sekcji "Aktualizowanie aplikacji"

Po zakończeniu rejestracji aplikacji klienckiej możemy przejść do kodu klienta, w którym utworzysz żądanie REST i obsłużysz odpowiedź.

Tworzenie żądania

W tej sekcji omówiono pierwsze 3 z 5 omówionych wcześniej składników. Najpierw musimy uzyskać token dostępu z Azure AD, którego użyjemy podczas tworzenia nagłówka komunikatu żądania.

Uzyskiwanie tokenu dostępu

Po zarejestrowaniu prawidłowej rejestracji klienta istnieją zasadniczo 2 sposoby integracji z Azure AD w celu uzyskania tokenu dostępu:

Azure AD punktów końcowych usługi OAuth2 neutralnych dla języka, co jest tym, czego będziemy używać. Podobnie jak w przypadku używanych punktów końcowych interfejsu API REST platformy Azure, instrukcje podane w tej sekcji nie przyjmują żadnych założeń dotyczących platformy lub języka/skryptu klienta podczas korzystania z punktów końcowych Azure AD; tylko wtedy, gdy może wysyłać/odbierać żądania HTTPS do/z Azure AD i analizować komunikat odpowiedzi.
Biblioteki uwierzytelniania firmy Microsoft specyficzne dla platformy/języka (MSAL). Biblioteki udostępniają asynchroniczne otoki dla żądań punktu końcowego OAuth2 oraz niezawodne funkcje obsługi tokenów, takie jak buforowanie i zarządzanie tokenami odświeżania. Aby uzyskać więcej informacji, w tym dokumentację referencyjną, pliki do pobrania biblioteki i przykładowy kod, zobacz Biblioteki uwierzytelniania firmy Microsoft.

2 Azure AD punktów końcowych, których będziesz używać do uwierzytelniania klienta i uzyskiwania tokenu dostępu, są określane jako OAuth2 /authorize i /token punkty końcowe. Sposób ich używania zależy od rejestracji aplikacji oraz typu przepływu udzielania autoryzacji OAuth2 potrzebnego do obsługi aplikacji w czasie wykonywania. Na potrzeby tego artykułu przyjęto założenie, że klient będzie używał jednego z następujących przepływów udzielania autoryzacji: kodu autoryzacji lub poświadczeń klienta. Postępuj zgodnie z instrukcjami dotyczącymi tego, który najlepiej pasuje do danego scenariusza, aby uzyskać token dostępu, który będzie używany w pozostałych sekcjach.

Udzielanie kodu autoryzacji (klienci interaktywni)

To przyznanie może być używane zarówno przez klientów internetowych, jak i natywnych, i wymaga poświadczeń od zalogowanego użytkownika w celu delegowania dostępu do zasobów do aplikacji klienckiej. Używa punktu końcowego /authorize do uzyskania kodu autoryzacji (w odpowiedzi na logowanie/wyrażenie zgody użytkownika), a następnie /token punktu końcowego w celu wymiany kodu autoryzacji dla tokenu dostępu.

Najpierw klient będzie musiał zażądać kodu autoryzacji z Azure AD. Zobacz Żądanie kodu autoryzacji , aby uzyskać szczegółowe informacje na temat formatu żądania HTTPS GET do /authorize punktu końcowego i przykładowych komunikatów żądania/odpowiedzi. Identyfikator URI będzie zawierać parametry ciągu zapytania, w tym następujące elementy specyficzne dla aplikacji klienckiej:
- client_id — znany również jako identyfikator aplikacji, jest to identyfikator GUID przypisany do aplikacji klienckiej po zarejestrowaniu się w powyższej sekcji
- redirect_uri — zakodowana pod adresem URL wersja [jednego z] identyfikatorów URI odpowiedzi/przekierowania określonych podczas rejestracji aplikacji klienckiej. Pamiętaj, że przekazana wartość musi być dokładnie zgodna z rejestracją!
- resource — identyfikator URI zakodowany w adresie URL określony przez wywoływany interfejs API REST. Interfejsy API sieci Web/REST (nazywane również aplikacjami zasobów) mogą uwidaczniać co najmniej jeden identyfikator URI identyfikatora aplikacji w konfiguracji. Przykład:
  - Interfejsy API dostawcy usługi Azure Resource Manager (i klasycznego zarządzania usługami) używająhttps://management.core.windows.net/
  - Aby uzyskać informacje o innych zasobach, zobacz dokumentację interfejsu API lub konfigurację aplikacji zasobów w Azure Portal. Aby uzyskać więcej informacji, zobacz również identifierUris właściwość obiektu aplikacji Azure AD.
Żądanie do punktu końcowego /authorize najpierw wyzwoli monit logowania w celu uwierzytelnienia użytkownika końcowego. Otrzymana odpowiedź zostanie dostarczona jako przekierowanie (302) do identyfikatora URI określonego w pliku redirect_uri. Komunikat nagłówka odpowiedzi będzie zawierać location pole zawierające identyfikator URI przekierowania, po którym code następuje parametr zapytania zawierający kod autoryzacji potrzebny w kroku 2.
Następnie klient będzie musiał zrealizować kod autoryzacji dla tokenu dostępu. Zobacz Używanie kodu autoryzacji do żądania tokenu dostępu, aby uzyskać szczegółowe informacje na temat formatu żądania HTTPS POST do punktu końcowego /token oraz przykładowych komunikatów żądania/odpowiedzi. Ponieważ jest to żądanie POST, tym razem spakujesz parametry specyficzne dla aplikacji w treści żądania. Oprócz niektórych wymienionych powyżej (wraz z innymi nowymi), przekażesz polecenie :
- code — jest to parametr zapytania, który będzie zawierać kod autoryzacji uzyskany w kroku 1.
- client_secret — ten parametr będzie potrzebny tylko wtedy, gdy klient jest skonfigurowany jako aplikacja internetowa. Jest to ta sama wartość wpisu tajnego/klucza wygenerowana wcześniej w rejestracji klienta.

Udzielanie poświadczeń klienta (klienci nieinterakcyjni)

To udzielenie może być używane tylko przez klientów internetowych, co umożliwia aplikacji bezpośredni dostęp do zasobów (bez delegowania użytkownika) przy użyciu własnych poświadczeń klienta, które są udostępniane w czasie rejestracji. Jest on zwykle używany przez nieinterakcyjnych klientów (bez interfejsu użytkownika) działających jako demon/usługa i wymaga tylko /token punktu końcowego do uzyskania tokenu dostępu.

Interakcje klienta/zasobu dla tego grantu są bardzo podobne do kroku 2 udzielania kodu autoryzacji. Zobacz sekcję "Żądanie tokenu dostępu" w temacie Service to service calls using client credentials (Żądania tokenu dostępu do wywołań usługi przy użyciu poświadczeń klienta ), aby uzyskać szczegółowe informacje na temat formatu żądania HTTPS POST do punktu końcowego /token oraz przykładowych komunikatów żądania/odpowiedzi.

Skompletuj komunikat żądania

Należy pamiętać, że większość języków programowania/struktur i środowisk skryptowych ułatwia tworzenie i wysyłanie komunikatu żądania. Zazwyczaj udostępniają one klasę internetową/http lub interfejs API, która abstrakcji tworzy/formatowanie żądania, co ułatwia pisanie kodu klienta (tj. klasy HttpWebRequest w .NET Framework, na przykład). W celu zwięzłości omówimy tylko ważne elementy żądania, biorąc pod uwagę, że większość z tych czynności będzie dla Ciebie obsługiwana.

Identyfikator URI żądania

Wszystkie zabezpieczone żądania REST wymagają protokołu HTTPS dla schematu identyfikatora URI, zapewniając żądanie i odpowiedź z bezpiecznym kanałem, ze względu na fakt, że poufne informacje są przesyłane/odbierane. Te informacje (tj. kod autoryzacji Azure AD, token dostępu/elementu nośnego, poufne dane żądania/odpowiedzi) są szyfrowane przez niższą warstwę transportu, zapewniając prywatność komunikatów.

Pozostała część identyfikatora URI żądania usługi (hosta, ścieżki zasobu i wszelkich wymaganych parametrów ciągu zapytania) zostanie określona przez powiązaną specyfikację interfejsu API REST. Na przykład interfejsy API dostawcy usługi Azure Resource Manager używają https://management.azure.com/klasycznych interfejsów https://management.core.windows.net/API usługi Azure Service Management , oba wymagają api-version parametru ciągu zapytania itp.

Nagłówek żądania

Identyfikator URI żądania zostanie dołączony do nagłówka komunikatu żądania wraz z dodatkowymi polami określonymi przez specyfikację interfejsu API REST usługi i specyfikację PROTOKOŁU HTTP. Poniżej przedstawiono kilka typowych pól nagłówków, które mogą być potrzebne w żądaniu:

Authorization: zawiera token elementu nośnego OAuth2 w celu zabezpieczenia żądania, jak nabyty wcześniej z Azure AD
Content-Type: zazwyczaj ustawiono wartość "application/json" (pary nazw/wartości w formacie JSON) i określa typ MIME treści żądania.
Host: jest to nazwa domeny lub adres IP serwera, na którym jest hostowany punkt końcowy usługi REST

Treść żądania

Jak wspomniano wcześniej, treść komunikatu żądania jest opcjonalna, w zależności od określonej operacji, której żądasz, i jej wymagań dotyczących parametrów. Jeśli jest to wymagane, specyfikacja interfejsu API dla żądanej usługi określi również kodowanie i format.

Treść żądania jest oddzielona od nagłówka pustym wierszem, powinna być sformatowana dla pola nagłówka Content-Type . Przykład sformatowanej treści "application/json" będzie wyświetlany w następujący sposób:

{
  "<name>": "<value>"
}

Wysyłanie żądania

Teraz, gdy masz identyfikator URI żądania usługi i utworzono powiązany nagłówek/treść komunikatu żądania, możesz wysłać żądanie do punktu końcowego usługi REST.

Na przykład metoda żądania HTTPS GET dla dostawcy usługi Azure Resource Manager może zostać wysłana przy użyciu pól nagłówka żądania podobnych do następujących, ale zwróć uwagę, że treść żądania jest pusta:

GET /subscriptions?api-version=2014-04-01-preview HTTP/1.1
Authorization: Bearer <bearer-token>
Host: management.azure.com

<no body>

Metoda żądania HTTPS PUT dla dostawcy usługi Azure Resource Manager może być wysyłana przy użyciu pól nagłówka i treści żądania podobnych do następujących:

PUT /subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/resourcegroups/ExampleResourceGroup?api-version=2016-02-01  HTTP/1.1
Authorization: Bearer <bearer-token>
Content-Length: 29
Content-Type: application/json
Host: management.azure.com

{
  "location": "West US"
}

Po wykonaniu żądania zostanie zwrócony nagłówek komunikatu odpowiedzi i opcjonalna treść.

Przetwarzanie komunikatu odpowiedzi

Teraz skończymy z ostatnimi 2 z 5 składników.

Aby przetworzyć odpowiedź, należy przeanalizować nagłówek odpowiedzi i opcjonalnie treść odpowiedzi (w zależności od żądania). W przykładzie HTTPS GET podanym powyżej użyliśmy punktu końcowego /subscriptions, aby pobrać listę subskrypcji dla użytkownika. Przy założeniu, że odpowiedź zakończyła się pomyślnie, powinniśmy otrzymywać pola nagłówka odpowiedzi podobne do następujących:

HTTP/1.1 200 OK
Content-Length: 303
Content-Type: application/json;

oraz treść odpowiedzi zawierająca listę subskrypcji platformy Azure i ich poszczególne właściwości zakodowane w formacie JSON, podobnie jak:

{
    "value":[
        {
        "id":"/subscriptions/04f09293-ce69-583a-a091-z06ea46dfb8c",
        "subscriptionId":"04f09293-ce69-583a-a091-z06ea46dfb8c",
        "displayName":"My Azure Subscription",
        "state":"Enabled",
        "subscriptionPolicies":{
            "locationPlacementId":"Public_2015-09-01",
            "quotaId":"MSDN_2014-05-01",
            "spendingLimit":"On"}
        }
    ]
}

Podobnie w przypadku przykładu HTTPS PUT powinniśmy otrzymać nagłówek odpowiedzi podobny do poniższego, potwierdzając, że nasza operacja PUT w celu dodania elementu "ExampleResourceGroup" zakończyła się pomyślnie:

HTTP/1.1 200 OK
Content-Length: 193
Content-Type: application/json;

oraz treść odpowiedzi, potwierdzając zawartość nowo dodanej grupy zasobów zakodowanej w formacie JSON, podobnie jak:

{
    "id":"/subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

Podobnie jak w przypadku żądania, większość języków programowania/platform ułatwia przetwarzanie komunikatu odpowiedzi. Zazwyczaj zwracają te informacje do aplikacji po żądaniu, umożliwiając przetwarzanie ich w formacie typowym/ustrukturyzowanym. Przede wszystkim interesuje Cię potwierdzenie kodu stanu HTTP w nagłówku odpowiedzi, a w przypadku niepowodzenia analizowania treści odpowiedzi zgodnie ze specyfikacją interfejsu API (lub Content-Type polami nagłówka odpowiedzi i).Content-Length

Gotowe. Po zarejestrowaniu aplikacji Azure AD i skomponowanej techniki uzyskiwania tokenu dostępu i tworzeniu i przetwarzaniu żądań HTTP można dość łatwo replikować kod, aby korzystać z nowych interfejsów API REST.

Aby uzyskać więcej informacji na temat rejestracji aplikacji i modelu programowania Azure AD, zobacz Platforma tożsamości Microsoft (Azure Active Directory dla deweloperów), w tym kompleksowy indeks artykułów HowTo i QuickStart oraz przykładowy kod.
Aby przetestować żądania HTTP/odpowiedzi, zapoznaj się z
- Fiddler. Fiddler to bezpłatny serwer proxy debugowania internetowego, który może przechwytywać żądania REST, co ułatwia diagnozowanie żądań HTTP i komunikatów odpowiedzi.
- Dekoder JWT i JWT.io, które ułatwiają szybkie i łatwe zrzuty oświadczeń w tokenie elementu nośnego, dzięki czemu można zweryfikować ich zawartość.

Skorzystaj z sekcji komentarzy LiveFyre, która jest zgodna z tym artykułem, aby przekazać opinię i pomóc nam uściślić i kształtować naszą zawartość.