Übersicht über die Vorgänge | Graph-API-Konzepte

  • Artikel

Die Azure AD (Active Directory) Graph-API ist ein mit OData 3.0 kompatibler Dienst, den Sie zum Lesen und Ändern von Objekten, z. B. Benutzer, Gruppen und Kontakte in einem Mandanten, verwenden können. Die Azure AD Graph-API macht REST-Endpunkte, an die Sie HTTP-Anforderungen senden, verfügbar, um Vorgänge mit dem Dienst auszuführen. Die folgenden Abschnitte enthalten allgemeine Informationen zum Formatieren von Anforderungen und zum Inhalt der Antworten, wenn Sie die Graph-API zum Lesen und Schreiben von Verzeichnisressourcen, zum Aufrufen von Verzeichnisfunktionen oder -aktionen oder zum Ausführen von Abfragen des Verzeichnisses verwenden. Ausführlichere Informationen zum Ausführen bestimmter Vorgänge für Verzeichnisressourcen finden Sie im Thema zum entsprechenden Vorgang in der Referenz zur Azure AD Graph-API.

Wichtig

Es wird dringend empfohlen, für den Zugriff auf Azure Active Directory-Ressourcen Microsoft Graph zu verwenden, nicht die Azure AD Graph-API. Wir konzentrieren unsere Entwicklungsarbeit auf Microsoft Graph, weitere Verbesserungen für die Azure AD Graph-API sind nicht geplant. Es gibt einige wenige Szenarien, in denen die Azure AD Graph-API möglicherweise noch geeignet ist. Weitere Informationen finden Sie im Office Dev Center im Blogbeitrag Microsoft Graph or the Azure AD Graph.

Eine erfolgreiche Anforderung an die Graph-API muss an einen gültigen Endpunkt gerichtet und ordnungsgemäß formatiert sein, d. h., sie muss alle erforderlichen Header und ggf. eine JSON-Nutzlast im Anforderungstext enthalten. Die App, von der die Anforderung ausgeführt wird, muss ein von Azure AD empfangenes Token enthalten, das nachweist, dass sie zum Zugriff auf die für die Anforderung benötigten Ressourcen berechtigt ist. Die App muss alle Antworten verarbeiten können, die sie von der Graph-API empfängt.

In den Abschnitten dieses Themas wird Ihnen das Format der mit der Graph-API verwendeten Anforderungen und Antworten erläutert.

Authentifizierung und Autorisierung

An jede Anforderung an die Graph-API muss ein von Azure Active Directory ausgestelltes Trägertoken angefügt sein. Das Token enthält Informationen über die App, den angemeldeten Benutzer (im Fall von delegierten Berechtigungen), Authentifizierung und die Vorgänge für das Verzeichnis, zu deren Ausführung die App berechtigt ist. Dieses Token wird im Authorization-Header der Anforderung übertragen. Beispiel (aus Gründen der Übersichtlichkeit wird nur ein Teil des Tokens dargestellt):

Authorization: Bearer eyJ0eX ... FWSXfwtQ

Der Graph-API führt die Autorisierung basierend auf den OAuth 2.0-Berechtigungsbereichen im Token aus. Weitere Informationen zu den Berechtigungsbereichen, die von der Graph-API verfügbar gemacht werden, finden Sie unter Berechtigungsbereiche | Graph-API-Konzepte.

Damit die App bei Azure AD authentifiziert wird und die Graph-API aufruft, müssen Sie sie dem Mandanten hinzufügen und sie so konfigurieren, dass sie Berechtigungen (OAuth 2.0-Berechtigungsbereiche) für Windows Azure Active Directory erfordert. Informationen zum Hinzufügen und Konfigurieren einer App finden Sie unter Integrieren von Anwendungen in Azure Active Directory.

Azure AD verwendet das OAuth 2.0-Authentifizierungsprotokoll. Weitere Informationen zu OAuth 2.0 in Azure AD, einschließlich der unterstützten Datenflüsse und Zugriffstoken, finden Sie unter OAuth 2.0 in Azure AD.

Endpunktadressierung

Zum Ausführen von Vorgängen mit der Graph-API senden Sie mit einer unterstützten Methode – in der Regel GET, POST, PATCH, PUT oder DELETE – HTTP-Anforderungen an einen Endpunkt für den Dienst, für eine Ressourcensammlung, für eine einzelne Ressource, für eine Navigationseigenschaft einer Ressource oder für eine vom Dienst verfügbar gemachte Funktion oder Aktion. Endpunkte werden als URLs angegeben.

Im Folgenden wird das grundlegende Format eines Graph-API-Endpunkts beschrieben:

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}

Die URL besteht aus den folgenden Komponenten:

  • Dienststamm: Der Dienststamm für alle Graph-API-Anforderungen lautet https://graph.windows.net.
  • Mandantenbezeichner {tenant_id}: Der Bezeichner für den Mandanten, an den die Anforderung gerichtet ist.
  • Ressourcenpfad {resource_path}: Der Pfad zur Ressource, z. B. ein Benutzer oder eine Gruppe, an die die Anforderung gerichtet ist.
  • Graph-API-Version {ppi_version}: Die Version der Graph-API, an die die Anforderung gerichtet ist. Diese wird als Abfrageparameter angegeben und ist erforderlich.

Hinweis: In einigen Fällen können beim Lesen von Ressourcensammlungen OData-Abfrageparameter zur Abfrage hinzugefügt werden, um das Resultset zu filtern, zu sortieren und zu paginieren. Weitere Informationen finden Sie im Abschnitt OData-Abfrageparameter dieses Themas.

Mandantenbezeichner {tenant_id}

Sie können den Zielmandanten einer Anforderung auf eine von vier Arten angeben:

  • Anhand der Objekt-ID des Mandanten. Die GUID, die beim Erstellen des Mandanten zugewiesen wurde. Sie finden diese in der objectId-Eigenschaft des TenantDetail-Objekts. Die folgende URL zeigt, wie die users-Ressourcensammlung mit der Objekt-ID des Mandanten adressiert wird:
    https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.

  • Anhand des überprüften (registrierten) Domänennamens. Einer der Domänennamen, die für den Mandanten registriert sind. Sie finden diese in der verifiedDomains-Eigenschaft des TenantDetail-Objekts. Die folgende URL zeigt, wie die users-Ressourcensammlung eines Mandanten mit der Domäne „contoso.com“ adressiert wird:
    https://graph.windows.net/contoso.com/users?api-version=1.6.

  • Durch Verwenden des Alias myOrganization. Dieser Alias ist nur verfügbar, wenn Authentifizierung vom Typ OAuth Authorization Code Grant (dreiteilig), d. h. ein delegierter Berechtigungsbereich, verwendet wird. Beim Alias wird nicht zwischen Groß- und Kleinschreibung unterschieden. Er ersetzt die Objekt-ID oder die Mandantendomäne in der URL. Wenn der Alias verwendet wird, leitet die Graph-API den Mandanten von den Ansprüchen ab, die im Token bereitgestellt werden, das an die Anforderung angefügt ist. Die folgende URL zeigt, wie die users-Ressourcensammlung eines Mandanten mit diesem Alias adressiert wird:
    https://graph.windows.net/myorganization/users?api-version=1.6.

  • Durch Verwenden des Alias me. Dieser Alias ist nur verfügbar, wenn Authentifizierung vom Typ OAuth Authorization Code Grant (dreiteilig), d. h. ein delegierter Berechtigungsbereich, verwendet wird. Beim Alias wird nicht zwischen Groß- und Kleinschreibung unterschieden. Er ersetzt die Objekt-ID oder die Mandantendomäne in der URL. Wenn der Alias verwendet wird, leitet die Graph-API den Benutzer von den Ansprüchen ab, die im Token bereitgestellt werden, das an die Anforderung angefügt ist. Die folgende URL zeigt, wie der angemeldete Benutzer mit diesem Alias adressiert wird:
    https://graph.windows.net/me?api-version=1.6.

Hinweis: Sie verwenden den Alias me nur, wenn das Ziel Vorgänge für den angemeldeten Benutzer sind. Weitere Informationen finden Sie unter Vorgänge für den angemeldeten Benutzer.

Ressourcenpfad {resource_path}

Der Ressourcenpfad, den Sie in {resource_path} angeben, hängt davon ab, ob das Ziel eine Ressourcensammlung, eine einzelne Ressource, eine Navigationseigenschaft einer Ressource, eine für den Mandanten verfügbar gemachte Funktion oder Aktion oder eine für eine Ressource verfügbar gemachte Funktion oder Aktion ist.

Ziel Pfad Erläuterung
Dienstmetadaten /$metadata Gibt das Dienstmetadatendokument zurück. Im folgenden Beispiel werden mit dem Mandanten „contoso.com“ Dienstmetadaten als Ziel verwendet.
https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Hinweis: Zum Lesen der Dienstmetadaten ist keine Authentifizierung erforderlich.
Ressourcensammlung /{resource_collection} Das Ziel ist eine Ressourcensammlung, z. B. Benutzer oder Gruppen im Mandanten. Sie können diesen Pfad zum Lesen von Ressourcen in der Sammlung und je nach Ressourcentyp zum Erstellen einer neuen Ressource im Mandanten verwenden. In vielen Fällen kann das durch einen Lesevorgang zurückgegebene Resultset weiter optimiert werden, indem Abfrageparameter zum Filtern, Sortieren oder Paginieren der Ergebnisse hinzugefügt werden. Im folgenden Beispiel ist das Ziel die Benutzersammlung.
https://graph.windows.net/myorganization/users?api-version=1.6
Einzelne Ressource /{resource_collection}/{resource_id} Das Ziel ist eine bestimmte Ressource in einem Mandanten, z. B. ein Benutzer, ein Organisationskontakt oder eine Gruppe. Für die meisten Ressourcen ist die resource_id die Objekt-ID. Einige Ressourcen lassen zusätzliche Bezeichner zu. Beispielsweise können Benutzer auch durch den Benutzerprinzipalnamen (User Principal Name, UPN) angegeben werden. Abhängig von der Ressource können Sie diesen Pfad zum Abrufen der deklarierten Eigenschaften der Ressource, zum Ändern ihrer deklarierten Eigenschaften oder zum Löschen der Ressource verwenden. Im folgenden Beispiel ist das Ziel der Benutzer john@contoso.com:.
https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6
Navigationseigenschaft (Objekte) /{resource_collection}/{resource_id}/{property_name} Das Ziel ist eine Navigationseigenschaft einer bestimmten Ressource, z. B. der Vorgesetzte eines Benutzers, Gruppenmitgliedschaften oder die Mitglieder einer Gruppe. Sie können diesen Pfad verwenden, um das Objekt oder die Objekte zurückzugeben, auf das bzw. die von der Zielnavigationseigenschaft verwiesen wird. Im folgenden Beispiel ist das Ziel der Vorgesetzte von john@contoso.com:.
https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6

Hinweis: Diese Form der Adressierung ist nur für Lesevorgänge verfügbar.
Navigationseigenschaft (Links) /{resource_collection}/{resource_id}/$links/{property_name} Das Ziel ist eine Navigationseigenschaft einer bestimmten Ressource, z. B. der Vorgesetzte eines Benutzers, Gruppenmitgliedschaften oder die Mitglieder einer Gruppe. Sie können diese Form der Adressierung für Lesevorgänge und zum Ändern einer Navigationseigenschaft verwenden. Bei Lesevorgängen werden Objekte, auf die von der Eigenschaft verwiesen wird, als einer oder mehrere Links im Antworttext zurückgegeben. Bei Schreibvorgängen werden die Objekte als einer oder mehrere Links im Anforderungstext angegeben. Im folgenden Beispiel ist das Ziel der Eigenschaft des Vorgesetzten von john@contoso.com:.
https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6
Funktionen oder Aktionen, die für den Mandanten verfügbar gemacht werden /{function_name} Das Ziel ist eine Funktion oder Aktion, die für den Mandanten verfügbar gemacht wird. Funktionen und Aktionen werden in der Regel mit einer POST-Anforderung aufgerufen und können einen Anforderungstext enthalten. Im folgenden Beispiel ist das Ziel die isMemberOf-Funktion:
https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.
Funktionen oder Aktionen, die für eine Ressource verfügbar gemacht werden. /{resource_collection}/{resource_id}/{function_name} Das Ziel ist eine Funktion oder Aktion, die für eine Ressource verfügbar gemacht wird. Funktionen und Aktionen werden in der Regel mit einer POST-Anforderung aufgerufen und können einen Anforderungstext enthalten. Im folgenden Beispiel ist das Ziel die getMemberGroups-Funktion:
https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.

Graph-API-Version {api-version}

Sie verwenden den api-version-Abfrageparameter zum Abfragen einer bestimmten Version der Graph-API für einen Vorgang. Dieser Parameter ist erforderlich.

Der api-version-Parameter kann einen der folgenden Werte aufweisen:

  • beta
  • 1.6
  • 1.5
  • 2013/11/08
  • 2013/04/05

Beispielsweise gibt die folgende URL die Benutzersammlung mit Version 1.6 der Graph-API an:

https://graph.windows.net/myorganization/users?api-version=1.6

Weitere Informationen zu Versionen und Featureänderungen zwischen den Versionen finden Sie unter Versionsverwaltung.

OData-Abfrageparameter

In vielen Fällen können Sie beim Lesen einer Sammlung von Ressourcen das Resultset filtern, sortieren und paginieren, indem Sie OData-Abfrageparameter an die Anforderung anfügen.

Die Graph-API unterstützt die folgenden OData-Abfrageparameter:

  • $filter
  • $batch
  • $expand
  • $orderby
  • $top
  • $skiptoken und previous-page

Weitere Informationen zu den unterstützten OData-Abfrageparametern und ihren Beschränkungen in der Graph-API finden Sie unter Unterstützte Abfragen, Filter und Paginierungsoptionen.

Anforderungs- und Antwortheader

In der folgenden Tabelle sind allgemeine HTTP-Header aufgeführt, die in Abfragen mit der Graph-API verwendet werden. Es werden allerdings nicht alle Einschränkungen genannt.

Anforderungsheader Beschreibung
Autorisierung Erforderlich. Ein Trägertoken, das von Azure Active Directory ausgestellt wird. Weitere Informationen finden Sie unter Authentifizierung und Autorisierung in diesem Thema.
Content-Type Erforderlich, wenn Anforderungstext vorhanden ist. Der Medientyp des Inhalts im Anforderungstext. Verwenden Sie „application/json“. Parameter können ggf. mit dem Medientyp angegeben werden.
Hinweis: „application/atom+xml“ und „application/xml“ (für Links) werden unterstützt, jedoch nicht empfohlen, und zwar aus Leistungsgründen und weil XML in einer zukünftigen Version nicht mehr unterstützt wird.
Content-Length Erforderlich, wenn Anforderungstext vorhanden ist. Die Länge der Anforderung in Bytes.

In der folgenden Tabelle sind allgemeine HTTP-Header aufgeführt, die in Antworten von der Graph-API zurückgegeben werden. Es werden allerdings nicht alle Einschränkungen genannt.

Antwortheader Beschreibung
Content-Type Der Medientyp des Inhalts im Antworttext. Der Standardwert ist „application/json“. Anforderungen von Benutzerminiaturfotos geben standardmäßig „image/jpeg“ zurück.
Standort Wird in Antworten auf POST-Anforderungen zurückgegeben, durch die eine neue Ressource (Objekt) im Verzeichnis erstellt wird. Enthält den URI der neu erstellten Ressource.
ocp-aad-diagnostics-server-name Der Bezeichner für den Server, der den angeforderten Vorgang ausgeführt hat.
ocp-aad-session-key Der Schlüssel, der die aktuelle Sitzung mit dem Verzeichnisdienst identifiziert.

Es wird empfohlen, für jede Anforderung mindestens die folgenden Aktionen auszuführen:

  1. Protokollieren Sie einen genauen Zeitstempel für die Übermittlung der Anforderung.
  2. Senden und protokollieren Sie die client-request-id.
  3. Protokollieren Sie den HTTP-Antwortcode und die request-id.

Anhand der Informationen in diesen Protokollen kann Microsoft Probleme leichter beheben, wenn Sie Hilfe oder Unterstützung anfordern.

Anforderungs- und Antworttext

Anforderungstext für POST-, PATCH- und PUT-Anforderungen können in JSON- oder XML-Nutzlasten gesendet werden. Die Serverantworten können in JSON- oder XML-Nutzlasten zurückgegeben werden. Sie können die Nutzlast im Anforderungstext mit dem Content-Type-Anforderungsheader und in Antworten mit dem Accept-Anforderungsheader angeben.

Es wird dringend empfohlen, in Anforderungen und Antworten mit der Graph-API JSON-Nutzlasten zu verwenden. Die Empfehlung erfolgt aus Leistungsgründen und weil XML in einer zukünftigen Version nicht mehr unterstützt wird.

Erweiterte Features

In den vorherigen Abschnitten wurde das Formatieren der grundlegenden Anforderungen und Antworten mit der Graph-API erläutert. Durch erweiterte Features werden möglicherweise zusätzliche Abfragezeichenfolgenparameter hinzugefügt, oder sie bewirken, dass sie einen erheblich anderen Anforderungs- und Antworttext als die grundlegenden Vorgänge aufweisen, die weiter oben in diesem Artikel erläutert wurden.

Zu diesen Funktionen gehören:

  • Batchverarbeitung: Die Graph-API unterstützt Batchverarbeitung. Das Senden von Anforderungen in Batches verringert die Anzahl der Roundtrips zum Server. Dies wiederum verringert den Netzwerkmehraufwand und trägt dazu bei, dass Vorgänge schneller abgeschlossen werden. Weitere Informationen zur Batchverarbeitung mit der Graph-API finden Sie unter Batchverarbeitung.
  • Differenzielle Abfrage: Die Graph-API unterstützt das Ausführen differenzieller Abfragen. Eine differenzielle Abfrage ermöglicht es Ihnen, Änderungen an bestimmten Entitäten in einem Mandanten zurückzugeben, die zwischen Anforderungen erfolgt sind, die zu unterschiedlichen Zeiten ausgegeben wurden. Dieses Feature wird häufig verwendet, um einen lokalen Speicher mit Änderungen auf dem Mandanten zu synchronisieren. Weitere Informationen zu differenziellen Abfragen mit der Graph-API finden Sie unter Differenzielle Abfrage.

Zusätzliche Ressourcen