directoryObject: checkMemberGroups

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Prüft die Mitgliedschaft in einer angegebenen Liste von Gruppen-IDs und gibt von dieser Liste die IDs von Gruppen zurück, in denen ein bestimmtes Objekt Mitglied ist. Das angegebene Objekt kann einen der folgenden Typen aufweisen:

Diese Funktion ist transitiv.

Sie können maximal 20 Gruppen pro Anforderung überprüfen. Diese Funktion unterstützt alle in Microsoft Entra ID bereitgestellten Gruppen. Da Microsoft 365-Gruppen keine anderen Gruppen enthalten können, ist die Mitgliedschaft in einer Microsoft 365-Gruppe immer direkt.

Wichtig

Microsoft Graph wertet die groupIds-Sammlung als eine einzelne Anforderung aus. Wenn die Anforderung ungültig ist (z. B. eine falsch formatierte Gruppen-ID), schlägt die gesamte Anforderung fehl. Wenn der Aufrufer keinen Zugriff zum Auswerten bestimmter Gruppen hat (z. B. Gruppen mit ausgeblendeter Mitgliedschaft), enthält die Antwort möglicherweise nur die Gruppen, die er auswerten darf.

Hinweis

Die Antwortzeit hängt von der Verzeichnisstruktur Ihres Mandanten ab, einschließlich Gruppenschachtelungstiefe und Mitgliedschaftsgröße. Microsoft Graph veröffentlicht keine Latenzziele für transitive Mitgliedschafts-APIs.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Weltweiter Service US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet

Berechtigungen

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie unter Berechtigungen.

Gruppenmitgliedschaften für ein Verzeichnisobjekt

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Directory.Read.All Directory.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung Directory.Read.All Directory.ReadWrite.All

Hinweis

Mit den Directory .* -Berechtigungen können Sie jeden unterstützten Verzeichnisobjekttyp über diese API abrufen. Um nur einen bestimmten Typ abzurufen, können Sie ressourcenspezifische Berechtigungen verwenden.

Gruppenmitgliedschaften für den angemeldeten Benutzer

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) User.Read User.ReadBasic.All und GroupMember.Read.All, User.Read.All und GroupMember.Read.All, User.ReadBasic.All und Group.Read.All, User.Read.All und Group.Read.All, Directory.Read.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Application Nicht unterstützt Nicht unterstützt

Gruppenmitgliedschaften für andere Benutzer

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) User.ReadBasic.All und GroupMember.Read.All User.Read.All und GroupMember.Read.All, User.ReadBasic.All und Group.Read.All, User.Read.All und Group.Read.All, Directory.Read.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Application User.ReadBasic.All und GroupMember.Read.All User.Read.All und GroupMember.Read.All, User.Read.All und Group.Read.All, Directory.Read.All

Gruppenmitgliedschaften für eine Gruppe

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) GroupMember.Read.All Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Application GroupMember.Read.All Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All

Gruppenmitgliedschaften für einen Dienstprinzipal

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Application.Read.All Directory.Read.All, Application.ReadWrite.All, Directory.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Application Application.Read.All Directory.Read.All, Application.ReadWrite.All, Directory.ReadWrite.All

Gruppenmitgliedschaften für einen organisatorischen Kontakt

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Directory.Read.All Directory.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung Directory.Read.All Directory.ReadWrite.All

Gruppenmitgliedschaften für ein Gerät

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Device.Read.All Directory.Read.All, Directory.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Application Device.Read.All Directory.Read.All, Directory.ReadWrite.All

Wichtig

Um die Mitgliedschaft in Gruppen mit ausgeblendeter Mitgliedschaft zu bewerten, ist zusätzlicher Zugriff erforderlich:

  • Anwendungsberechtigungen: Die App muss über die Member.Read.Hidden Berechtigung verfügen.
  • Delegierte Berechtigungen: Der angemeldete Benutzer muss Mitglied der Gruppe "Versteckte Mitglieder" sein.

Wenn keine der beiden Bedingungen erfüllt ist, werden Gruppen mit ausgeblendeter Mitgliedschaft nicht ausgewertet, und diese Gruppen-IDs werden in der Antwort weggelassen.

HTTP-Anforderung

Gruppenmitgliedschaften für ein Verzeichnisobjekt (Benutzer, Gruppe, Dienstprinzipal oder Organisationskontakt).

POST /directoryObjects/{id}/checkMemberGroups

Gruppenmitgliedschaften für den angemeldeten Benutzer.

POST /me/checkMemberGroups

Gruppenmitgliedschaften für andere Benutzer.

POST /users/{id | userPrincipalName}/checkMemberGroups

Gruppenmitgliedschaften für eine Gruppe.

POST /groups/{id}/checkMemberGroups

Gruppenmitgliedschaften für einen Dienstprinzipal.

POST /servicePrincipals/{id}/checkMemberGroups

Gruppenmitgliedschaften für einen organisatorischen Kontakt.

POST /contacts/{id}/checkMemberGroups

Gruppenmitgliedschaften für ein Gerät.

POST /devices/{id}/checkMemberGroups

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung.
Content-Type application/json

Anforderungstext

Geben Sie im Anforderungstext ein JSON-Objekt mit den folgenden Parametern an.

Parameter Typ Beschreibung
groupIds Zeichenfolgenauflistung Eine Sammlung mit den Objekt-IDs der Gruppen, in denen die Mitgliedschaft überprüft werden soll. Bis zu 20 Gruppen können angegeben werden.

Antwort

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK und das String-Sammlungsobjekt im Antworttext zurückgegeben.

Beispiele

Beispiel 1: Überprüfen der Gruppenmitgliedschaften für ein Verzeichnisobjekt

Anforderung

POST https://graph.microsoft.com/beta/directoryObjects/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e/checkMemberGroups
Content-type: application/json

{
    "groupIds": [
        "f448435d-3ca7-4073-8152-a1fd73c0fd09",
        "bd7c6263-4dd5-4ae8-8c96-556e1c0bece6",
        "93670da6-d731-4366-94b5-abed40b6016b",
        "f5484ab1-4d4d-41ec-a9b8-754b3957bfc7",
        "c9103f26-f3cf-4004-a611-2a14e81b8f79"
    ]
}

Antwort

Das folgende Beispiel zeigt die Antwort.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(Edm.String)",
    "value": [
        "f448435d-3ca7-4073-8152-a1fd73c0fd09",
        "93670da6-d731-4366-94b5-abed40b6016b",
        "f5484ab1-4d4d-41ec-a9b8-754b3957bfc7",
        "c9103f26-f3cf-4004-a611-2a14e81b8f79"
    ]
}

Beispiel 2: Überprüfen der Gruppenmitgliedschaft für den angemeldeten Benutzer

Anforderung

POST https://graph.microsoft.com/beta/me/checkMemberGroups
Content-type: application/json

{
  "groupIds": [
        "fee2c45b-915a-4a64-b130-f4eb9e75525e",
        "4fe90ae7-065a-478b-9400-e0a0e1cbd540"
  ]
}

Antwort

Das folgende Beispiel zeigt die Antwort.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(Edm.String)",
  "value": [
        "fee2c45b-915a-4a64-b130-f4eb9e75525e"
  ]
}