Gewusst wie: Verwenden der Azure AD-Graph-APIHow to: Use the Azure AD Graph API

Die Azure Active Directory (Azure AD) Graph-API ermöglicht programmgesteuerten Zugriff auf Azure AD über OData-REST-API-Endpunkte.The Azure Active Directory (Azure AD) Graph API provides programmatic access to Azure AD through OData REST API endpoints. Anwendungen können die Azure AD Graph-API verwenden, um CRUD-Vorgänge (Erstellen, Lesen, Aktualisieren und Löschen) für Verzeichnisdaten und Objekte auszuführen.Applications can use Azure AD Graph API to perform create, read, update, and delete (CRUD) operations on directory data and objects. Beispielsweise können Sie die Azure AD Graph-API verwenden, um einen neuen Benutzer zu erstellen, Eigenschaften des Benutzers anzuzeigen oder zu aktualisieren, das Kennwort des Benutzers zu ändern, die Gruppenmitgliedschaft für den rollenbasierten Zugriff zu überprüfen und den Benutzer zu deaktivieren oder zu löschen.For example, you can use Azure AD Graph API to create a new user, view or update user’s properties, change user’s password, check group membership for role-based access, disable, or delete the user. Weitere Informationen zu den Azure AD Graph-API-Features und Anwendungsszenarios finden Sie unter Azure AD Graph-API und Voraussetzungen für die Azure AD Graph-API.For more information on Azure AD Graph API features and application scenarios, see Azure AD Graph API and Azure AD Graph API Prerequisites.

Dieser Artikel gilt für die Azure AD Graph-API.This article applies to Azure AD Graph API. Ähnliche Informationen bezogen auf die Microsoft Graph-API finden Sie unter Verwenden der Microsoft Graph-API.For similar info related to Microsoft Graph API, see Use the Microsoft Graph API.

Wichtig

Es wird dringend empfohlen, dass Sie Microsoft Graph anstelle der Azure AD Graph-API für den Zugriff auf Azure Active Directory-Ressourcen verwenden.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources. Unsere Entwicklungstätigkeiten konzentrieren sich nun auf Microsoft Graph, während für die Azure AD Graph-API keine weiteren Verbesserungen geplant sind.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API. Die Szenarien, für die die Azure AD Graph-API möglicherweise weiterhin geeignet ist, ist nur sehr begrenzt. Weitere Informationen dazu finden Sie im Blogbeitrag Microsoft Graph or the Azure AD Graph (Microsoft Graph oder Azure AD Graph) im Office Dev Center.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Erstellen einer Graph-API-URLHow to construct a Graph API URL

In der Graph-API können Sie für den Zugriff auf Verzeichnisdaten und Objekte (also Ressourcen oder Entitäten), für die Sie CRUD-Vorgänge ausführen möchten, URLs verwenden, die auf dem OData-Protokoll (Open Data) basieren.In Graph API, to access directory data and objects (in other words, resources or entities) against which you want to perform CRUD operations, you can use URLs based on the Open Data (OData) Protocol. Die URLs, die in der Graph-API verwendet werden, bestehen aus vier Hauptkomponenten: Dienststamm, Mandanten-ID, Ressourcenpfad und Optionen für Abfragezeichenfolgen: https://graph.windows.net/{tenant-identifier}/{resource-path}?[query-parameters].The URLs used in Graph API consist of four main parts: service root, tenant identifier, resource path, and query string options: https://graph.windows.net/{tenant-identifier}/{resource-path}?[query-parameters]. Betrachten Sie beispielsweise die folgende URL: https://graph.windows.net/contoso.com/groups?api-version=1.6.Take the example of the following URL: https://graph.windows.net/contoso.com/groups?api-version=1.6.

  • Dienststamm: In der Azure AD Graph-API ist der Dienststamm immer https://graph.windows.net.Service Root: In Azure AD Graph API, the service root is always https://graph.windows.net.
  • Mandanten-ID: Dieser Abschnitt kann ein überprüfter (registrierter) Domänenname sein, im Beispiel oben ist dies „contoso.com“.Tenant identifier: This section can be a verified (registered) domain name, in the preceding example, contoso.com. Es kann aber auch eine Objekt-ID des Mandanten oder der Alias „myorganization“ oder „me“ sein.It can also be a tenant object ID or the “myorganization” or “me” alias. Weitere Informationen finden Sie unter Adressieren von Entitäten und Vorgängen in der Azure AD Graph-API.For more information, see Addressing Entities and Operations in Azure AD Graph API.
  • Ressourcenpfad: Dieser Abschnitt einer URL identifiziert die Ressource, mit der interagiert werden soll (Benutzer, Gruppen, ein bestimmter Benutzer, eine bestimmte Gruppe usw.). Im obigen Beispiel ist es die oberste Ebene „groups“ zum Adressieren dieses Ressourcensatzes.Resource path: This section of a URL identifies the resource to be interacted with (users, groups, a particular user, or a particular group, etc.) In the example above, it is the top level “groups” to address that resource set. Sie können auch eine bestimmte Entität adressieren, beispielsweise "users/{objectId}" oder "users/userPrincipalName".You can also address a specific entity, for example “users/{objectId}” or “users/userPrincipalName”.
  • Abfrageparameter: Ein Fragezeichen (?) trennt den Abschnitt für den Ressourcenpfad vom Abschnitt für Abfrageparameter.Query parameters: A question mark (?) separates the resource path section from the query parameters section. Der Abfrageparameter „api-version“ ist für alle Anforderungen in der Azure AD Graph-API erforderlich.The “api-version” query parameter is required on all requests in Azure AD Graph API. Die Azure AD Graph-API unterstützt außerdem die folgenden OData-Abfrageoptionen: $filter, $orderby, $expand, $top und $format.Azure AD Graph API also supports the following OData query options: $filter, $orderby, $expand, $top, and $format. Die folgenden Abfrageoptionen werden zurzeit nicht unterstützt: $count, $inlinecount und $skip.The following query options are not currently supported: $count, $inlinecount, and $skip. Weitere Informationen finden Sie unter Unterstützte Abfragen, Filter und Paginierungsoptionen in der Azure AD Graph-API.For more information, see Supported Queries, Filters, and Paging Options in Azure AD Graph API.

Graph-API-VersionenGraph API versions

Sie geben die Version für eine Graph-API-Anforderung im Abfrageparameter "api-version" an.You specify the version for a Graph API request in the “api-version” query parameter. Verwenden Sie ab Version 1.5 einen numerischen Versionswert; api-version=1.6For version 1.5 and later, you use a numerical version value; api-version=1.6. Für frühere Versionen verwenden Sie eine Datumszeichenfolge, die dem Format JJJJ-MM-TT entspricht, beispielsweise „api-version=2013-11-08“.For earlier versions, you use a date string that adheres to the format YYYY-MM-DD; for example, api-version=2013-11-08. Verwenden Sie für Funktionen der Vorschauversion die Zeichenfolge "beta", beispielsweise "api-version=beta".For preview features, use the string “beta”; for example, api-version=beta. Weitere Informationen zu den Unterschieden zwischen den Graph-API-Versionen finden Sie unter Versionsverwaltung der Azure AD Graph-API.For more information about differences between Graph API versions, see Azure AD Graph API Versioning.

Graph-API-MetadatenGraph API metadata

Um die Metadatendatei der Azure AD Graph-API zurückzugeben, fügen Sie in der URL nach dem Mandantenbezeichner das Segment „$metadata“ hinzu. Beispielsweise gibt die folgende URL Metadaten für ein Demonstrationsunternehmen zurück: https://graph.windows.net/GraphDir1.OnMicrosoft.com/$metadata?api-version=1.6.To return the Azure AD Graph API metadata file, add the “$metadata” segment after the tenant-identifier in the URL For example, the following URL returns metadata for a demo company: https://graph.windows.net/GraphDir1.OnMicrosoft.com/$metadata?api-version=1.6. Sie können diese URL in die Adressleiste eines Webbrowsers eingeben, um die Metadaten anzuzeigen.You can enter this URL in the address bar of a web browser to see the metadata. Das zurückgegebene CSDL-Metadatendokument beschreibt die Entitäten und komplexen Typen, deren Eigenschaften und die Funktionen und Aktionen, die von der angeforderten Graph-API-Version verfügbar gemacht werden.The CSDL metadata document returned describes the entities and complex types, their properties, and the functions and actions exposed by the version of Graph API you requested. Wenn der Parameter „api-version“ nicht angegeben wird, werden Metadaten für die neueste Version zurückgegeben.Omitting the api-version parameter returns metadata for the most recent version.

Allgemeine AbfragenCommon queries

Unter Allgemeine Abfragen der Azure AD Graph-API werden allgemeine Abfragen aufgeführt, die mit Azure AD Graph verwendet werden können. Dazu gehören auch Abfragen, die für den Zugriff auf Ressourcen der obersten Ebene in Ihrem Verzeichnis verwendet werden können, und Abfragen zum Ausführen von Vorgängen in Ihrem Verzeichnis.Azure AD Graph API Common Queries lists common queries that can be used with the Azure AD Graph, including queries that can be used to access top-level resources in your directory and queries to perform operations in your directory.

Beispielsweise gibt https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 Unternehmensinformationen für das Verzeichnis "contoso.com" zurück.For example, https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 returns company information for directory contoso.com.

https://graph.windows.net/contoso.com/users?api-version=1.6 listet alle Benutzerobjekte im Verzeichnis "contoso.com" auf.Or https://graph.windows.net/contoso.com/users?api-version=1.6 lists all user objects in the directory contoso.com.

Verwenden des Azure AD Graph-ExplorersUsing the Azure AD Graph Explorer

Mit dem Azure AD Graph-Explorer für die Azure AD Graph-API können Sie Verzeichnisdaten abfragen, während Sie eine Anwendung erstellen.You can use the Azure AD Graph Explorer for the Azure AD Graph API to query the directory data as you build your application.

Im folgenden Screenshot wird die Ausgabe angezeigt, die Sie sehen würden, wenn Sie zum Azure AD Graph-Explorer navigieren, sich anmelden und https://graph.windows.net/GraphDir1.OnMicrosoft.com/users?api-version=1.6 zur Anzeige aller Benutzer im Verzeichnis des angemeldeten Benutzers eingeben:The following screenshot is the output you would see if you were to navigate to the Azure AD Graph Explorer, sign in, and enter https://graph.windows.net/GraphDir1.OnMicrosoft.com/users?api-version=1.6 to display all the users in the signed-in user's directory:

Beispielausgabe im Azure AD Graph-API-Explorer

Laden des Azure AD Graph-Testers: Navigieren Sie zu https://graphexplorer.azurewebsites.net/, um das Tool zu laden.Load the Azure AD Graph Explorer: To load the tool, navigate to https://graphexplorer.azurewebsites.net/. Klicken Sie auf Anmelden, um sich mit den Anmeldeinformationen Ihres Azure AD-Kontos anzumelden und den Azure AD Graph-Explorer für Ihren Mandanten auszuführen.Click Login and sign-in with your Azure AD account credentials to run the Azure AD Graph Explorer against your tenant. Wenn Sie den Azure AD Graph-Explorer für Ihren eigenen Mandanten ausführen, müssen Sie oder Ihr Administrator während der Anmeldung zustimmen.If you run Azure AD Graph Explorer against your own tenant, either you or your administrator needs to consent during sign-in. Wenn Sie ein Office 365-Abonnement haben, verfügen Sie automatisch über einen Azure AD-Mandanten.If you have an Office 365 subscription, you automatically have an Azure AD tenant. Die Anmeldeinformationen, die Sie verwenden, um sich bei Office 365 anzumelden, sind tatsächlich Azure AD-Konten, und Sie können diese Anmeldeinformationen mit dem Azure AD Graph-Explorer verwenden.The credentials you use to sign in to Office 365 are, in fact, Azure AD accounts, and you can use these credentials with Azure AD Graph Explorer.

Ausführen einer Abfrage: Um eine Abfrage auszuführen, geben Sie Ihre Abfrage im Textfeld für die Anforderung ein, und klicken Sie auf GET, oder drücken Sie die EINGABETASTE.Run a query: To run a query, type your query in the request text box and click GET or click the enter key. Die Ergebnisse werden im Antwortfeld angezeigt.The results are displayed in the response box. Beispielsweise listet https://graph.windows.net/myorganization/groups?api-version=1.6 alle Gruppenobjekte im Verzeichnis des angemeldeten Benutzers auf.For example, https://graph.windows.net/myorganization/groups?api-version=1.6 lists all group objects in the signed-in user's directory.

Beachten Sie die folgenden Funktionen und Einschränkungen für den Azure AD Graph-Explorer:Note the following features and limitations of the Azure AD Graph Explorer:

  • Funktion zum automatischen Vervollständigen für Ressourcensätze.Autocomplete capability on resource sets. Um diese Funktion zu sehen, klicken Sie auf das Textfeld für die Anforderung (in dem die Unternehmens-URL angezeigt wird).To see this functionality, click on the request text box (where the company URL appears). Sie können einen Ressourcensatz aus der Dropdownliste auswählen.You can select a resource set from the dropdown list.
  • Anforderungsverlauf.Request history.
  • Unterstützt die Adressierungsaliase "me" und "myorganization".Supports the “me” and “myorganization” addressing aliases. Beispielsweise können Sie https://graph.windows.net/me?api-version=1.6 verwenden, um das Benutzerobjekt des angemeldeten Benutzers zurückzugeben, oder https://graph.windows.net/myorganization/users?api-version=1.6, um alle Benutzer im Verzeichnis des angemeldeten Benutzers zurückzugeben.For example, you can use https://graph.windows.net/me?api-version=1.6 to return the user object of the signed-in user or https://graph.windows.net/myorganization/users?api-version=1.6 to return all users in the signed-in user's directory.
  • Unterstützt vollständige CRUD-Vorgänge für Ihr eigenes Verzeichnis mit POST, GET, PATCH und DELETE.Supports full CRUD operations against your own directory using POST, GET, PATCH and DELETE.
  • Ein Abschnitt für den Antwortheader.A response headers section. Dieser Abschnitt kann zur Behandlung von Problemen beim Ausführen von Abfragen verwendet werden.This section can be used to help troubleshoot issues that occur when running queries.
  • Ein JSON-Viewer für die Antwort mit Funktionen zum Erweitern und Reduzieren.A JSON viewer for the response with expand and collapse capabilities.
  • Keine Unterstützung für das Anzeigen oder Hochladen einer Miniaturansicht von Fotos.No support for displaying or uploading a thumbnail photo.

Verwenden von Fiddler zum Schreiben in das VerzeichnisUsing Fiddler to write to the directory

Im Rahmen dieses Schnellstarthandbuchs können Sie den Fiddler-Webdebugger verwenden, um Schreibvorgänge in das Azure AD-Verzeichnis zu üben.For the purposes of this Quickstart guide, you can use the Fiddler Web Debugger to practice performing ‘write’ operations against your Azure AD directory. Sie können z.B. das Profilfoto eines Benutzers abrufen und hochladen (dies ist mit dem Azure AD Graph-Explorer nicht möglich).For example, you can get and upload a user's profile photo (which is not possible with Azure AD Graph Explorer). Weitere Informationen – auch zur Installation – von Fiddler finden Sie unter https://www.telerik.com/fiddler.For more information and to install Fiddler, see https://www.telerik.com/fiddler.

Im folgenden Beispiel verwenden Sie den Fiddler-Webdebugger, um die neue Sicherheitsgruppe „MyTestGroup“ in Ihrem Azure AD-Verzeichnis zu erstellen.In the example below, you use Fiddler Web Debugger to create a new security group ‘MyTestGroup’ in your Azure AD directory.

Abrufen eines Zugriffstokens: Für den Zugriff auf Azure AD Graph müssen sich Clients zuerst bei Azure AD authentifizieren.Obtain an access token: To access Azure AD Graph, clients are required to successfully authenticate to Azure AD first. Weitere Informationen finden Sie unter Authentifizierungsszenarien für Azure AD.For more information, see Authentication Scenarios for Azure AD.

Erstellen und Ausführen einer Abfrage: Führen Sie die folgenden Schritte aus:Compose and run a query: Complete the following steps:

  1. Öffnen Sie den Fiddler-Webdebugger, und wechseln Sie zur Registerkarte Composer .Open Fiddler Web Debugger and switch to the Composer tab.

  2. Da Sie eine neue Sicherheitsgruppe erstellen möchten, wählen Sie Post als HTTP-Methode aus dem Dropdownmenü aus.Since you want to create a new security group, select Post as the HTTP method from the pull-down menu. Weitere Informationen zu Vorgängen und Berechtigungen für eine Gruppe finden Sie unter Gruppe in der Azure AD Graph-REST-API-Referenz.For more information about operations and permissions on a group object, see Group within the Azure AD Graph REST API Reference.

  3. Geben Sie in das Feld neben Post die folgende Anforderungs-URL ein: https://graph.windows.net/{mytenantdomain}/groups?api-version=1.6.In the field next to Post, type in the following request URL: https://graph.windows.net/{mytenantdomain}/groups?api-version=1.6.

    Hinweis

    Ersetzen Sie „{mytenantdomain}“ mit dem Domänennamen Ihres eigenen Azure AD-Verzeichnisses.You must substitute {mytenantdomain} with the domain name of your own Azure AD directory.

  4. Geben Sie im Feld direkt unterhalb des Pulldownmenüs „Post“ folgenden HTTP-Header ein:In the field directly below Post pull-down, type the following HTTP header:

    Host: graph.windows.net
    Authorization: Bearer <your access token>
    Content-Type: application/json
    

    Hinweis

    Ersetzen Sie <your access token> durch das Zugriffstoken für Ihr Azure AD-Verzeichnis.Substitute your <your access token> with the access token for your Azure AD directory.

  5. Geben Sie im Feld Anforderungstext folgenden JSON-Code ein:In the Request body field, type the following JSON:

        {
            "displayName":"MyTestGroup",
            "mailNickname":"MyTestGroup",
            "mailEnabled":"false",
            "securityEnabled": true
        }
    

    Weitere Informationen zum Erstellen von Gruppen finden Sie unter Erstellen einer Gruppe.For more information about creating groups, see Create Group.

Weitere Informationen zu Azure AD-Entitäten und -Typen, die von Graph bereitgestellt werden, und Informationen zu den Vorgängen, die mit Graph durchgeführt werden können, finden Sie unter Azure AD Graph-REST-API-Referenz.For more information on Azure AD entities and types that are exposed by Graph and information about the operations that can be performed on them with Graph, see Azure AD Graph REST API Reference.

Nächste SchritteNext steps