Feedback Bearbeiten

Gruppen auflisten

  • Artikel
  • 17 Minuten Lesedauer

Namespace: microsoft.graph

Wichtig

APIs unter der /beta Version in Microsoft Graph können geändert werden. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in Version 1.0 verfügbar ist, verwenden Sie die Versionsauswahl .

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 Standard eigenschaften 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. Die hasMembersWithLicenseErrors und isArchived bilden eine Ausnahme und werden in der Abfrage nicht$select zurückgegeben.

Berechtigungen

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

Berechtigungstyp Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
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
Anwendung GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All

HTTP-Anforderung

GET /groups

Optionale Abfrageparameter

Diese Methode unterstützt die $count, $expand, $filter, $orderBy, $search, $select, und $top OData-Abfrageparameter zur Anpassung der Antwort. 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 Azure AD-Verzeichnisobjekte.

Um nur Microsoft 365-Gruppen (auch als vereinheitlichte Gruppen bezeichnet) 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 Beschreibung werden standardmäßig auf das Verhalten $filter startswith festgelegt.

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

Abrufen von Erweiterungen und zugehörigen Daten

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

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich.
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 $count finden Sie unter Erweiterte Abfragefunktionen für Azure AD-Verzeichnisobjekte.

Anforderungstext

Geben Sie für diese Methode keinen Anforderungstext 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

Nachfolgend sehen Sie ein Beispiel der Anforderung.

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

Antwort

Nachfolgend sehen Sie ein Beispiel der Antwort.

Hinweis: Das hier gezeigte Antwortobjekt wurde möglicherweise aus Gründen der Lesbarkeit gekürzt. Bei einem tatsächlichen Aufruf werden alle Standardeigenschaften für jede Gruppe 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.onmicrosoft.com",
            "SMTP:golfassist@contoso.com"
         ],
         "renewedDateTime":"2018-12-22T02:21:05Z",
         "resourceBehaviorOptions":[
         ],
         "resourceProvisioningOptions":[
         ],
         "securityEnabled":false,
         "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.onmicrosoft.com",
            "SMTP:golftalk@contoso.com"
         ],
         "renewedDateTime":"2018-11-19T20:29:40Z",
         "resourceBehaviorOptions":[
         ],
         "resourceProvisioningOptions":[
         ],
         "securityEnabled":false,
         "theme":null,
         "visibility":null,
         "onPremisesProvisioningErrors":[
         ]
      }
   ]
}

Beispiel 2: Eine gefilterte Liste von Gruppen einschließlich der Anzahl der erhaltenen Objekte abrufen

Anforderung

Nachfolgend sehen Sie ein Beispiel der Anforderung. 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 $count finden Sie unter Erweiterte Abfragefunktionen für Azure AD-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=true&$filter=hasMembersWithLicenseErrors+eq+true&$select=id,displayName
ConsistencyLevel: eventual

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)",
   "@odata.count":2,
   "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

Nachfolgend sehen Sie ein Beispiel der Anforderung. 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 $count finden Sie unter Erweiterte Abfragefunktionen für Azure AD-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

Nachfolgend sehen Sie ein Beispiel der 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

Nachfolgend sehen Sie ein Beispiel der Anforderung. 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 $count finden Sie unter Erweiterte Abfragefunktionen für Azure AD-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

Nachfolgend sehen Sie ein Beispiel der 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 zu erhalten, die „Video“ enthalten, einschließlich der Anzahl erhaltener Objekte

Anforderung

Nachfolgend sehen Sie ein Beispiel der Anforderung. 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 $count finden Sie unter Erweiterte Abfragefunktionen für Azure AD-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"&$count=true
ConsistencyLevel: eventual

Antwort

Nachfolgend sehen Sie ein Beispiel der 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"
      }
   ]
}

Beispiel 6: Verwenden Sie $search, um Gruppen mit Anzeigenamen abzurufen, die „Video“ oder eine Beschreibung mit den Buchstaben „prod“ enthalten, einschließlich der Anzahl erhaltener Objekte

Anforderung

Nachfolgend sehen Sie ein Beispiel der Anforderung. 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 $count finden Sie unter Erweiterte Abfragefunktionen für Azure AD-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

Nachfolgend sehen Sie ein Beispiel der 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 7: Auflisten dynamischer Gruppen

Anforderung

Im Folgenden finden Sie ein Beispiel für die Anforderung, die nach der 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 $count finden Sie unter Erweiterte Abfragefunktionen für Azure AD-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

Nachfolgend sehen Sie ein Beispiel der 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 8: Auflisten von Gruppen mit beliebigen Lizenzen

Anforderung

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

Antwort

Nachfolgend sehen Sie ein Beispiel der Antwort.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups(id,assignedLicenses)",
    "value": [
        {
            "id": "5caf712c-8483-4b3d-8384-d8da988c0ca4",
            "assignedLicenses": [
                {
                    "disabledPlans": [],
                    "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900"
                }
            ]
        },
        {
            "id": "aae8ec2a-5a08-4013-ae70-fafbb5c20de1",
            "assignedLicenses": [
                {
                    "disabledPlans": [
                        "7547a3fe-08ee-4ccb-b430-5077c5041653"
                    ],
                    "skuId": "18181a46-0d4e-45cd-891e-60aabd171b4e"
                }
            ]
        },
        {
            "id": "e55bdaa0-e104-479a-979e-b0457fff6380",
            "assignedLicenses": [
                {
                    "disabledPlans": [
                        "7547a3fe-08ee-4ccb-b430-5077c5041653"
                    ],
                    "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900"
                }
            ]
        }
    ]
}