通过

Microsoft Entra B2B 协作 API 和自定义

  • 项目

适用于：带白色勾号的绿色圆圈。 员工租户 带灰色 X 号的白色圆圈。 外部租户（了解详细信息）

借助 Microsoft Graph REST API，可以以最适合组织的方式自定义邀请过程。

邀请 API 的功能

该 API 提供以下功能：

  1. 使用任何电子邮件地址邀请外部用户。

    "invitedUserDisplayName": "Sam"
"invitedUserEmailAddress": "sam@fabrikam.com"

  2. 自定义希望用户在接受其邀请后登陆的位置。

    "inviteRedirectUrl": "https://myapplications.windowsazure.cn/"

  3. 选择通过我们将包含可自定义消息的

    "sendInvitationMessage": true

    标准邀请邮件发送给收件人。

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

  4. 并选择你想要让其了解你邀请了此协作者的抄送人员。

  5. 或者完全自定义邀请，并通过选择不通过 Microsoft Entra ID 发送通知来加入工作流。

    "sendInvitationMessage": false

    在这种情况下，将通过可嵌入电子邮件模板的 API、即时消息或所选择的其他分发方法收到兑换 URL。

  6. 最后，如果你是管理员，可以选择以成员身份邀请用户。

    "invitedUserType": "Member"

确定用户是否已获邀加入你的目录

可使用邀请 API 确定资源租户中是否已存在某用户。 开发使用邀请 API 邀请用户的应用时，这会很有用。 如果你的资源目录中已存在该用户，该用户将不会收到邀请，因此可先运行查询来确定电子邮件是否已作为 UPN 或其他登录属性存在。

  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 轻松地将外部用户添加并邀请到组织。 使用 cmdlet 创建邀请：

New-MgInvitation

您可以使用下列选项：

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

邀请状态

向外部用户发送邀请后，可使用 Get-MgBetaUser cmdlet 查看是否用户已接受该邀请。 向外部用户发送邀请时，将填充 Get-MgBetaUser 的以下属性：

  • externalUserState 指示邀请是 PendingAcceptance 还是 Accepted。
  • externalUserStateChangeDateTime 显示 externalUserState 属性最新更改的时间戳。

可使用“筛选器”选项按 externalUserState 筛选结果。 以下示例显示了如何筛选结果以仅显示具有待处理邀请的用户。 该示例还显示了 Format-List 选项，借助该选项可以指定要显示的属性 。

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

注意

请确保具有最新版本的 Microsoft Graph PowerShell 模块

另请参阅

在 https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation 中查看邀请 API 参考。

后续步骤