catalog_itemsまたはcatalog_selection_itemsタグで保存した値を参照します。
操作できるリソース
ベースURLはhttps://api.notifly.techです。カタログのパスはプロジェクトごとに分かれています。
- データソースが
apiである。 - データ分類が
non_personalである。 - ステータスが
activeである。
カタログの検索には一覧取得を使います。カタログの単件取得や、名前、説明、スキーマ全体の変更には対応していません。フィールド名や型を変える場合は、新しいフィールドを追加して値を移行します。セレクションは作成と削除に対応しています。一覧取得、単件取得、更新はできません。
リクエストとレスポンスはJSON形式です。CSVをインポートまたはエクスポートする公開エンドポイントはありません。カタログを削除する前に、参照しているメッセージとバックアップを確認してください。カタログに
DELETEを実行すると、データと同期履歴が完全に削除されます。
認証する
Access KeyとSecret Keyを/authenticateに送信して、APIトークンを発行します。カタログへのリクエストには以下のヘッダーを指定します。
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件を送信できます。
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からカタログを移行する
認証、レスポンス、ステータスコードの違いと移行手順を確認します。
