AI連携でAPIのページング漏れを検出する

AI連携でAPIから取得したdataが少ないときは、AIの要約前に、全pageを取得して保存できたかを検査します。最初のHTTP 200や、画面に見える件数だけでは取得完了を証明できません。対象集合、API固有の継続値、終端条件、保存済みIDを一組で追います。

本稿はpage漏れの検出設計です。API呼出、data同期や削除は実施していません。Microsoft GraphとGoogle Driveを公式仕様の例にしますが、すべてのAPIで同じcursor名・上限・snapshot保証があるとは考えません。

「全件」の条件を先に固定する

resource、tenant/account、権限、filter、sort、対象期間、除外条件を記録します。UIが表示するviewの件数と、APIの別filterの件数は直接比較できません。SDKが自動page取得するか、上限で止まるかも、そのmethodの仕様で確認します。

表は横にスクロールできます

記録	役割	よくある欠落
query条件	対象集合を固定	2page目でfilterを落とす
page識別	継続の経路を追う	最初のcursorを繰返す
HTTP・parse結果	取得成功を確認	errorを空配列と扱う
保存IDと件数	書込完了を確認	取得後に保存失敗
終端と完了状態	全pageの終了を確認	page数上限で強制完了

tokenやnext URLに機密parameterがある場合は、logへ生の値を出しません。取得条件の安全な要約と、内部のpage参照・hashなどで追跡する設計にします。比較のためにcredentialをqueryへ埋め込む方法にはしません。

継続値は、APIが返した契約で使う

Microsoft Graphのpaging説明（新しいタブで開く）は、@odata.nextLinkのURL全体を次のGETへ使い、中のskiptokenだけを取り出して別requestへ組み直さないよう案内しています。resourceによってpage sizeや対応方式も異なります。必要なcustom headerが次のpageへ自動で付かない場合は、そのAPIの条件で引き継ぎます。

Google Drive files.list（新しいタブで開く）は、返されたnextPageTokenを次のpageTokenへ渡し、終端ではnextPageTokenがなくなる仕様です。これはGraphのnextLink URLと同じ文字列連結処理ではありません。どちらも自作のpage番号で置き換えず、使うAPIのresponseから次を決めます。

外部URLが返る方式では、認証情報をどのhostへ送ってよいかもclientの制約にします。次pageらしい文字列だからといって、任意hostへ同じAuthorizationを転送しません。信頼するAPIの公式継続先とHTTP clientの挙動を確認します。

空page・短いpageを、勝手な終端にしない

Graphの公式説明は、pageに0件以上の結果があり得るとしています。APIが継続値を返しているなら、配列が空または指定page size未満という理由だけで止めないようにします。反対に、ちょうど上限件数だから必ず次があるとも判断しません。

終了条件をAPIごとに明文化し、保護用の最大page数や時間上限へ達したときは「未完了」にします。無限loopを止める制限を、全件成功の条件へ読み替えません。継続値が繰り返された場合も、異常として記録し、同じpageの保存を増やし続けないようにします。

取得と保存のcheckpointを分ける

pageを受け取った時点でcursorを先へ進めると、そのpageの保存が失敗したときに欠落します。受信、検証、保存、完了確定の境界を決め、再試行で同じIDを重複作成しない保存方式にします。checkpointの具体的なtransaction設計は使用DBやqueueに合わせます。

表は横にスクロールできます

停止地点	再開前の確認	不正な完了判定
request失敗	同じ対象・継続値・再試行条件	空pageとして次へ
parse失敗	schemaとresponse	欠損fieldを0件扱い
保存途中	確定済みIDとpage状態	取得件数を保存件数にする
cursor無効	対象APIの再取得手順	cursorを推測生成
打切上限	未取得範囲と理由	全件取得済みと通知

Driveの公式資料は、tokenが拒否された場合は先頭からの再取得を案内し、取得中の追加・削除で期待結果が変わり得るとしています。別APIのtoken寿命やsnapshot性へ一般化せず、対象の契約を確認します。

件数とID、途中変更を別々に照合する

pageごとの取得数、保存数、一意ID数、重複ID、失敗page、最終継続値の有無を確認します。件数一致だけでは、あるIDの欠落と別IDの重複が相殺される場合があります。可能なら同一条件の期待ID集合と差分を取り、件数だけの監視を補います。

dataが取得中に変わる場合は、開始・終了、更新窓、source側のsnapshot保証や差分APIを確認します。DriveのincompleteSearch等、検索自体の不完全性を示すfieldがある場合も、page完走とは別に扱います。pageを追い切ったことだけで、権限外のdataや対象外の集合まで取得できたとは報告しません。

反例fixtureで漏れを見つける

通常の複数pageに加え、空だが継続あり、最終pageが上限ちょうど、同じcursor、途中429、保存途中停止、処理中の追加・削除を検証条件にします。これは試験設計で、今回実APIへ投入した結果ではありません。

完了報告には対象条件、取得・保存・一意件数、正式な終端、途中変更、未取得や不明範囲を残します。不一致があればAIへ欠落dataを補わせず、取得または保存の境界へ戻って修正します。部分集合を全件として後続の集計・削除・更新へ渡さないことが、page漏れ検査の目的です。