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

Создание приглашения

  • Статья

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

Важно!

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

Создайте новое приглашение или сбросьте состояние активации для гостевого пользователя, который уже активировал его приглашение. Приглашение добавляет внешнего пользователя в организацию в рамках совместной работы B2B. Совместная работа B2B поддерживается как в Внешняя идентификация Microsoft Entra в рабочей силе, так и во внешних клиентах.

Для создания приглашения доступны следующие варианты:

  1. При создании приглашения Microsoft Graph может автоматически отправить письмо с приглашением непосредственно приглашению, или ваше приложение может использовать inviteRedeemUrl , возвращенный в ответе, для создания собственного приглашения (с помощью выбранного вами механизма коммуникации) для приглашенного пользователя. Если вы решили, чтобы Microsoft Graph автоматически отправлял приглашение по электронной почте, вы можете указать содержимое и язык сообщения электронной почты с помощью метода invitedUserMessageInfo.
  2. При приглашении пользователя создается сущность пользователя ( userTypeGuest), которую можно использовать для управления доступом к ресурсам. Приглашенный пользователь должен пройти процесс активации, чтобы получить доступ к соответствующим ресурсам.

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

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

Разрешения

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

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

Важно!

В делегированных сценариях с рабочими или учебными учетными записями вошедшему пользователю должна быть назначена поддерживаемая роль Microsoft Entra или настраиваемая роль с разрешением поддерживаемой роли. Для этой операции поддерживаются следующие наименее привилегированные роли:

  • Чтобы пригласить гостей, выполните приведенные далее действия.
    • Пользователи, не являющиеся членами-администраторами, и гостевые пользователи могут приглашать гостей, если администратор клиента не ограничил разрешения пользователя по умолчанию.
    • Приглашенный гость, записи каталогов или администратор пользователей.
  • Чтобы сбросить состояние активации: администратор службы технической поддержки или администратор пользователей.
  • Разрешения приложений (только для приложений) не работают, если приглашения B2B отключены в клиенте или если приглашения B2B ограничены администраторами.
  • При сбросе состояния активации для гостевого пользователя разрешение User.ReadWrite.All является наименьшим привилегированным разрешением для операции.

HTTP-запрос

POST /invitations

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

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

Тело запроса

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

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

Параметр Тип Описание
invitedUserEmailAddress string Адрес электронной почты пользователя, который вы приглашаете.
inviteRedirectUrl string URL-адрес, на который пользователь перенаправляется после активации.

Отклик

В случае успеха этот метод возвращает код отклика 201 Created и объект invitation в теле отклика.

Пример

Пример 1. Приглашение гостевого пользователя

Запрос

В следующем примере показан запрос на добавление и приглашение гостевого пользователя.

POST https://graph.microsoft.com/beta/invitations
Content-type: application/json

{
  "invitedUserEmailAddress": "admin@fabrikam.com",
  "inviteRedirectUrl": "https://myapp.contoso.com"
}

Отклик

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

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

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#invitations/$entity",
    "id": "9071bfde-35e0-47d2-a582-d244ab1b4af6",
    "inviteRedeemUrl": "https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3ften...6ver%3d2.0",
    "invitedUserDisplayName": null,
    "invitedUserType": "Guest",
    "invitedUserEmailAddress": "admin@fabrikam.com",
    "sendInvitationMessage": false,
    "resetRedemption": false,
    "inviteRedirectUrl": "https://myapp.contoso.com",
    "status": "PendingAcceptance",
    "invitedUserMessageInfo": {
        "messageLanguage": null,
        "customizedMessageBody": null,
        "ccRecipients": [
            {
                "emailAddress": {
                    "name": null,
                    "address": null
                }
            }
        ]
    },
    "invitedUser": {
        "id": "cbb896f9-8306-49d0-b56b-b8e39cd28825"
    }
}

Пример 2. Сброс состояния активации гостевого пользователя

Запрос

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

POST https://graph.microsoft.com/beta/invitations
Content-type: application/json

{
    "invitedUserEmailAddress": "AdeleV@fabrikam.com",
    "inviteRedirectUrl": "https://myapp.contoso.com",
    "invitedUser": {
        "id": "264e6d50-eaec-461e-b187-873b1bcf855f"
    },
    "resetRedemption": true
}

Отклик

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

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

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#invitations/$entity",
    "id": "46d72876-dba6-4a05-b9ec-118faf16c4b7",
    "inviteRedeemUrl": "https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3fte...3d2.0",
    "invitedUserDisplayName": null,
    "invitedUserType": "Guest",
    "invitedUserEmailAddress": "AdeleV@fabrikam.com",
    "sendInvitationMessage": false,
    "resetRedemption": true,
    "inviteRedirectUrl": "https://myapp.contoso.com",
    "status": "PendingAcceptance",
    "invitedUserMessageInfo": {
        "messageLanguage": null,
        "customizedMessageBody": null,
        "ccRecipients": [
            {
                "emailAddress": {
                    "name": null,
                    "address": null
                }
            }
        ]
    },
    "invitedUser": {
        "id": "264e6d50-eaec-461e-b187-873b1bcf855f"
    }
}