Microsoft Graph コネクタの簡略化された管理者エクスペリエンスを有効にする

[アーティクル]
11/07/2024

この記事では、Teams 管理センターで Microsoft Graph コネクタの簡略化された管理エクスペリエンスを有効にする方法について説明します。このエクスペリエンスを有効にすると、Teams 管理者は Teams 管理センターでカスタム Microsoft Graph コネクタをシームレスに有効または無効にすることができます。

Teams 管理センターでの管理エクスペリエンスの簡素化

Teams 管理センターで簡略化された管理者エクスペリエンスを有効にするには:

Teams アプリマニフェストを更新します。
Microsoft Graph のアクセス許可を更新します。
Microsoft Graph Webhook 通知を処理します。
Microsoft Graph 接続を作成または削除します。
Teams 管理センターで Microsoft Graph コネクタを有効にして、エクスペリエンスを検証します。

Teams アプリマニフェストを更新する

Teams アプリマニフェストのルートで、名前、説明、 アイコンなどのプロパティと同じレベルで、 graphConnector プロパティ (アプリマニフェストの v1.11 で導入) を notificationUrl と共に追加します。このフィールドには、アプリケーションの Microsoft Graph コネクタ通知が送信される URL が含まれます。簡略化された管理者エクスペリエンスを機能させるには、アプリマニフェストのバージョンが v1.13 以上である必要があります。

webApplicationInfo プロパティがマニフェストに追加されていることを確認します。マニフェストを更新したら、アプリをサイドローディングするか、アプリをストアに発行してアップロードします。

{
 "$schema":"https://developer.microsoft.com/json-schemas/teams/v1.13/MicrosoftTeams.schema.json",
  "manifestVersion": "1.13",
  ...
  "webApplicationInfo": {
    "id": "<AAD_APP_ID>",  // e.g. "7e47846e-4bef-4c42-9817-a14e92287f28"
    "resource": "<AAD_APP_RESOURCE>" // e.g. "api://xmngc.loca.lt/7e47846e-4bef-4c42-9817-a14e92287f28"

  },
  "graphConnector": {
    "notificationUrl": "<AAD_APP_NOTIFICATION_URL>"
  }
}

Microsoft Graph のアクセス許可を更新する

[Microsoft Entra 管理センター] に移動します。
[ID] メニューを展開し、[アプリケーション>アプリの登録] に移動します。
アプリの登録を選択します。
[API のアクセス許可] に移動します>アクセス許可の追加>Microsoft Graph。
次の例に示すように、 ExternalConnection.ReadWrite.OwnedBy を選択し、Microsoft Graph のアクセス許可を ExternalItem.ReadWrite.OwnedBy します。

Microsoft Graph のアクセス許可を更新しました

Microsoft Graph Webhook 通知を処理する

管理者が Teams 管理センターから Microsoft Graph コネクタをオンまたはオフにすると、Microsoft Graph はマニフェストの notificationUrl プロパティで指定された URL に変更通知を送信します。アプリでは、これらの Microsoft Graph 接続を適切に管理する必要があります。

変更通知

変更通知を設定する方法の詳細については、「リソースデータの変更に関する通知を設定する」を参照してください。次の例は、ペイロードを示しています。

{
  "validationTokens": [
    "[jwt validation token]"
  ],
  "value": [
    {
      "changeType": "updated",
      "clientState": null,
      "resource": "external",
      "resourceData": {
        "@odata.id": "external",
        "id": "[graph connector id]",
        "state": "enabled", // or disabled
        "connectorsTicket": "[An opaque encoded string]",
        "@odata.type": "#Microsoft.Graph.connector"
      },
      "subscriptionExpirationDateTime": "2024-08-30T13:01:48.3441108-07:00",
      "subscriptionId": "[change notification's subscription id]",
      "tenantId": "[customer's tenant id]"
    }
  ]
}

受信変更通知を検証する方法については、「通知の信頼性の検証」を参照してください。

以下の点にご注意ください:

subscriptionExpirationDateTime と subscriptionId は無視できます。
変更通知は、リソースデータの @odata.type がサンプルペイロード内のデータと一致する場合にのみ、Microsoft Graph コネクタ管理用です。
識別される tenantId は、顧客のテナント ID です。 Microsoft Graph 接続を管理するために Microsoft Graph APIを呼び出す場合は、この顧客のテナント ID に代わってアプリトークンを生成する必要があります。
Microsoft Graph APIを呼び出して、顧客の表示名と既定のドメイン名を取得できます。この情報は、 tenantId をシステム内の一意の識別子にマップするのに役立ちます。詳細については、「テナント ID 別のテナント情報を検索する」を参照してください。
resourceData 内で、状態を使用して、接続を作成または削除するかどうかを決定します。接続を作成するには 、connectorsTicket が必要です。

"コネクタの有効化" 通知の処理

"コネクタの有効化" 通知を処理するには:

外部接続リスト API を使用してすべての接続のクエリを実行して、作成する Microsoft Graph 接続 (接続の数と各接続のスキーマ) を決定します。すべての接続をゼロから作成するか、接続の作成を再開するか (回復性フローで)、または no-op (必要なすべての接続が既に 準備完了 状態にある場合) を決定します。
接続は下書き状態で作成されます。 GraphConnectors-Ticket HTTP ヘッダーの接続作成 API に、connectorsTicket不透明なエンコードされた文字列を渡します。
スキーマを登録します。
スキーマの作成または更新が正常に完了すると、接続は 準備完了 状態に達します。

"コネクタの無効化" 通知の処理

"コネクタの無効化" 通知を処理するには:

外部接続リスト API を使用して、すべての接続のクエリを実行して、削除する Microsoft Graph 接続を決定します。
外部接続の削除 API を使用して、すべての接続を削除します。
削除された接続を再試行して削除されたことを確認するには、回復性ロジックを構築することをお勧めします。

要求

POST https://example.com/notificationEndpoint
Content-type: application/json
Content-length: 100

{
  "value": [
    {
      "changeType": "updated",
      "subscriptionId": "79f3b611-7f15-4bdd-9422-9606a24e49f3",
      "resource": "external",
      "clientState": null,
      "resourceData": {
        "@odata.type": "#Microsoft.Graph.connector",
        "@odata.id": "external",
        "id": "{{connectorId}}",
        "state": "enabled" //e.g. enabled or disabled
        "connectorsTicket":"eyJhbGciOiJIUzI1…"
      },
      "subscriptionExpirationDateTime": "2021-06-26T12:40:26.4436785-07:00",
      "tenantId": "9f4ebab6-520d-49c0-85cc-7b25c78d4a93"
    }
  ],
  "validationTokens": [ "eyJ0eXAiOiJKV…" ]
}

応答

HTTP/1.1 202 Accepted
Content-type: application/json
Content-length: 0

Microsoft Graph への応答で 202 - Accepted 状態コードを送信する必要があります。 Microsoft Graph が 2xx クラスコードを受け取らない場合は、約 4 時間、変更通知を複数回発行しようとします。その後、変更通知は削除され、配信されません。

validatonToken の信頼性を検証するには:

トークンの有効期限が切れていないことを確認します。
トークンが改ざんされておらず、Microsoft ID プラットフォームによって発行されたことを確認します。
validationToken で appId 要求があることを確認します。
validationToken の aud 要求が、指定した "{{Teams-appid}} と同じであることを確認します。

詳細については、「通知の信頼性の検証」を参照してください。

次の例は、検証トークンを示しています。

{ "typ": "JWT", "alg": "RS256", "x5t": "nOo3ZDrODXEK1jKWhXslHR_KXEg", "kid": "nOo3ZDrODXEK1jKWhXslHR_KXEg" }.{ "aud": "e478830d-8f49-4c26-80c6-58f68e0f064b", "iss": "https://sts.windows.net/9f4ebab6-520d-49c0-85cc-7b25c78d4a93/", "iat": 1624649764, "nbf": 1624649764, "exp": 1624736464, "aio": "E2ZgYGjnuFglnX7mtjJzwR5lYaWvAA==", "appid": "0bf30f3b-4a52-48df-9a82-234910c4a086", "appidacr": "2", "idp": "https://sts.windows.net/9f4ebab6-520d-49c0-85cc-7b25c78d4a93/", "oid": "1e7d79fa-7893-4d50-bdde-164260d9c5ba", "rh": "0.AX0AtrpOnw1SwEmFzHslx41KkzsP8wtSSt9ImoIjSRDEoIZ9AAA.", "sub": "1e7d79fa-7893-4d50-bdde-164260d9c5ba", "tid": "9f4ebab6-520d-49c0-85cc-7b25c78d4a93", "uti": "mIB4QKCeZE6hK71XUHJ3AA", "ver": "1.0" }.[Signature]

Microsoft Graph 接続を作成または削除する

Teams アプリ接続の作成を開始するときに、GraphConnectors-Ticket ヘッダーとして受信したペイロードから connectorTickets を送信する必要があります。次の例は、このプロセスを示しています。

要求

POST https://graph.microsoft.com/v1.0/external/connection
GraphConnectors-Ticket: {{connectorsTicket}}
Content-type: application/json
Authorization: bearer {{accessToken}}

{
    "id": "{{connectionId}}",
    "name": "Contoso HR",
    "description": "Connection to index Contoso HR system",
    "connectorId": "{{connectorId}}",
    "enabledContentExperiences": "MicrosoftSearch, Compliance, …",
    "searchSettings": { … },
    "complianceSettings": { … },
    …
}

注:

{{connectorId}} は、接続を作成するときに Graph コネクタからの通知で指定された値に設定する必要があります。
通知されるテナントのMicrosoft ID プラットフォームから {{accessToken}} を取得する必要があります。

応答

HTTP/1.1 200 Accepted
Content-type: application/json
Content-length: 0

注:

作成された接続に対して、さまざまな Microsoft 365 エクスペリエンスを有効にすることができます。詳細については、「Microsoft Graph コネクタの概要」を参照してください。

動作している Microsoft Graph 接続に外部項目を取り込む方法については、「Microsoft Graph コネクタを使用してアプリケーションによって追加された項目を作成、更新、削除する」を参照してください。

Teams 管理センターで Microsoft Graph コネクタを有効にしてエクスペリエンスを検証する

エクスペリエンスを検証するには:

Teams 管理者またはテナントのグローバル管理者として Teams 管理センターにサインインします。
左側のレールの [ アプリの管理 ] ブレードを選択します。
Teams アプリケーションに移動します。
Teams アプリの詳細ページには、管理者が Microsoft Graph コネクタを有効または無効にできる新しい [Graph コネクタ ] タブがあります。
切り替えボタンを選択して、アプリマニフェストの graphConnector.notificationUrl プロパティで指定されているように、アプリの通知エンドポイントに有効または無効の通知を送信します。

Teams 管理センターの他の組織で Microsoft Graph コネクタを使用できるようにする

Microsoft 365 全体で拡張された Teams アプリとしてパッケージ化された Microsoft Graph コネクタを Microsoft パートナーセンターに送信できます。これにより、Microsoft は Microsoft Graph コネクタを検証して、他の組織が Microsoft Teams管理センターで検出して展開できるようにします。

詳細な申請ガイドを使用して、アプリを送信する方法を学習できます。 Marketplace オファーの [Microsoft 365] タブと [Copilot] タブで Teams アプリを送信していることを確認します。

[ その他の認定情報 ] 手順で PDF を送信する必要があります。 Microsoft は、この PDF で提供した情報を使用して、Microsoft Graph コネクタがMicrosoft 365 Copilotで期待どおりに動作することを確認します。 PDF には次のセクションが必要です。

テストアカウント、ライセンスキー、資格情報
カスタム縦書き名
セマンティックラベル
サンプルプロンプト
接続の説明
アクティビティの設定

テストアカウント、ライセンスキー、資格情報

Microsoft Graph コネクタの検証に使用できるユーザーアカウントをデモテナントに作成します。これは、Microsoft 365 管理センターの [ユーザー] セクションで行うことができます。この新しいユーザーアカウントにMicrosoft 365 Copilot ライセンスがあることを確認します。

PDF のこのセクションで、この新しいユーザーアカウントの資格情報と該当するライセンスキーを指定します。この情報は必須です。検証のためにユーザーアカウントを準備する方法の詳細については、テストノートを提供するためのベストプラクティスに関するページを参照してください。

Microsoft がアプリを検証したら、ユーザーアカウントへのアクセスを取り消すことができます。

カスタム縦書き名

カスタムの Microsoft Graph コネクタからの結果のみを返すカスタム垂直を作成します。これは、検索 & インテリジェンスポータルの [カスタマイズ] タブの [垂直] セクションで行います。 PDF のこのセクションで、このカスタム縦書きの名前を指定します。カスタム縦書きの名前は必須です。

セマンティックラベル

[セマンティックラベル] セクションで、 title、 url、 iconUrl セマンティックラベルを持つ接続スキーマのプロパティを示します。このスキーママッピングは必須です。

サンプルプロンプト

[サンプルプロンプト] セクションで、Microsoft がMicrosoft 365 Copilotで Microsoft Graph コネクタを検証するために使用できる 2 つのサンプルプロンプトを指定します。これらのプロンプトには、 title セマンティックラベルに少なくとも部分的に一致するものが含まれている必要があります。これらのプロンプトは必須です。

接続の説明

[接続の説明] セクションで、カスタム Microsoft Graph 接続の description プロパティを指定します。 Microsoft はこれを使用して、Microsoft Graph 接続にMicrosoft 365 Copilotに関する豊富な説明があることを確認します。この説明は省略可能です。

アクティビティの設定

[アクティビティの設定] セクションで、 urlToItemResolvers リソースとの Microsoft Graph 接続のアクティビティ設定を指定します。アクティビティ設定は省略可能ですが、指定することを強くお勧めします。

次の方法で共有

Microsoft Graph コネクタの簡略化された管理者エクスペリエンスを有効にする

Teams アプリマニフェストを更新する

Microsoft Graph のアクセス許可を更新する

Microsoft Graph Webhook 通知を処理する

変更通知

"コネクタの有効化" 通知の処理

"コネクタの無効化" 通知の処理

要求

応答

Microsoft Graph 接続を作成または削除する

要求

応答

Teams 管理センターで Microsoft Graph コネクタを有効にしてエクスペリエンスを検証する

Teams 管理センターの他の組織で Microsoft Graph コネクタを使用できるようにする

テストアカウント、ライセンスキー、資格情報

カスタム縦書き名

セマンティックラベル

サンプルプロンプト

接続の説明

アクティビティの設定

フィードバック

その他のリソース

次の方法で共有

Microsoft Graph コネクタの簡略化された管理者エクスペリエンスを有効にする

Teams アプリ マニフェストを更新する

Microsoft Graph のアクセス許可を更新する

Microsoft Graph Webhook 通知を処理する

変更通知

"コネクタの有効化" 通知の処理

"コネクタの無効化" 通知の処理

要求

応答

Microsoft Graph 接続を作成または削除する

要求

応答

Teams 管理センターで Microsoft Graph コネクタを有効にしてエクスペリエンスを検証する

Teams 管理センターの他の組織で Microsoft Graph コネクタを使用できるようにする

テスト アカウント、ライセンス キー、資格情報

カスタム縦書き名

セマンティック ラベル

サンプル プロンプト

接続の説明

アクティビティの設定

フィードバック

その他のリソース

Teams アプリマニフェストを更新する

テストアカウント、ライセンスキー、資格情報

セマンティックラベル

サンプルプロンプト