Abfragen von Microsoft Graph mithilfe von REST

  • 3 Minuten

Microsoft Graph ist eine RESTful-Web-API, die Ihnen den Zugriff auf Ressourcen von Microsoft-Clouddiensten ermöglicht. Nachdem Sie Ihre App registriert und Authentifizierungstoken für einen Benutzer oder Dienst abgerufen haben, können Sie Anforderungen an die Microsoft Graph-API senden.

Die Microsoft Graph-API definiert die meisten ihrer Ressourcen, Methoden und Enumerationen im OData-Namespace, microsoft.graph, in den Microsoft Graph-Metadaten. Einige API-Sätze werden in ihren untergeordneten Namespaces definiert, z. B. die Aufrufdatensatz-API, die Ressourcen wie callRecord in microsoft.graph.callRecords definiert.

Sofern im entsprechenden Thema nicht explizit angegeben, wird davon ausgegangen, dass Typen, Methoden und Enumerationen Teil des microsoft.graph-Namespaces sind.

Aufrufen einer REST-API-Methode

Zum Lesen aus einer Ressource oder Schreiben in eine Ressource, z. B. einen Benutzer oder eine E-Mail-Nachricht, erstellen Sie eine Anforderung, die dem folgenden Beispiel ähnelt:

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

Zu den Komponenten einer Anforderung gehören:

  • {HTTP method}: Die HTTP-Methode, die für die 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, die die Antwort anpassen.

Nachdem Sie eine Anforderung gestellt haben, wird eine Antwort zurückgegeben, die Folgendes enthält:

  • Statuscode: Ein HTTP-Statuscode, der den Erfolg oder Fehler angibt.
  • Antwortnachricht: Die angeforderten Daten oder das Ergebnis des Vorgangs. Die Antwortnachricht kann für einige Vorgänge leer sein.
  • nextLink: Wenn Ihre Anforderung zahlreiche Daten zurückgibt, müssen Sie sie mithilfe der in @odata.nextLink zurückgegebenen URL durchblättern.

HTTP-Methoden

Microsoft Graph verwendet die HTTP-Methode für Ihre Anforderung, um zu bestimmen, was Ihre Anforderung tut. Die API unterstützt die folgenden Methoden.

Methode BESCHREIBUNG
GET Lesen von Daten aus einer Ressource.
POST Erstellen einer neuen Ressource oder Ausführen einer Aktion.
PATCH Aktualisieren einer Ressource mit neuen Werten.
PUT Ersetzen einer Ressource durch eine neue Ressource.
DELETE Entfernen einer Ressource.
  • Für die CRUD-Methoden GET und DELETE ist kein Anforderungstext erforderlich.
  • Die Methoden POST, PATCH und PUT erfordern einen Anforderungstext, der im JSON-Format angegeben wird und 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 enthält allgemein verfügbare APIs. Verwenden Sie die Version v1.0 für alle Produktions-Apps.
  • beta enthält APIs, die sich derzeit in der Vorschau befinden. Weil wir möglicherweise wichtige Änderungen (Breaking Changes) an unseren Beta-APIs einführen, empfehlen wir, die Betaversion nur zum Testen von Apps zu verwenden, die sich in der Entwicklung befinden. Verwenden Sie Beta-APIs nicht in Ihren Produktions-Apps.

Resource

Eine Ressource kann eine Entität sein oder ein komplexer Typ, der häufig mit Eigenschaften definiert wird. Entitäten unterscheiden sich von komplexen Typen, indem sie immer eine id-Eigenschaft einschließen.

Ihre URL enthält die Ressource, mit der Sie in der Anforderung interagieren, z. B. me, user, group, drive und site. Häufig enthalten Ressourcen der obersten Ebene auch Beziehungen, mit denen Sie auf andere Ressourcen wie me/messages oder me/drive zugreifen können. Sie können auch mithilfe von methods mit Ressourcen interagieren. Um eine E-Mail zu senden, verwenden Sie beispielsweise me/sendMail.

Für jede Ressource sind möglicherweise andere Berechtigungen erforderlich, um darauf zugreifen zu können. Häufig benötigen Sie zum Erstellen oder Aktualisieren einer Ressource eine höhere Berechtigungsstufe als zum Lesen. Ausführliche Informationen zu erforderlichen Berechtigungen finden Sie im Methodenreferenzthema.

Abfrageparameter

Abfrageparameter können OData-Systemabfrageoptionen oder andere Zeichenfolgen sein, die eine Methode akzeptiert, um ihre Antwort anzupassen.

Sie können optionale OData-Systemabfrageoptionen verwenden, um mehr oder weniger Eigenschaften als in der Standardantwort einzuschließen. Sie können die Antwort nach Elementen filtern, die einer benutzerdefinierten Abfrage entsprechen, oder Sie können andere Parameter für eine Methode bereitstellen.

Wenn Sie z. B. den folgenden filter-Parameter hinzufügen, werden die Nachrichten beschränkt, die mit der emailAddress-Eigenschaft von jon@contoso.com zurückgegeben werden.

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

Weitere Ressourcen

Im Folgenden finden Sie Links zu einigen Tools, mit denen Sie Anforderungen mithilfe von Microsoft Graph-APIs erstellen und testen können.