連携処理が正常に応答しても、2つのシステムに異なるデータが残ることがあります。外部システムが変更を保存した後にリクエストがタイムアウトする場合や、イベントの到着が遅れる場合、あるいはローカルでの更新によって、相手側のシステムも管理する項目が変更される場合があります。そのため、イベントを同期するだけでなく、状態を比較し、意図をもって不一致を解消できることが重要です。
PHPによるシステム間のデータ照合とは、関連するレコード間の差異を特定し、その意味を判断して、対応を提案または実行する定期的あるいはオンデマンドの処理です。一方のシステムの内容を無差別に他方へコピーすることではありません。有効な情報を失わないためには、データごとの正とするシステムを定義し、比較の根拠を保持し、修正の重複実行や大量適用からアプリケーションを守る必要があります。
比較の前にシステムごとの権限を定義する
エンティティ全体で単一の正とするデータソースが決まっているとは限りません。たとえば、CRMが商号や連絡先を管理し、請求システムが支払い状況や検証済みの納税者番号を管理する場合があります。項目を確認せずに一方のシステム全体を正とすると、照合によって正しい情報が古い、または不完全なコピーで置き換えられるおそれがあります。
連携する項目の管理主体を文書化しましょう。各項目について、変更を起点にできるシステム、競合時に優先するシステム、nullを許容するか、許容される変換を記録します。また、編集可能な項目と派生項目を区別することも重要です。たとえば計算済みの合計値はコピーするのではなく、構成要素から再生成する必要があるかもしれません。
- 項目ごとの権限: 値を決定するシステムと、両方のシステムで変更があった場合の対応を定義します。
- 統合ルール: 既存の値を置き換えずに、欠けているデータを補完できるか指定します。
- 例外: 承認、追加検証、または担当チームの介入が必要な競合を明示します。
安全なルールがない場合は、競合をレビュー対象としてマークするのが適切です。最も新しい日付のレコードを恣意的に選んではいけません。時計にはずれがある場合があり、タイムスタンプだけでは変更が正当なものだとは証明できません。
再現可能な比較を行う
有用な比較には、両側で同じレコードを特定する仕組みが必要です。双方で共有する安定した識別子、または明示的に管理された対応表を使いましょう。変更、重複、正規化の違いが生じる可能性のある名前、メールアドレスなどの項目だけに依存してはいけません。一意に対応づけられない場合は、近似的にレコードを統合せず、紐付け待ちとして分類します。
文書化されたルールに従って値を正規化してから比較します。たとえば、空白、大文字・小文字、日付形式などが対象です。ただし、比較のために正規化しても、永続化されたデータを変更してよいことにはなりません。元の値も保持してください。タイムゾーン、小数の精度、空の値、項目が存在しない状態と項目が存在して値がnullの状態には注意が必要です。これらを同等に扱うと、重要な変更を見落とす可能性があります。
大規模なデータセットでは、処理対象の期間と、更新日時やページネーションカーソルなどのウォーターマークを定義します。バッチが一貫した状態で処理された場合にのみ、進捗地点を保存してください。プロバイダーが信頼できるマーカーを提供しない場合、APIが保証していない増分処理を装うより、頻度を下げた全件走査や、サンプリングと対象を絞った照合の組み合わせのほうが安全な場合があります。適切な方法は、各システムの制限、安定性、実際の保証内容によって異なります。
PHPでは、データ取得、比較、結果の永続化を分離します。たとえば比較関数に、正規化した2つのデータ表現を渡し、型付きの差異リストを返すようにできます。リモート呼び出しやレコード更新は実行しません。この分離により、制御されたケースでルールをテストし、書き込みを有効にする前に提案内容を確認できます。
不一致を分類し、対応を決める
すべての差異がエラーを示すわけではなく、分類ごとに異なるポリシーが必要です。明確に分類することで診断しやすくなり、異なる状況に単一の破壊的なルールが適用されるのを防げます。
- 欠落: 一方のシステムにレコードがあり、他方にはありません。新規作成、正当な削除、フィルター、ページネーションの失敗のいずれかを確認します。
- 重複: 複数のレコードが同じエンティティに対応するように見えます。検証可能な識別ルールなしに、自動で1件を選ばないでください。
- 両立しない変更: 両方のシステムが、双方の管理対象である項目を変更しています。管理権限のポリシーを適用するか、競合をレビューに回します。
- 無効なデータ: 値が想定された形式や制約を満たしていません。隔離し、他のシステムへ伝播しないようにします。
- 時間差: 配信や処理の遅延によって差異が生じている可能性があります。継続的な競合と判断する前に、定めた期間待つか再試行します。
差異の検出、対応の決定、変更の適用という3つの段階を分けます。提案される対応には、項目の更新、関連付けの作成、レビュー依頼、何もしないことなどがあります。各段階を分けておけば、まず読み取り専用モードで開始し、自動修正を有効にする前に変更内容を把握できます。
新たな問題を生まずに変更を適用する
明確で検証可能なルールで対応できるケースだけを自動化します。それ以外のケースには、エンティティ識別子、観測された値、適用されるルール、提案された対応を含むレビューキューを用意します。画面または運用プロセスで提案を承認、却下、エスカレーションできるようにし、必要に応じて判断者も記録します。
同じ不一致を再処理しても重複が作成されたり、値が際限なく切り替わったりしないよう、操作を冪等に設計します。書き込み前に、レコードが想定した状態のままか確認してください。読み取り後に変更されていた場合は更新を中止し、再比較します。外部APIが対応している場合は、バージョン、条件付き書き込み、冪等性キーを使います。確認せずに利用できると思い込んではいけません。
小さなバッチ、実行ごとの変更数の上限、一時停止オプションで適用範囲を制限します。想定した件数を超える修正は、黙って続行させず停止するか、承認を必要とするようにします。影響の大きい変更では、補償操作の実行可能性を記録します。ただし、後続の変更や取り消せない外部への影響があり得るため、確実に元へ戻せる保証として示してはいけません。
調査と再実行のために各実行を記録する
実行ID、開始・終了時刻、処理した範囲またはカーソル、照会したシステム、カテゴリ別の結果、エラーを保存します。不一致ごとに、相関キー、関連する値または保護された表現、評価したルール、提案した対応、適用結果を保持します。これにより、判断の理由を説明し、連携処理の失敗と実際の競合を区別できます。
ログを保護してください。個人データ、間接的な認証情報、商業情報が含まれる可能性があります。必要な項目だけで済む場合はペイロード全体の出力を避け、アクセスを制限し、保持期間を定めます。管理されていない第2のデータベースにログをしてしまわないようにしつつ、調査を容易にするため、元レコードへの参照と観測時刻も含めます。
一時的な障害のみを、回数制限と待機時間の段階的な延長を設けて再試行します。再試行を記録し、無効なデータや権限不足などの恒久的なエラーは分離して、同じ問題を繰り返すループを防ぎます。実行は、PHPプロセスを無期限に稼働させることに依存せず、明確な基準で再開できなければなりません。
自動化の前に確認するチェックリスト
- 項目ごとの権限と、nullおよび削除の扱いが定義されていますか？
- 識別子でレコードを曖昧さなく紐付けられ、重複にも対処できますか？
- ページネーション、遅延、API制限、再試行、同時変更をテストしましたか？
- 差異が分類され、例外がレビューまたは隔離に回されますか？
- 読み取り専用モードで比較を実行し、提案する対応を表示できますか？
- 書き込みは冪等で、想定状態を条件とし、件数が制限されていますか？
- データ保護と適切なアクセス制御のもとで、判断と結果を記録していますか？
- 競合、空の値、重複、部分的な障害を含む、実データを代表するデータでテストしましたか？
修正ではなく、まず観察と分類から始めましょう。実データでルールを検証し、提案内容を確認してから、リスクの低い不一致だけを自動化します。一時停止できる手段を維持し、誤検出、未解決のケース、外部システムの変更を定期的に確認してください。これにより照合は、誰かが影響に気づくまで競合を隠す同期処理ではなく、繰り返し実行できる運用上の制御になります。
