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

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

Microsoft Graph のコネクタプラットフォームでは、外部データを Microsoft Graph に直感的に追加できます。接続は、管理者が単体として管理できる外部データの論理的なコンテナーです。

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

カスタムヘルプデスクシステムのチケットコネクタ構造のサンプル。

サンプルカスタムヘルプデスクシステムのチケットコネクタの構造

カスタムチケットコネクタを含む接続の管理ビュー。

カスタムチケットコネクタを含む接続の管理ビュー

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

状態と操作

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

状態	説明
下書き	空の接続がプロビジョニングされています。データソース、スキーマ、または設定は構成されていません。
準備完了	この接続は、登録されているスキーマでプロビジョニングされ、取り込みの準備ができています。
現在不使用	これは、API などの依存機能が使用されていない場合に発生します。接続の削除の操作のみ可能です。
LimitExceeded	すべての接続で 1 つの接続またはテナントレベルのクォータの上限に達した場合、状態を終了するまで項目を追加することはできません。

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

操作	下書き	準備完了	現在不使用	LimitExceeded
接続の作成	❌	✔️	❌	✔️
接続の読み取り	✔️	✔️	✔️	✔️
接続の更新	✔️	✔️	❌	✔️
接続の削除	✔️	✔️	✔️	✔️
スキーマの作成	✔️	❌	❌	❌
スキーマの読み取り	❌	✔️	✔️	✔️
スキーマを更新する	❌	❌	❌	❌
スキーマの削除	❌	❌	❌	❌
アイテムの作成	❌	✔️	❌	❌
アイテムの読み取り	❌	✔️	✔️	✔️
項目を更新する	❌	✔️	❌	✔️
アイテムの削除	❌	✔️	❌	✔️

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

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

接続を作成する

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

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

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

接続設定

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

検索の設定

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

アクティビティの設定

アクティビティ設定では、Microsoft 365 アプリが共有アクティビティを検出する方法を提供できます。これにより、そのコンテンツを最も操作するユーザーにコンテンツを推奨できます。これを行うには、 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 型」を参照してください。

接続を更新する

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

接続を削除する

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

次の方法で共有