创建邀请

项目
06/12/2024

命名空间：microsoft.graph

使用此 API 为已兑换其邀请的来宾用户创建新的邀请或重置兑换状态。邀请会将外部用户添加至组织。

创建新邀请时，有几个可用选项：

创建邀请时，Microsoft Graph 可以自动向受邀用户发送邀请电子邮件，或者你的应用可以使用响应中返回 的 inviteRedeemUrl ，通过所选) 到受邀用户的通信机制来创建自己的邀请 (。如果决定让 Microsoft Graph 自动发送邀请电子邮件，则可以使用 invitedUserMessageInfo 指定电子邮件的内容和语言。
邀请用户时，将创建 userTypeGuest) 的用户实体 (，可用于控制对资源的访问。受邀请的用户必须完成兑换过程才能访问其获得访问邀请的任意资源。

全局服务	美国政府 L4	美国政府 L5 (DOD)	由世纪互联运营的中国
✅	✅	✅	✅

权限

为此 API 选择标记为最低特权的权限。只有在应用需要它时，才使用更高的特权权限。有关委派权限和应用程序权限的详细信息，请参阅权限类型。要了解有关这些权限的详细信息，请参阅权限参考。

权限类型	最低特权权限	更高特权权限
委派（工作或学校帐户）	User.Invite.All	Directory.ReadWrite.All、User.ReadWrite.All
委派（个人 Microsoft 帐户）	不支持。	不支持。
应用程序	User.Invite.All	Directory.ReadWrite.All、User.ReadWrite.All

重要

如果租户上禁用了 B2B 邀请，或者 B2B 邀请仅限于管理员，则应用程序权限 (仅限应用) 不起作用。

重置来宾用户的兑换状态时， User.ReadWrite.All 权限是操作的最低特权权限。

对于委托方案，登录用户必须至少具有 来宾邀请者、 目录作者或 用户管理员Microsoft Entra 角色。若要重置兑换状态，已登录用户必须至少具有 支持人员管理员 或 用户管理员 角色。

HTTP 请求

POST /invitations

请求标头

标头	值
Authorization	持有者 {token}。必填。详细了解身份验证和授权。
Content-Type	application/json

请求正文

在请求正文中，提供 invitation 对象的 JSON 表示形式。

下表列出了创建邀请时所需的参数。

参数	类型	说明
invitedUserEmailAddress	string	要邀请的用户的电子邮件地址。
inviteRedirectUrl	string	兑现后用户将被重定向至的 URL。

响应

如果成功，此方法在 201 Created 响应正文中返回响应代码和邀请对象。

示例

示例 1：邀请来宾用户

请求

以下示例显示了添加和邀请来宾用户的请求。

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

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


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Invitation
{
	InvitedUserEmailAddress = "admin@fabrikam.com",
	InviteRedirectUrl = "https://myapp.contoso.com",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Invitations.PostAsync(requestBody);



mgc invitations post --body '{\
  "invitedUserEmailAddress": "admin@fabrikam.com",\
  "inviteRedirectUrl": "https://myapp.contoso.com"\
}\
'



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewInvitation()
invitedUserEmailAddress := "admin@fabrikam.com"
requestBody.SetInvitedUserEmailAddress(&invitedUserEmailAddress) 
inviteRedirectUrl := "https://myapp.contoso.com"
requestBody.SetInviteRedirectUrl(&inviteRedirectUrl) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
invitations, err := graphClient.Invitations().Post(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Invitation invitation = new Invitation();
invitation.setInvitedUserEmailAddress("admin@fabrikam.com");
invitation.setInviteRedirectUrl("https://myapp.contoso.com");
Invitation result = graphClient.invitations().post(invitation);


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);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Invitation;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Invitation();
$requestBody->setInvitedUserEmailAddress('admin@fabrikam.com');
$requestBody->setInviteRedirectUrl('https://myapp.contoso.com');

$result = $graphServiceClient->invitations()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Identity.SignIns

$params = @{
	invitedUserEmailAddress = "admin@fabrikam.com"
	inviteRedirectUrl = "https://myapp.contoso.com"
}

New-MgInvitation -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.invitation import Invitation
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Invitation(
	invited_user_email_address = "admin@fabrikam.com",
	invite_redirect_url = "https://myapp.contoso.com",
)

result = await graph_client.invitations.post(request_body)

响应

以下示例显示了相应的响应。

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#invitations/$entity",
    "id": "9071bfde-35e0-47d2-a582-d244ab1b4af6",
    "inviteRedeemUrl": "https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%...d%26ver%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：重置来宾用户的兑换状态

请求

以下示例显示了重置来宾用户的兑换状态的请求。请求会更改用户的电子邮件地址，但保留其当前用户 ID。在运行请求之前，必须将新电子邮件地址添加到现有来宾用户对象的 otherMails 属性。

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

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


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Invitation
{
	InvitedUserEmailAddress = "AdeleV@fabrikam.com",
	InviteRedirectUrl = "https://myapp.contoso.com",
	InvitedUser = new User
	{
		Id = "264e6d50-eaec-461e-b187-873b1bcf855f",
	},
	ResetRedemption = true,
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Invitations.PostAsync(requestBody);



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



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewInvitation()
invitedUserEmailAddress := "AdeleV@fabrikam.com"
requestBody.SetInvitedUserEmailAddress(&invitedUserEmailAddress) 
inviteRedirectUrl := "https://myapp.contoso.com"
requestBody.SetInviteRedirectUrl(&inviteRedirectUrl) 
invitedUser := graphmodels.NewUser()
id := "264e6d50-eaec-461e-b187-873b1bcf855f"
invitedUser.SetId(&id) 
requestBody.SetInvitedUser(invitedUser)
resetRedemption := true
requestBody.SetResetRedemption(&resetRedemption) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
invitations, err := graphClient.Invitations().Post(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Invitation invitation = new Invitation();
invitation.setInvitedUserEmailAddress("AdeleV@fabrikam.com");
invitation.setInviteRedirectUrl("https://myapp.contoso.com");
User invitedUser = new User();
invitedUser.setId("264e6d50-eaec-461e-b187-873b1bcf855f");
invitation.setInvitedUser(invitedUser);
invitation.setResetRedemption(true);
Invitation result = graphClient.invitations().post(invitation);


const options = {
	authProvider,
};

const client = Client.init(options);

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

await client.api('/invitations')
	.post(invitation);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Invitation;
use Microsoft\Graph\Generated\Models\User;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Invitation();
$requestBody->setInvitedUserEmailAddress('AdeleV@fabrikam.com');
$requestBody->setInviteRedirectUrl('https://myapp.contoso.com');
$invitedUser = new User();
$invitedUser->setId('264e6d50-eaec-461e-b187-873b1bcf855f');
$requestBody->setInvitedUser($invitedUser);
$requestBody->setResetRedemption(true);

$result = $graphServiceClient->invitations()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Identity.SignIns

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

New-MgInvitation -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.invitation import Invitation
from msgraph.generated.models.user import User
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Invitation(
	invited_user_email_address = "AdeleV@fabrikam.com",
	invite_redirect_url = "https://myapp.contoso.com",
	invited_user = User(
		id = "264e6d50-eaec-461e-b187-873b1bcf855f",
	),
	reset_redemption = True,
)

result = await graph_client.invitations.post(request_body)

响应