
APIの同期が「成功」でも、全件そろったとは限らない。ページ送り・差分・削除を確かめる受入設計
OPERUN.編集部|全文転載
元記事公開日:2026年11月16日
元記事:https://operun.versaroc.co.jp/ja/articles/api-sync-pagination-checkpoints-deletions-20261108
カバー:AI生成イメージ
外部サービスとのデータ連携を発注・受け入れる担当者へ。成功表示を確認する前に、対象範囲、ページ送りの終端、保存済みの位置、削除の扱いをどう説明できるかを整理します。AIへ渡してよいデータの範囲と、開発チームから受け取る証拠を、同じ受入条件につなげるための記事です。公式文書で確認したページ送り・差分同期の挙動には出典を付けています。Microsoft Graph、Google Calendar、GitHub REST APIはそれぞれ別の契約です。以下の状態名、保存の順序、管理画面、試験表、開発チームへの依頼方法は編集部の提案です。架空の案件一覧を用いた説明であり、実サイトで同期や障害試験を実施した記録、全件の瞬時一致や安全性の保証ではありません。実token・認証情報・続きURLの生値は掲載しません。
この記事のポイント
APIの応答、ローカル反映、一巡の確定、下流の業務完了を分け、成功時刻が示す対象範囲を明記する。
GitHub・Graph・Calendarの継続方法を混同せず、処理中の位置と次回に使う確定位置を区別する。
削除、不完全取得、権限変更、古い実行の遅延を分け、架空の応答データで受入条件を確かめる。
公式仕様の確認記録と、実装した連携の試験結果を別々に残し、未確認の状態をAIへ渡さない。
同期の対象と、完了が意味する範囲
編集部の実務提案
海外の開発チームが作った連携画面に、緑色の『同期成功』が表示された。ところが、AIが作る業務報告には一部の案件しか載っていない。架空の案件一覧が複数ページに分かれていて、最初のページを取得した時点で成功時刻だけを更新していた、という場面を考えます。HTTP応答を受け取ったこと、項目を保存したこと、対象範囲を一巡したこと、業務報告を完成させたことは、それぞれ別の確認が必要です。
件数が少ない検証データだけでは、ページ送りの欠落を見つけにくくなります。しかも、同じ項目が後で更新される、途中で削除される、同期の権限が変わるといった条件は、最初の一回が動くだけでは確認できません。受け入れ時に知りたいのは、データが表示されたかに加えて、何を対象に、どこまで反映し、何が未完了なのかです。その境界が記録されていれば、運用担当者は画面の色だけでなく根拠を見て判断できます。
この記事では、外部データを定期的に読み、業務やAI処理へ渡す同期を扱います。Webhookの受信確認や、失敗した業務をもう一度実行する手順そのものが主題ではありません。列挙の終端、途中の再開位置、削除、差分の確定を中心に、受け取る成果物を具体化します。すべてのAPIへ共通の再開方法を当てはめず、採用したAPIの公式仕様と、自分たちが必要とする業務の整合条件を結びつけることから始めます。
同期の対象は『案件を全部』という一言では決まりません。接続するサービス、組織やアカウント、collection、利用するAPIの版、選択する項目、絞り込み、閲覧できる権限を記録します。全件という言葉が、ある担当者に見える範囲なのか、組織全体なのかもそろえます。権限で見えない項目まで取得したと保証しないためです。この対象範囲が変わったときに、前の差分位置を使い続けてよいかを確認する項目にします。
台帳では、接続先の識別子と取得条件の版を、同期の確定位置に結びつける案が考えられます。別の顧客や別の絞り込みで得た位置を流用しないことが目的です。tokenそのものや認証情報を、人が読む設計資料や報告書へ貼る必要はありません。どの設定で発行されたものかを安全に照合できるようにし、生値は必要な実行環境だけで扱います。開発者がコピーした文字列を手作業で引き継ぐ方式に依存しないようにします。
取得条件を変える作業も、軽微な画面変更と同じには扱いません。対象期間を狭めたり、取り込む項目を増やしたりした場合、以前のローカルデータと新しい結果をどう結びつけるかを決めます。変えた後に再取得が必要なら、その間に何を未確認と表示するかも設計します。運用担当者が検索条件を変えるたびに、過去の確定記録が黙って別の意味になる構成を避け、変更理由と次に必要な確認を残します。
APIごとのページ送りと、一巡の終端
編集部の実務提案
GitHubのREST API公式資料は、結果がページに分かれる場合、LinkヘッダーのURLから追加ページを取得できると説明しています。ページ番号を増やす方法が使えるか、どのリンクが次を示すかは、採用するエンドポイントに合わせて確認します。これをすべてのAPIに共通するヘッダー仕様とは扱いません。一度の取得で件数が少なかったことだけを理由に、対象全体を取得したと判定しないことが出発点です。
開発依頼には、継続位置をどこから得るか、次の要求へ何を引き継ぐか、何をもって終端とするかを書いてもらいます。最大件数を大きくしたら一回で終わる、と仮定しないことも重要です。取得件数の上限や返る順序はAPIごとに違い、条件の変更で結果の意味も変わります。実際の仕様が不明なときは、一般的なページ送りのコードを先に作るのではなく、そのエンドポイントの契約を確認する作業として切り出します。
応答に含まれる続きURLを利用する設計では、そのURLの扱いも契約に含めます。認証情報を別の接続先へ送らないよう、許可する送信先や要求の組み立て方を確認します。一方、tokenの内容を解析して都合のよい番号へ書き換えるような実装は、提供側が保証した方法と区別します。接続先の安全確認と、ページ送りの意味を勝手に作り直さないことを両立させ、続き位置を通常ログへ露出させない扱いを決めます。
Microsoft Graphのdelta queryは、結果が空でもnextLinkがあれば取得を続け、deltaLinkが返るまで進むと説明しています。deltaLinkは、今回の状態について返すデータが残っていないことを示し、次の変更確認に使います。この区別を、他のAPIの空配列へ一律に当てはめるわけではありません。少なくともGraphのこの契約では、『データが空だから終了』という実装だけでは不十分です。
受入条件は、応答の件数ではなく、公式に定義された終端を確認したことと、必要な反映を終えたことの組合せにします。終端を受け取っていても、そのページの保存に失敗していれば、ローカルの同期は完了していません。逆に、あるページを保存しただけでは、次のページがないことを証明できません。画面に出す成功時刻をどの条件で更新するかを、取得処理と保存処理の両方を見て定義します。
完了という表示にも対象範囲と基準を添えます。ある一巡が終わったことは、その瞬間以後に起きる変更まで取得した保証ではありません。『この接続先・この条件について、前回の一巡を確定した』という記録と、情報の鮮度を判断する方針を分けます。AIの報告書が最新である必要があるなら、同期の確定時点と報告書の生成対象を結びつけ、同期ジョブが最後に起動した時刻だけで最新扱いにしないようにします。
反映した内容と、確定する位置
編集部の実務提案
編集部の提案は、処理中の再開位置と、一巡を完了した確定位置を別に管理することです。たとえば三ページある架空の一覧で、二ページ目を受信した直後に止まったとします。応答を受け取った位置だけを先へ保存していれば、まだ取り込んでいない項目を飛ばすかもしれません。ページの内容とローカル反映、次へ進む位置が、どこまで一組で確定したのかを説明できる構成にします。
同じ保存先の処理として一括確定できる構成なら、ページの適用と位置の更新をまとめる方法を検討します。別サービスに分かれて一括では確定できないなら、取得済み、適用中、適用済みを記録し、どの段階からやり直すかを設計します。特定のデータベース機能を使えば全体が必ず一度だけ動く、と保証する提案ではありません。途中で止めた試験によって、未反映のページが飛ばされず、同じページの再適用も扱えることを確認します。
前回の確定位置は、次の一巡の途中で失わないようにします。処理中の位置が壊れたり使えなくなったりした場合、どこを起点に再確認できるかが重要です。ただし、古い位置なら永久に使えるとは仮定しません。保存する情報には対象範囲、状態の版、処理中か確定済みかを持たせます。エラーから復帰したときに、今回の一部だけを取り込んだ状態を、前回からの全変更を反映した状態として表示しないための区別です。
図表:API同期の状態モデル

図表の説明:ページ取得中、反映中、一巡確定、次の差分待機、再同期が必要、権限確認待ちを分ける表。前回の確定位置は処理中に失わず、権限未確認の古いデータは下流へ渡さない。
編集部の状態モデル案。実装・対象範囲・APIの契約に合わせて具体化し、未完了を成功に含めません。
項目:状態 / 残す根拠 / 下流の扱いの例
ページ取得中 / 対象範囲と、取得を再開する位置 / 今回の一巡を完了扱いにしない
ローカル反映中 / 取得済みと反映済みの対応 / 未反映の位置まで確定しない
一巡を確定 / 終端確認と必要な反映の完了 / 確定した対象範囲・時刻を表示
次の差分を待機 / 前回の確定位置と次回の条件 / 更新保証の期限を別に扱う
再同期が必要 / token無効など、確定位置が使えない理由 / 新しい世代で再構築を管理
権限を確認中 / アクセス範囲の変化・不明点 / 権限不明の古い情報を業務へ渡さない
次ページと、次回同期のtoken
編集部の実務提案
Google Calendarの公式同期ガイドでは、次の同期に使うnextSyncTokenは、ページ分割される場合は最後のページにだけ現れます。差分取得中にpageTokenが返ったときは、同じsyncTokenと取得条件で後続ページをたどる説明です。この二種類を、単に『次のtoken』という一つの欄へ上書きしないことが重要です。名称が似ていても役割が違うため、APIごとに保存先と使用場面を分けます。
再開用の情報には、どの一巡で、どの条件から始めた取得なのかを対応させます。途中で停止した後に、前回の確定tokenと今回のページ位置を無関係に組み合わせると、何を取り込んだかを説明できなくなります。要求を再現する条件を安全な形で保持し、次回の定期ジョブが起動しても、処理中の一巡をどう扱うかを先に決めます。最終tokenを受け取った事実と、反映を確定して採用した事実も分けて記録します。
独自の更新日時を使って差分を取る連携なら、それは提供側の差分tokenと同じ保証ではありません。更新日時が同じ項目、遅れて反映される変更、過去の項目の削除を扱えるかを確認します。最新の日時だけを保存して、それ以前はもう見なくてよいと判断する前に、並び順や同値の扱いを仕様から確かめます。必要に応じて重なりのある再取得や全体照合を検討し、どの条件で取りこぼしを見つけられるかを受入条件へ書きます。
出典:[3]
同期の『完了』を、受け取る成果物から整理する
海外開発チームへデータ連携を任せる際、ページ送りや中断後の再開、AIが使ってよいデータの範囲が曖昧なら、接続先と困っている業務を整理してVERSAROCへご相談ください。画面の成功表示、保存する確定位置、受入試験のどこをそろえる必要があるかを相談する入口にできます。tokenや認証情報を初回の相談文へ貼り付ける必要はありません。
あわせて読みたいOPERUNの記事
毎回全文を取り直す前に。ETagで更新確認を設計する
媒体:OPERUN
単一表現の変更を確かめる方法と、対象全体をページ送りで同期する方法の役割を分けるために。
失敗した自動処理を安全に再開する:冪等性キーと実行台帳の設計
媒体:OPERUN
同期ページの再適用と、連携後の業務を再実行する際の重複防止を別々に整理するために。
APIの429で連打しない。再試行の待ち時間と回数を決める
媒体:OPERUN
一ページの再試行だけでなく、一巡全体の要求数・待機・停止の判断を組み合わせるために。
他メディアで実務を広げる
会計・顧客管理・メール。システム統合の前に確認すること
媒体:M&A INSIGHT
買収後のシステム統合で、接続先・アカウント・権限・データの引継ぎ範囲を整理するために。個別APIの同期仕様を代替する記事ではありません。
削除と状態の統合を区別する
編集部の実務提案
Google Calendarの差分同期ガイドは、変更結果には削除された項目も含まれ、クライアント側で取り除けると説明しています。削除を更新と別に扱う必要がある、具体的な契約の例です。ただし、任意の一覧APIで項目が返らないことを、そのまま削除通知と同じにはできません。対象サービスが何を削除として返すのか、絞り込みや権限変更で見えなくなる場合とどう区別するかを確認します。
ページを取り切っていない途中の一覧と、前回のローカル一覧を比べ、今回見えない項目をまとめて削除する処理は避けます。まだ後のページにあるのか、取得に失敗したのかを区別できないためです。全体の照合で消す方式を採るなら、同じ対象範囲について今回の列挙を完了した証拠が必要です。削除通知がある方式なら、通知の意味と識別子に従って適用します。二つの方式を状況に応じて無断で切り替えないことが要点です。
削除を下流へ反映する範囲も決めます。検索索引、AIが参照する資料、通知待ちの処理などに複製がある場合、一覧から消しただけで利用が止まるとは限りません。一方、監査のための記録と、業務で利用できるデータは目的が違います。保存が必要な記録まで一律に消すのではなく、何を参照対象から外し、何をどの権限で残すかを整理します。取得元の権限が失われた情報を、過去に取ったからという理由で使い続けない方針も必要です。
Microsoft Graphのdelta queryは、特定の返却順を仮定せず、同じ項目が複数回現れる場合を統合処理で扱うよう説明しています。また、状態tokenはクライアントにとって不透明なものです。返る並び順やtokenの文字列を、独自の更新番号として解釈する設計は避けます。この説明はGraphのdelta queryの範囲であり、別のAPIの版情報や更新順序を規定するものではありません。
同期先では、項目の識別と、その項目のどの状態を採用するかを分けます。識別子で重複行を減らすだけでは、古い内容で新しい内容を上書きする問題は解決しません。提供側に版や統合規則があるならそれを使い、必要な情報が差分だけでは確定できないなら、該当する項目を正規の取得方法で照合する設計を検討します。単純に最後に届いたものを採用するのではなく、対象APIが何を保証しているかを根拠にします。
データの統合と、通知や請求などの副作用も分離します。同じ項目を何度反映しても、業務操作を毎回発生させる必要があるとは限りません。同期の一巡が確定してから業務を起動するか、変更単位で処理するかを決め、その業務に必要な重複防止と結果照合を別に設計します。項目を更新する処理が再実行可能であっても、外部への送信まで同じ安全性を持つとは考えず、処理の境界ごとに受入試験を用意します。
全件再同期と、実行世代の管理
編集部の実務提案
Google Calendarのガイドは、tokenの期限や関連するアクセス制御の変更などでsync tokenが無効になる場合があり、410を受けたときは新しい全件同期が必要だと説明しています。これはCalendarの同期契約です。すべてのAPIの410を同じ指示とみなすわけではありません。ここで重要なのは、同じ要求の連打では直らない状態を、通常の一時エラーと分け、別の復旧手順へ移すことです。
再同期では、使えなくなった差分位置と古いローカル状態を、再び有効な確定状態として流用しません。編集部案は、再構築の世代を分けて進み具合を記録し、取得と反映を確認してから新しい状態を採用する方式です。提供側の仕様がローカル状態のリセットを求める場合も、監査記録を残すことと、古い状態を業務へ配信することを区別します。無条件に古いデータを表示し続けるための代替経路を追加する提案ではありません。
権限の変更が関係するなら、古いデータを使ってよいかを先に再評価します。新しい全件取得が終わるまで旧一覧を見せればよい、と一律には決められません。現在のアクセス範囲を確認できない情報は、下流のAIや業務へ渡さない方針を検討します。停止している理由と、いつ誰の確認が必要かを運用画面へ示し、同期エラーを単なるデータの古さとして扱わないことが、権限の境界を守るために重要です。
一巡が長くかかると、終わる前に次の定期実行が始まることがあります。接続先と対象範囲ごとに、どの実行が確定する権利を持つかを管理します。新しい実行へ引き継いだ後、古い処理から届いた結果で確定位置を戻さないことが受入条件です。これはジョブを一つ起動するだけでは確認できません。古い要求を意図的に遅らせ、新しい実行が進んだ後に戻す試験で、状態の版と採用の規則を確かめます。
実行時間、ページ数、要求数の内部上限も用意します。これらの上限で止めたことは、提供側の終端へ到達したこととは違います。停止した位置と理由を保存し、未完了として引き継ぎます。続きURLが循環する、同じページが繰り返されるといった異常も検知の候補です。上限を大きくすれば完成すると考えるのではなく、正しい対象範囲と終了条件を確認し、繰り返しの原因が分かるまで費用や負荷を増やさない方針を決めます。
要求制限や一時障害で待つ場合は、取得の再試行規則と一巡の予算を合わせます。一ページで許される回数を全ページに掛けたとき、想定外の負荷にならないかを確認します。停止中も最後の試行時刻だけを更新して正常に見せないよう、最後に一巡を確定した時刻は別に残します。再開を担当する人は、今回の試行だけでなく、前回から反映できていない範囲を見て判断できる必要があります。
出典:[3]
AIへ渡す条件と、失敗を再現する試験
編集部の実務提案
同期した一覧からAIが日報を作る構成なら、項目の本文だけでなく、対象範囲と同期の確定状態を入力前の判定へ使います。取得中の一部データで暫定集計する機能を設ける場合は、その範囲を表示し、全体の報告として出力しないようにします。プロンプトに『不完全なら注意』と書くだけでなく、不完全な状態を業務側が識別できる情報と、出力を止める条件を設計することが先です。
利用者向けの表示には、最後の試行、最後に一巡を確定した時刻、現在の状態、止まった理由を分ける案があります。『更新済み』だけでは、今試したのか、古いデータを表示しているのかが分かりません。対象外の組織や権限の範囲も表示できると、別の一覧と件数が違う理由を説明しやすくなります。ただし、表示するために接続先の機密情報や個別tokenを露出する必要はありません。
AIが同期結果から外部へ書き込む構成では、取り込んだ情報が現在も利用可能か、書き込み先の権限があるかを実行の境界で確認します。過去の同期で見えた情報を、永続的な実行許可と扱わないためです。また、同期対象のデータに含まれる文章を、実行方法を変更する指示として信用しません。同期の正確さ、AIの判断、外部操作の許可を分け、どこで人の確認が必要になるかを成果物に含めます。
受入試験には、ページ送りの応答を再現できるデータを用意します。個人情報や実tokenを使わず、架空の項目と、次に返す応答を制御できる試験用の接続先で確認する方法です。空ページに続きがある契約、途中の取得失敗、同じ項目の複数登場、削除、token無効を別のケースにします。実APIを大量に呼んで偶然エラーが起きるのを待つ方式より、どの条件を確かめたかを明確にできます。
たとえば架空の三ページで、二ページ目の応答後にローカル反映を失敗させます。再開後にそのページが飛ばされず、同じ項目が重複せず、確定時刻が未完了のまま保たれることを確認します。次は一ページ目だけ取得した状態で止め、後続にある既存項目が削除されないことを確かめます。単に処理が例外を出したという結果ではなく、同期先の内容と確定記録が期待どおりかを照合する試験です。
再同期のケースでは、古い世代の処理を遅延させ、新しい世代の確定後に結果が届く条件も作ります。古い位置や項目が採用されないこと、アクセス範囲の確認が必要な情報がAIへ渡らないことを見ます。試験の期待結果はAPIの契約から定め、都合のよい応答だけを作って通したものを本番の保証にはしません。仕様を模した試験で分かることと、実接続で別途確認すべき権限や設定を台帳で分けます。
図表:API同期の受入試験例

図表の説明:空ページの後続、途中ページの失敗、削除と不完全取得、同じ項目の複数登場、token無効、古い実行の遅延を試し、未完了の確定や権限外データの利用を防ぐ試験表。
編集部の試験条件案。APIが提供する継続・順序・削除の仕様を確認したうえで、該当するケースを選びます。
項目:起こす条件 / 確かめる結果 / 不合格の例
空のページにも続きがある契約 / 契約上の終端まで取得する / 空配列だけで完了にする
途中ページで取得が止まる / 最後の確定位置と未完了を保つ / 今回の成功時刻だけを更新
一部取得中に削除を観測 / 削除通知と未取得を区別する / 見えない全項目を一括削除
同じ項目が複数回現れる / 仕様に従って状態を統合する / 到着順だけで新旧を断定
token無効・権限範囲の変化 / 再同期とアクセス可否を再評価 / 古いデータを無条件に継続利用
古い実行の応答が遅れて到着 / 新しい同期世代の確定を守る / 古い位置で確定状態を上書き
海外チームへの引き継ぎと公開判断
編集部の実務提案
開発チームへの依頼では、対象APIの根拠、ページ送りと終端の規則、保存する位置の意味、削除と再同期の手順をまとめてもらいます。ログに成功と出た、という説明だけでなく、試験ケースごとの期待、取得した項目、反映した結果、採用した確定位置の対応が必要です。報告にtokenの生値を含める代わりに、試験内で比較できる仮の識別子と状態の版を使い、根拠へたどれる形にします。
運用の引き継ぎでは、誰が再開を判断できるかを決めます。通常の続行、再取得、全件再同期、権限の再確認を同じ『再実行』ボタンにまとめず、必要な条件と影響を示します。運用担当者がtokenを手で書き換えたり、都合のよい確定時刻を入力したりしなくてよい仕組みを検討します。再同期で下流の集計が変わる場合は、どの業務を一時停止し、何を確認して再開するかまで依頼範囲に入れます。
問い合わせに備えて残すのは、接続先の安全な識別情報、範囲の版、実行の世代、取得と反映の進捗、最後の確定、停止理由などです。取得した項目の本文を通常ログへ丸ごと複製する必要はありません。時差のある担当者にも、次にどの状態を照合すればよいかが伝わることを目指します。費用や性能の改善率を先に約束するのではなく、未完了を見つけ、止め、再開できる成果物かどうかで確認します。
最初の導入では、実際に必要な対象範囲を限定し、通常の一巡、中断からの復帰、削除、再同期、権限変更を確認します。使っていないAPIの機能まで増やす必要はありません。ただし、適用しないケースと、まだ確かめていないケースは分けます。更新対象が少ないという理由だけでページ送りの試験を外さず、将来ページをまたいでも同じ終端規則で動くかを、再現用データで先に確かめられます。
公開後も、成功した一巡の回数だけでなく、最後の確定からの経過、再同期待ち、権限確認待ち、上限で止めた処理を区別します。警告の数を増やすことより、誰がどの資料を見て次の判断をするかを決めることが重要です。取得元から消えた情報を古い保存分で復活させないことや、範囲が変わったデータを同じ集計へ混ぜないことを、更新時の回帰確認にも残します。
受け取る成果物を一つにまとめるなら、APIごとの契約表、同期の状態モデル、途中位置と確定位置の保存方針、削除と再同期の手順、試験データと結果、運用担当者の判断条件です。公式資料は、そのAPIの挙動を理解する根拠であって、作った連携が正しく動いた証明ではありません。対象範囲を最後まで読み、反映し、使ってよい状態として確定できたかを、画面と記録の両方で説明できることが、同期の受け入れ判断になります。
データ連携からAI業務まで、任せる境界を相談する
API同期の構築や改修で、確定したデータの範囲、削除の反映、復旧時の判断を海外開発チームとそろえたい場合は、VERSAROCの相談窓口へ。使うサービス、連携後に行う業務、現在困っている欠落や重複の条件が分かる範囲でお知らせください。確認する対象・実施可否・対応範囲は個別に整理するもので、この記事が費用、納期、動作結果を保証するものではありません。
日々のAI管理を、チームへ。
連携を任せる際は、画面の成功表示だけで判断せず、どの範囲を読み終え、保存し、利用可能な状態として確定したかを確認してください。OPERUNでは、海外開発チームへ依頼する成果物と、運用担当者が判断するための記録を整理する相談を受け付けています。対象のサービス、欠落や重複が起きる条件、同期後に行う業務を共有できる範囲でまとめることが、確認項目を具体化する出発点になります。
参考にした一次情報
出典確認:2026年11月16日。本文の手順・チェックリストは、編集部の実務提案です。
元記事の公開ページ:https://operun.versaroc.co.jp/ja/articles/api-sync-pagination-checkpoints-deletions-20261108