ナレッジベースの即時同期

ナレッジベースの有源ナレッジの増分同期を即時にトリガーできます。現在は Google Drive ソースのみサポートしています。

注意：

インターフェースは検証とプランニングの完了後すぐに返すため、返されるのは「受理済み」であって「更新済み」ではありません。

頻度制限：Agent / Workflow ごとに 1 分あたり最大 1 回。

リクエストメソッド

POST

リクエストURL

API Key が所属するリソースタイプに応じて対応するパスを選択します。2 つのインターフェースのリクエストパラメータ、レスポンス構造、レート制限ルールは完全に一致します。

• Agent：

https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync

• Workflow：

https://api-${endpoint}.gptbots.ai/v1/workflow/knowledge-base/sync

以下のリクエスト / レスポンスの説明は 2 つのパスに同時に適用され、例は Agent パスで記述しています。

リクエスト認証

詳細は API 概要 の認証方式の説明をご参照ください。

リクエスト

リクエスト例

• 指定したナレッジベースを同期：

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "source": "google-drive",
    "knowledge_base_ids": ["6a44c3512ceb43775567391c", "6a44c3512ceb43775567391d"]
}'

                    

• その Agent 配下のすべてのナレッジベースを同期：

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "source": "google-drive"
}'

                    

リクエストヘッダー

リクエストパラメータ

レスポンス

レスポンス例

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "accepted": true,
        "source": "google-drive",
        "matched_knowledge_base_count": 2,
        "matched_doc_count": 37,
        "matched_folder_count": 3,
        "skipped": [
            {
                "reason": "DRIVE_NOT_AUTHORIZED",
                "message": "The document owner has not authorized Google Drive, or the authorization has expired.",
                "knowledge_base_id": "6a44c3512ceb43775567391e",
                "doc_count": 8
            },
            {
                "reason": "KNOWLEDGE_BASE_NOT_FOUND",
                "message": "Knowledge base does not exist or does not belong to this agent.",
                "knowledge_base_id": "deadbeefdeadbeefdeadbeef"
            }
        ],
        "scheduled_round_running": false
    }
}

                    

成功時のレスポンス

skipped[].reason の値

エラー時のレスポンス

よくあるエラーコード：

source が不正な場合のレスポンス例：

                      
                      {
    "code": 40000,
    "message": "Unsupported source: sharepoint. Supported: google-drive"
}

                    

使用説明

返されるのは「受理済み」であって「完了済み」ではない

インターフェースは検証とプランニングの完了後すぐに返し、実際の取得、解析、ベクトル化はバックグラウンドで非同期に実行されます。そのため matched_doc_count は「今回いくつのドキュメントをチェックするか」であって、「いくつのドキュメントを更新したか」ではありません。最終結果を確認するには、ドキュメントリストの取得インターフェースをポーリングしてドキュメントステータスを確認してください。ドキュメントのステータスが AVAILABLE になれば、そのドキュメントの同期が完了したことを表します。

増分のみを行い、額度を重複消費しない

各ドキュメントについて、システムはまず Google Drive 上の最終更新時刻を比較します：

• ソースドキュメントが未変更：スキップし、再ダウンロード・再解析・額度消費を行いません。
• ソースドキュメントが変更済み：再取得し、再解析・ベクトル化を行います。
• 紐付けられたフォルダに新規ファイルがある：自動的にナレッジドキュメントとして追加します。

そのため本インターフェースを繰り返し呼び出すことは安全であり、変更のないコンテンツに追加費用が発生することはありません。

本インターフェースは解析に失敗したドキュメントを再試行できない

増分判定は Google Drive 上のソースドキュメントに変更があるかどうかだけを見ており、ドキュメントが現在どのようなステータスにあるかは見ません。

そのため、以前に解析に失敗した（ステータスが FAIL の）ドキュメントは、Google Drive 上のソースファイルが変更されていない限り、本インターフェースを呼び出しても再処理されません。「ソースドキュメント未変更」として直接スキップされ、ステータスは変わらず、skipped にも現れません。

解析に失敗したドキュメントを再試行するには、埋め込み処理に失敗したドキュメントを再処理インターフェースを使用してください。あるいは Google Drive 上でソースファイルを一度変更して最終更新時刻を更新すれば、本インターフェースで再取得できます。

同期はナレッジドキュメントを削除する

本インターフェースは新規追加と更新だけでなく、Google Drive の現在の状態に従ってナレッジドキュメントを削除することもあります。

紐付けられた Google Drive フォルダが空になると、そのフォルダ配下でインポート済みのナレッジドキュメントはすべて削除されます。 トリガー条件は、フォルダが Google Drive 上で依然としてアクセス可能でありながら、ファイルが 1 つも列挙されない場合です。システムはまずフォルダのアクセス可能性を検証し、フォルダのメタ情報を取得できない場合（フォルダが移動された、権限が変更された、一時的に到達不能など）は誤削除を避けるため削除をスキップします。

削除範囲は「そのフォルダ + そのナレッジベース」の中に限定されます。同一の Google Drive フォルダが複数のナレッジベースから参照されている場合、各ナレッジベースは互いに影響しません。

この挙動はシステムの定時同期と一致しており、本インターフェースはそれを前倒しで発生させるだけです。ただし本インターフェースは、インポート時に定時同期プランを設定しなかったドキュメント（この部分は本来どの自動フローでも削除されない）もカバーするため、呼び出し前に Google Drive 側のフォルダ内容が想定どおりであることを確認してください。

カバー範囲

同期範囲はナレッジベース内の Google Drive 由来のすべてのドキュメントをカバーします。インポート時に定時同期プランを設定しなかった部分も含まれます。この部分のドキュメントはシステムの定時ラウンドで処理されず、本インターフェースでのみ更新できます。

レート制限

• Agent / Workflow ごとに 1 分あたり最大 1 回。2 つのパスは同一のカウンターを共有するため、パスを切り替えてもレート制限は回避できません。
• 同時に組織プランのナレッジ系 API の 1 分あたりリクエスト数（RPM）制限も受け、他のナレッジインターフェースとこの額度を共有します。
• 同一 Agent / Workflow の前回の同期がまだ実行完了していない場合、再度呼び出すと accepted=false かつ reason=SYNC_IN_PROGRESS を返します。

定時同期との関係

本インターフェースはシステムの定時同期と互いに独立しており、互いをブロックしません。scheduled_round_running が true の場合でも今回のリクエストは受理され、定時ラウンドが実行中であることを理由に拒否されることはありません。

両者が同時に同一のドキュメントを処理しても重複コンテンツは生成されません。システムはソースドキュメントの最終更新時刻で増分判定を行い、かつインポート済みのファイルは重複作成されません。

定時同期はナレッジベース自身が設定した頻度で自動実行され、本インターフェースはその頻度を無視して即時にトリガーします。両者は相互補完の関係にあり、定時同期は通常の更新を担い、本インターフェースは「今すぐ同期したい」シナリオを担います。