Поделиться через

Создание группы

  • Статья

Пространство имен: microsoft.graph

Создание группы согласно инструкциям в тексте запроса. Вы можете создавать группы указанных ниже типов.

  • Группа Microsoft 365 (единая группа)
  • Группа безопасности

Эта операция по умолчанию возвращает только подмножество свойств для каждой группы. Эти свойства по умолчанию указаны в разделе Свойства.

Чтобы получить свойства, которые не возвращаются по умолчанию, выполните операцию GET и укажите их в параметре запроса OData $select.

Примечание. Несмотря на то, что Microsoft Teams создан на основе групп Microsoft 365, в настоящее время нельзя создать команду через этот API. Вы можете использовать другие API групп для управления командой, созданной в Microsoft Teams.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet
✅ ✅ ✅ ✅

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения Разрешения с наименьшими привилегиями Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись) Group.ReadWrite.All Directory.ReadWrite.All
Делегированные (личная учетная запись Майкрософт) Не поддерживается. Не поддерживается.
Приложение Group.Create Directory.ReadWrite.All, Group.ReadWrite.All

Чтобы приложение создавало группу с владельцами или участниками при наличии разрешения Group.Create , приложение должно иметь права на чтение типа объекта, который он хочет назначить в качестве владельца или участника группы. Следовательно:

  • Приложение может назначить себя владельцем или участником группы.
  • Чтобы создать группу с пользователями в качестве владельцев или участников, приложение должно иметь по крайней мере разрешение User.Read.All .
  • Чтобы создать группу с другими субъектами-службами в качестве владельцев или участников, приложение должно иметь по крайней мере разрешение Application.Read.All .
  • Чтобы создать группу с пользователями или субъектами-службами в качестве владельцев или участников, приложение должно иметь по крайней мере разрешение Directory.Read.All .

HTTP-запрос

POST /groups

Заголовки запросов

Имя Описание
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Content-Type application/json

Текст запроса

В тексте запроса предоставьте описание объекта group в формате JSON.

В следующей таблице перечислены свойства, необходимые при создании группы. При необходимости укажите другие записываемые свойства для своей группы.

Свойство Тип Описание
displayName String Имя, которое следует отобразить в адресной книге для группы. Максимальная длина: 256 символов. Обязательный.
mailEnabled Boolean Установите значение true для групп с включенной поддержкой почты. Обязательный.
mailNickname String Почтовый псевдоним для группы, уникальный для групп Microsoft 365 в организации. Максимальная длина: 64 символа. Это свойство может содержать только символы из набора символов ASCII от 0 до 127, за исключением следующих: @ () \ [] " ; : <> , SPACE. Обязательный.
securityEnabled Логический Установите значение true для групп с поддержкой безопасности, включая группы Microsoft 365. Обязательно. Примечание. Для Группы, созданных с помощью Центр администрирования Microsoft Entra или портал Azure для параметра securityEnabled всегда задано значение true.

Важно!

  • Создание группы с помощью разрешения приложения Group.Create без указания владельцев создает группу анонимно, и группа не может быть изменяема. Добавьте владельцев в группу при ее создании, чтобы владельцы могли управлять группой.

  • Создание группы Microsoft 365 в контексте только приложения без указания владельцев создает группу анонимно. Это может привести к тому, что связанный с ней сайт SharePoint Online не будет создан автоматически, пока дальнейшие действия не будут выполнены вручную.

  • Создание Microsoft 365 или группы безопасности в делегированном контексте, вход с правами пользователя, не являющегося администратором, без указания владельцев автоматически добавляет вызывающего пользователя в качестве владельца группы. Пользователь-администратор автоматически добавляется в качестве владельца группы Microsoft 365, создаваемой им, но не группы безопасности.

  • Пользователь без прав администратора не может добавить себя в коллекцию владельцев группы. Дополнительные сведения см. в статье Об известной проблеме.

  • Следующие свойства невозможно настроить в исходном запросе POST и необходимо настраивать в последующем запросе PATCH: allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isSubscribedByMail, unseenCount.

Параметры groupTypes

Свойство groupTypes используется для управления типом группы и участием в ней, как показано ниже.

Тип группы Назначенное участие Динамическое членство
Microsoft 365 (как единая группа) ["Unified"] ["Unified","DynamicMembership"]
Динамический [] (null) ["DynamicMembership"]

Отклик

При успешном выполнении этот метод возвращает код отклика 201 Created и объект group в теле отклика. Отклик включает в себя только свойства по умолчанию для группы.

Примеры

Пример 1. Создание группы Microsoft 365

В следующем примере создается группа Microsoft 365. Так как владельцы не указаны, вызывающий пользователь автоматически добавляется в качестве владельца группы.

Запрос

POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json

{
  "description": "Self help community for library",
  "displayName": "Library Assist",
  "groupTypes": [
    "Unified"
  ],
  "mailEnabled": true,
  "mailNickname": "library",
  "securityEnabled": false
}

Отклик

Ниже показан пример отклика. Значение свойства preferredDataLocation наследуется от предпочтительного расположения данных создателя группы.

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 201 Created
Content-type: application/json

{
    "id": "b320ee12-b1cd-4cca-b648-a437be61c5cd",
      "deletedDateTime": null,
      "classification": null,
      "createdDateTime": "2018-12-22T00:51:37Z",
      "description": "Self help community for library",
      "displayName": "Library Assist",
      "groupTypes": [
          "Unified"
      ],
      "mail": "library7423@contoso.com",
      "mailEnabled": true,
      "mailNickname": "library",
      "onPremisesLastSyncDateTime": null,
      "onPremisesSecurityIdentifier": null,
      "onPremisesSyncEnabled": null,
      "preferredDataLocation": "CAN",
      "proxyAddresses": [
          "SMTP:library7423@contoso.com"
      ],
      "renewedDateTime": "2018-12-22T00:51:37Z",
      "resourceBehaviorOptions": [],
      "resourceProvisioningOptions": [],
      "securityEnabled": false,
      "visibility": "Public",
      "onPremisesProvisioningErrors": []
}

Пример 2. Создание группы с владельцами и участниками

В следующем примере создается группа безопасности с указанным владельцем и участниками. Обратите внимание на то, что в рамках создания группы можно добавить не более 20 отношений, например владельцев и участников. Позже вы можете добавить дополнительных участников с помощью API добавления участников или пакетной обработки JSON.

Пользователь без прав администратора не может добавить себя в коллекцию владельцев группы. Дополнительные сведения см. в статье Об известной проблеме.

Запрос

POST https://graph.microsoft.com/v1.0/groups
Content-Type: application/json

{
  "description": "Group with designated owner and members",
  "displayName": "Operations group",
  "groupTypes": [
  ],
  "mailEnabled": false,
  "mailNickname": "operations2019",
  "securityEnabled": true,
  "owners@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/26be1845-4119-4801-a799-aea79d09f1a2"
  ],
  "members@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/ff7cb387-6688-423c-8188-3da9532a73cc",
    "https://graph.microsoft.com/v1.0/users/69456242-0067-49d3-ba96-9de6f2728e14"
  ]
}

Отклик

Ниже представлен пример успешного отклика. Он включает только свойства по умолчанию. Вы можете получить свойства навигации owners или members группы, чтобы проверить владельца или участников. Значение свойства preferredDataLocation наследуется от предпочтительного расположения данных создателя группы.

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/21d05557-b7b6-418f-86fa-a3118d751be4/Microsoft.DirectoryServices.Group",
    "id": "21d05557-b7b6-418f-86fa-a3118d751be4",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:09:14Z",
    "description": "Group with designated owner and members",
    "displayName": "Operations group",
    "expirationDateTime": null,
    "groupTypes": [],
    "isAssignableToRole": null,
    "mail": null,
    "mailEnabled": false,
    "mailNickname": "operations2019",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesDomainName": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesNetBiosName": null,
    "onPremisesSamAccountName": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": null,
    "preferredLanguage": null,
    "proxyAddresses": [],
    "renewedDateTime": "2021-09-21T07:09:14Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-567301463-1099937718-295959174-3827004813",
    "theme": null,
    "visibility": null,
    "onPremisesProvisioningErrors": []
}

Пример 3. Создание группы Microsoft 365, которую можно назначить Microsoft Entra роли

Запрос

Ниже показан пример запроса. Вызывающему пользователю необходимо назначить разрешение RoleManagement.ReadWrite.Directory , чтобы задать свойство isAssignableToRole или обновить членство в таких группах.

Группа со свойствомtrue isAssignableToRole не может иметь тип динамического членства, ее securityEnabled должно иметь значение true, а видимость может быть Privateтолько .

POST https://graph.microsoft.com/v1.0/groups
Content-Type: application/json

{
    "description": "Group assignable to a role",
    "displayName": "Role assignable group",
    "groupTypes": [
        "Unified"
    ],
    "isAssignableToRole": true,
    "mailEnabled": true,
    "securityEnabled": true,
    "mailNickname": "contosohelpdeskadministrators",
    "owners@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/99e44b05-c10b-4e95-a523-e2732bbaba1e"
    ],
    "members@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0",
        "https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
    ]
}

Примечание. Группа, свойству isAssignableToRole которой присвоено значение true, не может относиться к типу с динамическим членством и иметь владельца. Дополнительные сведения см. в статье Использование группы для управления Microsoft Entra назначениями ролей.

Отклик

Ниже показан пример отклика. Он включает только свойства по умолчанию. Значение свойства preferredDataLocation наследуется от предпочтительного расположения данных создателя группы.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/55ea2e8c-757f-4f2d-be9e-53c22e8c6a54/Microsoft.DirectoryServices.Group",
    "id": "55ea2e8c-757f-4f2d-be9e-53c22e8c6a54",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:23:06Z",
    "createdByAppId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
    "organizationId": "84841066-274d-4ec0-a5c1-276be684bdd3",
    "description": "Group assignable to a role",
    "displayName": "Role assignable group",
    "expirationDateTime": null,
    "groupTypes": [
        "Unified"
    ],
    "infoCatalogs": [],
    "isAssignableToRole": true,
    "isManagementRestricted": null,
    "mail": "contosohelpdeskadministrators@contoso.com",
    "mailEnabled": true,
    "mailNickname": "contosohelpdeskadministrators",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesDomainName": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesNetBiosName": null,
    "onPremisesSamAccountName": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": "EU",
    "preferredLanguage": null,
    "proxyAddresses": [
        "SMTP:contosohelpdeskadministrators@contoso.com"
    ],
    "renewedDateTime": "2021-09-21T07:23:06Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-1441410700-1328379263-3260260030-1416268846",
    "theme": null,
    "visibility": "Private",
    "writebackConfiguration": {
        "isEnabled": null,
        "onPremisesGroupType": null
    },
    "onPremisesProvisioningErrors": []
}