Freigeben über

Gruppen auflisten

  • Artikel

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.

Listen Sie alle in einer Organisation verfügbaren Gruppen auf, ausgenommen dynamische Verteilergruppen. Verwenden Sie zum Abrufen dynamischer Verteilergruppen das Exchange Admin Center.

Dieser Vorgang gibt standardmäßig nur eine Teilmenge der häufiger verwendeten Eigenschaften für jede Gruppe zurück. Diese Standardeigenschaften werden im Abschnitt Eigenschaften aufgeführt. Um Eigenschaften abzurufen, die nicht standardmäßig zurückgegeben werden, führen Sie eine GET-Operation für die Gruppe aus, und geben Sie die Eigenschaften in einer $select OData-Abfrageoption an. DiehasMembersWithLicenseErrors und isArchived bilden eine Ausnahme und werden in der Abfrage nicht$select zurückgegeben.

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

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

Berechtigungen

Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

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

HTTP-Anforderung

GET /groups

Optionale Abfrageparameter

Diese Methode unterstützt die OData-Abfrageparameter$count, $expand$orderby$filter, , $search, $selectund $top zum Anpassen der Antwort. $skip wird nicht unterstützt. Die Standard- und die maximale Seitengröße sind jeweils 100 bzw. 999 Gruppenobjekte. Einige Abfragen werden nur unterstützt, wenn Sie die Kopfzeile ConsistencyLevel verwenden, die auf eventual und $count festgelegt ist. Weitere Informationen finden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Um nur Microsoft 365-Gruppen (einheitliche Gruppen) aufzulisten, wenden Sie einen Filter auf groupTypes an:

GET https://graph.microsoft.com/beta/groups?$filter=groupTypes/any(c:c+eq+'Unified')

Der Abfrageparameter $search unterstützt die Tokenisierung nur für die Felder displayName und Beschreibung und erfordert die Kopfzeile ConsistencyLevel. Andere Felder als displayName und description werden standardmäßig auf $filterstartsWith Verhalten festgelegt.

Erweiterungseigenschaften unterstützen auch Abfrageparameter wie folgt:

Erweiterungstyp Kommentare
Schemaerweiterungen Wird nur mit $select zurückgegeben.
Offene Erweiterungen Wird nur mit $expand zurückgegeben.
Verzeichniserweiterungen Wird standardmäßig zurückgegeben.

Weitere Informationen zu OData-Abfrageoptionen finden Sie unter OData-Abfrageparameter. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Filtern nach Gruppentypen

Gruppentyp API-Anforderung
Microsoft 365-Gruppen (unified) ABRUFEN/groups?$filter=groupTypes/any(c:c+eq+'Unified')
Sicherheitsgruppen ABRUFEN/groups?$filter=mailEnabled eq false&securityEnabled eq true
E-Mail-aktivierte Sicherheitsgruppen ERHALTEN/groups?$filter=NOT groupTypes/any(c:c eq 'Unified') and mailEnabled eq true and securityEnabled eq true&$count=true **
Verteilergruppen ERHALTEN/groups?$filter=NOT groupTypes/any(c:c eq 'Unified') and mailEnabled eq true and securityEnabled eq false&$count=true **

** : Dieses Beispiel wird nur mit erweiterten Abfragefunktionen unterstützt.

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung.
ConsistencyLevel schließlich. Diese Kopfzeile und $count sind erforderlich, wenn $search verwendet wird oder wenn $filter verwendet wird. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Anforderungstext

Geben Sie keinen Anforderungstext für diese Methode an.

Antwort

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK und eine Sammlung von group-Objekten im Antworttext zurückgegeben. Die Antwort enthält nur die Standardeigenschaften der einzelnen Gruppen.

Beispiele

Beispiel 1: Eine Liste von Gruppen abrufen

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

GET https://graph.microsoft.com/beta/groups

Antwort

Das folgende Beispiel zeigt die Antwort.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden. Alle Standardeigenschaften werden für jede Gruppe in einem tatsächlichen Aufruf zurückgegeben.

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

{
   "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
   "value":[
      {
         "id":"45b7d2e7-b882-4a80-ba97-10b7a63b8fa4",
         "deletedDateTime":null,
         "classification":null,
         "createdDateTime":"2018-12-22T02:21:05Z",
         "description":"Self help community for golf",
         "displayName":"Golf Assist",
         "expirationDateTime":null,
         "groupTypes":[
            "Unified"
         ],
         "isAssignableToRole":null,
         "mail":"golfassist@contoso.com",
         "mailEnabled":true,
         "mailNickname":"golfassist",
         "membershipRule":null,
         "membershipRuleProcessingState":null,
         "onPremisesLastSyncDateTime":null,
         "onPremisesSecurityIdentifier":null,
         "onPremisesSyncEnabled":null,
         "preferredDataLocation":"CAN",
         "preferredLanguage":null,
         "proxyAddresses":[
            "smtp:golfassist@contoso.com",
            "SMTP:golfassist@contoso.com"
         ],
         "renewedDateTime":"2018-12-22T02:21:05Z",
         "resourceBehaviorOptions":[
         ],
         "resourceProvisioningOptions":[
         ],
         "securityEnabled":false,
         "serviceProvisioningErrors": [
         ],
         "theme":null,
         "visibility":"Public",
         "onPremisesProvisioningErrors":[
         ]
      },
      {
         "id":"d7797254-3084-44d0-99c9-a3b5ab149538",
         "deletedDateTime":null,
         "classification":null,
         "createdDateTime":"2018-11-19T20:29:40Z",
         "description":"Talk about golf",
         "displayName":"Golf Discussion",
         "expirationDateTime":null,
         "groupTypes":[
         ],
         "isAssignableToRole":null,
         "mail":"golftalk@contoso.com",
         "mailEnabled":true,
         "mailNickname":"golftalk",
         "membershipRule":null,
         "membershipRuleProcessingState":null,
         "onPremisesLastSyncDateTime":null,
         "onPremisesSecurityIdentifier":null,
         "onPremisesSyncEnabled":null,
         "preferredDataLocation":"CAN",
         "preferredLanguage":null,
         "proxyAddresses":[
            "smtp:golftalk@contoso.com",
            "SMTP:golftalk@contoso.com"
         ],
         "renewedDateTime":"2018-11-19T20:29:40Z",
         "resourceBehaviorOptions":[
         ],
         "resourceProvisioningOptions":[
         ],
         "securityEnabled":false,
         "serviceProvisioningErrors": [
         ],
         "theme":null,
         "visibility":null,
         "onPremisesProvisioningErrors":[
         ]
      }
   ]
}

Beispiel 2: Abrufen einer gefilterten Liste von Gruppen

Diese Anforderung, die nach der hasMembersWithLicenseErrors-Eigenschaft filtert , unterstützt nicht das Abrufen der Anzahl der zurückgegebenen Objekte.

Anforderung

GET https://graph.microsoft.com/beta/groups?$filter=hasMembersWithLicenseErrors+eq+true&$select=id,displayName

Antwort

Nachfolgend finden Sie ein Beispiel der Antwort, die nur die angeforderten Eigenschaften umfasst.

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

{
   "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups(id,displayName)",
   "value":[
      {
         "id":"11111111-2222-3333-4444-555555555555",
         "displayName":"Contoso Group 1"
      },
      {
         "id":"22222222-3333-4444-5555-666666666666",
         "displayName":"Contoso Group 2"
      }
   ]
}

Beispiel 3: Nur die Anzahl von Gruppen abrufen

Anforderung

Das folgende Beispiel zeigt eine Anfrage. Für diese Anforderung muss die Kopfzeile ConsistencyLevel auf eventual festgelegt werden, da $count in der Anforderung enthalten ist. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Hinweis: Die Abfrageparameter $count und $search sind im Azure AD B2C-Mandanten derzeit nicht verfügbar.

GET https://graph.microsoft.com/beta/groups/$count
ConsistencyLevel: eventual

Antwort

Das folgende Beispiel zeigt die Antwort.

HTTP/1.1 200 OK
Content-type: text/plain

893

Beispiel 4: Verwenden Sie $filter und $top, um eine Gruppe mit einem Anzeigenamen abzurufen, der mit 'a' beginnt, einschließlich der Anzahl erhaltener Objekte

Anforderung

Das folgende Beispiel zeigt eine Anfrage. Für diese Anforderung muss die Kopfzeile ConsistencyLevel auf eventual und die $count=true-Abfragezeichenfolge festgelegt werden, da die Anforderung die Abfrageparameter $orderby und $filter aufweist. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Hinweis: Die Abfrageparameter $count und $search sind im Azure AD B2C-Mandanten derzeit nicht verfügbar.

GET https://graph.microsoft.com/beta/groups?$filter=startswith(displayName, 'a')&$count=true&$top=1&$orderby=displayName
ConsistencyLevel: eventual

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#groups",
   "@odata.count":1,
   "value":[
      {
         "displayName":"a",
         "mailNickname":"a241"
      }
   ]
}

Beispiel 5: Verwenden sie $search, um Gruppen mit Anzeigenamen abzurufen, die die Buchstaben "Video" oder eine Beschreibung enthalten, die die Buchstaben "prod" enthält, einschließlich der Anzahl der zurückgegebenen Objekte

Anforderung

Das folgende Beispiel zeigt eine Anfrage. Für diese Anforderung muss die Kopfzeile ConsistencyLevel auf eventual festgelegt werden, da $search in der Anforderung enthalten ist. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Hinweis: Die Abfrageparameter $count und $search sind im Azure AD B2C-Mandanten derzeit nicht verfügbar.

GET https://graph.microsoft.com/beta/groups?$search="displayName:Video" OR "description:prod"&$orderby=displayName&$count=true
ConsistencyLevel: eventual

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#groups",
   "@odata.count":1396,
   "value":[
      {
         "displayName":"SFA Videos",
         "mail":"SFAVideos@service.contoso.com",
         "mailNickname":"SFAVideos"
      },
      {
         "description":"Video Production",
         "displayName":"Video Production",
         "mail":"videoprod@service.contoso.com",
         "mailNickname":"VideoProduction"
      }
   ]
}

Beispiel 6: Auflisten dynamischer Gruppen

Anforderung

Das folgende Beispiel zeigt eine Anforderung, die nach membershipRuleProcessingState filtert , um dynamische Gruppen abzurufen. Sie können auch nach den groupTypes-Eigenschaften filtern (d. h. $filter=groupTypes/any(s:s eq 'DynamicMembership')). Für diese Anforderung muss die Kopfzeile ConsistencyLevel auf eventual festgelegt und die $count=true-Abfragezeichenfolge ist erforderlich, da die Anforderung den not-Operator des $filter-Abfrageparameters verwendet. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Hinweis: Die Abfrageparameter $count und $search sind im Azure AD B2C-Mandanten derzeit nicht verfügbar.

GET https://graph.microsoft.com/beta/groups?$filter=mailEnabled eq false and securityEnabled eq true and NOT(groupTypes/any(s:s eq 'Unified')) and membershipRuleProcessingState eq 'On'&$count=true&$select=id,membershipRule,membershipRuleProcessingState

Antwort

Das folgende Beispiel zeigt die Antwort.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups(id,membershipRule,membershipRuleProcessingState)",
    "@odata.count": 1,
    "value": [
        {
            "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/e9f4a701-e7b5-4401-a0ca-5bd5f3cdcf4b/Microsoft.DirectoryServices.Group",
            "id": "e9f4a701-e7b5-4401-a0ca-5bd5f3cdcf4b",
            "membershipRule": "(user.userType -contains \"Guest\" and user.accountEnabled -eq true) or (user.city -eq \"Nairobi\")",
            "membershipRuleProcessingState": "On"
        }
    ]
}

Beispiel 7: Auflisten aller Gruppen mit beliebigen Lizenzen und Abrufen der Mitglieder der Gruppe

Anforderung

GET https://graph.microsoft.com/beta/groups?$select=id,assignedLicenses&$filter=assignedLicenses/any()&$expand=members($select=id,displayName)

Antwort

Das folgende Beispiel zeigt die Antwort.

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups(id,assignedLicenses,members())",
  "value": [
    {
      "id": "5caf712c-8483-4b3d-8384-d8da988c0ca4",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900"
        }
      ],
      "members": [
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "0952e4c8-432f-4950-a65c-769c45993527"
        },
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "49e373b6-4717-40c6-ad43-843c45a258f0"
        }
      ]
    },
    {
      "id": "aae8ec2a-5a08-4013-ae70-fafbb5c20de1",
      "assignedLicenses": [
        {
          "disabledPlans": [
            "7547a3fe-08ee-4ccb-b430-5077c5041653"
          ],
          "skuId": "18181a46-0d4e-45cd-891e-60aabd171b4e"
        }
      ],
      "members": []
    }
  ]
}