Добавление участников
Пространство имен: microsoft.graph
Важно!
API версии /beta
в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.
Добавьте участника в группу безопасности или Microsoft 365. При использовании API для добавления нескольких участников в одном запросе можно добавить до 20 участников.
В следующей таблице показаны типы участников, которых можно добавить в группы безопасности или группы Microsoft 365.
Тип объектов | Участник группы безопасности | Участник группы Microsoft 365 |
---|---|---|
User |
|
|
Группа безопасности |
|
|
Группа Microsoft 365 |
|
|
Устройство |
|
|
Субъект-служба |
|
|
Контакты организации |
|
|
Этот API доступен в следующих национальных облачных развертываниях.
Глобальная служба | Правительство США L4 | Правительство США L5 (DOD) | Китай управляется 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Разрешения
В следующей таблице показаны разрешения с наименьшими привилегиями, необходимые каждому типу ресурсов при вызове этого API. Дополнительные сведения, включая сведения о том, как выбрать разрешения, см. в статье Разрешения.
Поддерживаемый ресурс | Делегированное (рабочая или учебная учетная запись) | Делегированное (личная учетная запись Майкрософт) | Для приложений |
---|---|---|---|
device | GroupMember.ReadWrite.All и Device.ReadWrite.All | Не поддерживается. | GroupMember.ReadWrite.All и Device.ReadWrite.All |
group | GroupMember.ReadWrite.All | Не поддерживается. | GroupMember.ReadWrite.All |
orgContact | GroupMember.ReadWrite.All и OrgContact.Read.All | Не поддерживается. | GroupMember.ReadWrite.All и OrgContact.Read.All |
servicePrincipal | GroupMember.ReadWrite.All и Application.ReadWrite.All | Не поддерживается. | GroupMember.ReadWrite.All и Application.ReadWrite.All |
user | GroupMember.ReadWrite.All | Не поддерживается. | GroupMember.ReadWrite.All |
Важно!
В делегированных сценариях вошедшему пользователю также должна быть назначена поддерживаемая Microsoft Entra роль или пользовательская роль с разрешением ролиmicrosoft.directory/groups/members/update
. Следующие роли являются наименее привилегированными ролями, которые поддерживаются для этой операции, за исключением групп, назначаемых ролями:
- Владельцы групп
- Запись каталогов
- Администратор групп
- Администратор управления удостоверениями
- Администратор пользователей
- Администратор Exchange — только для групп Microsoft 365
- Администратор SharePoint — только для групп Microsoft 365
- Администратор Teams — только для групп Microsoft 365
- Администратор Yammer — только для групп Microsoft 365
- администратор Intune — только для групп безопасности.
Чтобы добавить участников в группу с возможностью назначения ролей, приложению также должно быть назначено разрешение RoleManagement.ReadWrite.Directory, а вызывающему пользователю должна быть назначена поддерживаемая Microsoft Entra роль. Администратор привилегированных ролей — это наименее привилегированная роль, которая поддерживается для этой операции.
HTTP-запрос
POST /groups/{group-id}/members/$ref
PATCH /groups/{group-id}/members
Заголовки запросов
Имя | Описание |
---|---|
Авторизация | Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации. |
Content-Type | application/json. Обязательно. |
Текст запроса
При использовании синтаксиса POST /groups/{group-id}/members/$ref
укажите объект JSON, содержащий свойство @odata.id со ссылкой по идентификатору на поддерживаемый тип объекта-члена группы.
При использовании синтаксиса PATCH /groups/{group-id}/members
укажите объект JSON, содержащий members@odata.bind свойство с одной или несколькими ссылками по идентификаторам на поддерживаемый тип объекта-члена группы. То есть:
- Для групп Microsoft 365 разрешено только
https://graph.microsoft.com/v1.0/directoryObjects/{id}
в томhttps://graph.microsoft.com/v1.0/groups/{id}
случае, если{id}
пользователь должен быть пользователем, так как только пользователи могут быть членами групп Microsoft 365. - Для групп безопасности разрешены следующие ссылки на идентификаторы:
-
https://graph.microsoft.com/v1.0/directoryObjects/{id}
где{id}
должен принадлежать пользователю, группе безопасности, устройству, субъекту-службе или контакту организации. -
https://graph.microsoft.com/v1.0/groups/{id}
где{id}
должен принадлежать к другой группе безопасности. Группы Microsoft 365 не могут быть членами групп безопасности. -
https://graph.microsoft.com/v1.0/devices/{id}
где{id}
принадлежит устройству. -
https://graph.microsoft.com/v1.0/servicePrincipal/{id}
где{id}
принадлежит субъекту-службе. -
https://graph.microsoft.com/v1.0/orgContact/{id}
где{id}
принадлежит контакту организации.
-
Отклик
В случае успешного выполнения этот метод возвращает код отклика 204 No Content
. Он возвращает код ответа, 400 Bad Request
если объект уже является членом группы или не поддерживается в качестве члена группы. Он возвращает код ответа, 404 Not Found
если добавляемый объект не существует. Он возвращается 403 Unauthorized
в одном из следующих сценариев:
- Вы пытаетесь добавить участника в группу, управление которыми невозможно с помощью Microsoft Graph. Этот API поддерживает только группы безопасности и Microsoft 365.
- Вы пытаетесь добавить участника, на который у вас нет разрешений. Разрешения, необходимые для добавления различных типов элементов, см. в предыдущем разделе Разрешения .
- Вы пытаетесь добавить участника в группу с возможностью назначения ролей, но у вас нет необходимых разрешений.
Пример
Пример 1. Добавление участника группы
Запрос
В следующем примере показан запрос, который использует ссылку directoryObjects для добавления участника в группу.
POST https://graph.microsoft.com/beta/groups/{group-id}/members/$ref
Content-type: application/json
{
"@odata.id": "https://graph.microsoft.com/beta/directoryObjects/{id}"
}
Отклик
Ниже показан пример отклика.
HTTP/1.1 204 No Content
Пример 2. Добавление нескольких участников в группу одним запросом
В этом примере показано, как добавить нескольких участников в группу с поддержкой с привязкой к ОData в операции PATCH. В одном запросе можно добавить до 20 участников. Если в тексте запроса существует условие ошибки, элементы не добавляются и возвращается соответствующий код отклика.
Запрос
Ниже показан пример запроса.
PATCH https://graph.microsoft.com/beta/groups/{group-id}
Content-type: application/json
{
"members@odata.bind": [
"https://graph.microsoft.com/beta/directoryObjects/{id}",
"https://graph.microsoft.com/beta/directoryObjects/{id}",
"https://graph.microsoft.com/beta/directoryObjects/{id}"
]
}
Отклик
Ниже показан пример отклика.
HTTP/1.1 204 No Content