> ## Documentation Index
> Fetch the complete documentation index at: https://cogno.studio/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SharePointをCognoに接続する

> Projectが選択したサイトの共有資料を、Cognoで検索・読み取り・保存・更新します。

![SharePointの共有ファイル](https://mintcdn.com/genaxis/SBpH_n58NKMVlbl7/images/integrations/sharepoint.svg?fit=max\&auto=format\&n=SBpH_n58NKMVlbl7\&q=85\&s=dc37c4d00f8b5594841170fcbb54a5d8)

## 概要

| | |
| - | - |
| **方向** | 双方向。共有資料を読み、完成したファイルを保存・置換します。 |
| **接続方法** | Cogno共通のMicrosoftアプリ。認証情報はNangoが管理します。 |
| **設定できる人** | 連携を管理できるワークスペースメンバーとMicrosoft管理者。 |
| **必要なもの** | Microsoftのグローバル管理者または特権ロール管理者と、共有が承認されたSharePointサイト。 |

Cognoが[Project](https://cogno.studio/docs/ja/projects.md)の仕事でチームの共有資料を参照し、完成したファイルをSharePointに保存します。利用するサイトはProjectごとに明示的に選択します。各メンバーが個人のMicrosoftアカウントを接続する必要はありません。

ワークスペースの1つの接続で複数サイトを扱えます。マルチテナントの共通MicrosoftアプリはCognoが用意します。利用する組織でのアプリ作成やクライアントシークレットの発行は不要です。アプリの認証情報の保管とアクセストークンの更新はNangoが担います。Cognoはその接続を使い、ファイル操作のためにMicrosoft Graph APIを呼び出します。

> [!WARNING]
>
> 組織の共有資料として接続します。各人のSharePoint権限は継承しません。サイトを選択するすべてのProjectの参加者に、そのサイト全体を共有してよいことを確認してください。内容の共有は、それらのProject内に留めてください。

## 始める前に

* Microsoftのグローバル管理者または特権ロール管理者に、接続設定時のログインとCogno共通アプリへの同意を依頼してください。この設定で管理者本人を確認します。日常のファイル操作で各メンバーがログインする必要はありません。
* 承認した各サイトに対し、Cognoのアプリへ`write`権限を別途付与してください。アプリはMicrosoft Graphの**アプリケーション**権限`Sites.Selected`を使用します。管理者同意だけではサイトにアクセスできません。**サイトを追加**はMicrosoft側の権限を変更しません。Microsoftの[選択された権限のガイド](https://learn.microsoft.com/en-us/graph/permissions-selected-overview)を参照してください。
* `https://contoso.sharepoint.com/sites/Shared`など、HTTPSのサイトURLを用意してください。ファイルの共有リンクは使用しません。

## CognoでSharePointを接続する

**1. Cogno共通アプリに同意する**

**連携 → SharePoint**を開き、**接続**を選びます。組織のグローバル管理者または特権ロール管理者アカウントでMicrosoftにログインし、要求されたアプリ権限に同意します。Cognoがサーバー側でNango接続を作成します。アプリの認証情報を入力する必要はありません。Teams接続は不要です。

**2. 承認されたサイトを接続する**

**SharePointサイトURL**を入力します。\*\*このサイト全体を、選択するProjectの参加者に共有してよいことを確認しました。\*\*にチェックし、**サイトを追加**を選びます。Cognoがサイトのドキュメントライブラリへのアクセスを確認します。この読み取り確認は、アプリの書き込み権限を証明するものではありません。

同じ接続から、承認されたサイトを追加できます。

**3. Projectでサイトを選ぶ**

Projectの連携設定を開き、接続済みのSharePointサイトを選択します。サイトを選択していないProjectはSharePointにアクセスできません。選択前にProjectの参加者を確認してください。

**4. エージェントの権限を確認する**

**Agentの操作**で**SharePointを読み取る**と**SharePointに書き込む**を確認します。初期設定では読み取りを許可し、保存・更新は都度承認を求めます。変更は次の実行から反映されます。Projectの設定でさらに制限できます。

## ファイルを探して読む

サイトのドキュメントライブラリ一覧、フォルダ内の一覧、ファイル名での検索をCognoに依頼します。検索は資料の本文を対象にせず、ファイル名を照合します。取得は最大20ページまでで、上限に達した場合は検索が未完了であることを示します。別の場所へのショートカットは対象外です。

Cognoが本文を読めるのは5MiB以下のテキストとPDFです。返す本文は最大20,000文字で、省略がある場合はその旨を示します。その他の形式はファイル情報とリンクを返し、本文は抽出しません。資料について回答するときは、返されたSharePointリンクを出典に使います。読み取り中にファイルが変わった場合は、再度読み取ってください。

## 完成したファイルを保存・更新する

現在のTaskまたは実行で作成したファイルの保存をCognoに依頼します。承認前に保存先、ファイル名、内容を確認してください。保存したファイルには保存先の共有設定が適用されます。

| 操作 | 動作 |
| - | - |
| 新規保存 | 選択したドキュメントライブラリとフォルダに保存します。同名ファイルがある場合は停止します。 |
| 更新 | 現在の版を読み、その版を指定してファイルを置き換えます。版の競合があれば停止します。 |
| 対応容量 | 1バイトから50MiB。空ファイルは保存できません。 |
| WordとExcel | 完成した文書やブックの保存、ファイル全体の置換に対応します。段落、セル、シートを直接編集する機能ではありません。 |
| 結果が不明 | Microsoftから書き込みの完了を確認できない場合、自動では再送しません。SharePointを確認してから次の書き込みを依頼してください。 |

ファイルの削除、共有権限の変更、SharePoint Lists、サイトページ、自動巡回は対象外です。SharePointを接続解除すると、登録済みの全サイトへのアクセスを止めます。Microsoft側でサイトへの権限を取り消すと、そのサイトへの新しいアクセスを止めます。すでに共有した回答やファイルは消しません。

## よくある状態

| 状態・症状 | 意味 | 次の操作 |
| - | - | - |
| **接続済みのサイトはありません。** | ワークスペースのSharePoint接続にサイトが追加されていません。 | 承認されたサイトを追加してください。 |
| 管理者の権限設定を求めるエラーが出る | Microsoftがアクセスを拒否しています。 | 管理者同意と、そのサイトへのアプリの権限付与を確認してください。読み取り権限だけでは書き込めません。 |
| 接続したサイトをProjectで使えない | Projectでサイトが未選択、または操作がブロックされています。 | Projectのサイト選択とエージェントの権限を確認してください。 |
| 検索でファイルが見つからない | ファイル名検索には取得上限があります。 | 該当するドキュメントライブラリやフォルダを開き、ファイル名を絞ってください。 |
| ファイル情報だけが返る | 本文抽出に未対応の形式、または5MiBを超えるファイルです。 | SharePointリンクから原本を開いてください。 |
| 名前または版の競合が報告される | 同名ファイルが存在するか、対象の版が変わっています。 | 別名で保存するか、現在のファイルを読み直して更新内容を再確認してください。 |
| 書き込み結果が不明 | SharePointに書き込み済みの可能性があります。 | 保存先を確認し、同じ保存を繰り返し依頼しないでください。 |

## Cogno運用者の設定

Cognoの運用者が運用環境ごとに設定します。顧客のワークスペースごとにアプリを作成する必要はありません。

* Cogno側のMicrosoftテナントで、複数の組織テナントのアカウントに対応する共通アプリを登録し、Microsoft Graphの`Sites.Selected`アプリケーション権限を追加します。
* `COGNO_API_URL`に`/api/v1/sharepoint/callback`を付けたHTTPSのWebリダイレクトURIを登録します。
* アプリのマニフェストで`groupMembershipClaims`を`DirectoryRole`に設定します。接続設定では署名検証済みIDトークンの`wids`から、グローバル管理者または特権ロール管理者であることを確認します。ロール情報がなければ接続設定を停止します。
* サーバーのシークレット管理により`SHAREPOINT_CLIENT_ID`と`SHAREPOINT_CLIENT_SECRET`を設定します。シークレットをブラウザー、Task、Projectの指示に渡さないでください。
* セルフホストNangoの`sharepoint-online-oauth2-cc`連携にスコープ`https://graph.microsoft.com/.default`を設定し、サーバーにNangoのURLとシークレットキーを設定します。Cognoが組織の確認後、サーバー側から共通の認証情報をNangoに渡します。
* 共通クライアントシークレットの更新時は、サーバー設定と、その認証情報を保存した既存のNango接続をすべて更新してください。連携設定だけを変更しても、各接続に保存済みの認証情報は置き換わりません。

## 参考URL

* [Nango: SharePointのクライアント認証情報による接続](https://nango.dev/docs/integrations/all/sharepoint-online-oauth2-cc)
* [Microsoft: 選択された権限](https://learn.microsoft.com/en-us/graph/permissions-selected-overview)
* [Microsoft: アップロードセッションと競合の扱い](https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession?view=graph-rest-1.0)
* [Microsoft: ファイル内容の置換](https://learn.microsoft.com/en-us/graph/api/driveitem-put-content?view=graph-rest-1.0)
* [Microsoft: ファイル検索の権限制約](https://learn.microsoft.com/en-us/graph/api/driveitem-search?view=graph-rest-1.0)

## 関連ドキュメント

* [連携](https://cogno.studio/docs/ja/integrations.md)
* [Project](https://cogno.studio/docs/ja/projects.md)
* [トラブルシューティング](https://cogno.studio/docs/ja/troubleshooting.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.