命名空间:microsoft.graph
使用该 API 创建新的邀请。邀请将外部用户添加至组织。
创建新的邀请时,有多个选项可供使用:
- 创建邀请后,Microsoft Graph 可以自动向邀请的用户直接发送邀请电子邮件,或者你的应用可以使用创建响应中返回的 inviteRedeemUrl 创建自己的邀请(通过你所选择的通信机制)并发送给邀请的用户。如果决定让 Microsoft Graph 自动发送邀请电子邮件,则你可以使用 invitedUserMessageInfo 控制电子邮件的内容和语言。
- 邀请用户后,会创建用户实体(userType 为“来宾”)并且现在可以使用它来控制对资源的访问。 受邀请的用户必须完成兑换过程才能访问其获得访问邀请的任意资源。
权限
要调用此 API,需要以下权限之一。要了解详细信息,包括如何选择权限的信息,请参阅权限。
| 权限类型 | 权限(从最低特权到最高特权) |
|---|---|
| 委派(工作或学校帐户) | User.Invite.All、User.ReadWrite.All、Directory.ReadWrite.All |
| 委派(个人 Microsoft 帐户) | 不支持。 |
| 应用程序 | User.Invite.All、User.ReadWrite.All、Directory.ReadWrite.All |
HTTP 请求
POST /invitations
请求标头
| 标头 | 值 |
|---|---|
| Authorization | Bearer {token}。必需。 |
| Content-Type | application/json |
请求正文
在请求正文中,提供 invitation 对象的 JSON 表示形式。
下表显示创建邀请时所需的属性。
| 参数 | 类型 | 说明 |
|---|---|---|
| invitedUserEmailAddress | string | 你要邀请的用户的电子邮件地址。 |
| inviteRedirectUrl | string | 兑现后用户将被重定向至的 URL。 |
响应
如果成功,此方法将在响应正文中返回 201 Created 响应代码和 invitation 对象。
示例
请求
下面展示了示例请求。
HTTP
POST https://graph.microsoft.com/v1.0/invitations
Content-type: application/json
{
"invitedUserEmailAddress": "admin@fabrikam.com",
"inviteRedirectUrl": "https://myapp.contoso.com"
}
C#
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var invitation = new Invitation
{
InvitedUserEmailAddress = "admin@fabrikam.com",
InviteRedirectUrl = "https://myapp.contoso.com"
};
await graphClient.Invitations
.Request()
.AddAsync(invitation);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档。
JavaScript
const options = {
authProvider,
};
const client = Client.init(options);
const invitation = {
invitedUserEmailAddress: 'admin@fabrikam.com',
inviteRedirectUrl: 'https://myapp.contoso.com'
};
await client.api('/invitations')
.post(invitation);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档。
Java
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
Invitation invitation = new Invitation();
invitation.invitedUserEmailAddress = "admin@fabrikam.com";
invitation.inviteRedirectUrl = "https://myapp.contoso.com";
graphClient.invitations()
.buildRequest()
.post(invitation);
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档。
Go
//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)
requestBody := msgraphsdk.NewInvitation()
invitedUserEmailAddress := "admin@fabrikam.com"
requestBody.SetInvitedUserEmailAddress(&invitedUserEmailAddress)
inviteRedirectUrl := "https://myapp.contoso.com"
requestBody.SetInviteRedirectUrl(&inviteRedirectUrl)
result, err := graphClient.Invitations().Post(requestBody)
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档。
PowerShell
Import-Module Microsoft.Graph.Identity.SignIns
$params = @{
InvitedUserEmailAddress = "admin@fabrikam.com"
InviteRedirectUrl = "https://myapp.contoso.com"
}
New-MgInvitation -BodyParameter $params
有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息,请参阅 SDK 文档。
响应
下面展示了示例响应。
注意: 为了提高可读性,可能缩短了此处显示的响应对象。
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#invitations/$entity",
"id": "7b92124c-9fa9-406f-8b8e-225df8376ba9",
"inviteRedeemUrl": "https://invitations.microsoft.com/redeem/?tenant=04dcc6ab-388a-4559-b527-fbec656300ea&user=7b92124c-9fa9-406f-8b8e-225df8376ba9&ticket=VV9dmiExBsfRIVNFjb9ITj9VXAd07Ypv4gTg%2f8PiuJs%3d&lc=1033&ver=2.0",
"invitedUserDisplayName": "Fabrikam Admin",
"invitedUserEmailAddress": "admin@fabrikam.com",
"sendInvitationMessage": false,
"invitedUserMessageInfo": {
"messageLanguage": null,
"ccRecipients": [
{
"emailAddress": {
"name": null,
"address": null
}
}
],
"customizedMessageBody": null
},
"inviteRedirectUrl": "https://myapp.contoso.com",
"status": "Completed",
"invitedUser": { "id": "243b1de4-ad9f-421c-a933-d55305fb165d" }
}
历史资料。此文对应 2023-02-03 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 Sammak)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
