API совместной работы Microsoft Entra B2B и настройка

  • Статья

С помощью REST API Microsoft Graph можно настроить процесс приглашения таким образом, который лучше всего подходит для вашей организации.

Возможности API приглашения

Интерфейс API предоставляет следующие возможности:

  1. Пригласите внешнего пользователя, используя любой адрес электронной почты.

    "invitedUserDisplayName": "Taylor"
"invitedUserEmailAddress": "taylor@fabrikam.com"

  2. Настройте, куда будет перенаправляться пользователь после принятия приглашения.

    "inviteRedirectUrl": "https://myapps.microsoft.com/"

  3. Выберите для отправки стандартной почты приглашения через нас.

    "sendInvitationMessage": true

    с сообщением получателю, который можно настроить.

    "customizedMessageBody": "Hello Sam, let's collaborate!"

  4. Выберите также, кому отправить копию. Это могут быть пользователи, которых вы хотите известить о приглашении данного сотрудника.

  5. Или полностью настройте приглашение и рабочий процесс подключения, выбрав не отправлять уведомления с помощью идентификатора Microsoft Entra.

    "sendInvitationMessage": false

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

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

    "invitedUserType": "Member"

Определите, был ли пользователь уже приглашен в ваш каталог

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

  1. Убедитесь, что домен электронной почты пользователя не является частью подтвержденного домена вашего клиента ресурса.

  2. В клиенте ресурсов используйте следующий запрос на получение пользователя, где {0} - это адрес электронной почты, на который направлено приглашение:

    “userPrincipalName eq '{0}' or mail eq '{0}' or proxyAddresses/any(x:x eq 'SMTP:{0}') or signInNames/any(x:x eq '{0}') or otherMails/any(x:x eq '{0}')"

Модель авторизации

API можно запустить в следующих режимах авторизации:

Приложение + пользователь

В этом режиме приложение или пользователь, использующий API, должен иметь разрешения на создание приглашений в службу B2B.

Только приложение

В контексте "только приложение" для успешного выполнения приглашения приложению требуется область User.Invite.All.

Для получения дополнительной информации см. https://developer.microsoft.com/graph/docs/authorization/permission_scopes

PowerShell

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

New-MgInvitation

Можно использовать следующие параметры.

  • -InvitedUserDisplayName
  • -InvitedUserEmailAddress
  • -SendInvitationMessage
  • -InvitedUserMessageInfo

Статус приглашения

После отправки приглашения внешнего пользователя можно использовать командлет Get-MgBetaUser , чтобы узнать, приняли ли они его. Следующие свойства Get-MgBetaUser заполняются при отправке приглашения внешним пользователем:

  • externalUserState указывает, является ли приглашение ожидающей или принятой.
  • externalUserStateChangeDateTime показывает метку времени последнего изменения в свойстве externalUserState .

Параметр "Фильтр" можно использовать для фильтрации результатов по externalUserState. В приведенном ниже примере показано, как фильтровать результаты, чтобы показывать только тех пользователей, у которых есть ожидающее приглашения. В примере также показан параметр Format-List, который позволяет указывать свойства для отображения.

Get-MgBetaUser -Filter "externalUserState eq 'PendingAcceptance'" | Format-List -Property DisplayName,UserPrincipalName,externalUserState,externalUserStateChangeDateTime

Примечание.

Убедитесь, что у вас установлена последняя версия модуля Microsoft Graph PowerShell

См. также

Ознакомьтесь со справочником по API приглашения по адресу https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation.

Следующие шаги