メインコンテンツへスキップ
Braze Catalogs と Notifly Catalogs は、カタログ、アイテム、フィールド、セレクションのパスとリクエスト構造がほぼ共通しています。ただし、ベース URL と認証、プロジェクトのパス、レスポンスのラッパー形式、同期処理と非同期処理のステータスコード、データ分類の宣言が異なります。URL を変更するだけでは移行できません。 このガイドは、2026 年 8 月 4 日時点の Braze 公式 Catalog API と Notifly Catalog REST API を比較しています。実際の移行時には、使用中の Braze クラスターの REST エンドポイントと、最新の Braze ドキュメントも確認してください。

主な違いを確認する

Braze に保存したデータに、氏名、メールアドレス、電話番号、外部ユーザー ID などの個人を識別できる情報がある場合は、そのまま移行しないでください。 Notifly の API カタログは、個人情報を含まない参照データのみをサポートします。

エンドポイントを変更する

Braze のパスの前に、Notifly のプロジェクトプレフィックスを追加します。
Braze のパスパラメーター 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 件作成すると、次の成功メッセージが返されます。
Notifly は、作成または取得したリソースを data に返します。
一括操作、フィールド操作、セレクション操作、削除のリクエストが成功すると、次の空の成功レスポンスが返されます。
既存のコードで response.message === "success" または status === 202 のみを確認している場合は、response.error === null と、エンドポイントごとの成功ステータス 200 または 201 を確認するように変更してください。

エラーレスポンス

Braze の errors[] を解析するコードを、Notifly の error.code、error.message、任意の error.details を読むコードに変更します。
エラーメッセージの文字列比較ではなく、HTTP ステータスと error.code に基づいて処理してください。details がある場合は、field または path で不正な入力箇所を特定できます。

ページネーション

両 API とも、1 ページで最大 50 件のアイテムを返します。Notifly は、次のカーソルをレスポンス本文と Link ヘッダーの両方で返します。
Braze の Link ヘッダーをたどるコードは、引き続きヘッダーを使用できます。新しく実装する場合は、data.next_cursor が null になるまでページを取得する方法も使えます。カーソルは API の内部形式のため、解釈したり、自分で生成したりしないでください。

データを移行する

1. Braze の資産を調査する

最初に、次の情報を記録します。
  • カタログ名、説明、フィールドの順序と型。
  • アイテム数とデータの総容量。
  • メッセージで使用している catalog_items と catalog_selection_items の Liquid タグ。
  • セレクション名、フィルター、並び順、取得件数の上限。
  • カタログを使用するバッチジョブ、Webhook、運用ツール、API key の権限。
  • フィールド数が id を含めて 500 以下で、JSON のネストが 50 階層以下であるか。
  • object のキーに . または $ がないか、個人を識別できる情報が含まれていないか。
Braze の公開 API には、セレクション一覧を取得するエンドポイントがありません。セレクションの定義は、Braze Dashboard と既存の設定を参照して確認してください。

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. 呼び出し先を切り替える

  1. 読み取りとメッセージのレンダリングには、引き続き Braze を使用します。書き込みは先に Braze に適用し、同じ変更を Notifly に送信します。Notifly への書き込みに失敗した場合は、再処理キューに記録します。
  2. 事前に決めた観察期間中に、アイテム数、ハッシュ、主要な値、セレクション結果、API エラーを比較します。
  3. 不一致と未解決の再処理がなくなったら、読み取り先とメッセージの Liquid を Notifly に切り替えます。
  4. 切り替え後に不一致、継続的な API エラー、Liquid のレンダリングエラーが発生した場合は、読み取り先を Braze に戻します。Notifly のみに対する書き込みを停止し、チェックポイントから再同期します。
  5. ロールバック期間が終了し、両システムの一致が続いていれば、Braze への書き込みを停止します。
  6. Braze Catalogs の削除は、別途承認を得て、バックアップを確認してから実行します。
移行中に Braze Catalogs を先に削除しないでください。Notifly のアイテム数、主要な値、Liquid のレンダリングを検証した後、 別の変更作業として削除してください。

Liquid を移行する

基本的な構文は同じため、カタログ名とフィールド名を維持していれば、多くの場合はそのまま使用できます。
Braze で :rerender の対象値に別の catalog_items または catalog_selection_items タグを含めている場合は、 移行前にそのタグを削除するか、1 階層に展開してください。Notifly は、再帰的なカタログタグをレンダリングエラーとして扱います。
Liquid の構文が共通していても、API レスポンスが同じという意味ではありません。Catalog REST クライアントの認証、URL、ステータスコード処理、レスポンスの解析は、前述の違いに合わせて個別に修正してください。

公式参考資料