次の方法で共有

招待状の作成

  • [アーティクル]

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

招待を既に引き換えたゲスト ユーザーに対して、新しい 招待 を作成するか、引き換えの状態をリセットします。 招待により、B2B コラボレーションの一部として外部ユーザーがorganizationに追加されます。 B2B コラボレーションは、従業員と外部テナントの両方のMicrosoft Entra 外部 IDでサポートされます。

招待を作成するには、次のオプションを使用できます。

  1. 招待の作成時に、Microsoft Graph は招待されたユーザーに招待メールを自動的に直接送信できます。または、アプリは応答で返された inviteRedeemUrl を 使用して、招待されたユーザーに (選択したコミュニケーション メカニズムを通じて) 独自の招待を作成できます。 Microsoft Graph で招待メールを自動的に送信する場合は、 invitedUserMessageInfo を使用してメールの内容と言語を指定できます。
  2. ユーザーが招待されると、ユーザー エンティティ ( userTypeGuest) が作成され、リソースへのアクセスを制御するために使用できます。 招待ユーザーは、招待されたリソースにアクセスするためには、引き換え処理を行う必要があります。

この 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 招待が無効になっている場合、または 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"
}

応答

次の例は応答を示しています。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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"
    }
}

例 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
}

応答

次の例は応答を示しています。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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"
    }
}