Freigeben über

Azure REST-API-Referenz

  • Artikel

Willkommen bei der Azure REST-API-Referenz.

REST-APIs (Representational State Transfer) sind Dienstendpunkte, die Sätze von HTTP-Vorgängen (Methoden) unterstützen, die zugriff auf die Ressourcen des Diensts erstellen/abrufen/aktualisieren/löschen. Die folgenden Abschnitte führen Sie durch:

  • Die grundlegenden Komponenten eines REST-API-Anforderungs-/Antwortpaars
  • Registrieren Ihrer Clientanwendung bei Azure Active Directory (Azure AD) zum Schützen Ihrer REST-Anforderungen
  • Übersichten zum Erstellen und Senden einer REST-Anforderung sowie zum Behandeln der Antwort

Hinweis

Die meisten REST-APIs des Azure-Diensts verfügen über eine entsprechende Client-SDK-Bibliothek, die einen Großteil des Clientcodes für Sie verarbeitet. Thema

Azure .NET SDK
Azure Java SDK
Azure CLI 2.0 SDK

Komponenten einer REST-API-Anforderung/Antwort

Ein REST-API-Anforderungs-Antwort-Paar kann in fünf Komponenten unterteilt werden:

  1. Der Anforderungs-URI, der aus {URI-scheme} :// {URI-host} / {resource-path} ? {query-string} besteht. Beachten Sie, dass wir dies hier separat aufrufen, da die meisten Sprachen/Frameworks erfordern, dass Sie diese getrennt von der Anforderungsnachricht übergeben, aber sie ist tatsächlich im Anforderungsnachrichtenheader enthalten.
    • URI-Schema: Gibt das Protokoll an, das zum Übertragen der Anforderung verwendet wird. Zum Beispiel: http oder https.
    • URI-Host: Der Domänenname oder die IP-Adresse des Servers, auf dem der REST-Dienstendpunkt gehostet wird, z. B. graph.microsoft.com
    • Ressourcenpfad: Gibt die Ressourcen- oder Ressourcensammlung an, die mehrere Segmente enthalten kann, die vom Dienst zum Bestimmen der Auswahl dieser Ressourcen verwendet werden. Beispiel: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners kann verwendet werden, um die Liste der Besitzer einer bestimmten Anwendung innerhalb der Anwendungssammlung abzufragen.
    • Abfragezeichenfolge (optional): Wird verwendet, um zusätzliche einfache Parameter bereitzustellen, z. B. api-Version, Ressourcenauswahlkriterien usw.
  2. Headerfelder für HTTP-Anforderungsnachrichten
    • Eine erforderliche HTTP-Methode (auch als Vorgang oder Verb bezeichnet), die dem Dienst angibt, welche Art von Vorgang Sie anfordern. Azure REST-APIs unterstützen GET-, HEAD-, PUT-, POST- und PATCH-Methoden.
    • Optionale zusätzliche Headerfelder, wie für den angegebenen URI und die HTTP-Methode erforderlich. Beispielsweise ein Autorisierungsheader, der ein Bearertoken mit Clientautorisierungsinformationen für die Anforderung bereitstellt.
  3. Optionale Nachrichtentextfelder mit HTTP-Antworten zur Unterstützung des URI und des HTTP-Vorgangs. Beispielsweise enthalten POST-Vorgänge MIME-codierte Objekte, die als komplexe Parameter übergeben werden. Der MIME-Codierungstyp für den Text sollte auch im Anforderungsheader Content-type für POST/PUT-Vorgänge angegeben werden. Beachten Sie, dass für einige Dienste die Verwendung eines bestimmten MIME-Typs erforderlich ist, z application/json. B. .
  4. Headerfelder für HTTP-Antwortnachrichten
    • Ein HTTP-status Code, der von 2xx-Erfolgscodes bis zu 4xx/5xx-Fehlercodes reicht. Stattdessen kann auch, wie in der API-Dokumentation angegeben, ein Statuscode zurückgegeben werden, der für einen Dienst definiert ist.
    • Optionale zusätzliche Headerfelder nach Bedarf, um die Antwort der Anforderung zu unterstützen, z. B. einen Content-type Antwortheader.
  5. Optionale Felder für http-Antwortnachrichten
    • MIME-codierte Antwortobjekte können im HTTP-Antworttext zurückgegeben werden, z. B. eine Antwort von einer GET-Methode, die Daten zurückgibt. In der Regel werden diese in einem strukturierten Format als JSON oder XML zurückgegeben, wie durch den Content-type Antwortheader angegeben. Wenn Sie beispielsweise ein Zugriffstoken von Azure AD anfordern, wird es im Antworttext als access_token Element zurückgegeben, eines von mehreren Namen-Wert-paaren Objekten in einer Datensammlung. In diesem Beispiel wird auch ein Antwortheader von Content-Type: application/json eingeschlossen.

Registrieren Ihrer Clientanwendung bei Azure AD

Die meisten Azure-Dienste (z. B. Azure Resource Manager-Anbieter und die klassischen Dienstverwaltungs-APIs) erfordern die Authentifizierung Ihres Clientcodes mit gültigen Anmeldeinformationen, bevor Sie die API des Diensts aufrufen können. Die Authentifizierung wird zwischen den verschiedenen Akteuren von Azure AD koordiniert, wodurch Ihrem Client ein Zugriffstoken als Nachweis für die Authentifizierung/Autorisierung bereitgestellt wird. Das Token wird dann im HTTP-Autorisierungsheader aller nachfolgenden REST-API-Anforderungen an den Azure-Dienst gesendet. Die Ansprüche des Tokens stellen auch Informationen für den Dienst bereit, sodass er den Client überprüfen und alle erforderlichen Autorisierungen ausführen kann.

Wenn Sie eine REST-API verwenden, die keine integrierte Azure AD-Authentifizierung verwendet, oder Wenn Sie Ihren Client bereits registriert haben, können Sie mit dem Abschnitt Erstellen der Anforderung fortfahren.

Voraussetzungen

Ihre Clientanwendung muss ihre Identitätskonfiguration azure AD vor der Laufzeit bekannt machen, indem sie in einem Azure AD-Mandanten registriert wird. Im Folgenden finden Sie eine Liste der Punkte, die Sie berücksichtigen sollten, bevor Sie Ihren Client bei Azure AD registrieren:

  • Wenn Sie noch keinen Azure AD-Mandanten haben, finden Sie weitere Informationen unter Abrufen eines Azure Active Directory-Mandanten.
  • Gemäß dem OAuth2-Autorisierungsframework unterstützt Azure AD zwei Arten von Clients. Wenn Sie die einzelnen Informationen verstehen, können Sie entscheiden, welches für Ihr Szenario am besten geeignet ist:
    • Web-/vertrauliche Clients (wird auf einem Webserver ausgeführt) können entweder unter ihrer eigenen Identität (d. h. Dienst/Daemon) auf Ressourcen zugreifen oder delegierte Autorisierung für den Zugriff auf Ressourcen unter der Identität des angemeldeten Benutzers (d. h. Web-App) erhalten. Nur ein Webclient kann seine eigenen Anmeldeinformationen während der Azure AD-Authentifizierung sicher verwalten und präsentieren, um ein Zugriffstoken abzurufen.
    • native/öffentliche Clients (installiert/ausgeführt auf einem Gerät) können nur unter delegierter Autorisierung auf Ressourcen zugreifen, wobei die Identität des angemeldeten Benutzers verwendet wird, um im Namen des Benutzers ein Zugriffstoken abzurufen.
  • Der Registrierungsprozess erstellt 2 verwandte Objekte im Azure AD-Mandanten, in dem die Anwendung registriert ist: ein Anwendungsobjekt und ein Dienstprinzipalobjekt. Weitere Informationen zu diesen Komponenten und deren Verwendung zur Laufzeit finden Sie unter Anwendungs- und Dienstprinzipalobjekte in Azure Active Directory.

Jetzt können wir Ihre Clientanwendung bei Azure AD registrieren.

Clientregistrierung

Informationen zum Registrieren eines Clients, der auf eine Azure Resource Manager REST-API zugreift, finden Sie unter Verwenden des Portals zum Erstellen einer Active Directory-Anwendung und eines Dienstprinzipals, der auf Ressourcen zugreifen kann, eine Schritt-für-Schritt-Registrierungsanleitung. In diesem Artikel (auch in PowerShell- und CLI-Versionen für die Automatisierung der Registrierung verfügbar) erfahren Sie, wie Sie:

  • Registrieren der Clientanwendung bei Azure AD
  • Festlegen von Berechtigungsanforderungen, damit der Client auf die Azure Resource Manager-API zugreifen kann
  • Konfigurieren der RBAC-Einstellungen (Role Based Access Control) von Azure Resource Manager zum Autorisieren des Clients

Informationen zu allen anderen Clients finden Sie unter Integrieren von Anwendungen in Azure Active Directory. In diesem Artikel wird Folgendes gezeigt:

  • Registrieren der Clientanwendung bei Azure AD im Abschnitt "Hinzufügen einer Anwendung"
  • erstellen Sie einen geheimen Schlüssel (wenn Sie einen Webclient registrieren), im Abschnitt "Aktualisieren einer Anwendung"
  • Hinzufügen von Berechtigungsanforderungen gemäß den Anforderungen der API im Abschnitt "Aktualisieren einer Anwendung"

Nachdem Sie die Registrierung Ihrer Clientanwendung abgeschlossen haben, können wir zu Ihrem Clientcode wechseln, wo Sie die REST-Anforderung erstellen und die Antwort verarbeiten.

Erstellen der Anforderung

In diesem Abschnitt werden die ersten 3 der 5 Komponenten behandelt, die wir zuvor erläutert haben. Zuerst müssen wir das Zugriffstoken von Azure AD abrufen, das wir zum Zusammenstellen des Anforderungsnachrichtenheaders verwenden.

Abrufen eines Zugriffstokens

Sobald Sie über eine gültige Clientregistrierung verfügen, gibt es im Wesentlichen zwei Möglichkeiten, ein Zugriffstoken in Azure AD zu integrieren:

  • Plattform-/sprachneutrale OAuth2-Dienstendpunkte von Azure AD, die wir verwenden werden. Genau wie die Azure REST-API-Endpunkte, die Sie verwenden, treffen die Anweisungen in diesem Abschnitt keine Annahmen über die Plattform oder sprache/das Skript Ihres Clients, wenn Sie die Azure AD-Endpunkte verwenden. nur, dass https-Anforderungen an/von Azure AD gesendet/empfangen und die Antwortnachricht analysiert werden kann.
  • Die plattform-/sprachspezifischen Microsoft-Authentifizierungsbibliotheken (MSAL). Die Bibliotheken stellen asynchrone Wrapper für die OAuth2-Endpunktanforderungen und robuste Tokenbehandlungsfeatures wie zwischenspeichern und aktualisieren von Token bereit. Weitere Informationen, einschließlich Referenzdokumentation, Bibliotheksdownloads und Beispielcode, finden Sie unter Microsoft-Authentifizierungsbibliotheken.

Die zwei Azure AD-Endpunkte, die Sie zum Authentifizieren Ihres Clients und zum Abrufen eines Zugriffstokens verwenden, werden als OAuth2 /authorize - und /token Endpunkte bezeichnet. Wie Sie sie verwenden, hängt von der Registrierung Ihrer Anwendung und dem Typ des OAuth2-Autorisierungserteilungsflows ab, den Sie benötigen, um Ihre Anwendung zur Laufzeit zu unterstützen. Für die Zwecke dieses Artikels wird davon ausgegangen, dass Ihr Client einen der folgenden Autorisierungsgenehmigungsflows verwendet: Autorisierungscode oder Clientanmeldeinformationen. Befolgen Sie die Anweisungen für das, das ihrem Szenario am besten entspricht, um das Zugriffstoken abzurufen, das Sie in den verbleibenden Abschnitten verwenden werden.

Autorisierungscodezuweisung (interaktive Clients)

Diese Gewährung kann sowohl von Web- als auch von nativen Clients verwendet werden und erfordert Anmeldeinformationen eines angemeldeten Benutzers, um den Ressourcenzugriff an die Clientanwendung zu delegieren. Es verwendet den /authorize Endpunkt, um einen Autorisierungscode (als Reaktion auf die Benutzeranmeldung/-zustimmung) abzurufen, gefolgt vom /token Endpunkt, um den Autorisierungscode gegen ein Zugriffstoken auszutauschen.

  1. Zuerst muss Ihr Client einen Autorisierungscode von Azure AD anfordern. Ausführliche Informationen zum Format der HTTPS GET-Anforderung an den /authorize Endpunkt sowie Beispiel-Anforderungs-/Antwortnachrichten finden Sie unter Anfordern eines Autorisierungscodes. Der URI enthält Abfragezeichenfolgenparameter, einschließlich der folgenden Parameter, die für Ihre Clientanwendung spezifisch sind:

    • client_id – auch als Anwendungs-ID bezeichnet. Dies ist die GUID, die Ihrer Clientanwendung zugewiesen wurde, als Sie sich im obigen Abschnitt registriert haben.

    • redirect_uri – eine URL-codierte Version von [eine der] Antwort-/Umleitungs-URIs, die bei der Registrierung Ihrer Clientanwendung angegeben wurden. Beachten Sie, dass der übergebene Wert genau mit Ihrer Registrierung übereinstimmen muss!

    • resource – ein URL-codierter Bezeichner-URI, der von der VON Ihnen aufgerufenen REST-API angegeben wird. Web-/REST-APIs (auch als Ressourcenanwendungen bezeichnet) können eine oder mehrere Anwendungs-ID-URIs in ihrer Konfiguration verfügbar machen. Beispiel:

      • Verwendung von Azure Resource Manager-Anbieter-APIs (und klassischen Dienstverwaltungs-APIs)https://management.core.windows.net/
      • Weitere Ressourcen finden Sie in der API-Dokumentation oder in der Konfiguration der Ressourcenanwendung im Azure-Portal. Weitere Details finden Sie auch in der identifierUris -Eigenschaft des Azure AD-Anwendungsobjekts.

    Die Anforderung an den /authorize Endpunkt löst zunächst eine Anmeldeaufforderung zur Authentifizierung des Endbenutzers aus. Die zurückgegebene Antwort wird als Umleitung (302) an den URI übermittelt, den Sie in redirect_uriangegeben haben. Die Antwortheadernachricht enthält ein location Feld, das den Umleitungs-URI gefolgt von einem code Abfrageparameter enthält, der den Autorisierungscode enthält, den Sie für Schritt 2 benötigen.

  2. Als Nächstes muss Ihr Client den Autorisierungscode für ein Zugriffstoken einlösen. Ausführliche Informationen zum Format der HTTPS POST-Anforderung an den /token Endpunkt sowie Beispiel-Anforderungs-/Antwortnachrichten finden Sie unter Verwenden des Autorisierungscodes zum Anfordern eines Zugriffstokens. Da es sich um eine POST-Anforderung handelt, packen Sie diesmal Ihre anwendungsspezifischen Parameter im Anforderungstext. Zusätzlich zu einigen der oben genannten (zusammen mit anderen neuen) werden Sie passieren:

    • code : Dies ist der Abfrageparameter, der den Autorisierungscode enthält, den Sie in Schritt 1 erhalten haben.
    • client_secret – Sie benötigen diesen Parameter nur, wenn Ihr Client als Webanwendung konfiguriert ist. Dies ist derselbe Geheimnis-/Schlüsselwert, den Sie zuvor in der Clientregistrierung generiert haben.

Gewährung von Clientanmeldeinformationen (nicht interaktive Clients)

Diese Gewährung kann nur von Webclients verwendet werden, sodass die Anwendung direkt auf Ressourcen zugreifen kann (keine Benutzerdelegierung), indem sie die anmeldeinformationen des Clients verwendet, die zum Zeitpunkt der Registrierung bereitgestellt werden. Es wird in der Regel von nicht interaktiven Clients (keine Benutzeroberfläche) verwendet, die als Daemon/Dienst ausgeführt werden, und erfordert, dass nur der /token Endpunkt ein Zugriffstoken abruft.

Die Client-/Ressourceninteraktionen für diese Gewährung ähneln sehr schritt 2 der Autorisierungscodezuweisung. Im Abschnitt "Anfordern eines Zugriffstokens" unter Dienst-zu-Dienst-Aufrufe mit Clientanmeldeinformationen finden Sie Details zum Format der HTTPS POST-Anforderung an den /token Endpunkt sowie Beispiel-Anforderungs-/Antwortnachrichten.

Zusammenstellen der Anforderungsnachricht

Beachten Sie, dass die meisten Programmiersprachen/Frameworks und Skriptumgebungen das Zusammenstellen und Senden der Anforderungsnachricht vereinfachen. Sie stellen in der Regel eine Web-/HTTP-Klasse oder API bereit, die die Erstellung/Formatierung der Anforderung abstrahiert, sodass der Clientcode einfacher geschrieben werden kann (z. B. die HttpWebRequest-Klasse im .NET Framework). Aus Gründen der Kürze werden wir nur die wichtigen Elemente der Anfrage behandeln, da die meisten davon für Sie behandelt werden.

Anforderungs-URI

Alle gesicherten REST-Anforderungen erfordern das HTTPS-Protokoll für das URI-Schema, das die Anforderung und die Antwort mit einem sicheren Kanal bereitstellt, da vertrauliche Informationen übertragen/empfangen werden. Diese Informationen (d. h. azure AD-Autorisierungscode, Zugriffs-/Bearertoken, vertrauliche Anforderungs-/Antwortdaten) werden durch eine niedrigere Transportebene verschlüsselt, wodurch der Datenschutz der Nachrichten gewährleistet wird.

Der Rest des Anforderungs-URI Ihres Diensts (Host, Ressourcenpfad und alle erforderlichen Abfragezeichenfolgenparameter) wird durch die zugehörige REST-API-Spezifikation bestimmt. Beispielsweise verwenden https://management.azure.com/Azure Resource Manager-Anbieter-APIs , klassische Azure Service Management-APIs verwenden https://management.core.windows.net/, beide erfordern einen api-version Abfragezeichenfolgenparameter usw.

Anforderungsheader

Der Anforderungs-URI wird im Anforderungsnachrichtenheader zusammen mit allen zusätzlichen Feldern gebündelt, die durch die REST-API-Spezifikation Ihres Diensts und die HTTP-Spezifikation bestimmt werden. Im Folgenden finden Sie einige allgemeine Headerfelder, die Sie möglicherweise in Ihrer Anforderung benötigen:

  • Authorization: enthält das OAuth2-Bearertoken zum Sichern der Anforderung, wie es zuvor von Azure AD abgerufen wurde.
  • Content-Type: in der Regel auf "application/json" (Name/Wert-Paare im JSON-Format) festgelegt und gibt den MIME-Typ des Anforderungstexts an.
  • Host: Dies ist der Domänenname oder die IP-Adresse des Servers, auf dem der REST-Dienstendpunkt gehostet wird.

Anforderungstext

Wie bereits erwähnt, ist der Anforderungsnachrichtentext optional, je nach dem von Ihnen angeforderten vorgang und den Parameteranforderungen. Wenn dies erforderlich ist, gibt die API-Spezifikation für den von Ihnen angeforderten Dienst auch die Codierung und das Format an.

Der Anforderungstext wird durch eine leere Zeile vom Header getrennt und sollte entsprechend dem Content-Type Headerfeld formatiert werden. Ein Beispiel für einen "application/json"-formatierten Text würde wie folgt angezeigt:

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

Senden der Anforderung

Nachdem Sie nun über den Anforderungs-URI des Diensts verfügen und den zugehörigen Header/Text der Anforderungsnachricht erstellt haben, können Sie die Anforderung an den REST-Dienstendpunkt senden.

Beispielsweise kann eine HTTPS GET-Anforderungsmethode für einen Azure Resource Manager-Anbieter mithilfe von Anforderungsheaderfeldern ähnlich den folgenden gesendet werden. Beachten Sie jedoch, dass der Anforderungstext leer ist:

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

<no body>

Und eine HTTPS PUT-Anforderungsmethode für einen Azure Resource Manager-Anbieter kann mithilfe von Anforderungsheader- UND Textfeldern ähnlich den folgenden gesendet werden:

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"
}

Nachdem Sie die Anforderung gestellt haben, werden der Header der Antwortnachricht und der optionale Text zurückgegeben.

Verarbeiten der Antwortnachricht

Nun werden die letzten 2 der 5 Komponenten abgeschlossen.

Um die Antwort zu verarbeiten, müssen Sie den Antwortheader und optional den Antworttext analysieren (abhängig von der Anforderung). Im obigen HTTPS GET-Beispiel haben wir den Endpunkt /subscriptions verwendet, um die Liste der Abonnements für einen Benutzer abzurufen. Wenn die Antwort erfolgreich war, sollten wir Antwortheaderfelder ähnlich den folgenden erhalten:

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

und einen Antworttext mit der Liste der Azure-Abonnements und deren individuellen Eigenschaften, die im JSON-Format codiert sind, ähnlich wie:

{
    "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"}
        }
    ]
}

Entsprechend sollten wir für das HTTPS PUT-Beispiel einen Antwortheader ähnlich dem folgenden erhalten, der bestätigt, dass der PUT-Vorgang zum Hinzufügen von "ExampleResourceGroup" erfolgreich war:

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

und einen Antworttext, der den Inhalt der neu hinzugefügten Ressourcengruppe bestätigt, die im JSON-Format codiert ist, ähnlich wie:

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

Wie bei der Anforderung erleichtern die meisten Programmiersprachen/Frameworks die Verarbeitung der Antwortnachricht. Sie geben diese Informationen in der Regel nach der Anforderung an Ihre Anwendung zurück, sodass Sie sie in einem typisierten/strukturierten Format verarbeiten können. In erster Linie werden Sie daran interessiert sein, den HTTP-status Code im Antwortheader zu bestätigen, und wenn erfolgreich, den Antworttext gemäß der API-Spezifikation (oder den Content-Type Antwortheadernfeldern und Content-Length ) zu analysieren.

Das ist alles! Nachdem Sie Ihre Azure AD-Anwendung registriert haben und eine integrierte Technik zum Abrufen eines Zugriffstokens und zum Erstellen und Verarbeiten von HTTP-Anforderungen vorhanden sind, ist es ziemlich einfach, Ihren Code zu replizieren, um neue REST-APIs zu nutzen.

Verwandter Inhalt

  • Weitere Informationen zur Anwendungsregistrierung und zum Azure AD-Programmiermodell finden Sie unter Microsoft Identity Platform (Azure Active Directory für Entwickler), einschließlich eines umfassenden Indexes von HowTo- und Schnellstartartikeln sowie Beispielcode.
  • Informationen zum Testen von HTTP-Anforderungen/-antworten finden Sie unter
    • Fiddler. Fiddler ist ein kostenloser Webdebuggenproxy, der Ihre REST-Anforderungen abfangen kann, sodass die Diagnose der HTTP-Anforderungs- und Antwortnachrichten einfach ist.
    • JWT-Decoder und JWT.io, mit denen Sie die Ansprüche schnell und einfach in Ihrem Bearertoken speichern können, damit Sie deren Inhalt überprüfen können.

Verwenden Sie den LiveFyre-Kommentarabschnitt, der auf diesen Artikel folgt, um Feedback zu geben und uns dabei zu helfen, unsere Inhalte zu verfeinern und zu gestalten.