名前空間: microsoft.graph
重要
Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
新しい 招待 を作成するか、既に招待を利用したゲスト ユーザーの引き換え状態をリセットします。 招待により、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 応答コードと、応答本文で invitation オブジェクトを返します。
例
例 1: ゲスト ユーザーを招待する
要求
次の例は、ゲスト ユーザーを追加および招待する要求を示しています。
POST https://graph.microsoft.com/beta/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.Beta.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);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-beta-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')
.version('beta')
.post(invitation);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\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.Beta.Identity.SignIns
$params = @{
invitedUserEmailAddress = "admin@fabrikam.com"
inviteRedirectUrl = "https://myapp.contoso.com"
}
New-MgBetaInvitation -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.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/beta/$metadata#invitations/$entity",
"id": "9071bfde-35e0-47d2-a582-d244ab1b4af6",
"inviteRedeemUrl": "https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3ften...6ver%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",
"userPrincipalName": "admin_fabrikam.com#EXT#@doc.onmicrosoft.com"
}
}
例 2: ゲスト ユーザーの引き換え状態をリセットする
要求
次の例は、ゲスト ユーザーの引き換えステータスをリセットする要求を示しています。 要求により、ユーザーのメール アドレスは変更されますが、現在のユーザー ID は保持されます。 要求を実行する前に、既存のゲスト ユーザー オブジェクトの otherMails プロパティである新しい電子メール アドレスを追加する必要があります。
POST https://graph.microsoft.com/beta/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.Beta.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);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-beta-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')
.version('beta')
.post(invitation);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\Invitation;
use Microsoft\Graph\Beta\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.Beta.Identity.SignIns
$params = @{
invitedUserEmailAddress = "AdeleV@fabrikam.com"
inviteRedirectUrl = "https://myapp.contoso.com"
invitedUser = @{
id = "264e6d50-eaec-461e-b187-873b1bcf855f"
}
resetRedemption = $true
}
New-MgBetaInvitation -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.models.invitation import Invitation
from msgraph_beta.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)
応答
次の例は応答を示しています。
注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$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",
"userPrincipalName": "AdeleV_fabrikam.com#EXT#@doc.onmicrosoft.com"
}
}