Anforderungsunterschiede zwischen Azure AD Graph und Microsoft Graph

  • Artikel

Dieser Artikel ist Teil von Schritt 1: Überprüfen der API-Unterschiede beim Prozess zum Migrieren von Apps.

Microsoft Graph und die Azure Active Directory-Graph-API (Azure AD) sind beide REST-APIs, die OData-Konventionen für Abfrageparameter unterstützen. Die Syntax variiert jedoch zwischen diesen beiden APIs.

Verwenden Sie Graph Explorer, um diese Anforderungsmuster anhand Ihrer eigenen Daten auszuprobieren und sich über die Unterschiede zwischen Anforderung und Antwort zu informieren, bevor Sie Ihren Code aktualisieren.

Grundlegende Anforderungen

In der folgenden Tabelle werden die Standard Anforderungsunterschiede zwischen den beiden APIs hervorgehoben:

Anfragedetails Azure AD Graph Microsoft Graph
Anforderungssyntax https://graph.windows.net/{tenant_id}/{resource}?{version}&query-parameters https://graph.microsoft.com/{version}/{resource}?query-parameters
Dienstendpunkte:
-Globalen https://graph.windows.net https://graph.microsoft.com
- US Gov L4 https://graph.microsoftazure.us https://graph.microsoft.us
– US Gov L5 (DOD) https://graph.microsoftazure.us https://dod-graph.microsoft.us
- Deutschland (eingestellt) https://graph.cloudapi.de https://graph.microsoft.de
- China (21Vianet) https://graph.chinacloudapi.cn https://microsoftgraph.chinacloudapi.cn
{tenant_id} Geben Sie die Mandanten-ID oder den Domänennamen in der Anforderung an. Optional. Die Mandanten-ID wird aus dem Zugriffstoken abgeleitet.

Wenn Sie die Mandanten-ID angeben, verwenden Sie die folgende Syntax: https://graph.microsoft.com/{version}/{tenant_id}/{resource}?query-parameters.
{version} Geben Sie die Releaseversion von Azure AD Graph in der Anforderung mithilfe eines erforderlichen Abfrageparameters an. Geben Sie die Releaseversion von Microsoft Graph in der Anforderung als Teil des URL-Pfads direkt hinter dem Dienstendpunkt an.

Die Abfrageparametersyntax ist für Microsoft Graph und Azure AD Graph identisch. Microsoft Graph unterstützt jedoch mehr Abfrageparameter und Abfragefunktionen als Azure AD Graph.

Beispiel für einen Anforderungsvergleich

Angenommen, Sie möchten eine Liste aller Benutzer, deren Namen mit "Dan" im Contoso-Mandanten beginnen. Die folgende Tabelle zeigt die Anforderungsunterschiede zwischen Azure AD Graph und Microsoft Graph.

Azure AD Graph Microsoft Graph
GET https://graph.windows.net/contoso.com/users?$filter=startswith(givenName,'Dan')&api-version=1.6 GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName,'Dan')

Primärschlüsselbezeichner: objectId vs. id

In Azure AD Graph verfügen alle Entitätsressourcentypen über einen eindeutigen Bezeichner (oder Primärschlüssel) namens objectId. Für die meisten Entitäten (sofern nicht anders angegeben) wird dieser Bezeichner in Microsoft Graph als ID bezeichnet.

Zusätzlich zum Primärschlüssel unterstützen einige Entitäten einen alternativen Schlüsselbezeichner. Beispielsweise unterstützen die Application - und servicePrincipal-Ressourcen in Microsoft Graph einen alternativen Schlüsselbezeichner für ihre appId-Eigenschaft .

Standardeigenschaften und $select

Es ist eine bewährte Methode, nur die Eigenschaften anzufordern, die Ihre App wirklich benötigt. Verwenden Sie den $select Abfrageparameter in GET-Anforderungen, um die Antwort so anzupassen, dass sie nur die Eigenschaften enthält, die Ihre App benötigt.

In einigen Fällen in Microsoft Graph, z. B. bei den GET - oder LIST-Vorgängen für Benutzer - und Gruppenressourcen , wird nur eine Teilmenge aller Eigenschaften zurückgegeben. Diese Standardeigenschaften stellen die am häufigsten verwendeten Eigenschaften für die Ressourcen dar. Auf der anderen Seite gibt Azure AD Graph den vollständigen Satz aller Eigenschaften für die jeweilige Ressource zurück. Wenn die Ressource nur die Standardeigenschaften zurückgibt, muss Ihre App explizit andere Eigenschaften mithilfe des Abfrageparameters $select anfordern.

Um den Unterschied zu veranschaulichen, verwenden Sie Graph Explorer, um die folgenden Anforderungen auszuführen und die verschiedenen Antworten zu vergleichen.

GET https://graph.microsoft.com/v1.0/me/
GET https://graph.microsoft.com/beta/me/

Beachten Sie den Unterschied in den Antworten. Die /beta Version gibt mehr Eigenschaften als die /v1.0 Version zurück. Wenn Ihre App z. B. auf der streetAddress-Eigenschaft basiert, müssen Sie Ihre v1.0 Anforderungen so aktualisieren, dass der $select Abfrageparameter verwendet wird, um die streetAddress-Eigenschaft zusätzlich zu anderen Eigenschaften anzufordern, die die App benötigt. Zum Beispiel:

https://graph.microsoft.com/v1.0/me?$select=displayName,streetAddress,city,state,postalCode

Weitere Informationen:

Beziehungen und Navigationseigenschaften

Beziehungen (oder Navigationseigenschaften) sind ein wichtiges Konzept in Azure AD Graph und Microsoft Graph und erstellen ein Netzwerk verwandter Ressourcen. Beispielsweise erweitern die Eigenschaften manager und directReports die Benutzerressource, um eine Organisationshierarchie bereitzustellen.

Beziehungen definieren auch Mitgliedschaften, z. B. die Gruppen, zu der ein Benutzer gehört, die Mitglieder einer Gruppe oder einer Verzeichnisrolle usw.

Azure AD Graph-Anforderungen verwenden $links , um Beziehungen zwischen Ressourcen anzugeben. Microsoft Graph verwendet stattdessen die OData v4.01-Notation $ref .

Die folgende Tabelle enthält mehrere Beispiele:

Aufgabe Azure AD Graph Microsoft Graph
Mitglied hinzufügen POST /groups/{id}/$links/members POST /groups/{id}/members/$ref
Memberlinks auflisten GET /groups/{id}/$links/members GET /groups/{id}/members/$ref
Mitglieder auflisten GET /groups/{id}/members GET /groups/{id}/members
Mitglied entfernen DELETE /groups/{id}/$links/members/{id} DELETE /groups/{id}/members/{id}/$ref

Aktualisieren Sie beim Migrieren Ihrer Apps zu Microsoft Graph Verweise, die verwenden $links , um stattdessen ressourcen zu verwenden $ref .

Nächster Schritt

Überprüfen Sie die Migrationsprüfliste erneut.