创建邀请

命名空间：microsoft.graph

使用该 API 创建新的邀请。邀请将外部用户添加至组织。

创建新的邀请时，有多个选项可供使用：

1. 创建邀请后，Microsoft Graph 可以自动向邀请的用户直接发送邀请电子邮件，或者你的应用可以使用创建响应中返回的 inviteRedeemUrl 创建自己的邀请（通过你所选择的通信机制）并发送给邀请的用户。如果决定让 Microsoft Graph 自动发送邀请电子邮件，则你可以使用 invitedUserMessageInfo 控制电子邮件的内容和语言。
2. 邀请用户后，会创建用户实体（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" }
}