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


Группа Upsert

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

Создайте новый объект группы , если он не существует, или обновите свойства существующего объекта группы . Можно создать или обновить следующие типы групп:

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

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

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

Разрешения

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

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

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

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

HTTP-запрос

PATCH /groups/(uniqueName='uniqueName')

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

Имя Описание
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Content-Type application/json. Обязательный параметр.
Prefer create-if-missing. Требуется для поведения upsert, в противном случае запрос обрабатывается как операция обновления.

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

В тексте запроса предоставьте описание объекта 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 не будет создан автоматически, пока дальнейшие действия не будут выполнены вручную.
  • Пользователь без прав администратора не может добавить себя в коллекцию владельцев группы. Дополнительные сведения см. в статье Об известной проблеме.
  • Следующие свойства не могут быть заданы в первоначальном запросе POST и должны быть заданы в последующем запросе PATCH: allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isSubscribedByMail, unseenCount.

Так как ресурс group поддерживает расширения, вы можете добавлять настраиваемые свойства с собственными данными к группе при ее создании.

Параметры groupTypes

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

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

Отклик

Если объект с uniqueName не существует, этот метод возвращает код отклика 201 Created и новый объект группы в теле отклика.

Если объект с uniqueName не существует и Prefer: create-if-missing заголовок не указан, этот метод возвращает 404 Not Found код ошибки.

Если объект с uniqueName уже существует, этот метод обновляет объект группы и возвращает 204 No Content код ответа.

Примеры

Пример 1. Создание группы Microsoft 365, если она не существует

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

Запрос

PATCH https://graph.microsoft.com/v1.0/groups(uniqueName='uniqueName')
Content-type: application/json
Prefer: create-if-missing

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

Отклик

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

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "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"
    ],
    "renewedDateTime": "2018-12-22T02:21:05Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": false,
    "securityIdentifier": "S-1-12-1-1753967289-1089268234-832641959-555555555",
    "theme": null,
    "visibility": "Public",
    "uniqueName": "uniqueName",
    "onPremisesProvisioningErrors": []
}

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

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

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

Запрос

Ниже показан пример запроса.

PATCH https://graph.microsoft.com/v1.0/groups(uniqueName='uniqueName')
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/1226170d-83d5-49b8-99ab-d1ab3d91333e/Microsoft.DirectoryServices.Group",
    "id": "1226170d-83d5-49b8-99ab-d1ab3d91333e",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:14:44Z",
    "createdByAppId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
    "organizationId": "84841066-274d-4ec0-a5c1-276be684bdd3",
    "description": "Group with designated owner and members",
    "displayName": "Operations group",
    "expirationDateTime": null,
    "groupTypes": [],
    "infoCatalogs": [],
    "isAssignableToRole": null,
    "isManagementRestricted": 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:14:44Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-304486157-1236829141-2882644889-1043566909",
    "theme": null,
    "uniqueName": "uniqueName",
    "visibility": null,
    "writebackConfiguration": {
        "isEnabled": null,
        "onPremisesGroupType": null
    },
    "onPremisesProvisioningErrors": []
}

Пример 3. Обновление существующей группы

В этом примере указанная группа уже существует, поэтому операция обрабатывается как обновление.

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

Запрос

Ниже показан пример запроса.

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

Отклик

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

HTTP/1.1 204 No Content