Notionコネクタ

概要

Notionコネクタは、Notionのページとデータベースの行を取得して Fess のインデックスに登録する機能を提供します。 Notionの内部インテグレーションとして認証し、そのインテグレーションに共有されているすべてのコンテンツを索引対象にします。

この機能には fess-ds-notion プラグインが必要です。

対応コンテンツ

• ページ（ブロックのテキスト）

• データベースの行（プロパティ値を含む）

• Notionにホストされたファイルブロックとpdfブロックの添付ファイル（それぞれ独立した文書として索引化します）

• ページの未解決コメント（ページの文書に取り込みます）

以下は対象外です:

• Notionの外部にあるファイル（外部リンクのファイル）。ダウンロードするのはNotionにホストされた file ブロックと pdf ブロックのみです

• Notionのゴミ箱に入っているページとデータベースの行

• ページ単位のアクセス制御（後述の「権限」を参照）

前提条件

1. プラグインのインストールが必要です

2. Notionの内部インテグレーションの作成が必要です

3. クロール対象のページとデータベースをインテグレーションに共有する必要があります

プラグインのインストール

管理画面の「システム」→「プラグイン」からインストールするか、bin/fess-setup install plugin fess-ds-notion を実行して Fess を再起動します。 詳細は プラグイン を参照してください。

Notionインテグレーションの設定

1. Notionで内部インテグレーションを作成し、「内部インテグレーションシークレット」(Internal Integration Secret)をコピーします。

2. インテグレーションの設定ページ(Configuration)で、以下のケイパビリティを有効にします:

   ケイパビリティ	必須	用途
   コンテンツの読み取り(Read content)	常に必須	ページ、ブロック、データベース、データベースの行の読み取り。無効にすると、すべてのリクエストが 401 unauthorized で失敗し、クロールは即座に中止されます
   コメントの読み取り(Read comments)	include_comments=true （既定）の場合のみ	ページのコメントの取得。無効の場合、警告を1回ログに出力し、そのクロールの残りではコメントの取得を無効にします。クロール自体は失敗しません
   ユーザー情報の読み取り(Read user information)	任意	ユーザーID（created_by、last_edited_by、people プロパティ）の表示名への解決。無効の場合は、名前の代わりにユーザーIDが索引化されます

3. クロール対象のすべてのページまたはデータベースを、Notion上でインテグレーションに共有します。 ケイパビリティを追加しただけでは、どのコンテンツにもアクセスできるようにはなりません。

設定方法

管理画面から「クローラー」→「データストア」→「新規作成」で設定します。

基本設定

項目	設定例
名前	Company Notion
ハンドラ名	NotionDataStore
有効	オン

パラメーター設定

token=secret_************************************

パラメーター一覧

パラメーター	必須	説明
token	はい	内部インテグレーションシークレット。スクリプトには渡されず、ログにも出力されません
root_page_ids	いいえ	クロールの起点にするページIDのカンマ区切りリスト。これと database_ids の両方が空の場合は、Notionの検索でインテグレーションに共有されているすべてのページとデータベースを探索します
database_ids	いいえ	クロールの起点にするデータベースIDのカンマ区切りリスト。各データベースのすべての行を索引化します
include_comments	いいえ	各ページの未解決コメントを取得し、そのテキストを notion.content と notion.comments に含めます（デフォルト: true）
include_files	いいえ	Notionにホストされた file ブロックと pdf ブロックの添付ファイルをダウンロードしてテキストを抽出し、それぞれを独立した文書として索引化します（デフォルト: true）
max_file_size	いいえ	このバイト数を超える添付ファイルは、空のコンテンツでも索引化せず、完全にスキップします（デフォルト: 10485760）
include_pattern	いいえ	文書の notion.url が一致する必要がある正規表現（「クロール範囲」を参照）
exclude_pattern	いいえ	文書の notion.url が一致してはいけない正規表現（「クロール範囲」を参照）
request_interval	いいえ	Notionのレート制限（毎秒約3リクエスト）を超えないよう、各APIリクエストの前に待機するミリ秒数（デフォルト: 350）
max_retry_count	いいえ	429、5xx、529 の応答、またはタイムアウトなどの通信エラーになったリクエストの最大リトライ回数（デフォルト: 5）
connection_timeout	いいえ	各APIリクエストの接続タイムアウト（ミリ秒、デフォルト: 10000）
read_timeout	いいえ	各APIリクエストの読み取りタイムアウト（ミリ秒、デフォルト: 30000）
ignore_error	いいえ	ダウンロードできた添付ファイルのテキスト抽出に失敗した場合に、文書を失敗扱いにせず、空のコンテンツで索引化します（デフォルト: true）。ダウンロードの失敗は、この設定に関係なく常に文書の失敗になります

注釈

数値パラメーターに空値または数値でない値を指定すると、警告をログに出力して既定値を使用します。 request_interval と max_retry_count に負の値を指定した場合（0 はどちらも有効）や、 true / false のパラメーターにそれ以外の値を指定した場合も同様です。

スクリプト設定

title=notion.title
content=notion.content
url=notion.url
mimetype=notion.mimetype
last_modified=notion.last_edited_time
created=notion.created_time

利用可能なフィールド

ページ、データベースの行、添付ファイルのすべての文書は、スクリプトから notion オブジェクトとして参照できます。

フィールド	説明
notion.type	ページまたはデータベースの行は page、添付ファイルは file
notion.id	ページID。添付ファイルの場合はブロックID
notion.title	ページのタイトル（名前に関係なく、型が title のプロパティ）。添付ファイルの場合はファイル名
notion.content	ページの場合: タイトル以外のプロパティ値（データベースの行のみ）、ブロックのテキスト、コメントのテキストを連結したもの。添付ファイルの場合: 抽出したテキスト
notion.url	ページのNotion URL。添付ファイルの場合は、含まれるページのURLの末尾に #<ブロックID> を付けたもの
notion.mimetype	ページは text/html、添付ファイルは検出したMIMEタイプ
notion.created_time	ページの作成日時。添付ファイルでは利用できません
notion.last_edited_time	ページ（または添付ファイルのブロック）の最終編集日時
notion.created_by	ページの作成者。Notionが名前を返した場合は名前、そうでなければユーザーID。添付ファイルでは利用できません
notion.last_edited_by	最終編集者（同じ形式）。添付ファイルでは利用できません
notion.parent_id	親のページ、データベース、データソース、ブロックのID。ワークスペース直下のページでは空。添付ファイルでは利用できません
notion.properties	データベースの行の、列名から整形済みテキストへのマップ。通常のページでは空。添付ファイルでは利用できません
notion.comments	ページのコメントのテキストを連結したもの。include_comments=false の場合やコメントがない場合は空。添付ファイルでは利用できません
notion.page_url	含まれるページのURL。添付ファイルのみ
notion.page_title	含まれるページのタイトル。添付ファイルのみ
notion.size	添付ファイルのバイト数（Notionが返した場合）。添付ファイルのみ

クロール範囲

• root_page_ids と database_ids のどちらも指定しない場合は、Notionの検索でインテグレーションに共有されているすべてのページとデータベースを探索します。 Notionの検索はすべてを網羅することが保証されていません。索引にないコンテンツがある場合は、root_page_ids または database_ids を明示的に指定してください。

• 各起点から辿れる子ページと子データベースもすべてクロールするため、通常は1つのルートページを指定すれば、ワークスペースの1つのセクション全体に届きます。

• include_pattern と exclude_pattern が決めるのは、そのページ（または添付ファイル）自身の文書を索引化するかどうかだけです。 子孫の探索は止まりません。ページのブロックは、ページ自身のURLに対してパターンを判定する前に必ず辿るため、 除外したページの子ページも、それぞれのURLで引き続きクロールされ、索引化されます。 サブツリー全体を除外するには、ルートだけでなく、その配下のすべてのURLに一致するパターンを指定してください。

• Notionのゴミ箱に入っているページとデータベースの行はスキップします。

権限

Notion APIはページの共有設定を公開していないため、このコネクタはページ単位のアクセス制御を同期できません。 すべての文書は、データストア設定の「権限」フィールドに設定した権限だけで索引化されます。

警告

インテグレーションに共有したすべてのコンテンツは、Notion上で誰が閲覧できるかに関係なく、このフィールドで許可したロールで検索できるようになります。 それらのロールに検索させてよいページとデータベースだけを、インテグレーションに共有してください。

エラー処理

• クロールが中止されるのは、HTTP 401 （トークンで認証できない）、または public_api_request_blocked を示す 429 応答 （Notionのレート制限によってインテグレーションがブロックされた）の場合だけです。 root_page_ids も database_ids も指定していないときにNotionの検索が失敗した場合も、起点がなくなるためクロールが中止されます。

• それ以外の失敗は文書ごとに処理されます。1つのページ、データベース、コメントスレッド、ブロックに対する 404 や 403、 1つのリクエストで max_retry_count を使い切った場合は、ログに記録してスキップし、クロールを続行します。

• 文書ごとの失敗は、その文書のURL（ページはNotion URL、添付ファイルは <ページのURL>#<ブロックID>）で 「クローラー」→「障害URL」に記録されます。 添付ファイルの署名付きダウンロードURLは、記録もログ出力もされません。

• パラメーターに keep_expires_docs=false を指定すると、クロールで再索引化されなかったデータストアの文書は、クロール終了時に削除されます。 これは、中止したクロールでも同様です。 既定では、文書には有効期限が付き、その期限が過ぎるまで索引に残ります。

使用例

特定のページツリーをクロール

パラメーター:

token=secret_************************************
root_page_ids=0123456789abcdef0123456789abcdef
include_comments=false

スクリプト:

title=notion.title
content=notion.content
url=notion.url
mimetype=notion.mimetype
last_modified=notion.last_edited_time

データベースをクロール

パラメーター:

token=secret_************************************
database_ids=fedcba9876543210fedcba9876543210
include_files=false

スクリプト:

title=notion.title
content=notion.content
url=notion.url
created=notion.created_time
last_modified=notion.last_edited_time

インテグレーションに共有されたすべてをクロール

パラメーター:

token=secret_************************************
request_interval=500

トラブルシューティング

クロールが 401 ですぐに中止される

トークンがインテグレーションの「内部インテグレーションシークレット」であること、「コンテンツの読み取り」ケイパビリティが有効であることを確認してください。

索引にないページがある

1. ページまたはデータベースがインテグレーションに共有されていることを確認します

2. 探索に任せている場合は、Notionの検索がすべてを網羅するとは限らないため、root_page_ids または database_ids を明示的に指定します

3. include_pattern と exclude_pattern を確認します

4. 「クローラー」→「障害URL」で、個別に失敗した文書を確認します

コメントが索引化されない

インテグレーションの「コメントの読み取り」ケイパビリティを有効にしてください。無効の場合は、警告を1回ログに出力し、そのクロールではコメントをスキップします。 索引化されるのは、未解決のコメントだけです。

参考情報

• データストアコネクタの概要 - データストアコネクタ概要

• Slackコネクタ - Slackコネクタ

• データストアクロール - データストア設定ガイド

• 障害URL - 障害URL

• プラグイン - プラグイン管理ガイド

• Notion APIドキュメント