主な違いを確認する
エンドポイントを変更する
Braze のパスの前に、Notifly のプロジェクトプレフィックスを追加します。catalog_name、item_id、field_name は、Notifly では catalogName、itemId、fieldName と表記します。実際の URL の値と役割は同じです。
カタログ
アイテム
PUT は、送信したアイテムの値をすべて置き換え、アイテムが存在しなければ作成します。PATCH は、既存アイテムの送信したフィールドのみを変更し、存在しない ID に対しては 404 を返します。配列フィールドでは、Braze と同じ $add、$remove 操作を使用できます。
フィールドとセレクション
Notifly のセレクション作成リクエストでは、Braze の
external_id と source を削除します。フィルター値に null は使用できません。フィールドの型ごとに使用できる演算子は、セレクションのフィルターを参照してください。
認証コードを変更する
Braze の REST API key をリクエストごとに送信する代わりに、Notifly の/authenticate で認証トークンを発行し、再利用します。トークンの有効期間は 1 時間です。
本番コードでは、リクエストごとにトークンを発行せず、有効期限が切れるまでメモリにキャッシュしてください。
Access Key、Secret Key、トークン、認証レスポンスの本文はログに記録しないでください。
詳しくは、APIの概要を参照してください。
カタログ作成リクエストを変換する
Braze のcatalogs[0] オブジェクトに data_classification を追加します。フィールドの順序を維持し、先頭のフィールドが id:string であることを確認してください。
- フィールドが 500 を超える場合は、不要なフィールドを削除するか、カタログを分割します。
- カタログとフィールドの識別子、およびアイテム ID は最大 250 文字です。英大文字、英小文字、数字、ハイフン、アンダースコアのみ使用できます。
array値は文字列の配列で、要素数は最大 100 です。geo値は[longitude, latitude]の順序です。time値は ISO 8601 文字列または Unix 秒です。保存時に UTC の ISO 8601 文字列に正規化されます。objectのキーには、ピリオド(.)とドル記号($)を使用できません。- 文字列の値は最大 5,000 文字、アイテム 1 件は最大 1 MiB です。
レスポンス処理を変更する
成功レスポンス
Braze でアイテムを 1 件作成すると、次の成功メッセージが返されます。data に返します。
response.message === "success" または status === 202 のみを確認している場合は、response.error === null と、エンドポイントごとの成功ステータス 200 または 201 を確認するように変更してください。
エラーレスポンス
Braze のerrors[] を解析するコードを、Notifly の error.code、error.message、任意の error.details を読むコードに変更します。
error.code に基づいて処理してください。details がある場合は、field または path で不正な入力箇所を特定できます。
ページネーション
両 API とも、1 ページで最大 50 件のアイテムを返します。Notifly は、次のカーソルをレスポンス本文とLink ヘッダーの両方で返します。
Link ヘッダーをたどるコードは、引き続きヘッダーを使用できます。新しく実装する場合は、data.next_cursor が null になるまでページを取得する方法も使えます。カーソルは API の内部形式のため、解釈したり、自分で生成したりしないでください。
データを移行する
1. Braze の資産を調査する
最初に、次の情報を記録します。- カタログ名、説明、フィールドの順序と型。
- アイテム数とデータの総容量。
- メッセージで使用している
catalog_itemsとcatalog_selection_itemsの Liquid タグ。 - セレクション名、フィルター、並び順、取得件数の上限。
- カタログを使用するバッチジョブ、Webhook、運用ツール、API key の権限。
- フィールド数が
idを含めて 500 以下で、JSON のネストが 50 階層以下であるか。 - object のキーに
.または$がないか、個人を識別できる情報が含まれていないか。
2. Braze のアイテムをエクスポートする
GET /catalogs/{catalog_name}/items を呼び出し、Link ヘッダーから rel="next" がなくなるまで、50 件ずつ取得します。エクスポートした JSON とアイテム数は、変更前のデータを確認できる原本として保管してください。
移行ファイルは暗号化されたストレージに保存し、作業担当者には必要最小限のアクセス権だけを付与します。保管期間を決め、検証とロールバックの期間が終了したら削除してください。個人を識別できる情報が見つかった場合は、移行を中断し、ファイルを隔離します。該当フィールドを削除するか、ユーザー属性に分離してから移行を再開してください。ファイルの内容や認証情報を、チケット、チャット、アプリケーションログに貼り付けないでください。
3. Notifly のカタログを作成する
Braze のカタログ定義にdata_classification: "non_personal" を追加し、POST /v1/projects/{projectId}/catalogs で作成します。同じ名前で再作成すると競合するため、再実行する前にカタログがすでに作成されていないか確認してください。
4. アイテムをインポートする
移行が完了するまでは、Braze を正本として扱います。エクスポートしたアイテムを最大 50 件ずつに分け、リクエスト本文が 4 MiB に近づく場合は、さらにバッチを小さくします。 全件コピーを繰り返す必要がある場合は、一括PUT /catalogs/{catalogName}/items を使用してください。同じ ID のアイテムは全置換し、存在しない ID は新規作成します。新規アイテムだけを許可し、重複をエラーにする必要がある場合に限り、POST を使用してください。
バッチごとに、カタログ名、メソッド、ソート済みのアイテム ID、アイテム数、リクエスト本文のハッシュ、開始時刻と完了時刻、結果ステータスをチェックポイントに記録します。1 リクエスト内の変更はトランザクションとして処理されるため、200 レスポンスを受け取ってから完了として記録してください。
レスポンスを受信できなかった場合や 500 が返された場合は、同じ POST をすぐに再送しないでください。単件の GET /items/{itemId} でバッチ内のアイテムが反映済みか確認し、未反映のアイテムだけを再送します。PUT は、リクエスト本文全体を再適用できます。再試行には、ランダムな待ち時間を加えた指数バックオフを使用し、次のように処理してください。
401の場合は、認証トークンを再発行してから再試行します。- ネットワークタイムアウトまたは
500の場合は、反映状況を確認してから、回数を制限して再試行します。 400、403、404、409、413の場合は、入力、権限、対象リソース、重複、バッチサイズを修正するまで自動再試行しません。
5. セレクションを再作成する
アイテムの読み込みが完了したら、調査時に記録したセレクションをPOST /catalogs/{catalogName}/selections で 1 件ずつ作成します。Braze のリクエストから external_id と source を削除し、フィールドの型ごとの演算子規則と null の制限を適用してください。
200 レスポンスを受け取った後、セレクション名とリクエストのハッシュをチェックポイントに記録します。Notifly の公開 API には、セレクションの一覧取得や更新のエンドポイントがありません。タイムアウトで結果が不明な場合は、まずそのセレクションを使用する Liquid をテストし、存在するか、期待どおりの結果が返るかを確認してください。定義が誤っている場合に限り、影響範囲を確認したうえで DELETE し、再作成します。
その後、アイテムやフィールドを変更すると、保存済みのセレクション結果は同じリクエスト内で再計算されます。
6. 移行結果を検証する
- Notifly の
GET /catalogsが返すnum_itemsと、Braze からエクスポートしたアイテム数が一致することを確認します。 - すべてのページを再取得し、ID の集合、リクエスト本文のハッシュ、主要フィールドの値を比較します。
- メッセージのプレビューで、本番で使用している Liquid を実行します。
- 存在しない ID、空の配列、
null、ハングル、絵文字、time、geo、object、array の値など、境界ケースを確認します。 - セレクションごとのアイテム数と並び順を比較します。並び順を指定していないセレクションの結果はランダムなため、同じ順序になることは期待しないでください。
- 未解決のバッチやセレクションのチェックポイントが残っていないことを確認します。
7. 呼び出し先を切り替える
- 読み取りとメッセージのレンダリングには、引き続き Braze を使用します。書き込みは先に Braze に適用し、同じ変更を Notifly に送信します。Notifly への書き込みに失敗した場合は、再処理キューに記録します。
- 事前に決めた観察期間中に、アイテム数、ハッシュ、主要な値、セレクション結果、API エラーを比較します。
- 不一致と未解決の再処理がなくなったら、読み取り先とメッセージの Liquid を Notifly に切り替えます。
- 切り替え後に不一致、継続的な API エラー、Liquid のレンダリングエラーが発生した場合は、読み取り先を Braze に戻します。Notifly のみに対する書き込みを停止し、チェックポイントから再同期します。
- ロールバック期間が終了し、両システムの一致が続いていれば、Braze への書き込みを停止します。
- Braze Catalogs の削除は、別途承認を得て、バックアップを確認してから実行します。
