APIによるデータ同期

1）同期が必要な理由と目標は何ですか

ドメインの一貫性：プロファイル、ウォレット、ディレクトリ、制限、KYC。
ラグを下げる：重要なプロセス（支払い、ボーナス）のほぼリアルタイム。
レジリエンス：イベントの損失なしにネットワーク/プロバイダの停止を経験しています。
経済学：デルタおよび包装化によって出口/CPUを最小にして下さい。

成功指標：ソースと消費者の間の遅延、鮮度、重複の割合、競合の割合、GB/時間の青色のコスト。

2）同期モデル

2.1プル（ポーリング）

クライアントは間隔で変更を要求します。

長所：シンプルさ、負荷制御。
短所：遅延、「空」の世論調査、変化の高い割合でスキップのリスク。
改善：If-Modified-Since、 Etag/If-None-Match、 change_token。

2.2プッシュ（webhook/イベント）

ソースはイベントを受信者に流します。

長所：ほとんどリアルタイム、世論調査経済。
短所：リトレイ、重複排除、セキュリティ（署名、mTLS）での配信が必要です。
要件：idempotent消費者、指数関数的なバックオフ、再生。

2.3 CDC/ストリーミング（変更データキャプチャ）

トランザクションログ/イベントログ（Kafka、 Debezium）からの変更のスナップショット。

長所：完全性、順序、スケール。
短所：複雑さ、あなたは操作の種類を制御する必要があります（挿入/更新/削除/墓石）。

2.4ハイブリッド

Webhookは「トリガー」として、フォールバックとして、そして和解のためにポーリングします。

3）差分デルタ

3.1透かし（タイムスタンプ）

クライアントは'last_seen_ts'を格納し、'updated_at> watermark'を要求します。

リスク：時間のドリフト-UTCとNTPを使用します。1-2 minのオーバーラップウィンドウを取得し、ID+バージョンでデッドアップします。

3.2トークン/カーソルの変更

安定したシーケンストークン：'？cursor=eyJvZmZzZXQiOjEwMDB9'。

長所：順序、スケールを変える回復力。
要件：劣化していないカーソル、TTL、安全な再生。

3.3番号付きオフセット（自動増分）

'id> last_id'。シンプルですが、シャーディング時に分解し、シーケンスで「穴」を開けます。

4）大きいサンプルpagination

キーセット/カーソル（推奨）：'？after=cursor&limit=1000'-変更で安定。
オフセット/リミット-シンプルですが、高価でシフトの対象となります。
常に安定したソートキー（'（updated_at、 id）'など）を指定します。

json
{
"items": [ { "id": "u_1", "updated_at": "2025-11-03T16:59:10Z" } ],
"next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0xMS0wM1QxNjo1OToxMFoifQ==",
"has_more": true
}

5）セマンティクスの変更： upsert、 merge、 delete

5.1アップサート/マージ

'PUT/resource/{ id}'は完全な置換です。
'PATCH/resource/{ id}'-部分更新（検証でパッチをマージ）。
すべての書き込みに対して'Idempotency-Key'によるIdempotency。

5.2削除

ソフト削除（フィールド'deleted=true'、 'deleted_at'）-履歴を保存します。シンクは墓石を与える。
Hard delete-イベントが消える前に'deleted'を与えます。

json
{ "id":"u_1", "event":"deleted", "deleted_at":"2025-11-03T17:00:00Z" }

6）バージョン管理と競争

6.1 ETag/If-Match（楽観ロック）

"ETag：" v123"を返します。
"If-Match：" v123"からの更新-"lost updates"からの保護。
競合の場合-409 'error_code： "CONFLICT_VERSION"'と競合します。

6.2レコードのバージョン管理

フィールド'version'/'updated_at'-デルタ計算と重複除外。

6.3コンフリクト

ポリシー：last-write-wins、 server-wins、 merge-strategy by fields（例：sum→additive、 flags→source priority）。

7）順序および重複除外

7.1配達プロシージャ

保証：最低1回+idempotency→事実上の標準。
重要なキャッシュフローの場合は、idempotencyストアを通じて正確に1回の効果を発揮します。

7.2 Idempotenceキー

ドメインフィールドの構成：'source_id' event_type 'sequence'。
ストレージTTL 24-72時間（SLAでは以上）。

7.3重複除外

受信者に適用された最後のバージョン/seqを保存します。古いものをドロップします。

8）繰り返し、タイムアウト、バックオフ

取得可能：5xx/429/408/timeouts；取得不可：400/401/403/404/ 409/422/410/412。
指数関数バックオフ+ジッタ：1s、 2s、 4s……30-60年代に。
429/503の再試行後の尊重。
クライアントのタイムアウト：接続3-5s、一般的な要求10-30s；試行の合計制限3-6。

9） LagsおよびSLA制御

9.1 SLI/SLO

SLI Lag： 'consumer'と'applied in consumer'の間の中央値/p95 lag。

SLO： 例えば、'p95 lag ≤ 60s （28d）'、 "share of lost events=0"、 "share of duplicates ≤ 0。01%».

エラー予算：リリース/実験に費やす。

9.2メトリクス

'sync_lag_seconds'、 'events_received_total'、 'events_applied_total'、 'duplicates_total'、 'conflicts_total'、 'retries_total'、 'backlog_size'、 'cursor_advance_rate_rate_rate'。

10）和解とバックフィル

日/時間の調整：合計/ウィンドウのハッシュ値。
和解API： 'GET/和解？from=……&to=……チェックサムと分散を返す。
Backfill： DDOSソースなしで、カーソルを使用してバッチ内の履歴データを安全に再ロードします。限界を守れ。

11）スキームと例

11.1 Webhookイベント（署名済み）

json
{
"event": "user. updated",
"id": "evt_01HX",
"occurred_at": "2025-11-03T18:00:05Z",
"sequence": 123456,
"data": { "id": "u_1", "email": "a@b. com", "updated_at": "2025-11-03T18:00:02Z" }
}

• 'X-Signature： sha256='
• 'X-Event-Id： evt_01HX'
• 'X-Retry： 0。。 N'

11.2インクリメンタルサンプリング（ポーリング）

'GET/v1/users？updated_after=2025-11-03T17:58:00Z&cursor=...&limit=1000'

11.3 Idempotentアップサート

POST /v1/users
Idempotency-Key: upsert-u_1-20251103T1800Z
{ "id":"u_1","email":"a@b. com","version":124 }
→ 201/200 (stable)

12）安全性とコンプライアンス

Auth： OAuth2 スコープ/JWT；リンクチャンネル-mTLSオンデマンド。
キャプション：WebhookのためのHMACの見出し、回転秘密。
PIIの最小化、ログのマスキング；GDPR/DSARアップロード/削除。
RBAC/ABAC：テナント/組織へのアクセス、厳格なクォータ。

13） Observabilityおよびログ

「env」「、service」「、tenant」「、source」「、cursor」「、seq」「、event_type」。
相関：'trace_id'を入力→ログとトレースに適用します。
ダッシュボード：遅延、バックログ、カーソル速度、タイプエラー、429/5xx、コスト（egress/min）。

14） FinOps： 同期コスト

バッチ（バッチサイズ100-1000）+圧縮（gzip/br）。
変更されていないページのキャッシュとETag。
薄いペイロード：変更されたフィールドのみ、需要に応じて完全なリソースへのリンク。
バックフィルのための並行限界と「夜間窓」。

15）テストおよび質

15.1契約とマイナスのケース

JSONスキーム、必須フィールド、安定性'error_code'を検証します。
テスト：順不同、重複、イベントのスキップ、バージョン競合、429/5xx。

15.2カオス/ゲーム

注射：ネットワーク遅延、ドロップ10-30％イベントの、順序を変更します。。
基準：維持された順序/完全性か？損失はないのか？SLO内の遅延？

16）実装チェックリスト

• 選択したモデル（プッシュ/プル/ハイブリッド）と真実のソース。
• 差分デルタ：透かしまたはカーソル/トークン。
• ページネーション：安定したグレードのカーソル/キーセット。
• Idempotency-store、キーおよびTTL；dedup by '（id、 version/seq）'。
• ETag/If-Matchと競合ポリシー（LWW/server-wins/merge）。
• Retry/backoff/jitter、 respect 'Retry-After'。
• メトリクスlag/backlog/duplicates/conflicts、ダッシュボード、アラート。
• 和解API+毎日の和解。
• セキュリティ：OAuth2/JWT、 webhook署名、mTLS、 PIIポリシー。
• FinOps： batch+compression、 concurrency limits、 egress quotas。
• テストスイート：並べ替え、重複、停止、バックフィル。

17）実施計画（3つの反復）

1.MVP （1-2週）：

カーソルページネーション、透かしデルタ、idempotent upsert、基本的な遅延/バックログ、再試行+バックオフメトリクス。

2.スケール（2-3週）：

trigger+polling-fallback、 HMACシグネチャ、和解、ETag/If-Match、ダッシュボード、書き込みアラートなどのWebhook。

3.プロ（3-4週間）：

ホットドメイン用のCDC/ストリーミング （Kafka/Debezium）、自動バックフィル、DRスクリプト、FinOps最適化（batch/brotley）、遅延およびレポート用のSLA。

18） ミニFAQ

選択するもの：透かしまたはカーソル？
カーソル/キーセットは、並べ替えやスケールに耐性があります。ウォーターマークの起動は簡単ですが、オーバーラップとデッドアップを追加します。

それは正確に一度必要ですか？
一般的に、高価です。練習-少なくとも一度+idempotency；正確に一度-金銭的効果のためにのみ。

競合を最小限に抑えるには？
ETag/If-Matchを使用して、フィールドごとにデザインのマージを行い、「非表示」の副作用を避けます。

合計

信頼性の高い同期は、インクリメンタルデルタ+正しいペジネーション+独自性とバージョン制御であり、観測性、輝き、経済的な輸送によって強化されています。適切なモデル（プッシュ/プル/CDC）を選択し、遅延時にSLOをピン留め、競合ポリシーと汚れたシナリオテストを実装します。データ交換は予測可能で、持続可能で費用対効果が高くなります。