Verwenden der Microsoft Graph-APIUse the Microsoft Graph API

Microsoft Graph ist eine RESTful-Web-API, mit der Sie auf Microsoft Cloud-Dienstressourcen zugreifen können. Nachdem Sie Ihre App registriert und Authentifizierungstoken für einen Benutzer oder einen Dienst abgerufen haben, können Sie Anforderungen an die Microsoft Graph-API tätigen.Microsoft Graph is a RESTful web API that enables you to access Microsoft Cloud service resources. After you register your app and get authentication tokens for a user or service, you can make requests to the Microsoft Graph API.

Wichtig: Die Anwendung der Richtlinien für bedingten Zugriff für Microsoft Graph wurde geändert.Important: How conditional access policies apply to Microsoft Graph is changing. Anwendungen müssen aktualisiert werden, um Szenarien ausführen zu können, für die bedingte Richtlinien konfiguriert sind.Applications need to be updated to handle scenarios where conditional access policies are configured. Weitere Informationen und Anleitungen hierzu finden Sie unter Developer-Leitfaden zum bedingten Zugriff in Azure Active Directory.For more information and guidance, see Developer Guidance for Azure Active Directory Conditional Access.

OData-NamespaceOData namespace

Die Microsoft Graph-API definiert die meisten ihrer Ressourcen, Methoden und Enumerationen im OData-Namespace, microsoft.graph, in den Microsoft Graph-Metadaten.The Microsoft Graph API defines most of its resources, methods, and enumerations in the OData namespace, microsoft.graph, in the Microsoft Graph metadata. Eine kleine Anzahl von API-Sätzen wird in ihren Unter-Namespaces definiert, wie z. B. die API für Anrufdatensätze, die Ressourcen wie callRecord in microsoft.graph.callRecordsdefiniert.A small number of API sets are defined in their sub-namespaces, such as the call records API which defines resources like callRecord in microsoft.graph.callRecords.

Sofern im entsprechenden Thema nicht explizit angegeben, nehmen Sie an, dass Typen, Methoden und Enumerationen Teil des Namespaces microsoft.graph sind.Unless explicitly specified in the corresponding topic, assume types, methods, and enumerations are part of the microsoft.graph namespace.

Aufrufen einer REST-API-MethodeCall a REST API method

Erstellen Sie eine Anforderung, die der folgenden ähnlich ist, um in eine Ressource zu schreiben bzw. daraus zu lesen. Ressourcen können z. B. Benutzer oder E-Mail-Nachrichten sein.To read from or write to a resource such as a user or an email message, you construct a request that looks like the following:

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

Die Komponenten einer Anforderung umfassen Folgendes:The components of a request include:

  • {HTTP-Methode} – Die HTTP-Methode, die in der Anforderung an Microsoft Graph verwendet wird.{HTTP method} - The HTTP method used on the request to Microsoft Graph.
  • {version} – Die Version der Microsoft Graph-API, die Ihre Anwendung verwendet.{version} - The version of the Microsoft Graph API your application is using.
  • {resource} – Die Ressource in Microsoft Graph, auf die Sie verweisen.{resource} - The resource in Microsoft Graph that you're referencing.
  • {query-parameters} – Optionale OData-Abfrageoptionen oder REST-Methodenparameter zur Anpassung der Antwort.{query-parameters} - Optional OData query options or REST method parameters that customize the response.

Nachdem Sie eine Anforderung vorgenommen haben, wird eine Antwort zurückgegeben, die Folgendes umfasst:After you make a request, a response is returned that includes:

  • Statuscode – Ein HTTP-Statuscode, der eine erfolgreiche oder fehlerhafte Ausführung angibt. Informationen zu HTTP-Fehlercodes finden Sie unter Fehler.Status code - An HTTP status code that indicates success or failure. For details about HTTP error codes, see Errors.
  • Antwortnachricht – Die angeforderten Daten oder das Ergebnis des Vorgangs. Die Antwortnachricht kann für einige Vorgänge leer sein.Response message - The data that you requested or the result of the operation. The response message can be empty for some operations.
  • nextLink – Wenn Ihre Anforderung eine große Datenmenge zurückgibt, müssen Sie diese unter Verwendung der in @odata.nextLink zurückgegebenen URL durchblättern. Weitere Informationen finden Sie unter Auslagern.nextLink - If your request returns a lot of data, you need to page through it by using the URL returned in @odata.nextLink. For details, see Paging.

HTTP-MethodenHTTP methods

Microsoft Graph verwendet die HTTP-Methode in Ihrer Anforderung, um zu ermitteln, welche Aktion Ihre Anforderung ausführt. Die API unterstützt die folgenden Methoden.Microsoft Graph uses the HTTP method on your request to determine what your request is doing. The API supports the following methods.

MethodeMethod BeschreibungDescription
GETGET Dient zum Lesen von Daten aus einer Ressource.Read data from a resource.
POSTPOST Dient zum Erstellen einer neuen Ressource oder Durchführen einer Aktion.Create a new resource, or perform an action.
PATCHPATCH Dient zum Aktualisieren einer Ressource mit neuen Werten.Update a resource with new values.
PUTPUT Dient zum Ersetzen einer Ressource durch eine neue.Replace a resource with a new one.
DELETEDELETE Dient zum Entfernen einer Ressource.Remove a resource.
  • Für die CRUD-Methoden GET und DELETE ist kein Anforderungstext erforderlich.For the CRUD methods GET and DELETE, no request body is required.
  • Die Methoden POST, PATCH und PUT erfordern einen Anforderungstext, in der Regel im JSON-Format, der zusätzliche Informationen enthält, z. B. die Werte für Eigenschaften der Ressource.The POST, PATCH, and PUT methods require a request body, usually specified in JSON format, that contains additional information, such as the values for properties of the resource.

VersionVersion

Microsoft Graph unterstützt derzeit zwei Versionen: v1.0 und beta.Microsoft Graph currently supports two versions: v1.0 and beta.

  • v1.0 umfasst allgemein verfügbare APIs. Verwenden Sie die Version 1.0 für alle Produktions-Apps.v1.0 includes generally available APIs. Use the v1.0 version for all production apps.
  • beta umfasst APIs, die sich derzeit in der Vorschau befinden. Da möglicherweise grundlegende Änderungen an unseren Beta-APIs eingeführt werden, wird empfohlen, dass Sie die Betaversion nur zum Testen von Apps verwenden, die sich in der Entwicklung befinden; verwenden Sie keine Beta-APIs in Ihren Produktions-Apps.beta includes APIs that are currently in preview. Because we might introduce breaking changes to our beta APIs, we recommend that you use the beta version only to test apps that are in development; do not use beta APIs in your production apps.

Wir freuen uns immer über Feedback zu unseren Beta-APIs. Auf unserer UserVoice-Seite können Sie Feedback abgeben oder Features anfordern.We are always looking for feedback on our beta APIs. To provide feedback or request features, see our UserVoice page.

Weitere Informationen zu API-Versionen finden Sie unter Versionsverwaltung und Support.For more information about API versions, see Versioning and support.

RessourceResource

Eine Ressource kann eine Entität oder ein komplexer Typ sein, und wird normalerweise mit Eigenschaften definiert.A resource can be an entity or complex type, commonly defined with properties. Entitäten unterscheiden sich von komplexen Typen dadurch, dass sie immer eine id-Eigenschaft enthalten.Entities differ from complex types by always including an id property.

Ihre URL enthält die Ressource, mit der Sie in der Anforderung interagieren, z. B. me, user, group, drive und site.Your URL will include the resource you are interacting with in the request, such as me, user, group, drive, and site. Ressourcen der obersten Ebene umfassen häufig auch Beziehungen, die Sie verwenden können, um auf zusätzliche Ressourcen wie me/messages oder me/drive zuzugreifen.Often, top-level resources also include relationships, which you can use to access additional resources, like me/messages or me/drive. Sie können auch mithilfe von Methoden mit Ressourcen interagieren. Um beispielsweise eine E-Mail-Nachricht zu senden, verwenden Sie me/sendMail.You can also interact with resources using methods; for example, to send an email, use me/sendMail. Weitere Informationen finden Sie unter Zugreifen auf Daten und Methoden durch Navigieren in Microsoft Graph.For more information, see Access data and methods by navigating Microsoft Graph.

Für jede Ressource sind möglicherweise andere Berechtigungen für den Zugriff erforderlich. Häufig benötigen Sie zum Erstellen oder Aktualisieren einer Ressource eine höhere Ebene von Berechtigungen als zum Lesen. Ausführliche Informationen über die erforderlichen Berechtigungen finden Sie im Methodenreferenzthema.Each resource might require different permissions to access it. You will often need a higher level of permissions to create or update a resource than to read it. For details about required permissions, see the method reference topic.

Weitere Informationen zu Berechtigungen finden Sie unter Berechtigungsreferenz.For details about permissions, see Permissions reference.

AbfrageparameterQuery parameters

Abfrageparameter können OData-Systemabfrageoptionen oder andere Zeichenfolgen sein, die eine Methode zum Anpassen Ihrer Antwort akzeptieren.Query parameters can be OData system query options, or other strings that a method accepts to customize its response.

Sie können optional OData-Systemabfrageoptionen verwenden, um mehr oder weniger Eigenschaften als in der Standardantwort einzuschließen, die Antwort auf Elemente zu filtern, die einer benutzerdefinierten Abfrage entsprechen, oder zusätzliche Parameter für eine Methode anzugeben.You can use optional OData system query options to include more or fewer properties than the default response, filter the response for items that match a custom query, or provide additional parameters for a method.

Durch Hinzufügen der folgenden filter-Parameter werden beispielsweise die zurückgegebenen Nachrichten so eingeschränkt, dass nur diejenigen mit der emailAddress-Eigenschaft jon@contoso.com zurückgegeben werden.For example, adding the following filter parameter restricts the messages returned to only those with the emailAddress property of jon@contoso.com.

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

Weitere Informationen zu OData-Abfrageoptionen finden Sie unter Verwenden von Abfrageparametern zum Anpassen von Antworten.For more information about OData query options, see Use query parameters to customize responses.

Abgesehen von OData-Abfrageoptionen erfordern einige Methoden Parameterwerte, die als Teil der Abfrage-URL angegebene werden.Aside from OData query options, some methods require parameter values specified as part of the query URL. Sie können z. B. eine Sammlung von Ereignissen während eines bestimmten Zeitraums im Kalender eines Benutzers abrufen, indem Sie die calendarView-Beziehung eines Benutzers abfragen und die Werte startDateTime und endDateTime für den Zeitraum als Abfrageparameter angeben:For example, you can get a collection of events that occurred during a time period in a user's calendar, by querying the calendarView relationship of a user, and specifying the period startDateTime and endDateTime values as query parameters:

GET https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

Tools für die Interaktion mit Microsoft GraphTools for interacting with Microsoft Graph

Graph ExplorerGraph Explorer

Graph Explorer ist ein webbasiertes Tool, das Sie verwenden können, um Abfragen mithilfe von Microsoft Graph-APIs zu erstellen und zu testen.Graph Explorer is a web-based tool that you can use to build and test requests using Microsoft Graph APIs. Der Zugriff auf Graph Explorer ist möglich unter: https://developer.microsoft.com/graph/graph-explorer.You can access Graph Explorer at: https://developer.microsoft.com/graph/graph-explorer.

Sie können entweder auf Demodaten zugreifen ohne sich anzumelden, oder sich bei einem eigenen Mandanten anmelden.You can either access demo data without signing in, or you can sign in to a tenant of your own. Führen Sie die folgenden Schritte durch, um eine Abfrage zu erstellen:Use the following steps to build the request:

  1. Wählen Sie die HTTP-Methode aus.Select the HTTP method.
  2. Wählen Sie die API-Version aus, die Sie verwenden möchten.Select the version of API that you want to use.
  3. Geben Sie die Abfrage im Abfragetextfeld ein.Type the query in the request text box.
  4. Wählen Sie Abfrage ausführen aus.Select Run Query.

Das folgende Beispiel zeigt eine Abfrage, die Informationen zu Benutzern im Demomandanten zurückmeldet:The following example shows a request that returns information about users in the demo tenant:

Screenshot von Graph Explorer mit hervorgehobener Abfrage „Benutzer ANFORDERN“

In Graph Explorer werden Beispielabfragen zur Verfügung gestellt, damit Sie häufig auftretende Abfragen schneller durchführen können.Sample queries are provided in Graph Explorer to enable you to more quickly run common requests. Wenn Sie die verfügbaren Beispiele ansehen möchten, wählen Sie Weitere Beispiele anzeigen aus.To see the samples that are available, select show more samples. Wählen Sie für die Gruppe der Beispiele, die Sie ansehen möchten, Einaus, und nach dem Schließen des Auswahlfensters sollte dann eine Liste der vordefinierten Abfragen bzw. Anforderungen angezeigt werden.Select On for the set of samples that you want to see, and then after closing the selection window, you should see a list of predefined requests.

Nach dem Senden einer Abfrage werden ein Statuscode und eine Nachricht angezeigt, und die Antwort wird in der Registerkarte Antwort Vorschau angezeigt.A status code and message are displayed after a request is sent and the response is shown in the Response Preview tab.

PostmanPostman

Postman ist ein Tool, das Sie verwenden können, um Abfragen mithilfe von Microsoft Graph-APIs zu erstellen und zu testen.Postman is a tool that you can use to build and test requests using the Microsoft Graph APIs. Postman kann unter: https://www.getpostman.com/ heruntergeladen werden.You can download Postman at: https://www.getpostman.com/. Wenn Sie mit Microsoft Graph in Postman interagieren möchten, verwenden Sie die Microsoft Graph-Sammlung.To interact with Microsoft Graph in Postman, you use the Microsoft Graph collection.

Weitere Informationen finden Sie unter Verwenden von Postman mit einer Microsoft Graph-API.For more information, see Use Postman with the Microsoft Graph API.

Nächste SchritteNext steps

Sie sind nun bereit für Ihre ersten Schritte mit Microsoft Graph.You're ready to get up and running with Microsoft Graph. Probieren Sie den Schnellstartaus oder beginnen Sie mit einem unserer SDKs und Codebeispiele.Try the Quick Start, or get started using one of our SDKs and code samples.