Zugreifen auf Daten und Methoden durch Navigieren in Microsoft Graph

  • Artikel

Zusätzlich zur Verwendung des Microsoft Graph-API zum Lesen und Schreiben von Daten können Sie eine Reihe von Anforderungsmustern verwenden, um die Ressourcen in Microsoft Graph zu durchlaufen. Das Metadatendokument hilft Ihnen auch, das Datenmodell der Ressourcen und Beziehungen in Microsoft Graph zu verstehen.

Microsoft Graph-API-Metadaten

Das Metadatendokument ($metadata) wird im Dienststamm veröffentlicht. Sie können das Dienstdokument für die v1.0- und Beta-Versionen der Microsoft Graph-API über die folgenden URLs anzeigen.

Metadaten für Microsoft Graph-API v1.0

https://graph.microsoft.com/v1.0/$metadata

Metadaten für Microsoft Graph-API Beta

https://graph.microsoft.com/beta/$metadata

Mithilfe der Metadaten können Sie das Datenmodell von Microsoft Graph sehen und verstehen, einschließlich Entitätstypen, komplexen Typen und Aufzählungen, aus denen Ressourcen bestehen, die in den Anforderungs- und Antwortpaketen dargestellt sind.

Außerdem unterstützen die Metadaten das Definieren von Typen, Methoden und Enumerationen in entsprechenden OData-Namespaces. Der Großteil der Microsoft Graph-API ist im OData-Namespace, microsoft.graph, definiert. Einige APIs werden in Unternamespaces definiert, z. B microsoft.graph.callRecords. .

Die Metadaten können Sie verwenden, um die Beziehungen zwischen Entitäten in Microsoft Graph zu verstehen und URLs einzurichten, die zwischen diesen Entitäten navigieren.

Hinweis

  • Verwenden Sie Ressourcen-IDs in der gleichen Schreibweise, wie Sie von Microsoft Graph-APIs zurückgegeben werden.
  • Gehen Sie davon aus, dass bei Ressourcen-IDs, zugewiesenen Werten und anderen base64-codierten Werten nach Groß-/Kleinschreibung unterschieden wird.
  • Gehen Sie davon aus, dass bei Pfad-URL-Ressourcennamen, Abfrageparameter, Aktions-und Funktionsnamen, deren Anforderungstext-Parameter, einschließlich aller API-Eigenschaftennamen und Werten, nicht nach Groß-/Kleinschreibung unterschieden wird.

Anzeigen einer Sammlung von Ressourcen

Mit Microsoft Graph können Sie Ressourcen in einem Mandanten mithilfe von HTTP-GET-Abfragen anzeigen. Die Abfrageantwort enthält die Eigenschaften der einzelnen Ressourcen. Entitätsressourcen werden jeweils durch die ID angegeben. Das Format einer Ressourcen-ID variiert in der Regel je nach Ressourcentyp.

Sie können die Sammlung von in einem Mandanten definierten Benutzerressourcen beispielsweise folgendermaßen abrufen:

GET https://graph.microsoft.com/v1.0/users HTTP/1.1
Authorization : Bearer {access_token}

Bei erfolgreicher Ausführung erhalten Sie die Antwort 200 OK, die die Sammlung von Benutzerressourcen in der Nutzlast enthält. Jeder Benutzer wird durch die Id-Eigenschaft identifiziert und von seinen Standardeigenschaften begleitet. Die unten gezeigte Nutzlast wird aus Platzgründen abgeschnitten.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "value":[
    {
      "id":"f71f1f74-bf1f-4e6b-b266-c777ea76e2c7",
      "businessPhones":[

      ],
      "displayName":"CIE Administrator",
      "givenName":"CIE",
      "jobTitle":null,
      "mail":"admin@contoso.com",
      "mobilePhone":"+1 3528700812",
      "officeLocation":null,
      "preferredLanguage":"en-US",
      "surname":"Administrator",
      "userPrincipalName":"admin@contoso.com"
    },
    {
      "id":"d66f2902-9d12-4ff8-ab01-21ec6706079f",
      "businessPhones":[

      ],
      "displayName":"Alan Steiner",
      "givenName":"Alan",
      "jobTitle":"VP Corporate Marketing",
      "mail":"alans@contoso.com",
      "mobilePhone":null,
      "officeLocation":null,
      "preferredLanguage":"en-US",
      "surname":"Steiner",
      "userPrincipalName":"alans@contoso.com"
    }
  ]
}

Mit Microsoft Graph können Sie auch Sammlungen anzeigen, indem Sie in den Beziehungen einer Ressource zu einer anderen navigieren. Beispielsweise können Sie über die mailFolders-Navigationseigenschaft eines Benutzers die Sammlung von mailFolder-Ressourcen im Postfach des Benutzers abfragen:

GET https://graph.microsoft.com/v1.0/me/mailfolders HTTP/1.1
Authorization : Bearer {access_token}

Wenn dies erfolgreich ist, erhalten Sie eine 200 OK-Antwort, die die Sammlung von mailFolder-Ressourcen in der Nutzlast enthält. Jeder mailFolder wird durch die id-Eigenschaft identifiziert und von seinen Eigenschaften begleitet. Die unten gezeigte Nutzlast wird aus Platzgründen abgeschnitten.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('16f5a7b6-5a15-4568-aa5a-31bb117e9967')/mailFolders",
  "value":[
    {
      "id":"AAMkADRm9AABDGisXAAA=",
      "displayName":"Archive",
      "parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
      "childFolderCount":0,
      "unreadItemCount":0,
      "totalItemCount":0
    },
    {
      "id":"AQMkADRm0AAAIBXAAAAA==",
      "displayName":"Sales reports",
      "parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
      "childFolderCount":0,
      "unreadItemCount":0,
      "totalItemCount":0
    },
    {
      "id":"AAMkADRCxI9AAAT6CAIAAA=",
      "displayName":"Conversation History",
      "parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
      "childFolderCount":1,
      "unreadItemCount":0,
      "totalItemCount":0
    }
  ]
}

Anzeigen einer bestimmten Ressource aus einer Sammlung nach ID

Bei den meisten Entitäten in Microsoft Graph ist die ID der Primärschlüssel.

Wir verwenden weiterhin user als Beispiel. Zum Anzeigen der Informationen zu einem Benutzer verwenden Sie eine HTTPS GET-Anforderung, um einen bestimmten Benutzer anhand der Benutzer-ID abzurufen. Für eine user-Entität können Sie entweder die id- oder die userPrincipalName-Eigenschaft als Bezeichner verwenden.

Im folgenden Anforderungsbeispiel wird der userPrincipalName-Wert als Benutzer-ID verwendet.

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.com HTTP/1.1
Authorization : Bearer {access_token}

Wenn der Vorgang erfolgreich ist, erhalten Sie den Statuscode 200 OK mit der Benutzerressourcendarstellung in der Nutzlast, wie im Folgenden dargestellt.

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 982

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "id": "c95e3b3a-c33b-48da-a6e9-eb101e8a4205",
    "city": "Redmond",
    "country": "USA",
    "department": "Help Center",
    "displayName": "John Doe",
    "givenName": "John",
    "userPrincipalName": "john.doe@contoso.com",

    ...
}

Anzeigen einer bestimmten Ressource aus einer Sammlung anhand eines alternativen Schlüssels

Einige Entitäten unterstützen einen alternativen Schlüssel, den Sie zum Abrufen eines Objekts anstelle der Primärschlüssel-ID verwenden können. Beispielsweise unterstützen die Entitäten application und servicePrincipal den alternativen Schlüssel appId .

Im folgenden Beispiel wird die Syntax des alternativen Schlüssels verwendet, um einen Dienstprinzipal anhand seiner appId abzurufen.

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='00000003-0000-0000-c000-000000000000') HTTP/1.1
Authorization : Bearer {access_token}

Lesen der spezifischen Eigenschaften einer Ressource

Um nur biographische Daten des Benutzers abzurufen, z. B. die vom Benutzer bereitgestellte Beschreibung im Feld Über mich und seine Qualifikationen, können Sie den select-Abfrageparameter zu der vorherigen Anforderung hinzufügen, wie im folgenden Beispiel dargestellt.

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.com?$select=displayName,aboutMe,skills HTTP/1.1
Authorization : Bearer {access_token}

Bei erfolgreicher Antwort wird der Statuscode 200 OK und eine Nutzlast zurückgegeben, wie dargestellt. 

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 169

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "aboutMe": "A cool and nice guy.",
    "displayName": "John Doe",
    "skills": [
        "n-Lingual",
        "public speaking",
        "doodling"
    ]
}

Statt aller Eigenschaftensätze für die user-Entität werden hier nur die grundlegenden aboutMe-, displayName- und skills-Eigenschaften zurückgegeben.

Wenn Sie eine GET-Anforderung ausführen, ohne $select die Menge der Eigenschaftendaten zu begrenzen, enthält Microsoft Graph eine @microsoft.graph.tips-Eigenschaft , die eine Empfehlung für bewährte Methoden für die Verwendung $select ähnlich der folgenden Meldung bietet:

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

Nur eine Eigenschaft einer Ressource lesen

Sie können eine einzelne Eigenschaft einer Ressource abrufen, ohne zu verwenden $select, indem Sie den Eigenschaftennamen als Pfadsegment angeben. Mit dieser Abfrage können Sie nicht mehrere Eigenschaften abrufen, aber sie kann nützlich sein, wenn Sie nur eine einzelne Eigenschaft benötigen.

Im folgenden Beispiel wird der displayName eines Benutzers abgerufen.

GET https://graph.microsoft.com/beta/users/8afc02cb-4d62-4dba-b536-9f6d73e9be26/displayName HTTP/1.1
Authorization : Bearer {access_token}

Lesen der spezifischen Eigenschaften der Ressourcen in einer Sammlung

Zusätzlich zum Lesen spezifischer Eigenschaften einer einzelnen Ressource können Sie auch den ähnlichen Abfrageparameter $select auf eine Sammlung anwenden, um alle Ressourcen in der Sammlung mit nur den spezifischen Eigenschaften zurückzugeben, die jeweils zurückgegeben werden.

Senden Sie zum Abfragen des Namens der Laufwerkelemente vom angemeldeten Benutzer die folgende HTTPS-GET-Anforderung:

GET https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name HTTP/1.1
Authorization : Bearer {access_token}

Bei einer erfolgreichen Antwort werden der Statuscode 200 OK und eine Nutzlast mit den Namen der freigegebenen Dateien zurückgegeben, wie im folgenden Beispiel dargestellt:

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('john.doe%40contoso.com')/drive/root/children(name,type)",
  "value": [
    {
      "@odata.etag": "\"{896A8E4D-27BF-424B-A0DA-F073AE6570E2},2\"",
      "name": "Shared with Everyone"
    },
    {
      "@odata.etag": "\"{B39D5D2E-E968-491A-B0EB-D5D0431CB423},1\"",
      "name": "Documents"
    },
    {
      "@odata.etag": "\"{9B51EA38-3EE6-4DC1-96A6-230E325EF054},2\"",
      "name": "newFile.txt"
    }
  ]
}

Durchqueren von einer Ressource zu einer anderen anhand der Beziehung

Ein Vorgesetzter verfügt über eine directReports-Beziehung mit den anderen Benutzern, die ihm berichte. Zum Abfragen der Liste der direkten Mitarbeiter eines Benutzers können Sie die folgende HTTPS-GET-Anforderung zum Navigieren zum gewünschten Ziel über das Durchlaufen von Beziehungen verwenden.

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.com/directReports HTTP/1.1
Authorization : Bearer {access_token}

Bei erfolgreicher Antwort wird der Statuscode 200 OK und eine Nutzlast zurückgegeben, wie dargestellt. 

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 152

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#directoryObjects/$entity",
    "@odata.type": "#microsoft.graph.user",
    "id": "c37b074d-fe9d-4e68-83ad-b4401d3be174",
    "department": "Sales & Marketing",
    "displayName": "Bonnie Kearney",

    ...
}

Ebenso können Sie anhand einer Beziehung zu verwandten Ressourcen navigieren. Beispielsweise ermöglicht die Benutzer-Nachrichten-Beziehung den Durchlauf von einem Microsoft Entra Benutzer zu einer Gruppe von Outlook-E-Mail-Nachrichten. Das folgende Beispiel zeigt, wie dies in einem REST-API-Aufruf erfolgt.

GET https://graph.microsoft.com/v1.0/me/messages HTTP/1.1
Authorization : Bearer {access_token}

Bei erfolgreicher Antwort wird der Statuscode 200 OK und eine Nutzlast zurückgegeben, wie dargestellt. 

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
odata-version: 4.0
content-length: 147

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('john.doe%40contoso.com')/Messages",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$top=1&$skip=1",
  "value": [
    {
      "@odata.etag": "W/\"FwAAABYAAABMR67yw0CmT4x0kVgQUH/3AAJL+Kej\"",
      "id": "<id-value>",
      "createdDateTime": "2015-11-14T00:24:42Z",
      "lastModifiedDateTime": "2015-11-14T00:24:42Z",
      "changeKey": "FwAAABYAAABMR67yw0CmT4x0kVgQUH/3AAJL+Kej",
      "categories": [],
      "receivedDateTime": "2015-11-14T00:24:42Z",
      "sentDateTime": "2015-11-14T00:24:28Z",
      "hasAttachments": false,
      "subject": "Did you see last night's game?",
      "body": {
        "ContentType": "HTML",
        "Content": "<content>"
      },
      "BodyPreview": "it was great!",
      "Importance": "Normal",

       ...
    }
  ]
}

Sie können alle Beziehungen in einer bestimmten Ressource anzeigen, indem Sie zu den Metadaten wechseln, den EntityType suchen und sich alle NavigationProperty-Werte für diesen EntityType ansehen.

Anrufen von Aktionen und Funktionen

Microsoft Graph unterstützt auch Aktionen und Funktionen zum Bearbeiten von Ressourcen auf andere Art und Weise als einfache CRUD-Vorgänge (Erstellen, Lesen, Aktualisieren und Löschen). Diese liegen häufig in der Form von HTTPS-POST-Anforderungen vor, um Argumente für die Aktion oder Funktion aufzunehmen. Die folgende Aktion z. B. ermöglicht es dem angemeldeten Benutzer (me), eine E-Mail zu senden.

POST https://graph.microsoft.com/v1.0/me/sendMail HTTP/1.1
authorization: bearer {access_token}
content-type: application/json
content-length: 96

{
  "message": {
    "subject": "Meet for lunch?",
    "body": {
      "contentType": "Text",
      "content": "The new cafeteria is open."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "garthf@contoso.com"
        }
      }
    ],
    "attachments": [
      {
        "@odata.type": "microsoft.graph.fileAttachment",
        "name": "menu.txt",
        "contentBytes": "bWFjIGFuZCBjaGVlc2UgdG9kYXk="
      }
    ]
  },
  "saveToSentItems": "false"
}

Sie können alle Funktionen sehen, die in den Metadaten verfügbar sind. Sie werden als Funktionen oder Aktionen angezeigt.

Verwendung der Microsoft Graph-SDKs

Sie bevorzugen die Benutzerfreundlichkeit und die leistungsstarken Funktionen von SDKs? Sie können zwar immer REST-APIs verwenden, um Microsoft Graph aufzurufen, aber wir stellen auch SDKs für viele beliebte Plattformen bereit. Informationen zu den verfügbaren SDKs finden Sie unter Codebeispiele und SDKs.

Verwandte Inhalte