Anforderungsunterschiede zwischen Azure AD Graph und Microsoft Graph

  • Artikel
  • 4 Minuten Lesedauer

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 und unterstützen jeweils OData-Konventionen für Abfrageparameter. Die Syntax variiert jedoch zwischen diesen beiden APIs.

Verwenden Sie graph-Explorer , um diese Anforderungsmuster für Ihre eigenen Daten zu testen, da dies eine hervorragende Möglichkeit ist, sich über die Unterschiede zwischen Anforderung und Antwort zu informieren.

Grundlegende Anforderungen

In der folgenden Tabelle werden die wichtigsten 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 https://graph.cloudapi.de https://graph.microsoft.de
- China (21Vianet) https://graph.chinacloudapi.cn https://microsoftgraph.chinacloudapi.cn
{tenant_id} Geben Sie die ID des Mandanten in der Anforderung an. Es ist optional, eine Mandanten-ID in der Anforderung anzugeben, da sie aus dem Zugriffstoken abgeleitet wird.

Wenn Sie die Mandanten-ID angeben, wechselt sie zwischen und {version} in der {resource} Anforderungs-URL.
{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.

Sie können weiterhin dieselben Abfrageparameter in Microsoft Graph wie Azure AD Graph verwenden.

Beispiel für einen Anforderungsvergleich

Angenommen, Sie möchten eine Liste aller Benutzer mit Namen, die mit "Dan" beginnen.

In Azure AD Graph können Sie diese Anforderung verwenden:

GET https://graph.windows.net/contoso.com/users?$filter=startswith(givenName,'Dan')&api-version=1.6 Oder

GET https://graph.windows.net/myOrganization/users?$filter=startswith(givenName,'Dan')&api-version=1.6

Diese Anforderung:

  • Zielversion 1.6 von Azure AD Graph.
  • Gibt als Mandanten-ID an contoso.com . Die Alternative zeigt die Verwendung eines Alias myOrganization basierend auf der Mandanten-ID im Zugriffstoken.
  • Ruft die Ressource users auf.
  • Verwendet den $filter Abfrageparameter, um die Antwort auf bestimmte Namen zu beschränken, die mit Danbeginnen.

Zu den Ergebnissen gehören Benutzer mit Namen wie Daniel, Danforth, Danielle, Danerys usw.

Eine ähnliche Anforderung für Microsoft Graph wäre:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName,'Dan')

Hier:

  • Die Version ist v1.0.
  • Die Mandanten-ID wird aus dem Zugriffstoken abgeleitet (nicht angezeigt).
  • Die Ressource und $filter der Abfrageparameter sind identisch mit der Azure AD-Abfrage.

HINWEIS: Wenn Sie die Azure AD Graph .NET-Clientbibliothek verwenden, finden Sie unter .NET-Clientbibliotheken spezifischere Strategien und Unterstützung für den Wechsel zur Microsoft Graph .NET-Clientbibliothek.

Schlüsselbezeichner: objectId vs. id

In Azure AD Graph verfügen alle Entitätsressourcentypen über einen eindeutigen Bezeichner (oder Schlüssel) namens objectId. Derselbe Bezeichner wird in Microsoft Graph größtenteils (sofern nicht anders angegeben) als ID bezeichnet.

Standardeigenschaften und $select

Verwenden Sie den $select Abfrageparameter in GET-Anforderungen, um die Antwort so anzupassen, dass sie alle Eigenschaften enthält, die Ihre App benötigt.

Microsoft Graph-Get- oder List-Vorgänge für Benutzer- oder Gruppenressourcen gibt nur eine Teilmenge aller Eigenschaften zurück, die als Standardeigenschaften bezeichnet werden. Die Standardeigenschaften stellen die am häufigsten verwendeten Eigenschaften für eine Ressource dar. Auf der anderen Seite gibt Azure AD Graph den vollständigen Satz aller Eigenschaften für die jeweilige Ressource zurück.

Um andere Eigenschaften in v1.0 abzurufen, muss Ihre App diese mithilfe des $select Abfrageparameters explizit anfordern. Dies schließt alle Verzeichnisschemaerweiterungen ein, die Ihre App möglicherweise verwendet. Es ist eine bewährte Methode, nur die Eigenschaften anzufordern, die Ihre App wirklich benötigt.

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/

Überprüfen Sie die Antworten jeder Abfrage. Sie werden feststellen, dass Adressinformationen von der /beta-Version zurückgegeben werden, aber nicht von der Version /v1.0. Das liegt daran, dass die Adresseigenschaften nicht im Standardeigenschaftensatz enthalten sind.

Wenn Ihre App auf den Adresseigenschaften basiert, müssen Sie Ihre v1.0-Anforderungen aktualisieren, um den $select Abfrageparameter einzuschließen:

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

Die Antwort für diese Anforderung würde die Adresseigenschaften enthalten. Es enthält auch die displayName-Eigenschaft , aber nur, weil sie vom Abfrageparameter angegeben wurde.

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. In Microsoft Graph wird stattdessen die OData v4.01-Notation $ref verwendet.

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

Wenn Sie Ihre Apps zu Microsoft Graph migrieren, suchen Sie nach Anforderungen, die zum Zuordnen von Ressourcen verwenden $links . Ändern Sie diese stattdessen, um sie zu verwenden $ref .

Nächste Schritte