Gruppen auflistenList groups

Namespace: microsoft.graphNamespace: microsoft.graph

Wichtig

APIs unter der /beta Version in Microsoft Graph können Änderungen unterworfen werden.APIs under the /beta version in Microsoft Graph are subject to change. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt.Use of these APIs in production applications is not supported.

Dient zum Auflisten aller Gruppen in einer Organisation, einschließlich, aber nicht beschränkt auf Office 365-Gruppen.List all the groups in an organization, including but not limited to Office 365 Groups.

Dieser Vorgang gibt standardmäßig nur eine Teilmenge der häufiger verwendeten Eigenschaften für jede Gruppe zurück.This operation returns by default only a subset of the more commonly used properties for each group. Diese _Standard_eigenschaften werden im Abschnitt Eigenschaften aufgeführt.These default properties are noted in the Properties section. 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.To get properties that are not returned by default, do a GET operation for the group and specify the properties in a $select OData query option. Die hasMembersWithLicenseErrors-Eigenschaft ist eine Ausnahme und wird in der $select-Abfrage nicht zurückgegeben.The hasMembersWithLicenseErrors property is an exception and is not returned in the $select query.

BerechtigungenPermissions

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.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

BerechtigungstypPermission type Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)Permissions (from least to most privileged)
Delegiert (Geschäfts-, Schul- oder Unikonto)Delegated (work or school account) Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.AllGroup.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
Delegiert (persönliches Microsoft-Konto)Delegated (personal Microsoft account) Nicht unterstütztNot supported.
ApplicationApplication Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.AllGroup.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All

HTTP-AnforderungHTTP request

GET /groups

Optionale AbfrageparameterOptional query parameters

Um nur Office 365-Gruppen (auch als einheitliche Gruppen bezeichnet) aufzulisten, wenden Sie einen Filter auf groupTypes an:To list only Office 365 Groups (aka unified groups), apply a filter on groupTypes:

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

Sie können die OData-Abfrageoption $orderby verwenden, um Gruppen in einer Organisation nach ihrem jeweiligen Wert für displayName zu sortieren. Hier ein Beispiel:You can use the OData query option $orderby to sort groups in an organization by the displayName values, as shown in the following example:

GET https://graph.microsoft.com/beta/groups?$orderby=displayName

Sie können auch die $count -und $search Abfrageparameter verwenden, um die Antwort zu begrenzen.You can also use the $count and $search query parameters to limit the response. Der $search Abfrageparameter unterstützt die Tokenisierung nur für die Felder DisplayName und Description .The $search query parameter supports tokenization only on the displayName and description fields. Andere Felder Verhalten standardmäßig $filter .Other fields default to $filter behavior. Wenn Elemente für diese Ressource hinzugefügt oder aktualisiert werden, werden Sie speziell für die Verwendung mit den $count -und $search Abfrageparametern indiziert.When items are added or updated for this resource, they are specially indexed for use with the $count and $search query parameters. Es kann eine geringfügige Verzögerung zwischen dem Hinzufügen oder Aktualisieren eines Elements und der Verfügbarkeit im Index auftreten.There can be a slight delay between when an item is added or updated and when it is available in the index.

Weitere Informationen finden Sie unter OData-Abfrageparameter.For more information, see OData query parameters.

AnforderungsheaderRequest headers

NameName BeschreibungDescription
AuthorizationAuthorization Bearer {token}. Erforderlich.Bearer {token}. Required.
ConsistencyLevelConsistencyLevel eventuelle.eventual. Diese Kopfzeile und $count sind bei Verwendung $search von oder bei Verwendung $filter mit dem $orderby Abfrageparameter erforderlich.This header and $count are required when using $search, or when using $filter with the $orderby query parameter. Es wird ein Index verwendet, der möglicherweise nicht auf dem neuesten Stand der letzten Änderungen am Objekt ist.It uses an index that may not be up-to-date with recent changes to the object.

AnforderungstextRequest body

Geben Sie für diese Methode keinen Anforderungstext an.Do not supply a request body for this method.

AntwortResponse

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK und eine Sammlung von group-Objekten im Antworttext zurückgegeben.If successful, this method returns a 200 OK response code and collection of group objects in the response body. Die Antwort enthält nur die Standardeigenschaften der einzelnen Gruppen.The response includes only the default properties of each group.

BeispieleExamples

Beispiel 1: Abrufen einer Liste von GruppenExample 1: Get a list of groups

AnfrageRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

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

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis:  Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.Note: The response object shown here might be shortened for readability. Alle Standardeigenschaften werden für jede Gruppe in einem tatsächlichen Aufruf zurückgegeben.All the default properties are returned for each group in an actual call.

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups",
  "value": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "mail": "group1@contoso.com",
      "mailEnabled": true,
      "mailNickname": "ContosoGroup1",
      "securityEnabled": true
    }
  ]
}

Beispiel 2: Abrufen einer gefilterten Liste von Gruppen, einschließlich der Anzahl zurückgegebener ObjekteExample 2: Get a filtered list of groups including the count of returned objects

AnforderungRequest

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

AntwortResponse

Nachfolgend finden Sie ein Beispiel der Antwort, die nur die angeforderten Eigenschaften umfasst.The following is an example of the response which includes only the requested properties.

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: Abrufen der Anzahl von GruppenExample 3: Get only a count of groups

AnfrageRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

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

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

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

893893

Beispiel 4: Verwenden Sie $Filter und $Top, um eine Gruppe mit einem Anzeigenamen zu erhalten, der mit "a" beginnt, einschließlich der Anzahl zurückgegebener Objekte.Example 4: Use $filter and $top to get one group with a display name that starts with 'a' including a count of returned objects

AnfrageRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

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

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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 von $Search zum Abrufen von Gruppen mit Anzeigenamen, die die Buchstaben "Video" enthalten, einschließlich einer Anzahl zurückgegebener ObjekteExample 5: Use $search to get groups with display names that contain the letters 'Video' including a count of returned objects

AnfrageRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

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

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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 die Buchstaben "Video" enthalten, oder eine Beschreibung, die die Buchstaben "Prod" enthält, einschließlich der Anzahl der zurückgegebenen Objekte.Example 6: Use $search to get groups with display names that contain the letters 'Video' or a description that contains the letters 'prod' including a count of returned objects

AnfrageRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

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

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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"
    }
  ]
}