🔗

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

2024/07/09に公開

Microsoft 365

Copilot

Microsoft Teams

tech

はじめに

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

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

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

実行手順

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

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

事前準備

チュートリアルでは 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 カスタムコネクタの利用を検討いただければと思います。