名前空間: microsoft.graph
この API を使用して、新しい招待を作成するか、既に 招待 を引き換えたゲスト ユーザーの引き換え状態をリセットします。 招待により、B2B コラボレーションの一部として外部ユーザーがorganizationに追加されます。 B2B コラボレーションは、従業員と外部テナントの両方のMicrosoft Entra 外部 IDでサポートされます。
新しい招待を作成するときは、いくつかのオプションを使用できます。
- 招待の作成時に、Microsoft Graph は招待されたユーザーに招待メールを自動的に直接送信できます。または、アプリは応答で返された inviteRedeemUrl を 使用して、招待されたユーザーに (選択したコミュニケーション メカニズムを通じて) 独自の招待を作成できます。 Microsoft Graph で招待メールを自動的に送信する場合は、 invitedUserMessageInfo を使用してメールの内容と言語を指定できます。
- ユーザーが招待されると、ユーザー エンティティ ( userType
Guest
) が作成され、リソースへのアクセスを制御するために使用できます。 招待ユーザーは、招待されたリソースにアクセスするためには、引き換え処理を行う必要があります。
この API は、次の国内クラウド展開で使用できます。
グローバル サービス |
米国政府機関 L4 |
米国政府機関 L5 (DOD) |
21Vianet が運営する中国 |
✅ |
✅ |
✅ |
✅ |
アクセス許可
この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。
アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。
アクセス許可の種類 |
最小特権アクセス許可 |
より高い特権のアクセス許可 |
委任 (職場または学校のアカウント) |
User.Invite.All |
Directory.ReadWrite.All、User.ReadWrite.All |
委任 (個人用 Microsoft アカウント) |
サポートされていません。 |
サポートされていません。 |
アプリケーション |
User.Invite.All |
Directory.ReadWrite.All、User.ReadWrite.All |
重要
職場または学校アカウントを使用した委任されたシナリオでは、サインインしているユーザーに、サポートされているMicrosoft Entraロールまたはサポートされているロールのアクセス許可を持つカスタム ロールを割り当てる必要があります。 この操作では、次の最小特権ロールがサポートされています。
- ゲストを招待するには:
- テナント管理者が既定のユーザーアクセス許可を制限していない場合は、管理者以外の メンバー ユーザーとゲスト ユーザーの両方がゲストを招待できます。
- ゲスト招待者、ディレクトリ ライター、またはユーザー管理者。
- 引き換えの状態をリセットするには:ヘルプデスク管理者またはユーザー管理者。
- テナントで B2B 招待が無効になっている場合、アプリケーションのアクセス許可 (アプリ専用) は機能しません。
- ゲスト ユーザーの引き換え状態をリセットする場合、 User.ReadWrite.All アクセス許可は、操作の最小特権アクセス許可です。
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);
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
mgc invitations post --body '{\
"invitedUserEmailAddress": "admin@fabrikam.com",\
"inviteRedirectUrl": "https://myapp.contoso.com"\
}\
'
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
// 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)
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
// 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);
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
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 のドキュメントを参照してください。
<?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();
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
Import-Module Microsoft.Graph.Identity.SignIns
$params = @{
invitedUserEmailAddress = "admin@fabrikam.com"
inviteRedirectUrl = "https://myapp.contoso.com"
}
New-MgInvitation -BodyParameter $params
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
# 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)
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
応答
次の例は応答を示しています。
注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。
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);
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
mgc invitations post --body '{\
"invitedUserEmailAddress": "AdeleV@fabrikam.com",\
"inviteRedirectUrl": "https://myapp.contoso.com",\
"invitedUser": {\
"id": "264e6d50-eaec-461e-b187-873b1bcf855f"\
},\
"resetRedemption": true\
}\
'
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
// 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)
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
// 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);
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
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);
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
<?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();
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
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
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
# 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)
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
応答
次の例は応答を示しています。
注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。
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"
}
}