Пространство имен: microsoft.graph
Важно!
API версии /beta
в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.
Получение списка прямых участников группы . В группе могут быть пользователи, контакты, устройства, субъекты-службы и другие группы в качестве участников. Эта операция не является транзитивной.
Этот API доступен в следующих национальных облачных развертываниях.
Глобальная служба |
Правительство США L4 |
Правительство США L5 (DOD) |
Китай управляется 21Vianet |
✅ |
✅ |
✅ |
✅ |
Разрешения
Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.
Тип разрешения |
Разрешения с наименьшими привилегиями |
Более высокие привилегированные разрешения |
Делегированные (рабочая или учебная учетная запись) |
GroupMember.Read.All |
Directory.Read.All, Group.Read.All, Group.ReadWrite.All, GroupMember.ReadWrite.All |
Делегированные (личная учетная запись Майкрософт) |
Не поддерживается. |
Не поддерживается. |
Приложение |
GroupMember.Read.All |
Directory.Read.All, Group.Read.All, Group.ReadWrite.All, GroupMember.ReadWrite.All |
Важно!
Когда приложение запрашивает связь, которая возвращает коллекцию типов directoryObject , если у него нет разрешения на чтение определенного типа ресурсов, возвращаются члены этого типа, но с ограниченной информацией. Например, возвращается только свойство @odata.type для типа объекта и идентификатор , в то время как другие свойства указываются как null
. При таком поведении приложения могут запрашивать необходимые разрешения с наименьшими привилегиями, а не полагаться на набор каталогов.*Разрешения. Сведения см. в разделе Ограниченные сведения, возвращаемые для недоступных объектов member.
В делегированных сценариях пользователю, выполнившему вход, также необходимо назначить поддерживаемую роль Microsoft Entra или пользовательскую роль с разрешением microsoft.directory/groups/members/read
роли или microsoft.directory/groups/members/limitedRead
ролью для microsoft.directory/groups/hiddenMembers/read
чтения скрытых членов. Для этой операции поддерживаются следующие наименее привилегированные роли:
- Владельцы групп
- Пользователи -члены
- "Гостевые" пользователи — имеют ограниченные разрешения на чтение
- Читатели каталогов
- Запись каталогов
- Администратор групп
- Администратор пользователей — включение скрытых участников
- Администратор Exchange — включение скрытых участников
- Администратор SharePoint — включение скрытых участников
- администратор Intune — включение скрытых участников
- Администратор Teams — включение скрытых участников
- Администратор Yammer — включение скрытых участников
Для вывода списка участников скрытой группы членства также требуется разрешение Member.Read.Hidden .
HTTP-запрос
GET /groups/{id}/members
Необязательные параметры запросов
Этот метод поддерживает $filter
параметры запроса OData , $count
$select
, $search
, , $top
и $expand
для настройки ответа.
- Приведение OData включено. Например,
/groups/{id}/members/microsoft.graph.user
извлекает членов группы, которые являются пользователями.
-
$search
поддерживается только в свойствах displayName и description .
- По умолчанию и максимальный размер страницы — 100 и 999 объектов групп соответственно.
- Использование параметров запроса с этим API, за исключением
$expand
, поддерживается только с расширенными параметрами запроса.
$expand
не поддерживается с расширенными параметрами запроса. Дополнительные сведения см. в разделе Расширенные возможности запросов к объектам каталогов.
Имя |
Описание |
Авторизация |
Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации. |
ConsistencyLevel |
необязательный. Этот заголовок и $count требуются при использовании $search , $filter , $orderby или с параметрами запросов OData cast. В нем используется индекс, который может не соответствовать последним изменениям объекта. |
Текст запроса
Не указывайте текст запроса для этого метода.
Отклик
В случае успеха этот метод возвращает код отклика 200 OK
и коллекцию объектов directoryObject в тексте отклика.
Попытка фильтрации по приведения OData, представляющего неподдерживаемый тип элемента, возвращает ошибку 400 Bad Request
Request_UnsupportedQuery
с кодом. Например, /groups/{id}}/members/microsoft.graph.group
если группа является группой Microsoft 365, возвращается эта ошибка, так как группы Microsoft 365 не могут содержать другие группы в качестве участников.
Примеры
Пример 1. Получение сведений о непосредственном участии в группе
Запрос
Ниже показан пример запроса.
GET https://graph.microsoft.com/beta/groups/{id}/members
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].Members.GetAsync();
mgc-beta groups members list --group-id {group-id}
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
//other-imports
)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
members, err := graphClient.Groups().ByGroupId("group-id").Members().Get(context.Background(), nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
DirectoryObjectCollectionResponse result = graphClient.groups().byGroupId("{group-id}").members().get();
const options = {
authProvider,
};
const client = Client.init(options);
let members = await client.api('/groups/{id}/members')
.version('beta')
.get();
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$result = $graphServiceClient->groups()->byGroupId('group-id')->members()->get()->wait();
Import-Module Microsoft.Graph.Beta.Groups
Get-MgBetaGroupMember -GroupId $groupId
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
result = await graph_client.groups.by_group_id('group-id').members.get()
Отклик
Ниже показан пример отклика.
Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"id": "11111111-2222-3333-4444-555555555555",
"mail": "[email protected]",
"mailEnabled": true,
"mailNickname": "Contoso1",
"securityEnabled": true
}
]
}
Пример 2. Получение только количества всех участий
Запрос
Ниже показан пример запроса.
GET https://graph.microsoft.com/beta/groups/{id}/members/$count
ConsistencyLevel: eventual
Отклик
Ниже показан пример отклика.
HTTP/1.1 200 OK
Content-type: text/plain
893
Пример 3. Использование приведения к OData для получения только количества участий пользователей
Запрос
Ниже показан пример запроса.
GET https://graph.microsoft.com/beta/groups/{id}/members/microsoft.graph.user/$count
ConsistencyLevel: eventual
Отклик
Ниже показан пример отклика.
HTTP/1.1 200 OK
Content-type: text/plain
893
Пример 4. Использование $search и приведения OData для получения членства пользователей в группах с отображаемыми именами, содержащими буквы Pr, включая количество возвращаемых объектов
Запрос
Ниже показан пример запроса.
GET https://graph.microsoft.com/beta/groups/{id}/members/microsoft.graph.user?$count=true&$orderby=displayName&$search="displayName:Pr"&$select=displayName,id
ConsistencyLevel: eventual
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].Members.GraphUser.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.QueryParameters.Orderby = new string []{ "displayName" };
requestConfiguration.QueryParameters.Search = "\"displayName:Pr\"";
requestConfiguration.QueryParameters.Select = new string []{ "displayName","id" };
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
mgc-beta groups members graph-user get --group-id {group-id} --search ""displayName:Pr"" --count "true" --orderby "displayName" --select "displayName,id" --consistency-level "eventual"
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphgroups "github.com/microsoftgraph/msgraph-beta-sdk-go/groups"
//other-imports
)
headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")
requestCount := true
requestSearch := "\"displayName:Pr\""
requestParameters := &graphgroups.ItemMembersGraph.userRequestBuilderGetQueryParameters{
Count: &requestCount,
Orderby: [] string {"displayName"},
Search: &requestSearch,
Select: [] string {"displayName","id"},
}
configuration := &graphgroups.ItemMembersGraph.userRequestBuilderGetRequestConfiguration{
Headers: headers,
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphUser, err := graphClient.Groups().ByGroupId("group-id").Members().GraphUser().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.groups().byGroupId("{group-id}").members().graphUser().get(requestConfiguration -> {
requestConfiguration.queryParameters.count = true;
requestConfiguration.queryParameters.orderby = new String []{"displayName"};
requestConfiguration.queryParameters.search = "\"displayName:Pr\"";
requestConfiguration.queryParameters.select = new String []{"displayName", "id"};
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
const options = {
authProvider,
};
const client = Client.init(options);
let user = await client.api('/groups/{id}/members/microsoft.graph.user')
.version('beta')
.header('ConsistencyLevel','eventual')
.search('displayName:Pr')
.select('displayName,id')
.orderby('displayName')
.get();
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Groups\Item\Members\Graph\User\UserRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new GraphUserRequestBuilderGetRequestConfiguration();
$headers = [
'ConsistencyLevel' => 'eventual',
];
$requestConfiguration->headers = $headers;
$queryParameters = GraphUserRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->count = true;
$queryParameters->orderby = ["displayName"];
$queryParameters->search = "\"displayName:Pr\"";
$queryParameters->select = ["displayName","id"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->groups()->byGroupId('group-id')->members()->graphUser()->get($requestConfiguration)->wait();
Import-Module Microsoft.Graph.Beta.Groups
Get-MgBetaGroupMemberAsUser -GroupId $groupId -CountVariable CountVar -Sort "displayName" -Search '"displayName:Pr"' -Property "displayName,id" -ConsistencyLevel eventual
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.groups.item.members.graph.user.user_request_builder import UserRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UserRequestBuilder.UserRequestBuilderGetQueryParameters(
count = True,
orderby = ["displayName"],
search = "\"displayName:Pr\"",
select = ["displayName","id"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")
result = await graph_client.groups.by_group_id('group-id').members.graph_user.get(request_configuration = request_configuration)
Отклик
Ниже показан пример отклика.
Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#users(displayName,id)",
"@odata.count":7,
"value":[
{
"displayName":"Joseph Price",
"id":"11111111-2222-3333-4444-555555555555"
},
{
"displayName":"Preston Morales",
"id":"11111111-2222-3333-4444-555555555555"
}
]
}
Пример 5. Использование параметра $filter для получения участия в группах с отображаемым именем, которое начинается на "А", включая количество возвращаемых объектов
Запрос
Ниже показан пример запроса.
GET https://graph.microsoft.com/beta/groups/{id}/members?$count=true&$filter=startswith(displayName, 'a')
ConsistencyLevel: eventual
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].Members.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.QueryParameters.Filter = "startswith(displayName, 'a')";
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
mgc-beta groups members list --group-id {group-id} --filter "startswith(displayName, 'a')" --count "true" --consistency-level "eventual"
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphgroups "github.com/microsoftgraph/msgraph-beta-sdk-go/groups"
//other-imports
)
headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")
requestCount := true
requestFilter := "startswith(displayName, 'a')"
requestParameters := &graphgroups.ItemMembersRequestBuilderGetQueryParameters{
Count: &requestCount,
Filter: &requestFilter,
}
configuration := &graphgroups.ItemMembersRequestBuilderGetRequestConfiguration{
Headers: headers,
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
members, err := graphClient.Groups().ByGroupId("group-id").Members().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
DirectoryObjectCollectionResponse result = graphClient.groups().byGroupId("{group-id}").members().get(requestConfiguration -> {
requestConfiguration.queryParameters.count = true;
requestConfiguration.queryParameters.filter = "startswith(displayName, 'a')";
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
const options = {
authProvider,
};
const client = Client.init(options);
let members = await client.api('/groups/{id}/members')
.version('beta')
.header('ConsistencyLevel','eventual')
.filter('startswith(displayName, \'a\')')
.get();
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Groups\Item\Members\MembersRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new MembersRequestBuilderGetRequestConfiguration();
$headers = [
'ConsistencyLevel' => 'eventual',
];
$requestConfiguration->headers = $headers;
$queryParameters = MembersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->count = true;
$queryParameters->filter = "startswith(displayName, 'a')";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->groups()->byGroupId('group-id')->members()->get($requestConfiguration)->wait();
Import-Module Microsoft.Graph.Beta.Groups
Get-MgBetaGroupMember -GroupId $groupId -CountVariable CountVar -Filter "startswith(displayName, 'a')" -ConsistencyLevel eventual
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.groups.item.members.members_request_builder import MembersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MembersRequestBuilder.MembersRequestBuilderGetQueryParameters(
count = True,
filter = "startswith(displayName, 'a')",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")
result = await graph_client.groups.by_group_id('group-id').members.get(request_configuration = request_configuration)
Отклик
Ниже показан пример отклика.
Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
"@odata.count":76,
"value":[
{
"displayName":"AAD Contoso Users",
"mail":"[email protected]",
"mailEnabled":true,
"mailNickname":"AADContoso_Users",
"securityEnabled":true
}
]
}
Пример 6. Использование приведения OData для получения субъектов-служб, добавленных в качестве членов группы
Запрос
Ниже показан пример запроса.
GET https://graph.microsoft.com/beta/groups/3802e9bb-0951-4e18-b9eb-f934b4241194/members/microsoft.graph.servicePrincipal
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].Members.GraphServicePrincipal.GetAsync();
mgc-beta groups members graph-service-principal get --group-id {group-id}
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
//other-imports
)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphServicePrincipal, err := graphClient.Groups().ByGroupId("group-id").Members().GraphServicePrincipal().Get(context.Background(), nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipalCollectionResponse result = graphClient.groups().byGroupId("{group-id}").members().graphServicePrincipal().get();
const options = {
authProvider,
};
const client = Client.init(options);
let servicePrincipal = await client.api('/groups/3802e9bb-0951-4e18-b9eb-f934b4241194/members/microsoft.graph.servicePrincipal')
.version('beta')
.get();
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$result = $graphServiceClient->groups()->byGroupId('group-id')->members()->graphServicePrincipal()->get()->wait();
Import-Module Microsoft.Graph.Beta.Groups
Get-MgBetaGroupMemberAsServicePrincipal -GroupId $groupId
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
result = await graph_client.groups.by_group_id('group-id').members.graph_service_principal.get()
Отклик
Ниже показан пример отклика.
Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals",
"value": [
{
"id": "11111111-2222-3333-4444-555555555555",
"deletedDateTime": null,
"accountEnabled": true,
"appDisplayName": "Contoso Azure App",
"appId": "11111111-2222-3333-4444-555555555555",
}
]
}