このページの内容
注文の更新が作成の出来事より先に届きます。別の場所では、支払いの出来事がそれ以前のサブスクリプションのイベントより先に届きます。ここに登場するチームは、違う製品と内容を使う例示です。どちらも到着時刻で並べ替えて解決したくなります。
これは両チームで起きた事故の報告ではありません。提供元の詳細は違っても、失敗の形が共通かを問う例です。
数学的なつながりについての対話は、見た目の違う問題が有用な形を共有することがあると述べます。この考えをソフトウェア連携に当てるのは推論です。共通の形から、各システムの文書化された振る舞いに支えられるテストを作れる場合にのみ役立ちます。
名前を外し、契約を戻す
最初の事例を製品名なしに説明します。ある資源についての出来事が、同じ資源の後の変更より遅れて届くことがあります。受け取る側が到着順を状態の順と見なすと、新しい情報を古い情報で上書きします。
ここで実際の二つの契約を調べます。Shopify のWebhook文書は、同じトピックのイベントでも順序は保証されず、商品の更新が作成通知より先に届く例を示します。Stripe のWebhook文書も出来事が生成順に届く保証はないとし、先に期待した出来事がまだ届かない場合には欠けたオブジェクトを取得するよう勧めます。
Shopify と Stripe は、出来事の配達順が保証されないと説明します。共通の問いは最終状態が正しいかどうかです。識別子と復旧ルールは提供元ごとに試します。
移せる問いは、「関連する出来事より先にこれが届いても、正しい現在の状態を導けるか」です。実装上の答えは、仮定だけでは移せません。Shopify は X-Shopify-Webhook-Id などのヘッダーと時刻を文書化しています。Stripe には固有の出来事 ID とオブジェクトの取得ルールがあります。あるシステムで「配達」を意味する識別子が、別のシステムでも同じ意味とは限りません。
Brevo コネクターガイドは、フィールドと対応付けの別の詳細を扱います。動く連携には必要ですが、普遍的な API の振る舞いと取り違えてはいけません。
共通の形は守るべき状態
顧客同期なら、守るべき状態は「処理後、送信先の顧客レコードが許可されたソースの現在の状態を反映する」かもしれません。請求なら「支払いに依存する行動は、権威ある支払い状態が許すときだけ起こる」かもしれません。出来事が遅れ、重複し、不完全でも何が正しくなければならないかを定めます。
修正方法を選ぶ前に四つを書きます。
| 問い | 重要な理由 |
|---|---|
| どの識別子が業務上のオブジェクトを指すか | 出来事 ID は顧客や注文でなく、通知一件を指すかもしれません。 |
| どのシステムが現在の状態を持つか | 内容は状態の写し、変更、または参照先だけかもしれません。 |
| 元のシステムが保証する時間の順序は何か | 配達順と状態の順は違い得ます。 |
| 成功を証明する事後条件は何か | 出来事の受信では送信先が正しいと証明できません。 |
この表は考える助けであり、通信の仕様ではありません。正本はワークフローによって変わります。あるシステムでは現在状態の照会が必要でも、別では適切でないかもしれません。いくつかの出来事は最新の状態に畳むのでなく、履歴上の事実として残すべきです。
テストを再利用し、対処法を合わせる
小さな契約テストでは、関係する出来事を逆順に送り、最終的な送信先の状態が正しいかを問えます。同じ配達を二度送るテストもできます。リスクの形をあぶり出した後、各出来事の識別、検証、復旧の方法は提供元の文書から決めます。
この区別は、構造をそのままコピーするのを防ぎます。ある API の重複排除キーは、別では失敗するかもしれません。精度の粗い時刻では順序を決められないかもしれません。現在のオブジェクトの取得は状態同期には必要でも、途中の歴史的な出来事をすべて再現できるとは限りません。複数の業務ツールの連携ガイドは各フィールドの所有者を決めるところから始めます。それなしでは「最新」の意味も不明です。
パターンを移すことには限界があります。似た症状でも原因は違い得ます。レコードの欠落は、未許可の照会、遅れたWebhook、不正な対応付け、拒否された書き込みのいずれかかもしれません。二つの事例を同一視する前に、元と送信先の契約、観測された事後条件を比べます。違いがあれば共通の問いだけ残し、テストを変えます。
この方法は出来事の配達以外にも役立ちます。API がフィールドを受け入れたのに、画面上のレコードにない場合、どのコネクターでも一般的な問いは同じです。受理は何を証明し、意図した状態は何で証明できるか。答えには送信先の読み取り、スキーマの照会、権限確認が必要かもしれません。パターンは転送と意味を分けるよう促しますが、呼び出すべきフィールドや操作は教えません。この控えめな教訓は、各システム固有の事実を見えるように保つからこそ、広く使えます。
最も再利用しやすい教訓は処理コードの断片ではありません。別のシステムに移しても残り、その場所の契約を調べやすくする問いです。
よくある質問
同じ連携テストを提供元間で再利用できますか？
更新が順不同で届くかなど、問いは移せることがあります。しかし出来事 ID、内容の意味、署名、復旧手順はそれぞれの提供元の契約から得なければなりません。
パターンとコピーした修正の違いは何ですか？
パターンは失敗条件と守るべき状態を名指しします。コピーした修正は、二つ目のシステムの識別子、順序、状態の意味が同じだと確かめずに仮定します。
出来事を適用した後は何を確認しますか？
受信や HTTP 応答だけでなく、ワークフローが必要とする送信先の状態を調べます。事後条件は業務オブジェクトと正本のルールによります。