取り込みで危険なのは、応答が返らなかったときです。クライアントがタイムアウトしても、サーバーでは提案の作成やマージが完了しているかもしれません。新しい要求として全件を再送すると、同じ業務データが重複する可能性があります。
復旧では、元の要求がどこまで進んだか、どの業務オブジェクトが存在するかを分けて確認します。要求の冪等キーと業務上の安定キーは、それぞれ別の役割を持ちます。
送信前にバッチ台帳を用意する
OpenAPIではbulk-change-requestのrecordsは最大1000件で、一つのChangeRequestとして提案されます。大きな取り込みは確認可能な単位へ分割するか、適切な専用取り込み手段を選びます。
Space、Base、送信者、元資料と内容ダイジェスト、業務キー、要求本文、idempotencyKey、返されたCR IDを残します。内容が変わった要求を元の要求と区別できることが重要です。認証情報は台帳に保存しません。
構造図・調整可能な設計
二種類のキーを使い分ける
一括作成のidempotencyKeyはBaseと送信者の単位で作用します。同じ範囲の同じキーによる再試行は元のCRを返します。ただし、Base全体の業務上の一意性を自動で保証する仕組みではありません。
業務の安定キーは、元システムにあるオブジェクト識別子などです。送信前に資料内の重複と既存レコードを確認し、復旧後も同じキーで一意性を検証します。表示名が同じかどうかだけで判断しません。
まず元のCRを探す
CR IDがあれば、そのCRの状態、操作、結果のレコードを読みます。応答を失った場合は、保存した元の本文、対象、冪等キーで元の送信を復旧します。並べ替えや編集後のバッチに古いキーを無条件で流用しないでください。
ChangeRequestのin_review、approved、mergedは異なる段階です。承認済みでもマージ済みとは限りません。正式レコードに見つからないことだけで、要求が未到達だったと断定するのも危険です。
構造図・調整可能な設計
バッチごとに完了を確認する
複数バッチを一つの横断的なトランザクションとは考えません。「応答不明」「CR作成済み」「審査待ち」「マージ済み」「再読確認済み」など、各バッチの状態をAgentやスクリプトで管理します。これは推奨する台帳設計です。
前半が完了して後半が不明なら、不明なバッチから確認を再開します。表を空にしたり、全ファイルを新しいキーで再送したりしません。最後に業務キーごとのレコード数と必須項目を再読し、不足、重複、矛盾を列挙します。
既存の対象は現在のバージョンを読んで更新する
既に存在するオブジェクトはcreateで増やさず、recordIdと現在のbaseCommitIdを使って更新します。fieldsは変更部分に限定します。省略項目は維持され、nullは消去を意味するため、元資料の未入力を一律にnullへ変換しません。
write権限なら即時マージされる場合があり、提案専用権限なら審査を待ちます。人の確認が必要な経路は明示的に維持します。再試行は、同時更新の上書きや審査回避の許可にはなりません。
構造図・調整可能な設計
再開可能な成果物をAgentへ求める
次の指示を接続済みAgentへ渡せます。
指定Baseの取り込み台帳を作り、業務キーを事前に照合してください。各バッチの元本文、個別の冪等キー、CR IDを保存します。タイムアウト後は元CRと正式レコードを確認し、未確認バッチに依存する作業を止めてください。マージ後はキーごとの件数と必須項目を再読し、不足、重複、矛盾、残バッチを報告してください。
代表的な少量の資料で、送信、審査、再読、中断復旧を通して確認してから拡大します。REST APIガイドで接続と権限を確かめ、アップロード完了メッセージに加えて、台帳と原提案、検証結果を残してください。