Создание приглашения

Статья
11/05/2024

Пространство имен: microsoft.graph

Используйте этот API, чтобы создать новое приглашение или сбросить состояние активации для гостевого пользователя, который уже активировал свое приглашение. Приглашение добавляет внешнего пользователя в организацию в рамках совместной работы B2B. Совместная работа B2B поддерживается как в Внешняя идентификация Microsoft Entra в рабочей силе, так и во внешних клиентах.

При создании нового приглашения у вас есть несколько вариантов:

При создании приглашения Microsoft Graph может автоматически отправить письмо с приглашением непосредственно приглашению, или ваше приложение может использовать inviteRedeemUrl , возвращенный в ответе, для создания собственного приглашения (с помощью выбранного вами механизма коммуникации) для приглашенного пользователя. Если вы решили, чтобы Microsoft Graph автоматически отправлял приглашение по электронной почте, вы можете указать содержимое и язык сообщения электронной почты с помощью метода invitedUserMessageInfo.
При приглашении пользователя создается сущность пользователя ( userTypeGuest), которую можно использовать для управления доступом к ресурсам. Приглашенный пользователь должен пройти процесс активации, чтобы получить доступ к соответствующим ресурсам.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба	Правительство США L4	Правительство США L5 (DOD)	Китай управляется 21Vianet
✅	✅	✅	✅

Разрешения

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

Тип разрешения	Разрешения с наименьшими привилегиями	Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись)	User.Invite.All	Directory.ReadWrite.All, User.ReadWrite.All
Делегированные (личная учетная запись Майкрософт)	Не поддерживается.	Не поддерживается.
Приложение	User.Invite.All	Directory.ReadWrite.All, User.ReadWrite.All

Важно!

В делегированных сценариях с рабочими или учебными учетными записями вошедшему пользователю должна быть назначена поддерживаемая роль Microsoft Entra или настраиваемая роль с разрешением поддерживаемой роли. Для этой операции поддерживаются следующие наименее привилегированные роли:

Чтобы пригласить гостей, выполните приведенные далее действия.
- Пользователи, не являющиеся членами-администраторами, и гостевые пользователи могут приглашать гостей, если администратор клиента не ограничил разрешения пользователя по умолчанию.
- Приглашенный гость, записи каталогов или администратор пользователей.
Чтобы сбросить состояние активации: администратор службы технической поддержки или администратор пользователей.
Разрешения приложений (только для приложений) не работают, если приглашения B2B отключены в клиенте или если приглашения B2B ограничены администраторами.
При сбросе состояния активации для гостевого пользователя разрешение User.ReadWrite.All является наименьшим привилегированным разрешением для операции.

HTTP-запрос

POST /invitations

Заголовки запросов

Заголовок	Значение
Авторизация	Bearer {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://video2.skills-academy.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://video2.skills-academy.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://video2.skills-academy.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. Сброс состояния активации гостевого пользователя

Запрос

В следующем примере показан запрос на сброс состояния активации гостевого пользователя. Запрос изменяет адрес электронной почты пользователя, но сохраняет его текущий идентификатор пользователя. Перед выполнением запроса необходимо добавить новый адрес электронной почты в свойство 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://video2.skills-academy.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://video2.skills-academy.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://video2.skills-academy.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)

Отклик

Ниже показан пример отклика.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#invitations/$entity",
    "id": "46d72876-dba6-4a05-b9ec-118faf16c4b7",
    "inviteRedeemUrl": "https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3fte...3d2.0",
    "invitedUserDisplayName": null,
    "invitedUserType": "Guest",
    "invitedUserEmailAddress": "AdeleV@fabrikam.com",
    "sendInvitationMessage": false,
    "resetRedemption": true,
    "inviteRedirectUrl": "https://myapp.contoso.com",
    "status": "PendingAcceptance",
    "invitedUserMessageInfo": {
        "messageLanguage": null,
        "customizedMessageBody": null,
        "ccRecipients": [
            {
                "emailAddress": {
                    "name": null,
                    "address": null
                }
            }
        ]
    },
    "invitedUser": {
        "id": "264e6d50-eaec-461e-b187-873b1bcf855f"
    }
}

Поделиться через

Создание приглашения

Разрешения

HTTP-запрос

Заголовки запросов

Тело запроса

Отклик

Пример

Пример 1. Приглашение гостевого пользователя

Запрос

Отклик

Пример 2. Сброс состояния активации гостевого пользователя

Запрос

Отклик

Обратная связь

Дополнительные ресурсы