Freigeben über

Verwenden der Microsoft Graph-API

  • Artikel

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 finden Sie unter Entwicklerleitfaden für Microsoft Entra bedingten Zugriff.

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.
  • {headers} – Anforderungsheader, die die Anforderung anpassen. Kann je nach API optional oder erforderlich sein.

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.
  • @odata.nextLink – Wenn Ihre Anforderung viele Daten zurückgibt, müssen Sie sie mithilfe der url durchlaufen, die in @odata.nextLinkzurückgegeben wird. Weitere Informationen finden Sie unter Auslagern.
  • Antwortheader: Zusätzliche Informationen zur Antwort, z. B. den Typ des zurückgegebenen Inhalts und die Anforderungs-ID, die Sie verwenden können, um die Antwort mit der Anforderung zu korrelieren.

HTTP-Methoden

Microsoft Graph verwendet die HTTP-Methode für Ihre Anforderung, um zu bestimmen, wie Ihre Anforderung ausgeführt wird. Abhängig von der Ressource unterstützt die API möglicherweise Vorgänge wie Aktionen, Funktionen oder CRUD-Vorgänge, die unten beschrieben werden.

Methode Beschreibung
GET Dient zum Lesen von Daten aus einer Ressource.
POST Dient zum Erstellen einer neuen Ressource oder Durchführen einer Aktion.
PATCH Aktualisieren Sie eine Ressource mit neuen Werten, oder führen Sie ein Upsert für eine Ressource durch (erstellen Sie, wenn die Ressource nicht vorhanden ist, aktualisieren Sie andernfalls).
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.

Wichtig

Schreibanforderungen im Microsoft Graph-API haben eine Größenbeschränkung von 4 MB.

In einigen Fällen liegt die tatsächliche Größenbeschränkung für Schreibanforderungen unter 4 MB. Das Anfügen einer Datei an ein Benutzerereignis über POST /me/events/{id}/attachments hat beispielsweise eine Anforderungsgröße von 3 MB, da eine Datei um 3,5 MB größer als 4 MB werden kann, wenn sie in Base64 codiert wird.

Anforderungen, die die Größenbeschränkung überschreiten, schlagen mit dem status Code HTTP 413 und der Fehlermeldung "Anforderungsentität zu groß" oder "Nutzlast zu groß" fehl.

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, user, group, drive und 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. Sie können auch mithilfe von Methoden mit Ressourcen interagieren. Um beispielsweise eine E-Mail-Nachricht zu senden, verwenden Sie me/sendMail. Weitere Informationen finden Sie unter Zugreifen auf Daten und Methoden durch Navigieren in Microsoft Graph.

Jede Ressource benötigt möglicherweise unterschiedliche Berechtigungen für den Zugriff darauf. Sie benötigen häufig eine höhere Berechtigungsstufe, um eine Ressource zu erstellen oder zu aktualisieren, als sie zu lesen. Ausführliche Informationen zu erforderlichen Berechtigungen finden Sie im Referenzthema zu Methoden.

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

Header

Microsoft Graph unterstützt sowohl HTTP-Standardheader als auch benutzerdefinierte Header.

Für bestimmte APIs müssen möglicherweise zusätzliche Header in die Anforderung eingeschlossen werden. Auf der anderen Seite gibt Microsoft Graph immer obligatorische Header zurück, z. B. den request-id Header in der Antwort, oder einige Header können für einige APIs oder Funktionen spezifisch sein, z. B. wenn der Retry-After Header enthalten ist, wenn Ihre App Drosselungsgrenzwerte erreicht, oder der Header, der Location für zeitintensive Vorgänge enthalten ist.

Bei Headern wird die Groß-/Kleinschreibung nicht beachtet, wie in rfc 9110 definiert, sofern nicht explizit anders angegeben.

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. Der Zugriff auf Graph Explorer ist möglich 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 Abfrage 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, Einaus, 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

Sie sind nun bereit für Ihre ersten Schritte mit Microsoft Graph. Probieren Sie den Schnellstartaus oder beginnen Sie mit einem unserer SDKs und Codebeispiele.