> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifly.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# カタログ

> 商品や店舗などの共通データをカタログに登録し、Liquidでメッセージに差し込む手順です。

カタログに、商品や店舗、コンテンツなどの共通データを保存できます。アイテムIDを指定すると、外部APIを別途呼び出さずに、必要な値を取得してメッセージに差し込めます。

氏名や会員ランク、最終購入日など、ユーザーごとの情報はユーザー属性に保存します。商品名、価格、画像URLなど、複数のユーザーへのメッセージで使う情報はカタログに登録します。イベントに商品IDを含めると、配信時に商品の詳細をカタログから取得できます。

> [!NOTE]
>
> コンソールの **カタログ** メニューは、Proプラン以上のプロダクトで利用できます。

## データソースを選ぶ

データをどこで管理するかに合わせて、Google スプレッドシートかAPIを選びます。

* **Google スプレッドシート** でデータを管理すると、Notiflyが指定範囲全体をスケジュールに沿って同期します。すべてのフィールドを文字列として保存します。
* **API** を使う場合は、サーバーからCatalog REST APIを呼び出し、スキーマとアイテムを管理します。 `string`、`number`、`boolean`、`time`、`geo`、`object`、`array` の型を使用できます。

> [!WARNING]
>
> カタログには、商品情報など、個人を特定しない参照データのみを保存してください。氏名、メールアドレス、電話番号、外部ユーザーID、プロフィールの値などの個人情報は、Google スプレッドシートやAPIのアイテムに含めないでください。Notiflyはソースの値を自動で分類したりマスキングしたりしません。APIでカタログを作成する場合は、`data_classification` に `non_personal` を指定してください。

## Google スプレッドシートに接続する

### 1. シートを準備する

データが入っている最初の行をヘッダーとして読み込みます。

```csv theme={null}
id,name,price,category,image_url
sku-001,デイリーバックパック,59000,bag,https://example.com/sku-001.png
sku-002,軽量スニーカー,79000,shoes,https://example.com/sku-002.png
```

* 最初の列の名前は `id` にします。
* 各列のヘッダーに、重複しない名前を250文字以内で入力します。
* アイテムのIDとヘッダー名には、半角英字、数字、ハイフン（`-`）、アンダースコア（`_`）のみを使用できます。
* 各アイテムの `id` は250文字以内とし、カタログ内で重複しないようにします。商品情報が変わっても変わらない内部IDを推奨します。
* データが入った行で `id` が空欄になっていたり、ほかの行と重複していたりすると、同期に失敗します。
* すべてのセルが空欄の行は読み飛ばします。ヘッダーの列数を超える値がある行は、同期エラーになります。
* Notiflyは、Google スプレッドシートに表示されるとおりに値を文字列として保存します。価格や日付の表示形式を事前に確認してください。数値の比較や配列型のフィールドが必要な場合は、APIカタログを利用してください。

### 2. カタログを作成する

1. コンソールで **データ管理** > **カタログ** を開きます。
2. **カタログを作成** をクリックし、データソースに **Google Sheets** を選びます。
3. プロジェクト内で重複しないカタログ名を入力します。Liquidでそのまま参照できるよう、`products` のように短く意味が分かる名前を推奨します。半角英字、数字、ハングル、ハイフン、アンダースコアを250文字まで使用できます。
4. **スプレッドシート ID** を入力します。取り込むタブや範囲を指定する場合は、**シートのタブ名** または **A1 範囲** を入力します。両方入力する場合は、同じタブを指定してください。どちらも入力しなければ、先頭のタブ全体が読み込まれます。
5. Google スプレッドシートの共有設定で、`catalog-reader@notifly.tech` に **閲覧者** 権限を付与します。
6. **同期頻度** と **基準タイムゾーン** を選び、**カタログを作成** をクリックします。作成後すぐに初回同期が始まります。

![Google Sheetsカタログの作成画面](https://mintcdn.com/notifly/DHduOkdsm1-HMvmh/images/i18n/ja/catalogs/google-sheets-create.png?fit=max\&auto=format\&n=DHduOkdsm1-HMvmh\&q=85\&s=1affba42194a55e5f86565b9af7a1496)

スプレッドシートIDは、URL内の `/d/` と `/edit` の間にある文字列です。

```text theme={null}
https://docs.google.com/spreadsheets/d/{SPREADSHEET_ID}/edit
```

たとえば、`https://docs.google.com/spreadsheets/d/1AbCdEfGhIjKlMnOpQrStUvWxYz/edit` のスプレッドシートIDは `1AbCdEfGhIjKlMnOpQrStUvWxYz` です。A1範囲は `A1:Z50000` や `Products!A1:Z50000` のように入力します。

### 3. 同期スケジュールを設定する

**繰り返さない**、**15分ごと**、**30分ごと**、**毎時**、**毎日**、**毎週**、**毎月** から選べます。同期は指定したタイムゾーンに従って実行されます。実行時刻を指定する場合、分は `00`、`15`、`30`、`45` から選びます。毎月の同期日は1日から28日まで指定できます。

* 作成直後の初回同期や **今すぐ同期** を実行しても、定期スケジュールは変わりません。
* データソースを変更すると、ステータスが **同期待ち** に変わります。次の定期同期または **今すぐ同期** の実行後に、新しい設定が反映されます。
* 変更がない場合、同期履歴に **変更なし** と記録されます。
* 同期に失敗した場合は、最後に成功した同期のデータがあれば、そのデータを引き続き使います。権限、ヘッダー、行の形式などを修正してから、再度同期してください。
* カタログを無効にすると、自動同期と手動同期が止まります。メッセージからも参照できなくなります。

### 4. 同期結果を確認する

同期が完了したら、カタログの詳細を開きます。

1. **ステータス** と **行数** を確認します。
2. **項目をプレビュー** を開き、ページを切り替えながら、IDと主なフィールドが元のシートと一致するかを確認します。
3. **同期履歴** で **実行方法**、**開始日時**、**完了日時**、**行数**、**サイズ**、**ステータス** を確認します。ステータスには **成功**、**変更なし**、**失敗** などが表示されます。
4. 失敗した場合は、共有権限、最初の列の `id`、ヘッダーの空欄や重複、不正な行を確認します。修正したら **今すぐ同期** をもう一度実行します。

![Google Sheetsカタログの詳細と同期履歴](https://mintcdn.com/notifly/DHduOkdsm1-HMvmh/images/i18n/ja/catalogs/google-sheets-detail.png?fit=max\&auto=format\&n=DHduOkdsm1-HMvmh\&q=85\&s=19f953a731de82e3fb9c134956a96304)

### 5. ソースやカタログ名を変更する

カタログ詳細画面で **編集** をクリックすると、カタログ名、スプレッドシートID、シートのタブ、A1範囲、同期スケジュールを変更できます。

* データソースや範囲を変更した場合は、**変更を保存** をクリックし、同期結果を確認してください。
* カタログ名を変更した場合は、既存のキャンペーンやユーザージャーニーで使っている `catalog_items` と `catalog_selection_items` タグも、新しい名前に更新してください。
* ソースの行や値を変更しても、キャンペーンやユーザージャーニーは自動で開始しません。カタログを使うキャンペーンやユーザージャーニーを設定してください。

### 6. カタログを無効化、または削除する

Google スプレッドシートのカタログには、次の操作があります。

**無効化**を選ぶ前に、このカタログを参照しているメッセージを確認してください。

* **無効化**すると、自動同期と手動同期が止まり、Liquidからも参照できなくなります。カタログのデータと同期履歴は残ります。無効化後にコンソールでできる操作は完全削除のみです。
* **削除** をクリックし、確認ダイアログで **完全に削除** をクリックすると、アイテムと同期履歴がデータベースから削除されます。復元はできません。

## APIカタログを作成する

コンソールでデータソースに **API** を選ぶと、`id:string` フィールドのみの空のカタログを作れます。その後、REST APIでフィールドとアイテムを登録します。REST APIでカタログとスキーマをまとめて作成することもできます。

APIから作成する場合は、[API認証トークン](https://docs.notifly.tech/ja/api-reference/getting-started.md) を発行し、次のリクエストを送ります。

```bash theme={null}
curl --request POST \
  --url "https://api.notifly.tech/v1/projects/${PROJECT_ID}/catalogs" \
  --header "Authorization: Bearer ${NOTIFLY_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "catalogs": [
      {
        "name": "products",
        "description": "メッセージのパーソナライズに使う商品情報",
        "data_classification": "non_personal",
        "fields": [
          { "name": "id", "type": "string" },
          { "name": "name", "type": "string" },
          { "name": "price", "type": "number" },
          { "name": "tags", "type": "array" },
          { "name": "released_at", "type": "time" }
        ]
      }
    ]
  }'
```

最初のフィールドは必ず `{ "name": "id", "type": "string" }` にします。カタログを作成したら、1回のリクエストで最大50件のアイテムを登録できます。

```bash theme={null}
curl --request POST \
  --url "https://api.notifly.tech/v1/projects/${PROJECT_ID}/catalogs/products/items" \
  --header "Authorization: Bearer ${NOTIFLY_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "items": [
      {
        "id": "sku-001",
        "name": "デイリーバックパック",
        "price": 59000,
        "tags": ["bag", "new"],
        "released_at": "2026-08-01T09:00:00+09:00"
      }
    ]
  }'
```

REST APIで参照や変更ができるのは、データソースがAPIで、ステータスが有効なカタログのみです。Google スプレッドシートのカタログはコンソールで管理してください。

コンソールではAPIカタログを作成し、一覧や詳細を確認できます。アイテムのプレビューやREST APIの使用例も表示できます。アイテム、フィールド、選択項目を変更したり、カタログを完全に削除したりする場合はREST APIを使います。コンソールからの編集、同期、無効化、削除には対応していません。

## メッセージでカタログのアイテムを使う

メッセージエディターで、`catalog_items` タグにカタログ名とアイテムIDを順に指定します。検索結果は `items` 配列に格納されます。

> [!NOTE]
>
> **対応するキャンペーンとチャネル**
>
> 予約送信またはイベントベースのキャンペーン、およびユーザージャーニーでは、アプリプッシュ、ウェブプッシュ、SMS、カカオアリムトーク、カカオブランドメッセージ、Webhookでカタログを使用できます。
>
> アプリ内ポップアップとWebポップアップでは、イベントベースのキャンペーンとユーザージャーニーで使用できます。新しいポップアップエディターと、パーソナライズに対応したバージョンのSDKが必要です。入力方法は、[アプリ内ポップアップ](https://docs.notifly.tech/ja/user-guide/channel/in-app-message/file.md) と [Webポップアップ](https://docs.notifly.tech/ja/user-guide/channel/web-message/file.md) の作成ガイドを参照してください。
>
> APIベースの送信キャンペーンでは、チャネルにかかわらずカタログを参照できず、`items` は空の配列になります。APIによる直接送信でもカタログは参照されません。APIを呼び出す前に必要な値を取得し、メッセージに含めてください。

### イベントベースのキャンペーン

イベントパラメータに商品IDが含まれている場合は、`event` から読み取れます。

```json theme={null}
{
  "item_id": "sku-001"
}
```

```liquid theme={null}
{% catalog_items products {{ event["item_id"] }} %}
{% if items.size > 0 %}
  {{ items[0].name }}をもう一度チェックしてみませんか？
  現在の価格は{{ items[0].price }}ウォンです。
{% endif %}
```

イベントベースのキャンペーンでは `event` を使用します。

### ユーザージャーニー

イベントから開始するユーザージャーニーでは、開始イベントのパラメータを `entry_event` から読み取ります。

```liquid theme={null}
{% catalog_items products {{ entry_event["item_id"] }} %}
{% if items.size > 0 %}
  {{ items[0].name }}の現在の価格は{{ items[0].price }}ウォンです。
{% endif %}
```

### 複数のアイテムを参照する

複数のIDを空白で区切ると、一度に参照できます。IDにはユーザー属性やイベントパラメータの値も指定できます。

```liquid theme={null}
{% catalog_items products {{ event["primary_item_id"] }} {{ event["secondary_item_id"] }} %}
{% for item in items %}
  - {{ item.name }}: {{ item.price }}ウォン
{% endfor %}
```

存在するアイテムは、リクエストで指定した順に格納されます。対応するアイテムがないIDは結果に含まれません。その分、後ろのアイテムが配列の手前に移ることがあります。同じIDを複数回指定しても、結果には1件だけ含まれます。値を使う前に、`items.size` を確かめるか、`for` で結果を順に処理してください。結果が空の場合は、代わりの文言を表示するか、対応チャネルで `abort_message` を使って送信を中止できます。

同じメッセージでカタログタグを再度呼び出すと、`items` 配列は新しい結果に置き換わります。

カタログのフィールドの値にLiquidが含まれていて、その値もレンダリングする場合は `:rerender` を使用します。

```liquid theme={null}
{% catalog_items products sku-001 :rerender %}
{{ items[0].description }}
```

カタログを再帰的に呼び出すことはできません。 `:rerender` は信頼できるテンプレートの値にのみ使用してください。

## 選択項目を使う

APIカタログでは、フィルター、並び順、結果件数の上限を指定して選択項目を作れます。選択項目は最大30件、1つの選択項目に設定できるフィルターは最大4件、結果は最大50件です。

使える演算子はフィールドの型によって異なります。

* `string` は `equals`、`does not equal`。
* `number` は `equals`、`does not equal`、`greater than`、`less than`。
* `boolean` は `is`。
* `time` は `before`、`after`。
* `array` は `includes value`、`does not include value`。

`geo` と `object` はフィルターの対象外です。フィルター値には `null` を指定できません。

```bash theme={null}
curl --request POST \
  --url "https://api.notifly.tech/v1/projects/${PROJECT_ID}/catalogs/products/selections" \
  --header "Authorization: Bearer ${NOTIFLY_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "selection": {
      "name": "new-bags",
      "description": "新作バッグ",
      "filters": [
        { "field": "tags", "operator": "includes value", "value": "new" }
      ],
      "results_limit": 10,
      "sort_field": "price",
      "sort_order": "asc"
    }
  }'
```

メッセージからは、次のように参照します。

```liquid theme={null}
{% catalog_selection_items products new-bags %}
{% for item in items %}
  {{ item.name }} - {{ item.price }}ウォン
{% endfor %}
```

アイテムやフィールドを変更すると、保存した選択項目の結果が更新されます。選択項目で使っているフィールドを削除するには、その選択項目を先に削除します。

## トラブルシューティング

> [accordion] Google Sheetsの権限エラーが表示されます。
>
> 共有設定で `catalog-reader@notifly.tech` に閲覧者権限が付与されているか確認してください。スプレッドシートIDとシートのタブ名も確認します。

> [accordion] データ検証エラーが表示されます。
>
> 最初の列の名前が小文字の `id` であること、ヘッダーに空欄や重複がないことを確認してください。各行の `id` とヘッダーには、半角英字、数字、ハイフン、アンダースコアのみ使用できます。データ行の列数がヘッダーより多い場合も、同期に失敗します。

> [accordion] シートを編集してもメッセージの値が変わりません。
>
> シートの変更は同期後に反映されます。次の定期同期を待つか、**今すぐ同期** を実行してください。その後、詳細画面で直近の同期日時を確認し、**項目をプレビュー** を開きます。

> [accordion] 再入荷や値下げを知らせるメッセージは自動で送信されますか？
>
> カタログの値を変更しても、送信は開始しません。再入荷や値下げのイベントをNotiflyに送り、そのイベントをキャンペーンやユーザージャーニーの開始条件に設定してください。商品名、価格、リンクなど、メッセージに表示する値はカタログから取得します。

## 主な上限

* プロジェクトごとの有効なカタログ数：20件
* Google スプレッドシートのカタログのフィールド数：`id` を除き1,000件
* APIカタログのフィールド数：`id` を含め500件
* フィールド追加リクエストあたりのフィールド数：50件
* アイテムの作成、変更、削除リクエストあたりのアイテム数：50件
* アイテム1件あたりの保存サイズ：1 MiB
* カタログ1件あたりの保存サイズ：2 GiB
* プロジェクト内の有効なカタログの合計保存サイズ：15 GiB
* カタログ名、フィールド名、アイテムID：250文字
* 文字列：5,000文字
* 配列：文字列100件
* `object` と `array` のネスト：50階層。オブジェクトのキーに `.` または `$` は使用できません。
* 1回のGoogle スプレッドシート同期で読み込めるデータサイズ：100 MiB
* APIのJSONリクエスト本文：4 MiB

APIのパス、リクエストとレスポンスのスキーマ、ステータスコードは、[Catalog REST APIの利用を開始する](https://docs.notifly.tech/ja/api-reference/catalogs/getting-started.md) と **API Reference** > **カタログ** を参照してください。Brazeから移行する場合は、[Braze Catalogsから移行する](https://docs.notifly.tech/ja/developer-guide/migration/braze-catalogs.md) を参照してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.