メインコンテンツへスキップ
Catalog REST APIでは、商品やコンテンツなどの参照データをスキーマと一緒に管理できます。メッセージでは、Liquidのcatalog_itemsまたはcatalog_selection_itemsタグで保存した値を参照します。
カタログには個人を特定できない参照データだけを保存します。カタログの作成時は、data_classification: "non_personal"を指定してください。ユーザーID、メールアドレス、電話番号、デバイストークンなど、個人を特定できる値はフィールドやアイテムに含めないでください。

操作できるリソース

ベースURLはhttps://api.notifly.techです。カタログのパスはプロジェクトごとに分かれています。
公開APIで読み取りや変更ができるのは、以下の条件をすべて満たすカタログです。
  • データソースがapiである。
  • データ分類がnon_personalである。
  • ステータスがactiveである。
Googleスプレッドシートを使うカタログは、公開REST APIの一覧には表示されません。データソースと同期はコンソールで管理します。 カタログの検索には一覧取得を使います。カタログの単件取得や、名前、説明、スキーマ全体の変更には対応していません。フィールド名や型を変える場合は、新しいフィールドを追加して値を移行します。セレクションは作成と削除に対応しています。一覧取得、単件取得、更新はできません。 リクエストとレスポンスはJSON形式です。CSVをインポートまたはエクスポートする公開エンドポイントはありません。カタログを削除する前に、参照しているメッセージとバックアップを確認してください。カタログにDELETEを実行すると、データと同期履歴が完全に削除されます。

認証する

Access KeyとSecret Keyを/authenticateに送信して、APIトークンを発行します。カタログへのリクエストには以下のヘッダーを指定します。
APIトークンの有効期間は、デフォルトで1時間です。期限が切れて401が返った場合は、トークンを再発行してからリクエストを再送します。認証の詳細はAPIの概要を参照してください。

カタログを作成してアイテムを取得する

1. カタログを作成する

1回のリクエストでカタログを1つ作成します。fieldsの最初の要素に、string型のidを定義してください。
フィールドの型にはstring、number、boolean、time、geo、object、arrayを指定できます。
  • timeには、ISO 8601形式の文字列またはUnixエポックからの経過秒数(安全な整数の範囲内)を指定します。NotiflyはUTCのISO 8601形式で保存します。
  • geoには、有限の数値を[経度, 緯度]の順に指定します。経度は-180から180、緯度は-90から90の範囲です。
  • arrayには文字列の配列を指定します。

2. アイテムを追加する

アイテムをまとめて作成するには、POST /itemsを呼び出します。1回のリクエストで最大50件を送信できます。
スキーマに合わないアイテムが1件でもあると、リクエスト全体が失敗します。その場合、アイテムは1件も保存されません。

3. 次のページを取得する

GET /itemsはアイテムをIDの昇順で50件ずつ返します。次のページがある場合、レスポンスにdata.next_cursorとLink: <...>; rel="next"ヘッダーが含まれます。
  • data.next_cursorの値を変更せず、次のリクエストのクエリパラメーターcursorに指定します。
  • nullが返った場合は、そのページが最後です。

セレクションのフィルター

セレクションには、メッセージで繰り返し使用するカタログアイテムの一部を保存できます。 フィルターの値にnullは使えません。sort_fieldを指定する場合は、sort_orderも指定します。results_limitのデフォルトは50件です。並べ替えを指定しない場合、セレクションの作成時にresults_limitで指定した件数を上限として、アイテムを無作為に選びます。

書き込みメソッド

配列フィールドの値を一部だけ追加、削除する例です。
アイテムの一括書き込みやフィールド、セレクションの変更に成功すると200が返ります。カタログや単一アイテムを作成すると201が返ります。

レスポンスとエラー

Catalog APIは以下の形式でレスポンスを返します。
エラーの場合、dataはnullになり、error.codeとerror.messageが返ります。入力検証のエラーでは、対象のフィールドやパスを含むerror.detailsが返る場合があります。
  • 400の場合は、プロジェクトIDの形式、スキーマ、フィールドの値を修正してから再送します。
  • 401の場合は、APIトークンを再発行します。
  • 403の場合は、プロジェクトIDとアクセス権限を確認します。
  • 404の場合は、カタログ、フィールド、アイテム、セレクションの名前を確認します。
  • 409の場合は、既存リソースとの重複や状態の競合を確認します。利用できる一覧または取得操作で確認するか、呼び出し側の処理記録を参照します。
  • 413の場合は、4 MiB未満に分割して送信します。
  • 500やタイムアウトでレスポンスを受け取れない場合、POSTは一覧または取得操作で反映済みのリソースを確認してから、未反映のものだけを再送します。アイテム全体を安全に何度も適用できる場合は、PUTを使用します。再試行までの間隔は指数バックオフで延ばし、ランダムな待機時間を加えます。
一括移行では、1回に最大50件のアイテムを送信します。大量の書き込みを継続する場合は、必要な処理量を事前にNotiflyと確認してください。Brazeのエンドポイントに適用される共有レート制限枠に相当する公開仕様は、Catalog APIにはありません。

主な上限

objectフィールド内のキーには.や$を使用できません。$addと$removeは、配列フィールドをPATCHする演算子として使用できます。

Catalog APIの操作一覧

カタログ、アイテム、フィールド、セレクションのリクエストとレスポンスのスキーマを確認します。

Brazeからカタログを移行する

認証、レスポンス、ステータスコードの違いと移行手順を確認します。