Verwenden der 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.

Wichtig: Die Anwendung der Richtlinien für bedingten Zugriff für Microsoft Graph wurde geändert. Anwendungen müssen aktualisiert werden, um Szenarien ausführen zu können, für die bedingte Richtlinien konfiguriert sind. Weitere Informationen und Anleitungen hierzu finden Sie unter Developer-Leitfaden zum bedingten Zugriff in Azure Active Directory.

OData-Namespace

Die Microsoft Graph-API definiert die meisten ihrer Ressourcen, Methoden und Enumerationen im OData-Namespace, microsoft.graph, in den Microsoft Graph-Metadaten. 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.

Sofern im entsprechenden Thema nicht explizit angegeben, nehmen Sie an, dass Typen, Methoden und Enumerationen Teil des Namespaces microsoft.graph sind.

Aufrufen einer REST-API-Methode

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.

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

Die Komponenten einer Anforderung umfassen Folgendes:

  • {HTTP-Methode} – Die HTTP-Methode, die in der Anforderung an Microsoft Graph verwendet wird.
  • {version} – Die Version der Microsoft Graph-API, die Ihre Anwendung verwendet.
  • {resource} – Die Ressource in Microsoft Graph, auf die Sie verweisen.
  • {query-parameters} – Optionale OData-Abfrageoptionen oder REST-Methodenparameter zur Anpassung der Antwort.

Nachdem Sie eine Anforderung vorgenommen haben, wird eine Antwort zurückgegeben, die Folgendes umfasst:

  • Statuscode – Ein HTTP-Statuscode, der eine erfolgreiche oder fehlerhafte Ausführung angibt. Informationen zu HTTP-Fehlercodes finden Sie unter Fehler.
  • Antwortnachricht – Die angeforderten Daten oder das Ergebnis des Vorgangs. Die Antwortnachricht kann für einige Vorgänge leer sein.
  • 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.

HTTP-Methoden

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.

Methode Beschreibung
GET Dient zum Lesen von Daten aus einer Ressource.
POST Dient zum Erstellen einer neuen Ressource oder Durchführen einer Aktion.
PATCH Dient zum Aktualisieren einer Ressource mit neuen Werten.
PUT Dient zum Ersetzen einer Ressource durch eine neue.
DELETE Dient zum Entfernen einer Ressource.
  • Für die CRUD-Methoden GET und DELETE ist kein Anforderungstext erforderlich.
  • 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.

Version

Microsoft Graph unterstützt derzeit zwei Versionen: v1.0 und beta.

  • v1.0 umfasst allgemein verfügbare APIs. Verwenden Sie die Version 1.0 für alle Produktions-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.

Wir freuen uns immer über Feedback zu unseren Beta-APIs. Wenn Sie Feedback geben oder Features anfordern möchten, besuchen Sie das Ideenforum der Microsoft 365-Entwicklerplattform.

Weitere Informationen zu API-Versionen finden Sie unter Versionsverwaltung und Support.

Ressource

Eine Ressource kann eine Entität oder ein komplexer Typ sein, und wird normalerweise mit Eigenschaften definiert. Entitäten unterscheiden sich von komplexen Typen dadurch, dass sie immer eine id-Eigenschaft enthalten.

Ihre URL enthält die Ressource, mit der Sie in der Anforderung interagieren, z. B. me, Benutzer, Gruppe, Laufwerk und Website. Häufig schließen Ressourcen auf oberster Ebene auch Beziehungen ein, die Sie für den Zugriff auf weitere Ressourcen verwenden können, z. B. me/messages oder me/drive. Sie können auch mit Ressourcen interagieren, indem Sie Methoden verwenden; z. B. um eine E-Mail zu senden, können Sie me/sendMail verwenden. Weitere Informationen finden Sie unter Auf Daten und Methoden zugreifen, indem Sie in Microsoft Graph navigieren.

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.

Weitere Informationen zu Berechtigungen finden Sie unter Berechtigungsreferenz.

Abfrageparameter

Abfrageparameter können OData-Systemabfrageoptionen oder andere Zeichenfolgen sein, die eine Methode zum Anpassen Ihrer Antwort akzeptieren.

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.

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.

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.

Abgesehen von OData-Abfrageoptionen erfordern einige Methoden Parameterwerte, die als Teil der Abfrage-URL angegebene werden. 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:

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 Graph

Graph Explorer

Graph Explorer ist ein webbasiertes Tool, das Sie verwenden können, um Abfragen mithilfe von Microsoft Graph-APIs zu erstellen und zu testen. Sie können auf den Graph-Explorer zugreifen unter: https://developer.microsoft.com/graph/graph-explorer.

Sie können entweder auf Demodaten zugreifen ohne sich anzumelden, oder sich bei einem eigenen Mandanten anmelden. Führen Sie die folgenden Schritte durch, um eine Anforderung zu erstellen:

  1. Wählen Sie die HTTP-Methode aus.
  2. Wählen Sie die API-Version aus, die Sie verwenden möchten.
  3. Geben Sie die Abfrage im Abfragetextfeld ein.
  4. Wählen Sie Abfrage ausführen aus.

Das folgende Beispiel zeigt eine Abfrage, die Informationen zu Benutzern im Demomandanten zurückmeldet:

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. Wenn Sie die verfügbaren Beispiele ansehen möchten, wählen Sie Weitere Beispiele anzeigen aus. Wählen Sie für die Gruppe der Beispiele, die Sie ansehen möchten, Ein aus, und nach dem Schließen des Auswahlfensters sollte dann eine Liste der vordefinierten Abfragen bzw. Anforderungen angezeigt werden.

Nach dem Senden einer Abfrage werden ein Statuscode und eine Nachricht angezeigt, und die Antwort wird in der Registerkarte Antwort Vorschau angezeigt.

Postman

Postman ist ein Tool, das Sie verwenden können, um Abfragen mithilfe von Microsoft Graph-APIs zu erstellen und zu testen. Postman kann unter: https://www.getpostman.com/ heruntergeladen werden. Wenn Sie mit Microsoft Graph in Postman interagieren möchten, verwenden Sie die Microsoft Graph-Sammlung.

Weitere Informationen finden Sie unter Verwenden von Postman mit einer Microsoft Graph-API.

Nächste Schritte

Jetzt können Sie Microsoft Graph verwenden. Probieren Sie den Schnellstartaus oder beginnen Sie mit einem unserer SDKs und Codebeispiele.