💻

Microsoft Graph のカスタム コネクタを使ってデータを検索する

2024/07/09に公開

はじめに

Copilot for Microsoft 365 に組織のデータを拡張するための方法のひとつに Microsoft Graph コネクタを使用する方法があります。

https://learn.microsoft.com/ja-jp/microsoft-365-copilot/extensibility/overview-graph-connector?WT.mc_id=M365-MVP-5002941

Microsoft Graph コネクタについては以前の記事でも紹介しています。

https://zenn.dev/karamem0/articles/2022_01_03_120000

ただし標準で提供されているコネクタの種類はそれほど多くありません。標準で提供されている以外のサービスについては Microsoft Graph コネクタ ギャラリー からサードパーティーのコネクタを使用できます。また、カスタム コネクタを作成して自分で実装することもできます。今回はカスタム コネクタを使ってデータを検索できるようにしたいと思います。

実行手順

カスタム コネクタの作成方法についてはチュートリアルがあります。

https://learn.microsoft.com/ja-jp/graph/connecting-external-content-build-quickstart?WT.mc_id=M365-MVP-5002941

ただ、現状ちょっとわかりにくいので、もう少し簡単に手順を確認してみたいと思います。

事前準備

チュートリアルでは Entra ID アプリケーションを登録してカスタム コネクタを作成するのですが、今回は Graph Explorer を使います。実行するユーザーにはグローバル管理者のアクセス許可が必要です。Graph Explorer には以下のアクセス許可が必要です。

  • ExternalConnection.ReadWrite.All
  • ExternalItem.ReadWrite.All

カスタム コネクタを Copilot for Microsoft 365 からも利用できるようにするには追加の設定が必要になります。

  • スキーマにセマンティック ラベルを適用する
  • 接続に urlToItemResolver を追加する
  • アイテムにユーザー アクティビティを追加する
  • 接続の description にわかりやすい説明を追加する
  • すべて のバーティカルで 結果をインラインで表示する を有効にする

接続の作成

接続を作成します。Graph Explorer で https://graph.microsoft.com/v1.0/external/connections に対して POST 要求を呼び出します。id は 4~32 文字までの文字列を指定できます。わかりやすい名前を付けても構いませんが、今回は GUID (からハイフンを除いたもの) を使用しています。

{
  "id": "9d1a4936352945faaef6fd22ea204b21",
  "name": "からめもぶろぐ。",
  "description": "からめもぶろぐ。のブログ記事を検索します。",
  "activitySettings": {
    "urlToItemResolvers": [
      {
        "@odata.type": "#microsoft.graph.externalConnectors.itemIdResolver",
        "priority": 1,
        "itemId": "{itemId}",
        "urlMatchInfo": {
          "baseUrls": [
            "https://zenn.dev/karamem0"
          ],
          "urlPattern": "/articles/(?<itemId>.+)"
        }
      }
    ]
  }
}

スキーマの作成

接続のスキーマを作成します。Graph Explorer で https://graph.microsoft.com/v1.0/external/connections/{{connector-id}}/shema に対して POST 要求を呼び出します。

{
  "baseType": "microsoft.graph.externalItem",
  "properties": [
    {
      "name": "iconUrl",
      "type": "String",
      "isQueryable": true,
      "isRefinable": false,
      "isRetrievable": true,
      "isSearchable": false,
      "label": [
        "iconUrl"
      ]
    },
    {
      "name": "title",
      "type": "String",
      "isQueryable": true,
      "isRefinable": false,
      "isRetrievable": true,
      "isSearchable": true,
      "label": [
        "title"
      ]
    },
    {
      "name": "url",
      "type": "String",
      "isQueryable": true,
      "isRefinable": false,
      "isRetrievable": true,
      "isSearchable": false,
      "label": [
        "url"
      ]
    },
    {
      "name": "description",
      "type": "String",
      "isQueryable": false,
      "isRefinable": false,
      "isRetrievable": true,
      "isSearchable": true
    },
    {
      "name": "created",
      "type": "DateTime",
      "isQueryable": true,
      "isRefinable": true,
      "isRetrievable": true,
      "isSearchable": false,
      "label": [
        "createdDateTime"
      ]
    },
    {
      "name": "updated",
      "type": "DateTime",
      "isQueryable": true,
      "isRefinable": true,
      "isRetrievable": true,
      "isSearchable": false,
      "label": [
        "lastModifiedDateTime"
      ]
    }
  ]
}

処理が終わるまでにある程度時間がかかるため気長に待ちましょう。状態は Microsoft 365 管理センターからも確認できます。正常に完了していれば以下のように表示されます。

データの作成

標準のコネクタでは自動的にクロールしてくれますが、カスタム コネクタの場合はクローラーを自分で作成する必要があります。これは Azure AI Search における プル 型と プッシュ 型の違いによく似ています。

Graph Explorer で https://graph.microsoft.com/v1.0/external/connections/{{connector-id}}/items/{{item-id}} に対して PUT 要求を呼び出します。

{
  "acl": [
    {
      "type": "everyone",
      "value": "{{tenant-id}}",
      "accessType": "grant"
    }
  ],
  "properties": {
    "iconUrl": "https://github.com/twitter/twemoji/blob/master/assets/72x72/1f607.png",
    "title": "サンプル記事",
    "iconUrl": "https://github.com/karamem0/articles/2024_07_01_090000",
    "description": "これはサンプル記事の投稿です。",
    "created": "2024-07-01T00:00:00Z",
    "updated": "2024-07-01T00:00:00Z"
  },
  "content": {
    "value": "これはサンプル記事の投稿です。",
    "type": "text"
  }
}

ユーザー アクティビティの追加

Graph Explorer で https://graph.microsoft.com/v1.0/external/connections/{{connector-id}}/items/{{item-id}}/addActivities に対して POST 要求を呼び出します。

{
  "activities": [
    {
      "@odata.type": "#microsoft.graph.externalConnectors.externalActivity",
      "type": "created",
      "startDateTime": "2024-07-01T09:00:00Z",
      "performedBy": {
        "type": "user",
        "id": "{{user-id}}"
      }
    }
  ]
}

結果の種類の追加

Microsoft 365 管理センターから結果の種類を追加します。

バーティカルの種類の追加

Microsoft 365 管理センターからバーティカルを追加します。

追加後に有効にするのを忘れないようにします。

結果のインライン表示の有効化

Microsoft 365 管理センターでバーティカルの すべて を選択し コネクタの結果を管理する をクリックします。作成した結果の種類をインライン表示するように設定します。

実行結果

まずは Microsoft Search で正しく表示されることを確認します。バーティカルが追加されていること、すべての検索結果に追加したコネクタの結果が表示されれば成功です。

Copilot for Microsoft 365 でも結果が返ってくることを確認します。

おわりに

現在 Azure AI Search を使った RAG システムは主流となっています。しかし、Microsoft Graph カスタム コネクタを使うことで、検索インターフェースを統合できるだけではなく、Copilot for Microsoft 365 でも利用できるようになります。かなり利用価値は高いですし、実装の難易度やアーキテクチャも Azure AI Search も場合とほとんど変わりません。今回は紹介しませんでしたが、組み込みのアクセス制御機能を利用すれば、よりセキュアに構築することもできます。今後、セマンティック インデックスのサポートも期待できるところです。ぜひ Microsoft Graph カスタム コネクタの利用を検討いただければと思います。

Discussion