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

[アーティクル]
05/21/2024

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

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

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

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

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

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

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

{
 "$schema":"https://developer.microsoft.com/json-schemas/teams/v1.11/MicrosoftTeams.schema.json",
  "manifestVersion": "1.11",
  ...
  "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 例に示すように、および ExternalItem.ReadWrite.OwnedBy Microsoft Graph のアクセス許可を選択します。更新された Microsoft Graph のアクセス許可

Microsoft Graph Webhook 通知を処理する

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

変更通知

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

Microsoft Graph Webhook 通知のペイロードの例

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

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

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 (必要なすべての接続が既に 準備完了 状態にある場合) を決定します。
接続は下書き状態で作成されます。 connectorsTicket の不透明なエンコードされた文字列を HTTP ヘッダーの接続作成 API にGraphConnectors-Ticket渡します。
スキーマを登録します。
スキーマの作成または更新が正常に完了すると、接続は 準備完了 状態に達します。

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

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

外部接続リスト 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

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

注:

その信頼性を検証する 202 - Accepted 前に、変更通知を受け取るとすぐに状態コードを送信します。変更通知の受信を確認し、不要な再試行を防止しています。現在のタイムアウトは 30 秒ですが、サービスのパフォーマンスを最適化するため、将来的に短縮される可能性があります。通知 URL が 10 分間にわたって Microsoft Graph からの要求の 10% を超えて 30 秒以内に返信しない場合、後続のすべての通知は遅延され、4 時間再試行されます。通知 URL が 10 分間にわたって Microsoft Graph からの要求の 20% を超えて 30 秒以内に返信しない場合、それ以降のすべての通知は削除されます。

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

トークンの有効期限が切れていないことを確認します。
トークンが改ざんされておらず、Microsoft ID プラットフォームによって発行されたことを確認します。
validationToken の appId 要求が 0bf30f3b-4a52-48df-9a82-234910c4a086 であることを確認します。
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 接続をCreateまたは削除する

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 コネクタを使用してアプリケーションによって追加されたアイテムをCreate、更新、削除する」を参照してください。

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

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

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

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

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

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

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

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

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

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

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

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

カスタム縦書き名

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

セマンティックラベル

[セマンティックラベル] セクションで、接続スキーマのどのプロパティに、url、および iconUrl セマンティックラベルが含titleまれているかを示します。このスキーママッピングは必須です。

サンプルプロンプト

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

接続の説明

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

アクティビティの設定

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

次の方法で共有

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

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

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

Microsoft Graph Webhook 通知を処理する

変更通知

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

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

要求

応答

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

要求

応答

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

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

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

カスタム縦書き名

セマンティックラベル

サンプルプロンプト

接続の説明

アクティビティの設定

フィードバック

フィードバック

その他のリソース

次の方法で共有

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

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

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

Microsoft Graph Webhook 通知を処理する

変更通知

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

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

要求

応答

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

要求

応答

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

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

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

カスタム縦書き名

セマンティック ラベル

サンプル プロンプト

接続の説明

アクティビティの設定

フィードバック

フィードバック

その他のリソース

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

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

セマンティックラベル

サンプルプロンプト