次の方法で共有


Microsoft Entra B2B コラボレーションの API とカスタマイズ

適用対象: 白いチェック マーク記号がある緑の円。 従業員テナント 灰色の X 記号が付いた白い円。 外部テナント (詳細情報)

Microsoft Graph REST API を使うと、組織に最適な方法で招待プロセスをカスタマイズできます。

招待 API の機能

API には次の機能が用意されています。

  1. "任意の" 電子メール アドレスで外部ユーザーを招待できます。

    "invitedUserDisplayName": "Taylor"
    "invitedUserEmailAddress": "taylor@fabrikam.com"
    
  2. 招待に応じたユーザーの移動先をカスタマイズできます。

    "inviteRedirectUrl": "https://myapps.microsoft.com/"
    
  3. 標準的な招待メールを Microsoft 経由で送信することを選択できます。

    "sendInvitationMessage": true
    

    カスタマイズできる受信者へのメッセージを添付できます。

    "customizedMessageBody": "Hello Sam, let's collaborate!"
    
  4. また、このコラボレーターの招待について知らせておきたい人を cc することができます。

  5. または、Microsoft Entra ID を通じて通知を送信しないことを選択して、招待とオンボード ワークフローを完全にカスタマイズすることができます。

    "sendInvitationMessage": false
    

    この場合は、招待に応じるための URL を API から受け取り、それを電子メール テンプレート、IM、またはその他の任意の配布方法に埋め込むことができます。

  6. 最後に、管理者である場合は、ユーザーをメンバーとして招待することを選択できます。

    "invitedUserType": "Member"
    

ユーザーが既にディレクトリに招待されたかどうかを判断する

招待 API を使用して、ユーザーがリソース テナントに既に存在するかどうかを判断できます。 これは、招待 API を使用してユーザーを招待するアプリを開発している場合に便利です。 ユーザーが既にリソース ディレクトリに存在する場合、そのユーザーは招待を受信しないため、まずクエリを実行して、電子メールが UPN またはその他のサインイン プロパティとして既に存在するかどうかを判定できます。

  1. ユーザーのメール ドメインが、リソース テナントの確認済みドメインに含まれていないことを確認します。

  2. リソース テナントで、次のユーザーの取得クエリを使用します。ここで、{0} は、招待するメール アドレスです。

    “userPrincipalName eq '{0}' or mail eq '{0}' or proxyAddresses/any(x:x eq 'SMTP:{0}') or signInNames/any(x:x eq '{0}') or otherMails/any(x:x eq '{0}')"
    

承認モデル

API は、以下の承認モードで実行できます。

アプリ + ユーザー モード

このモードでは、API を使用するユーザーは、B2B 招待を作成できるアクセス許可を付与されている必要があります。

アプリのみモード

アプリのみのコンテキストで招待を成功させるには、アプリに User.Invite.All スコープが必要です。

詳細については、「https://developer.microsoft.com/graph/docs/authorization/permission_scopes」を参照してください。

PowerShell

PowerShell を使用して、簡単に外部ユーザーを組織に追加および招待できます。 次のコマンドレットを使用して招待を作成します。

New-MgInvitation

以下のオプションを使用できます。

  • -InvitedUserDisplayName
  • -InvitedUserEmailAddress
  • -SendInvitationMessage
  • -InvitedUserMessageInfo

招待の状態

外部ユーザーに招待を送信した後、Get-MgBetaUser コマンドレットを使用して、招待が受け取られたかどうかを確認できます。 外部ユーザーに招待が送信されると、Get-MgBetaUser の次のプロパティが入力されます。

  • externalUserState は、招待が PendingAcceptance であるか Accepted であるかを示します。
  • externalUserStateChangeDateTime は、externalUserState プロパティに対する最新の変更のタイムスタンプを示します。

Filter オプションを使用して、externalUserState で結果をフィルター処理できます。 次の例では、保留中の招待を持っているユーザーのみを表示するように結果をフィルター処理する方法を示しています。 表示するプロパティを指定するための Format-List オプションも示しています。

Get-MgBetaUser -Filter "externalUserState eq 'PendingAcceptance'" | Format-List -Property DisplayName,UserPrincipalName,externalUserState,externalUserStateChangeDateTime

Note

必ず最新バージョンの Microsoft Graph PowerShell モジュールを使ってください。

関連項目

招待 API のリファレンスは、https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation で確認できます。

次のステップ