Microsoft Graph の接続を作成、更新、削除する

Microsoft 365 Copilot コネクタを使用すると、外部データを Microsoft Graph に直感的に追加できます。 接続は、管理者が単体として管理できる外部データの論理的なコンテナーです。

接続が作成されたら、オンプレミスのコンテンツ ソースやサービスとしての外部ソフトウェア (SaaS) サービスなど、任意の外部データ ソースからコンテンツを追加できます。 作成した接続、または明示的に 承認された接続のみ表示および管理できます。 検索管理者は、Microsoft 365 管理センターの Copilot>Agents とコネクタ のセクションを使用して、テナント内のすべての接続を表示および管理できます。

必要な接続を自由に作成することができますが、コネクタのすべてのインスタンスに対して 1 つの接続を作成するのが最も一般的です。 たとえば、Microsoft Windows ファイル共有コネクタを設定するたびに、新しい接続が作成されます。 1 つの接続を作成して、データ ソースからすべてのアイテムを追加することもできます。 たとえば、1 つの接続を作成して、ヘルプデスク システムの複数チームですべてのチケットとインシデントを追加することができます。

状態と操作

次のいずれかの状態のときに接続を使用できます。

次の表は、各状態で使用できる操作を示しています。

接続を使用すると、アプリケーションでインデックスが作成されるアイテムのスキーマを定義できます。また、インデックスにアイテムを追加したり、更新したり、インデックスから削除したりするためのサービスのエンドポイントを提供します。

アプリケーションで検索インデックスにアイテムを追加する最初のステップは、接続を作成することです。

接続を作成する

アプリケーションで検索インデックスにアイテムを追加する前に、接続を作成および構成する必要があります。

1. 一意の ID、表示名、説明を付けて、接続を作成します。
2. スキーマを登録して、インデックスに含まれるフィールドを定義します。

   注: 既存の接続のスキーマの更新の詳細については、「 スキーマの更新機能」を参照してください。

接続設定

有効になっている各コンテンツ エクスペリエンスの既定の接続設定を構成できます。 有効にすると、これらの設定は Microsoft Search とMicrosoft 365 Copilotのコンテンツ エクスペリエンスに影響します。

アクティビティの設定

アクティビティ設定](/graph/api/resources/externalconnectors-activitysettings)は、Url から ExternalItem へのマッピング メタデータをロービドします。これにより、Microsoft 365 は、URL が Copilot コネクタ接続の特定のインデックス付きアイテムに対応していることを認識できます。

• Microsoft 365 エクスペリエンスでの URL 解決

  • ユーザーが Microsoft Search や Microsoft 365 Copilot などの Microsoft 365 エクスペリエンスで URL を検索、貼り付け、共有すると、Microsoft 365 は構成されたurlToItemResolversを使用して、対応するexternalItemへの URL を解決できます。 これにより、Microsoft 365 は、URL で表されるインデックス付きアイテムを識別し、検出された操作を正しい外部アイテムに関連付けることができます。

• Microsoft 365 Copilot拡張機能を使用したアクティビティシグナルCapture

  • アクティビティ信号は、Microsoft 365 Copilot用のブラウザー ベースの拡張機能である Microsoft 365 Copilot 拡張機能を使用してキャプチャできます。 アクティビティ設定が構成され、拡張機能が有効になっている場合、拡張機能はアクティビティシグナルを自動的にキャプチャし、インデックス付きコネクタ項目に関連付けることができます。 これらのシグナルは、接続されたシステムでユーザーが関与するコンテンツを優先することで、Microsoft 365 Copilot全体のパーソナル化と関連性を向上させるのに役立ちます。

アクティビティ設定は、これらのシグナルを正しいインデックス付き項目に関連付けるために必要な URL から項目へのマッピングを提供します。 これを行うには、 urlToItemResolver を追加します。 これにより、Microsoft 365 アプリ内で検出された接続の URL を externalItem のそれぞれの項目 ID に解決できます。 次の図は、Microsoft 365 全体のレコメンデーション エクスペリエンス内でアイテムがどのように表示されるかを示しています。

次の例は、完全な urlToItemResolvers セクションを含む activitySettings ペイロードを示しています。 たとえば、リンク https://contoso.com/items/39483948/を共有するユーザーは、Microsoft Graph 接続を介して取り込まれた externalItem を 表します。 この例では、共有リンクは、itemId がid_39483948の externalItem を表します。 この接続は、URL からその externalItem の itemId にマップする方法を指定します。 この例では、この接続の ID は contosohr です。

接続にパッチ要求を送信して、アクティビティの設定を更新します。

PATCH https://graph.microsoft.com/v1.0/external/connections/contosohr

次の activitySettings ペイロードがパッチ要求と共に送信されます。

{
  "@odata.type": "#microsoft.graph.externalConnectors.activitySettings",
  "urlToItemResolvers": [
    {
        "@odata.type": "#microsoft.graph.externalConnectors.itemIdResolver",
          "itemId": "id_{myItemId}",  
          "priority": 1,
          "urlMatchInfo": {
            "@odata.type": "microsoft.graph.externalConnectors.urlMatchInfo",
            "baseUrls": [
              "https://contoso.com"
            ],
            "urlPattern": "/items/(?<myItemId>[0-9]+)"
          }
    }
  ]
}

この例では、 itemId フィールドで、URL が表す外部アイテムの ID を形成する方法を指定しました。 itemId は urlPattern (urlMatchInfo 内) で参照され、externalItem の ID として39483948を抽出します。

アクティビティ設定ペイロードの urlToItemResolvers リソースには、最大 8 つの itemIdResolver リソースの一覧を指定できます。 これらの urlMatchInfo リソースごとに、@odata.typeの#microsoft.graph.externalConnectors.itemIdResolverの値、priority プロパティに 1 から 8 までの整数、および基本 URL と正規表現のリストを含む urlMatchInfo オブジェクトを指定します。

リンクが共有されている場合、リゾルバーに属する urlMatchInfo オブジェクトは 、優先順位 の値が指定した順序で適用されます。 昇順の優先順位では、URL は最初に urlMatchInfo プロパティの baseUrls リスト内の URL と比較されます。 次に、リンク URL のベースが baseUrls リストにある場合は、 urlPattern 正規表現が URL に適用されます。 このパターンが一致する場合、リゾルバーは適用されません。 リンク URL のベースが baseUrls リストに含まれていない場合、または urlPattern が一致しない場合、次の urlToItemResolver は、一致するものが見つかるか、適用する urltoItemResolver リソースが存在しない限り評価されます。

urlMatchInfo リソースの詳細については、「urlMatchInfo 型」を参照してください。

検索の設定

searchSettings でコンテンツの既定の検索表示テンプレートを指定することで、Microsoft 検索結果ページでの検索結果の表示方法を定義できます。 一連の検索表示テンプレートを使用すると、異なる種類の検索結果を異なる方法で表示できます。 検索表示テンプレートには、アダプティブ カードと 1 つ以上の条件を指定するルールを使用して構築された結果レイアウトがあります。 これらの条件が満たされると、レイアウトが検索結果に適用され、結果ページに表示されます。

接続を更新する

既存の接続の表示名、説明、または有効なコンテンツ エクスペリエンスを変更するには、 接続を更新します。

接続を削除する

接続を介してインデックスが作成されたアイテムをすべて削除するために、接続を削除することができます。

関連コンテンツ

• 接続スキーマを登録する
• Copilot コネクタ API リファレンスを確認する
• GitHub からサンプル検索コネクタをダウンロードする