Copilot Studio のチャットボットから SharePoint のナレッジを参照するための設定

Microsoft Copilot Studio で作成したチャットボットの生成型の回答 (Generative Answer) では、Web 上の情報のほかにも同一テナントの SharePoint Online サイトに格納されたファイルをナレッジソースとして参照することができます。
公式の情報にも該当の機能についての設定方法がありますが、一部内容が古かったり公開情報に手順不足があるなどで苦しい思いをしたため、前述の構成を実現するにあたり必要だった設定内容をまとめました。

この情報が同じことをしたい人の参考になれば幸いです。

## 前提条件
以下の手順を実行するための Microsoft Entra ID のテナントの権限が付与されていること。
* Microsoft Entra ID にアプリケーションを登録する
* Microsoft Entra ID で API のアクセス許可を付与する

Microsoft Copilot Studio を使用したチャットボットの作成が可能であること。
Copilot Studio 側の必要なライセンスなどについては下記が詳しいです。 

https://learn.microsoft.com/ja-jp/training/modules/power-virtual-agents-bots/

また、検証に使用したチャットボット (Copilot) は下記の手順で作成したものを活用しました。言語設定は日本語の状態での動作を確認してます。
ナレッジの追加も作成時点では不要です。
なお、執筆時点で日本語環境では "生成アクションを使用する (Use generative actions)" は使用不可能なので、本記事の手順でも有効化の必要はありません。

生成 AI でコパイロットを構築するためのクイックスタート ガイド - Microsoft Copilot Studio | Microsoft Learn
https://learn.microsoft.com/ja-jp/microsoft-copilot-studio/nlu-gpt-quickstart

最後のチャットボットの動作確認には不要なので、AI が備える一般ナレッジの使用を AI に許可します (Allow the AI to use its own general knowledge) も無効化して問題ありません。

### SharePoint Online 上に用意するサイトについて

同じテナント上に、適当な名称でサイトを作成します。作成方法は下記を参照し、チームサイトを作成して検証した結果になります。
Copilot からナレッジを抽出して生成型の回答が可能なのは "モダン" スタイルのサイトのみです。

SharePoint でチーム サイトを作成する - Microsoft サポート
https://support.microsoft.com/ja-jp/office/ef10c1e7-15f3-42a3-98aa-b5972711777d

"クラシック" のスタイルのサイトではなく、"モダン エクスペリエンス" のスタイルのサイトができることを確認してください。

以降の手順では、以下の名称で必要なサイトと Copilot を作成した前提で説明します。
SharePoint Online サイト名: Copilot Studio 検証用サイト
チャットボット (Copilot) 名: Copilot-nlu-gpt-quickstart-ja-jp

## 手順概要

Copilot Studio からテナント上の SharePoint Online のサイトを参照する場合、Copilot でチャットボットを使用しているユーザーに代わって、Copilot に設定された認証設定を使用する必要があります。
Copilot Studio で選択可能な認証設定のうち "認証なし (No authentication)" および "チームのみ認証 (Only for Teams)" オプションの場合は、SharePoint または OneDrive for Business から情報を取得することができません。
また、"手動で認証する (Authenticate manually)" を選択したうえで Microsoft Entra ID からも適切な構成を行う必要があります。

前提条件は以上です。詳細な手順については以下にて解説します。

## Microsoft Entra ID にアプリケーションを登録する

Microsoft Entra 管理センター (entra.microsoft.com) にサインインし、以下の通り操作。
[ID (Identity)] メニューの [アプリケーション (Applications)] メニューを展開
[アプリの登録 (App registrations] を選択します。
Copilot Studio で作成したチャットボット (Copilot-nlu-gpt-quickstart-ja-jp) の名前が表示されている行の "アプリケーション (クライアント) ID" をコピーし、後述の手順実施時のために保存

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/5b5ea84f-d967-b2a6-e586-b918788ff2e8.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/15a9f31c-2c51-ee03-1e74-aab1444f9200.png)

作成したチャットボット (Copilot-nlu-gpt-quickstart-ja-jp) の名前をクリックし、[管理 (Manage)] ペインの [認証 (Authentication)] を選択
[プラットフォーム構成 (Platform configurations)] セクションの [プラットフォームを追加 (Add a platform)] を選択
[プラットフォームの構成 (Configure platforms
)] で、タイル "Web" を選択

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/3e27fad3-a981-0244-972c-c24fd46cc5c0.png)

"リダイレクト URI" (Redirect URIs) の入力画面に、https://token.botframework.com/.auth/web/redirect と https://europe.token.botframework.com/.auth/web/redirect を入力

"Implicit grant and hybrid flows" (暗黙的な許可とハイブリッド フロー) セクションで以下の両方をのチェックボックスを有効化
* "Access tokens (used for implicit flows)" (アクセス トークン (暗黙的なフローに使用)) 
* "ID tokens (used for implicit and hybrid flows)" (ID トークン (暗黙的およびハイブリッド フローに使用))

上記設定後、[保存 (Save)] 押下

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/01725b0e-e9f6-0e2c-f396-8ad2563eb9aa.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/c59ea71d-500b-ae1c-6d97-2499bcf139ae.png)

[証明書とシークレット (Certificates & secrets)] に移動、[クライアント シークレット (Client secrets)] セクションで、 [新しいクライアント シークレット (New client secret)] を選択します。
有効期限 (Expires) に既定値が入力されていることを確認し、[追加 (Add)] を選択
シークレットの 値 (Value) 列の内容をコピーして、ファイルなどに保存
(後でこのページに戻ってもマスキングされて見えないため、必ず該当のシークレットキーが保存されたか確認すること)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/e08043d1-4d6e-e525-b626-ceb7ecccdabb.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/446eecbe-f304-2a12-1d54-bc439afb0e2f.png)

参考情報:
https://learn.microsoft.com/ja-jp/training/modules/register-apps-use-microsoft-entra-id/4-create-app-registrations

## Copilot Studio から対象の Copilot の認証設定をする

Copilot Studio ポータル (https://copilotstudio.microsoft.com/) に移動し、以下の通り設定

Copilot Studio のサイドバー Copilot より、認証を設定する Copilot を選択
ナビゲーションメニューの [設定 (Settings)] を選択、遷移先で [セキュリティ (Security)] に移動し、認証 (Authentication) カードを選択

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/20179b03-099b-aa91-dbf6-ecba1bd350d4.png)

"手動で認証する (Authenticate manually)" を選択し、[ユーザーにサインインを要求する (Require users to sign in)] を有効化
プロパティに次の値を入力
- サービス プロバイダー: [Microsoft Entra ID] (あるいは、[Azure Active Directory v2])
- クライアント ID: Microsoft Entra 管理センター (entra.microsoft.com) からコピーしたアプリケーション (クライアント) ID
- クライアント シークレット: Microsoft Entra 管理センター (entra.microsoft.com) で前述の手順でコピーしたクライアント シークレット
- スコープ: `profile openid Sites.Read.All Files.Read.All` を入力

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/d37a2bce-3bf7-eb10-485a-6ce77aa64c0b.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/2d3551b7-ef9d-9fad-c8e6-18ac7e25f192.png)

## Microsoft Entra ID で API のアクセス許可を付与する

Microsoft Entra 管理センター (entra.microsoft.com) にサインインし、以下の通り操作。

[ID (Identity)] メニューの [アプリケーション (Applications)] メニューを展開し [アプリの登録 (App registrations)] を選択
[App applications] セクションから Copilot Studio で作成したチャットボット (Copilot-nlu-gpt-quickstart-ja-jp) の名前を選択
[API のアクセス許可 (API permissions)] に移動し [アクセス許可の追加 (Add a permission)] から [Microsoft Graph] を選択

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/5615ca17-e9d8-8856-ae76-d88e148a573d.png)

[委任されたアクセス許可 (Delegated permissions)] を選択、OpenId のアクセス許可を展開して openid と profile , Sites.Read.All, Files.Read.All を有効化して [アクセス許可の追加 (Add permissions)] を選択します。
選択後、[<テナント名> に管理者の同意を与えます (Grant admin consent for <xxxxxx>)] を選択、ポップアップに従い要求されたアクセス許可に対する同意を付与
"状態" (Status) が <テナント名> に付与されました (Granted for <xxxxxx>) となっていることを確認

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/f1f8f8db-1bc2-d3b8-de59-0ed7b733e1a6.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/76222236-73ff-3bc1-0b3f-1a9087f7dc14.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/7a5c67f8-4ab7-76c2-e334-7c9bb3102312.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/6a961b39-e0a7-6f83-c0e9-4e5220524fbd.png)

[API を公開する (Expose an API)] に移動し、[スコープの追加 (Add a scope)] > [保存してから続ける (Save and continue)] を選択

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/0bde7c68-5a49-abe0-0aaa-b5990b9e2024.png)

[同意できるのは誰ですか? (Who can consent?)] を "管理者とユーザー" (Admins and users) に変更
任意のスコープ名、表示名、説明を入力。その他のプロパティは空白のまま [スコープの追加] を選択

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/1b95597d-6549-f969-9caa-3b48e6c4150c.png)

## Copilot Studio からサインインが可能か確認する

Copilot Studio で作成した Copilot を選択し、[公開 (Publish)] を選択
Copilot の "テスト" ペインを選択し、チャット画面上で "続行するには、ログインしてください" の応答の下部の "ログイン" を選択
Web ブラウザの新規タブで "サインインを完了するには、この検証コードをチャット ウィンドウに入力してください (Please enter this validation code into the chat window to complete the sign-in:)" が表示されるのでコードをコピーし、Copilot のチャット入力欄に入力して応答 (下記のスクリーンショット参照)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/ae69ae2b-b420-c9d5-2a9b-b5395be069c5.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/35c0a7b5-8752-409a-431d-5673e3ba4994.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/c54bd243-e162-e88d-554b-f0ef75d9127c.png)

以上でサインイン完了。
Copilot Studio で、以下の公開情報の手順に従い対象の SharePoint Online 上のサイトをナレッジとして追加する

https://learn.microsoft.com/ja-jp/microsoft-copilot-studio/knowledge-add-existing-copilot#sharepoint-and-onedrive

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/773e75bc-7b12-676a-a2bc-72db90cf6ebd.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/da75f8a2-7dbb-eba4-3585-dc1f2956d243.png)

## 動作確認

SharePoint 上に任意の内容でファイルを保存し、その内容に関する質問をしてみます。
例えば、以下の "簡単な問題.docx" をナレッジとして追加した場合は下記のようにファイルの内容から生成型の回答を実行、参照したファイルのリンクを応答してくれます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/ae4d2223-1aac-b27e-5eaa-356232dc232e.png)


## よくある手順間違いやトラブルの対処方法について

### [Copilot Studio からサインインが可能か確認する] の手順で失敗する場合の対処について

途中のクライアント シークレットの入力を誤ると、Web ブラウザの新規タブで以下のようなレスポンスが表示されます。

```
{
  "message": "Login failed",
  "statusCode": 401,
  "responseBody": "{\"error\":\"invalid_client\",\"error_description\":\"AADSTS7000215: Invalid client secret provided. Ensure the secret being sent in the request is the client secret value, not the client secret ID, for a secret added to app '19f1379e-5082-4573-a318-1ad321fff61e'. Trace ID: 174cce4b-4f33-4aa2-b268-4f6f3f913800 Correlation ID: ce91dcc5-32bb-4e43-aa10-33544603cdd9 Timestamp: 2024-06-13 01:10:14Z\",\"error_codes\":[7000215],\"timestamp\":\"2024-06-13 01:10:14Z\",\"trace_id\":\"174cce4b-4f33-4aa2-b268-4f6f3f913800\",\"correlation_id\":\"ce91dcc5-32bb-4e43-aa10-33544603cdd9\",\"error_uri\":\"https://login.microsoftonline.com/error?code=7000215\"}"
}
```

記載の通り、クライアント シークレットが誤っていることが原因です。
コピーしたシークレットが正しいか確認しましょう。
特に、エラーメッセージにも書かれているとおり "シークレット ID" のほうをペーストする事故が起きがちなので注意しましょう。

### 公式情報との差異について (2024 年 6 月確認時点での情報)

Azure ポータル上で設定可能だった App Resistration は Microsoft Entra 管理センター (entra.microsoft.com) 側で設定できる項目になっています。
また、SharePoint Online のナレッジを追加したい場合は `profile openid Sites.Read.All Files.Read.All` をスコープとして指定する必要があります。

上記 2 点について、執筆時点で Microsoft Copilot Studio の公式情報に書かれている手順が古く、記載内容と実際に必要な手順との間に違いがあるため注意しましょう。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3561718/aa90af2f-0199-6fdd-82ef-9fa5fb769447.png)

Microsoft Entra ID を使用してユーザー認証を構成する - Microsoft Copilot Studio | Microsoft Learn 
https://learn.microsoft.com/ja-jp/microsoft-copilot-studio/configuration-authentication-azure-ad

下記の公開情報にも記載の通り、追加で指定している `Sites.Read.All Files.Read.All` は Microsoft Entra ID で API のアクセス許可を行う際にも指定する必要があります。
この点についても公開情報に具体的な手順の記載がないため、前述の手順 "Microsoft Entra ID で API のアクセス許可を行う" の通りアクセス許可を付与する必要があります。

生成型の回答に SharePoint または OneDrive コンテンツを使用する - Microsoft Copilot Studio | 
Microsoft Learn https://learn.microsoft.com/ja-jp/microsoft-copilot-studio/nlu-generative-answers-sharepoint-onedrive