概要
CognoがProjectの仕事でチームの共有資料を参照し、完成したファイルをSharePointに保存します。利用するサイトはProjectごとに明示的に選択します。各メンバーが個人のMicrosoftアカウントを接続する必要はありません。
ワークスペースの1つの接続で複数サイトを扱えます。マルチテナントの共通MicrosoftアプリはCognoが用意します。利用する組織でのアプリ作成やクライアントシークレットの発行は不要です。アプリの認証情報の保管とアクセストークンの更新はNangoが担います。Cognoはその接続を使い、ファイル操作のためにMicrosoft Graph APIを呼び出します。
始める前に
- Microsoftのグローバル管理者または特権ロール管理者に、接続設定時のログインとCogno共通アプリへの同意を依頼してください。この設定で管理者本人を確認します。日常のファイル操作で各メンバーがログインする必要はありません。
- 承認した各サイトに対し、Cognoのアプリへ
write権限を別途付与してください。アプリはMicrosoft Graphのアプリケーション権限Sites.Selectedを使用します。管理者同意だけではサイトにアクセスできません。サイトを追加はMicrosoft側の権限を変更しません。Microsoftの選択された権限のガイドを参照してください。 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に依頼します。承認前に保存先、ファイル名、内容を確認してください。保存したファイルには保存先の共有設定が適用されます。
ファイルの削除、共有権限の変更、SharePoint Lists、サイトページ、自動巡回は対象外です。SharePointを接続解除すると、登録済みの全サイトへのアクセスを止めます。Microsoft側でサイトへの権限を取り消すと、そのサイトへの新しいアクセスを止めます。すでに共有した回答やファイルは消しません。
よくある状態
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のクライアント認証情報による接続
- Microsoft: 選択された権限
- Microsoft: アップロードセッションと競合の扱い
- Microsoft: ファイル内容の置換
- Microsoft: ファイル検索の権限制約