Jira・GitHub・Salesforceなどの外部SaaSからデータを定期的に取り込む「データコネクタ」を自前で運用しているSREやバックエンド担当者に向けた内容です。ページネーション(APIの応答を複数ページに分けて取得する仕組み)とリトライ処理の実装に、見落としやすい落とし穴がいくつかあります。差分同期の信頼性に関わる部分なので、設計を見直すきっかけになれば幸いです。
何が起きるか
SaaS APIからのデータ同期では、全件を一度に取得せず「カーソル(次のページを指す位置情報)」や「オフセット(先頭から何件目か)」を使って少しずつ取得するのが一般的です。
途中でプロセスが落ちたり、APIがレート制限(短時間のリクエスト数上限)を返したりすると、同期が中断します。ここで問題になるのが、中断地点を正しく復元できるかどうかです。
復元に失敗すると起きる事象は大きく2つあります。1つは同じレコードを何度も取り込んでしまう重複。もう1つは、取りこぼしたまま次のカーソルに進んでしまい、永久に欠落するデータです。
後者は特に厄介です。エラーも出ず、ログ上は「正常に同期完了」と見えるため、検知が遅れます。数週間後にレポートの数値が合わないと気づいて初めて発覚するケースも想定されます。
なぜ起きるか
原因を段階的に分解すると、3つの層があります。
1つ目は状態(state)の永続化が不十分という問題です。カーソルやオフセットをプロセスのメモリ上にしか持たず、ディスクやデータベースに書き出していないと、プロセス再起動で状態が消えます。
2つ目はリトライ処理とカーソル更新の順序の問題です。典型的な実装では、ページを取得してからカーソルを次に進めます。この間でプロセスが落ちると「取得はしたが状態保存前に落ちた」状態になり、再開時に同じページを取り直すか、逆に飛ばすかが実装次第でブレます。
3つ目は指数バックオフ(リトライ間隔を指数関数的に伸ばす方式)の再試行回数に上限がないケース、あるいは上限到達時の挙動が「例外を投げて終了」だけになっているケースです。一時的なレート制限なのか、恒久的なAPI仕様変更なのかを区別せずに同じリトライを繰り返すと、同期ジョブ全体がタイムアウトし、SLO(サービスレベル目標)の「鮮度(データがどれだけ最新か)」を満たせなくなります。
状態管理にPydantic(Pythonのデータ検証ライブラリ)のようなスキーマ定義ツールを使っていても、スキーマが正しいだけで永続化のタイミングが誤っていれば、同じ問題は再発します。型安全性と再開の正しさは別の話です。
自分のプロジェクトが該当するか確認する
まず、同期処理のコードで状態保存のタイミングを確認します。
# 状態保存(state保存)の呼び出し箇所を grep で洗い出す
grep -rn "save_state\|load_from_state\|checkpoint" ./connectors/次の3点をコード上で確認してください。
- カーソル更新とページ内アイテムのyield(呼び出し元への値の受け渡し)が、同一トランザクション的に扱われているか
- 状態の永続化先がプロセス内メモリだけでなく、ファイルやDB・Redisなど外部ストレージになっているか
- リトライのmax_retries到達時に、アラートやログだけでなく後続処理が安全に止まる設計になっているか
さらに、実際に障害を模したテストで確認するのが確実です。同期処理を途中(たとえば3ページ目取得後)で強制終了し、再起動後に4ページ目から正しく再開するか、重複や欠落がないかを検証します。
オブザーバビリティ(システム内部の状態を外部から観測できるようにする設計)の観点では、同期ジョブごとに「処理した件数」「最終カーソル値」「リトライ回数」をメトリクスとして出力しているかも確認ポイントです。これらが可視化されていないと、重複や欠落が起きても気づく手段がありません。
対策の手順
1. 状態保存とカーソル更新をアトミックにする
ページ取得直後ではなく、アイテムをすべて処理(DBへの書き込みなど)し終えた後に状態を保存します。処理とyieldの順序を見直し、状態ファイルへの書き込みは一時ファイル経由のリネームなど、途中で壊れない方式にします。
2. 外部ストレージに状態を永続化する
import json
from pathlib import Path
def save_state(state: "ConnectorState", path: str = "sync_state.json"):
tmp_path = Path(path + ".tmp")
tmp_path.write_text(state.model_dump_json())
tmp_path.replace(path) # アトミックなリネームで上書きクラウド環境であれば、ローカルファイルよりもS3やCloud Storage、あるいは専用のKVS(キーバリューストア)に保存するほうが、コンテナ再起動やポッドの入れ替わりに強くなります。Terraformなどのインフラコード(IaC)でコネクタ基盤を構築している場合は、状態保存先のストレージリソースも同じリポジトリで宣言的に管理しておくと、環境ごとの設定漏れを防げます。
3. リトライに上限と分類を設ける
一時的なエラー(429や503)と恒久的なエラー(401や404)を区別し、恒久的なエラーは即座に停止してアラートを出します。max_retries到達時はジョブを失敗として明示的にマークし、次回同期を人手または自動で判断できるようにします。
import time
def fetch_page_with_backoff(fetch_fn, max_retries=5):
for attempt in range(max_retries):
try:
return fetch_fn()
except RateLimitError:
time.sleep(2 ** attempt)
except AuthError:
raise # 恒久的エラーは即座に伝播させる
raise MaxRetriesExceeded("Sync failed after retries")4. 重複・欠落を検知する仕組みを入れる
取得件数とAPI側の総件数(あれば)を突き合わせるチェックや、取り込んだレコードIDのユニーク数を監視ダッシュボードに出すことで、重複や欠落を早期に検知できます。障害対応の仕組み化という観点では、これを手動確認ではなくアラートルールとして定義しておくことが肝心です。
まとめ
SaaSコネクタのcheckpoint設計は、一見単純なページネーション処理に見えて、障害時の再開正しさがそのままデータ品質に直結します。
確認すべき点を整理すると次の3つです。
- 状態保存とカーソル更新の順序が、処理完了後になっているか
- 状態の永続化先がプロセス外の安全なストレージになっているか
- リトライの上限到達時やエラー種別ごとの挙動が明示されているか
まずは手元のコネクタで grep によるコード確認と、強制終了からの再開テストを一度試してみてください。小さな検証から、同期の信頼性を具体的に点検できます。