構文とルール

概要

ディレクティブを書きながら手元で参照するためのページです。使えるオプション、保存が拒否されるケース、上限、応用例をまとめています。

使える構文

構文	説明	書かない場合
`:save`	レスポンスを格納する名前。JSONは `{{ 名前.フィールド }}` で取り出します	JSONは `connected` に格納され、テキストはディレクティブの場所に出力
`:method`	`get` または `post`	`get`
`:body`	POSTで送るデータ。`:method post` と一緒に使う必要があります	データなしで呼び出し
`:content_type`	送信するデータの形式。JSON bodyは `application/json`	フォーム形式（`application/x-www-form-urlencoded`）
`:headers`	追加のヘッダーをJSONオブジェクトで書きます。例: `:headers {"X-Store-Id": "123"}` JSON形式でない場合は呼び出さずに失敗として処理されます。認証用のヘッダーには認証情報の登録を使ってください	デフォルトのヘッダーのみ送信
`:basic_auth`	Basic方式で登録した認証情報の名前	認証なしで呼び出し
`:auth_credentials`	Token方式で登録した認証情報の名前	認証なしで呼び出し
`:cache_max_age`	レスポンスの再利用時間。単位は秒です。受信者ごとに値が同じ呼び出しであれば、長めに設定して呼び出し回数を減らせます	デフォルトのキャッシュルール（レスポンスの再利用を設定するを参照）
`:no_cache`	毎回新しく呼び出します。在庫のように常に最新である必要がある値に使います	キャッシュを使用
`default:`	値が空のときに表示する文言（パーソナライズメッセージの既存フィルター）	空欄で配信
`{% abort_message %}`	この受信者には配信しません	空欄でも配信

保存が拒否されるケース

保存が拒否されるケース	解決方法
Liquid構文のエラー、サポートされていないフィルター・タグ	括弧の対応とフィルター名を確認してください
サポートされていないオプション、オプション値のエラー	`:method` にはgetとpostのみ使えます `:cache_max_age` は秒単位で書きます（例: `3600`） `:retry` はまだサポートしていません（今後対応予定）
メッセージあたりの呼び出し数の超過	件名・本文などすべてのフィールドを合わせて3つまでにしてください。
forループ内のディレクティブ	ループの外で1回呼び出し、レスポンスの配列をループしてください（下の例4）
リクエストURLのドメインにパーソナライズ変数	リクエストURLのドメインにはパーソナライズ変数を使えませんドメインは固定し、変数はパス・クエリにのみ使ってください
保存した名前をフィールドなしで使用	`{{ point }}` ではなく `{{ point.amount }}` のようにフィールドまで書いてください
認証情報の問題	登録済みの名前か、方式（Basic・Token）とオプション（`:basic_auth`・`:auth_credentials`）が合っているか、許可ドメインがリクエストURLと完全に一致しているかを確認してください

上限のまとめ

項目	上限
メッセージあたりの呼び出し数	件名・本文などすべてのフィールドを合わせて3つ · ディレクティブごとに1つと数えます。フィールドが異なれば、同じURLを書いてもそれぞれ数えます · `{% if %}` の分岐内のディレクティブも、実行されるかどうかに関係なくすべて数えます · ジャーニー自動化ではメッセージアクションごとに3つ
1回の呼び出しあたりの最大待機時間	2秒
レスポンスのサイズ	1MB
リクエストURLの長さ	変数の置換後で2048文字
レスポンスのキャッシュ保持時間	· GETはデフォルトで5分 · POSTは `:cache_max_age` を指定した場合のみ · `:cache_max_age` の指定範囲は300秒（5分）～14400秒（4時間）。範囲外の値は最も近い上限値に合わせて適用されます
認証情報の登録数	プロジェクトあたり10件

応用例

基本的な使い方に慣れたあとに参考にできる例です。

例1. 件名と本文で同じ値を使う

:save で保存した名前は、ディレクティブを書いたフィールドの中でのみ使えます。件名と本文のように別のフィールドで使うには、フィールドごとにディレクティブを書いてください。URLが同じであれば、キャッシュされたレスポンスを再利用します。

件名

{% connected_content https://api.example.com/products/{{ tags.wishlist_sku }} :save product %}お気に入りの{{ product.name }}が値下がりしました。

本文

{% connected_content https://api.example.com/products/{{ tags.wishlist_sku }} :save product %}今なら{{ product.price | number_with_delimiter }}円でお求めいただけます。

例2. 前のレスポンスを次の呼び出しに使う

ディレクティブは上から下へ実行されるため、先に保存した値を次のリクエストURLに使えます。前の呼び出しが終わってから次の呼び出しが始まるので、待機時間は積み重なります。

{% connected_content https://api.example.com/me?uid={{ userId }} :save me %}
{% connected_content https://api.example.com/orders/{{ me.id }} :save orders %}
{{ me.name }}様のご注文 {{ orders.total }}件

例3. 条件に応じて別のAPIを呼び出す

{% if %} の中でも呼び出すことができ、両方に同じ名前を使っても問題ありません。実際に実行された側のレスポンスが格納されます。

{% if tags.vip %}
  {% connected_content https://api.example.com/vip-deals :save deals %}
{% else %}
  {% connected_content https://api.example.com/normal-deals :save deals %}
{% endif %}
本日の特価：{{ deals.title }}

例4. レスポンスのリストをループで表示する

ディレクティブはループの外で1回だけ呼び出し、取得したリストをループで表示します。

{% connected_content https://api.example.com/reco?uid={{ userId }} :save reco %}
あなたへのおすすめ商品です。

{% for item in reco.items %}
- {{ item.title }} {{ item.price | number_with_delimiter }}円
{% endfor %}