Группа Upsert

  • Статья

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

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

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

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

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

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

Разрешения

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

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

Для приложения с группой. 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 уже существует, этот метод обновляет объект группы и возвращает 204 No Content код ответа.

Примеры

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

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

Запрос

PATCH https://graph.microsoft.com/beta/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/beta/$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. Create группы безопасности с владельцем и членами, если она не существует

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

Запрос

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

PATCH https://graph.microsoft.com/beta/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/beta/users/26be1845-4119-4801-a799-aea79d09f1a2"
  ],
  "members@odata.bind": [
    "https://graph.microsoft.com/beta/users/ff7cb387-6688-423c-8188-3da9532a73cc",
    "https://graph.microsoft.com/beta/users/69456242-0067-49d3-ba96-9de6f2728e14"
  ]
}

Отклик

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

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

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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/beta/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/beta/users/99e44b05-c10b-4e95-a523-e2732bbaba1e"
    ],
    "members@odata.bind": [
        "https://graph.microsoft.com/beta/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0",
        "https://graph.microsoft.com/beta/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
    ]
}

Отклик

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

HTTP/1.1 204 No Content

Связанные материалы