Connected Content APIの呼び出しを行う

Connected Contentを使用すると、APIでアクセス可能な情報をユーザーに送信するメッセージに直接挿入できます。Webサーバーから直接、または公開されているAPIからコンテンツを取得できます。

このページでは、Connected Content APIの呼び出し方法、高度なConnected Contentのユースケース、エラー処理などについて説明します。

Connected Contentの呼び出し量について

重要

1回の送信は1回のConnected Contentの呼び出しと等しくありません。Brazeはメッセージ送信とConnected Contentリクエストの間の1:1の比率を保証しません。システムは、呼び出し回数を最小限に抑えることよりも、正しいメッセージのレンダリングと配信を優先するように設計されています。エンドポイントは、受信者数や送信メッセージ数よりも多くのリクエストを処理できるように構築する必要があります。

Brazeは、受信者1人あたり同じConnected Content APIの呼び出しを複数回行う場合があります。一般的な理由は以下のとおりです。

• 複数パートのメール： 1通のメールで、HTML本文、プレーンテキスト本文、Accelerated Mobile Pages（AMP）バージョン（存在する場合）のそれぞれに対して個別のレンダリングパスがトリガーされることがあります。各パスでそのパートのConnected Contentがトリガーされるため、1人の受信者が複数の同一または類似の呼び出しを生成する可能性があります。
• バリデーションとリトライ： メッセージペイロードは、バリデーション、リトライロジック、その他の内部目的のために、受信者1人あたり複数回レンダリングされることがあります。
• チャネルの動作： Connected Contentはメッセージがレンダリングされるときに実行されます。アプリ内メッセージの場合、メッセージはインプレッション時にレンダリングされます。

ログで送信数や受信者数よりも多くのConnected Contentの呼び出しが確認される場合、その動作は想定どおりです。負荷の軽減とスケーリングの計画については、大量エンドポイントのベストプラクティスを参照してください。

Connected Content 呼び出しを送信する

Connected Content 呼び出しを送信するには、{% connected_content %} タグを使用します。このタグでは、:save を使用して変数を割り当てたり宣言したりできます。これらの変数の内容は、後でメッセージ内の Liquid で参照できます。

API 呼び出しの内訳

次の例では、Sunrise-Sunset API を使用して、今日の日の出時刻をメッセージに含めています。

1
2

{% connected_content https://api.sunrise-sunset.org/v2?lat=40.7128&lng=-74.0060&date=today :save result %}
Hi there, today's sunrise in NYC is at {{result.sunrise}}.

各部分の役割は次のとおりです。

Sunrise-Sunset API のレスポンスの仕組み

このエンドポイントは、sunrise、sunset、tzid などのトップレベルフィールドを含む JSON を返します。時刻はデフォルトでその場所のタイムゾーン (この例ではニューヨーク時間) で返されます。

たとえば、レスポンスの形式は次のようになります。

1
2
3
4
5
6

{
  "date": "2026-07-23",
  "tzid": "America/New_York",
  "sunrise": "2026-07-23T05:42:11-04:00",
  "sunset": "2026-07-23T20:21:32-04:00"
}

API レスポンスを Liquid にマッピングする

レスポンスは result として保存されるため、そのオブジェクトから各フィールドを直接参照します。

1
2
3

{{result.sunrise}}
{{result.sunset}}
{{result.tzid}}

Connected Content から JSON を保存する場合は、常に次のパターンを使用します。

1. :save を使用して API レスポンスを保存します。
2. JSON レスポンス内で目的のフィールドを見つけます。
3. Liquid で saved_variable.field_name として参照します。

変数を追加する

Connected Content リクエストを送信する際に、ユーザープロファイルの属性を変数として URL 文字列に含めることもできます。

たとえば、ユーザーのメールアドレスと ID に基づいてコンテンツを返す Web サービスがあるとします。アットマーク (@) などの特殊文字を含む属性を渡す場合は、次のメールアドレス属性の例のように、Liquid フィルター url_param_escape を使用して、URL で使用できない文字を URL セーフなエスケープ形式に置き換えてください。

1
2
3

Hi, here are some articles that you might find interesting:

{% connected_content http://www.yourwebsite.com/articles?email={{${email_address} | url_param_escape}}&user_id={{${user_id}}} %}

注

Braze の Liquid 構文で正しく動作させるには、属性値を ${} で囲む必要があります。

Connected Content リクエストは GET と POST のみをサポートしています。バナーの場合、サポートされるのは GET リクエストのみです。詳細については、バナーの Connected Content を参照してください。

エラー処理

URL が利用できず 404 ページに到達した場合、Braze はその箇所に空の文字列をレンダリングします。URL が HTTP 500 または 502 ページに到達した場合、その URL は再試行ロジックで失敗します。

エンドポイントが JSON を返す場合は、connected の値が null かどうかを確認することで検出でき、その後条件に応じてメッセージを中止できます。Braze では、ポート 80 (HTTP) とポート 443 (HTTPS) で通信する URL のみが許可されています。

異常ホストの検出

Connected Content には異常ホストの検出メカニズムが採用されています。このメカニズムは、ターゲットホストで著しい速度低下や過負荷が高い頻度で発生し、タイムアウトやリクエスト過多など、Braze がターゲットエンドポイントと正常に通信できない状態になっていることを検出します。これは、ターゲットホストの負担の原因となっている可能性のある不要な負荷を軽減するための安全策として機能します。また、Braze のインフラを安定させ、高速なメッセージング速度を維持する役割も果たします。

ターゲットホストで著しい速度低下や過負荷が高い頻度で発生した場合、Braze はターゲットホストへのリクエストを 1 分間一時停止し、代わりに失敗を示す応答をシミュレートします。1 分後、Braze は少数のリクエストを使用してホストの状態を確認し、ホストが正常であると判断された場合はリクエストを全速力で再開します。ホストがまだ異常な場合、Braze はさらに 1 分待ってから再試行します。

異常ホスト検出機能によってターゲットホストへのリクエストが停止された場合、Braze はエラー応答コードを受信した場合と同様に、メッセージのレンダリングを続行し、Liquid ロジックに従います。異常ホスト検出機能によって停止された Connected Content リクエストを確実に再試行したい場合は、:retry オプションを使用してください。:retry オプションの詳細については、Connected Content の再試行を参照してください。

異常ホストの検出が問題の原因となっている可能性がある場合は、Braze サポートにお問い合わせください。

注

Connected Content で使用する特定の URL を許可リストに登録できます。この機能を利用するには、カスタマーサクセスマネージャーにお問い合わせください。

ヒント

一般的なエラーコードの詳細については、Webhook と Connected Content リクエストのトラブルシューティングを参照してください。

レート制限 (429) と異常ホスト検出の違い

以下はそれぞれ異なるメカニズムです。

• 429 Too Many Requests: お客様のエンドポイント (またはアップストリームサービス) がこの応答を返しています。これは、お客様のサーバーまたはミドルウェアがトラフィックを拒否していることを意味し、多くの場合、そのサーバー独自のレート制限が原因です。Braze は Connected Content に個別のレート制限を適用しません。Connected Content のリクエスト量は、メッセージ配信速度のレート制限に正比例して増減します。メッセージは受信者ごとに複数回レンダリングされる場合があるため (たとえば、メールの HTML、プレーンテキスト、AMP など)、Connected Content のリクエスト数がそのレート制限を超えることがあります。設定した 1 分あたりのメッセージ数以下になるとは想定しないでください。429 が発生している場合は、想定されるリクエスト量を処理できるようにエンドポイントまたはミドルウェアをスケールするか、キャンペーンまたはキャンバスの配信速度のレート制限を下げて、1 分あたりに送信されるメッセージ (およびそれに伴う Connected Content の呼び出し) を減らしてください。
• 異常ホストの検出: 1 分間の時間枠内で失敗が高い頻度かつ大量に発生した後にトリガーされる、Braze 側の安全策です。失敗数には 408、429、502、503、504、529 のステータスコードが含まれます。トリガーされると、Braze はそのホストへのリクエストを一時的に停止し、失敗応答をシミュレートします。これはお客様独自のレート制限とは独立したものです。検出のしきい値と詳細については、Webhook と Connected Content リクエストのトラブルシューティングを参照してください。異常ホストの検出に引っかからないようにするには、Connected Content の呼び出し量についておよび大量のリクエストを処理するエンドポイントのベストプラクティスで説明されている呼び出し量を、エンドポイントが処理できることを確認してください。

効率的なパフォーマンスの確保

Brazeは非常に高速にメッセージを配信するため、コンテンツの取得時にオーバーロードしないよう、サーバーが数千の同時接続を処理できることを確認してください。パブリックAPIを使用する場合は、APIプロバイダーが設定しているレート制限に違反しないことを確認してください。Brazeはパフォーマンス上の理由から、サーバーのレスポンス時間が2秒未満であることを要求しています。サーバーのレスポンスに2秒以上かかる場合、コンテンツは挿入されません。

エンドポイントのキャパシティ計画と呼び出し量の削減については、大量エンドポイントのベストプラクティスを参照してください。

知っておくべきこと

• BrazeはAPI呼び出しに対して課金しません。また、API呼び出しは所定のデータポイント使用量にもカウントされません。
• Connected Contentのレスポンスには1 MBの制限があります。
• Connected Contentは、メッセージのレンダリング時に実行されます。アプリ内メッセージの場合、メッセージはインプレッション時にレンダリングされます。
• Connected Contentの呼び出しはリダイレクトに従いません。成功として扱われるのは2xxレスポンスのみです。エンドポイントが3xxリダイレクト (301や302など) を返した場合、Brazeはリダイレクト先の最終URLにアクセスしません。症状とトラブルシューティングの手順については、エンドポイントがリダイレクトを返すとConnected Contentが失敗するのはなぜですか?を参照してください。

Connected Contentの呼び出しの処理方法

単一のメッセージテンプレート内のConnected Contentの呼び出しは、Liquidのレンダリング中に順番に (上から下へ) 実行されます。つまり、後続の呼び出しで、先行する呼び出しで設定された変数を参照できます。この例では、最初の呼び出しでユーザーデータを取得し、2番目の呼び出しでそのデータを使用して設定を取得しています。

1
2

{% connected_content https://api.example.com/user :save user_data %}
{% connected_content https://api.example.com/preferences?user_id={{user_data.id}} :save preferences %}

グローバルな送信とリクエスト量

Connected Contentの呼び出しは単一のメッセージ内では順番に実行されますが、メッセージはキャンペーンやキャンバス全体で並行して送信されます。大量送信を行うと、送信のピーク時にエンドポイントへのリクエストトラフィックが大幅に増加する可能性があります。ワークスペースのメッセージングレート制限、配信速度のレート制限、キャッシュなど、このトラフィックを管理および調整する方法については、大量のリクエストを処理するエンドポイントのベストプラクティスを参照してください。

大量送信エンドポイントのベストプラクティス

Connected Contentを使用するメッセージを大量に送信する場合は、受信者数や送信数を上回るリクエストが発生することを想定して計画してください。

• ピーク負荷を見積もる: Connected Contentのリクエスト数は受信者数や送信メッセージ数を上回ることがあるため、エンドポイントやミドルウェアの規模を決める際は余裕を持った倍率を使用してください。たとえばメールでは、1人の受信者に対して複数の呼び出し (HTML、プレーンテキスト、AMP) が発生することがあるため、受信者数 × 2 または × 3 を控えめな見積もりとしてよく使用します。
• 必要に応じてキャッシュを使用する: GET リクエストはデフォルトでキャッシュされます。POST リクエストの場合、レスポンスを一定期間再利用できるとき (リクエストごとに変わらないトークンやコンテンツなど) は :cache_max_age を追加してください。詳しくは、レスポンスのキャッシュと、次のセクションの POST キャッシュに関する FAQ を参照してください。
• メッセージのレート制限を設定する: キャンペーンやキャンバスに設定するワークスペースのメッセージングレート制限と配信速度のレート制限は、Connected Contentのリクエスト量を間接的に制限します。Braze はConnected Content自体にはレート制限を適用しません。Connected Contentのリクエストはメッセージと 1 対 1 で対応しないため、これらはあくまで完全ではない代替手段です。メッセージの量 (ひいてはConnected Contentの量) をエンドポイントが処理できる範囲に収めるために活用してください。
• べき等性と再試行を考慮して設計する: Braze は受信者 1 人につきエンドポイントを複数回呼び出すことがあります。重複したリクエストを受けても誤った副作用が発生しないよう、エンドポイントを設計してください。

認証タイプ

保存した認証情報は、設定 > 認証情報管理で管理します。これらの認証情報は、Connected Content と Webhook で使用できます。Webhook の設定については、保存した認証情報を使用するを参照してください。

基本認証の使用

URL で基本認証が必要な場合、Braze はユーザー名とパスワードを保存し、API 呼び出しで使用できるようにします。

新しい認証情報を追加するには、認証情報を追加 > 基本認証を選択します。

認証情報に名前を付け、ユーザー名とパスワードを入力します。

許可されたドメインフィールドは、Connected Content で使用する基本認証では任意で、Webhook で使用する場合は必須です。空のままにすると、Connected Content は認証情報を特定のドメインに制限しません。ドメインが設定されていない既存の基本認証の認証情報も、この動作を維持します。

ドメインを入力すると、Braze は Connected Content の呼び出しを含め、認証情報をそのドメインとそのすべてのサブドメインに制限します。既存の認証情報にドメインを追加する前に、その認証情報をすでに使用している呼び出しの送信先を確認してください。詳細については、許可されたドメインを選択するを参照してください。

その後、トークンの名前を参照することで、この基本認証の認証情報を API 呼び出しで使用できます。

1

Hi there, here is some fun trivia for you!: {% connected_content https://yourwebsite.com/random/trivia :basic_auth credential_name %}

注

認証情報を削除すると、その認証情報を使用しようとする Connected Content の呼び出しはすべて中止されることに注意してください。

{% connected_content %} タグで認証情報を参照すると、Braze がメッセージをレンダリングする際に、その Connected Content リクエストが認証されます。メインの Webhook リクエストを認証するには、Webhook 作成画面で別途認証情報を選択してください。認証と Connected Content の認証情報を参照してください。

トークン認証の使用

Braze の Connected Content を使用する際、一部の API ではユーザー名とパスワードの代わりにトークンが必要になる場合があります。Braze は、トークン認証のヘッダー値を保持する認証情報も保存できます。

トークン値を保持する認証情報を追加するには、認証情報を追加 > トークン認証を選択します。次に、API 呼び出しヘッダーのキーと値のペアと許可されたドメインを追加します。トークン認証ではドメインが必須です。認証情報は、そのドメインとそのすべてのサブドメインで使用できます。保存する前に、許可されたドメインを選択するを確認してください。

その後、認証情報の名前を参照することで、この認証情報を API 呼び出しで使用できます。

1
2
3
4
5
6
7
8
9

{% assign campaign_name="New Year Sale" %}
{% connected_content
     https://api.endpoint.com/your_path
     :method post
     :auth_credentials token_credential_abc
     :body campaign={{campaign_name}}&customer={{${user_id}}}&channel=Braze
     :content_type application/json
     :save publication
%}

許可されたドメインを選択する

api.example.com のようなホスト名を、http://、https://、ポート、パス、ワイルドカードを付けずに入力します。ドメインの照合では大文字と小文字は区別されません。許可されたドメインには、基本認証とトークン認証のどちらでも、入力したホスト名とその配下のすべてのサブドメインが含まれます。

次の例は、許可されたドメインによって認証情報の送信先がどのように決まるかを示しています。

警告

組織が管理している最も具体的なホスト名を使用してください。共有ホスティングプロバイダーの親ドメインは避けてください。別の組織がサブドメインを管理し、シークレットを受け取る可能性があります。たとえば、your-company.example.com と other-company.example.com をそれぞれ別の組織が管理している場合、example.com を許可すると、認証情報が両方に送信される可能性があります。your-company.example.com を使用して、アクセスを組織のホスト名とそのサブドメインに絞り込んでください。

ドメイン制限を追加または変更すると、その認証情報を使用している既存の呼び出しに影響します。許可されたドメイン外のホスト名でその認証情報を使用する呼び出しがあると、Connected Content はメッセージを中止します。

保存した認証情報を管理する

保存されたパスワードとトークン値は表示されません。変更を保存するには、許可されたドメインのみを変更する場合でも、基本認証のパスワード、または残すすべてのトークンヘッダー値を再入力してください。編集を送信する際、マスクされたプレースホルダーではシークレットは保持されません。

設定 > 認証情報管理に移動します。このページにアクセスし、認証情報を作成、編集、削除するには、「Manage App Group」権限が必要です。必要に応じて、ワークスペースの管理者に権限の付与を依頼してください。

認証情報は 1 つのワークスペースに属します。開発、ステージング、本番のワークスペースを分けて使用している場合は、認証情報が必要な各ワークスペースで作成してください。

利用可能な場所列には、各認証情報を使用できる場所が表示されます。

• Connected content: 許可されたドメインが設定されていない基本認証の認証情報です。Webhook で使用するには、許可されたドメインを追加してください。
• Connected content, Webhooks: 許可されたドメインが設定された認証情報です。そのドメイン制限の範囲内で、Connected Content と Webhook の両方に対応しています。

認証情報を編集する

認証情報の名前を選択すると、必要に応じてユーザー名、パスワード、トークンヘッダー、許可されたドメインを編集できます。認証情報の名前は作成後に変更できません。

認証情報を編集を選択して保存します。

認証情報は、それを参照する呼び出しと Webhook で共有されます。認証の詳細や許可されたドメインを変更する前に、それらの使用箇所を確認し、保存後に影響を受けるリクエストをテストしてください。

認証情報を削除する

削除ダイアログでは、Webhook キャンペーン、キャンバス、Webhook テンプレートでの認証情報の使用状況が確認されます。削除する前に、一覧に表示されたすべての Webhook から認証情報を削除するか、置き換えてください。保存された下書きや一時停止中のオブジェクトによって、削除がブロックされる場合もあります。

使用状況の一覧は Webhook のみを対象としています。Liquid や Content Blocks 内の Connected Content の参照は検出されません。認証情報を削除する前に、それらの参照を確認して更新してください。一覧に表示された Webhook での使用を削除し、Connected Content に関する警告を確認してから、認証情報を削除を選択します。

警告

認証情報の削除は元に戻せません。その認証情報を引き続き参照している Connected Content の呼び出しは中止されます。

Open Authentication (OAuth) を使用する

API の構成によっては、アクセスしたい API エンドポイントの認証に使用するアクセストークンを取得する必要があります。

ステップ 1: アクセストークンを取得する

次の例は、アクセストークンを取得してローカル変数に保存し、それを後続の API 呼び出しの認証に使用する方法を示しています。:cache_max_age パラメーターを追加すると、アクセストークンの有効期間に合わせて、送信される Connected Content の呼び出し回数を減らすことができます。詳細については、設定可能なキャッシュを参照してください。

1
2
3
4
5
6
7
8
9
10

{% connected_content
     https://your_API_access_token_endpoint_here/
     :method post
     :auth_credentials access_token_credential_abc
     :headers {
       "Content-Type": "YOUR-CONTENT-TYPE"
     }
     :cache_max_age 900
     :save token_response
%}

注

トークンエンドポイントが application/x-www-form-urlencoded を想定しており、:body で認証情報を渡す場合は、パラメーター値に含まれる特殊文字を URL エンコードしてください。たとえば、スラッシュ (/) は %2F に、プラス記号 (+) は %2B になります。特殊文字をエンコードしないと、OAuth トークンリクエストが失敗する可能性があります。

ステップ 2: 取得したアクセストークンを使用して API を承認する

トークンを保存したら、後続の Connected Content 呼び出しにダイナミックにテンプレート化して、リクエストを承認できます。

1
2
3
4
5
6
7
8
9

{% connected_content
     https://your_API_endpoint_here/
     :headers {
       "Content-Type": "YOUR-CONTENT-TYPE",
       "Authorization": "{{token_response}}"
     }
     :body key1=value1&key2=value2
     :save response
%}

認証情報の編集

各認証タイプの認証情報の名前を編集できます。

• 基本認証では、ユーザー名とパスワードを更新できます。以前に入力したパスワードは表示されないことに注意してください。
• トークン認証では、ヘッダーのキーと値のペアと許可されたドメインを更新できます。以前に設定したヘッダー値は表示されないことに注意してください。

コネクテッドコンテンツの IP 許可リスト

コネクテッドコンテンツを使用するメッセージが Braze から送信されると、Braze サーバーはデータを取得するために、お客様またはサードパーティのサーバーに対して自動的にネットワークリクエストを行います。IP 許可リストを使用すると、コネクテッドコンテンツのリクエストが実際に Braze から送信されていることを確認でき、セキュリティを強化できます。

Braze は、以下の IP 範囲からコネクテッドコンテンツのリクエストを送信します。記載されている範囲は、許可リストにオプトインしている API キーに自動的かつ動的に追加されます。

Braze には、すべてのサービスで使用する予約済みの IP セットがありますが、常にすべてがアクティブであるとは限りません。これは、必要に応じて Braze が別のデータセンターから送信したりメンテナンスを行ったりする際に、顧客に影響を与えないようにするための設計です。Braze は、コネクテッドコンテンツのリクエストを行う際に、以下に記載されている IP のうち 1 つ、一部、またはすべてを使用する場合があります。

コネクテッドコンテンツのリクエストが常に 403 Forbidden を返し、認証が正しく設定されている場合は、リクエストを受信するサーバーでこれらの IP を許可リストに追加してください。403 は権限不足や無効な認証情報を示している場合もあるため、ネットワーク設定と認証設定の両方を確認してください。Webhook 固有のガイダンスについては、403 Forbidden と IP 許可リストを参照してください。

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)
• japan (jp)
• south korea (kr)

Amazon S3 で IP 許可リストを使用する

コネクテッドコンテンツを使用して Amazon S3 からファイルを取得する場合は、Braze の IP アドレスからの認証されていない HTTP GET リクエストを許可するようにバケットを設定します。

1. IP 条件を含むバケットポリシーを追加する: Principal: "*" と、ご利用のインスタンスの Braze IP 範囲を使用する IpAddress 条件を指定して、バケットオブジェクトに対する s3:GetObject を付与します。個々のオブジェクトに public-read ACL を設定する必要はありません。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::your-bucket-name/*",
      "Condition": {
        "IpAddress": {
          "aws:SourceIp": ["{YOUR_BRAZE_IP_RANGE}"]
        }
      }
    }
  ]
}

{YOUR_BRAZE_IP_RANGE} を、コネクテッドコンテンツの IP 許可リストに記載されているご利用のインスタンスの Braze IP 範囲に置き換えてください。aws:SourceIp 配列には、1 つ以上の範囲を個別の値として追加できます。

2. S3 のパブリックアクセスブロック設定を確認する: Principal: "*" を使用するバケットポリシーは、IP 条件がある場合でも AWS ではパブリックアクセスとして扱われます。ACL ベースのパブリックアクセスはブロックしたまま、バケットポリシーベースのパブリックアクセスを許可する必要がある場合があります。

3. コネクテッドコンテンツタグで S3 オブジェクト URL を使用する: 標準の S3 URL (例: https://your-bucket.s3.amazonaws.com/path/to/object.json) でオブジェクトを参照します。

バケットポリシーと条件キーの詳細については、AWS のドキュメントを参照してください。

送信リクエストヘッダー

Brazeは、送信されるConnected Contentリクエストに以下のヘッダーを追加します。ほとんどのヘッダーは、タグ内でまだ指定されていない場合にのみ設定されます。:headers、認証情報、またはタグオプションで指定したヘッダーは、指定した通りに送信されます。

Webhook リクエストでは、User-Agent ヘッダーを設定していない場合、Braze Sender で始まる User-Agent も送信されます。

トラブルシューティング

コネクテッドコンテンツの呼び出しが正しくレンダリングされない、またはまったくレンダリングされない場合は、以下の点を確認してください。

• ライブのリクエストとレスポンスを確認する: プレビューとテストで コネクテッドコンテンツデバッガーを使用します。
• コネクテッドコンテンツの呼び出しが行われたことを確認する: 呼び出しが行われたかどうかは、メッセージ履歴タブで確認できます。単一のコネクテッドコンテンツリクエストをテスト送信することもできます。
• Postman または CURL リクエストで、想定どおりのリクエストが成功するかを確認する: リクエストが機能してレスポンスが返される場合は、リクエストの内容 (ヘッダーを含む) を詳しく比較します。ヘッダーが二重引用符で囲まれたキーと値のペアとして記述されていることを確認してください。
• 認証を検証する: 認証情報が 設定 > 認証情報管理に保存され、:basic_auth または :auth_credentials オプションで参照されていることを確認します。コネクテッドコンテンツの URL では、認証以外にも入力が必要なヘッダーが求められる場合があります。
• データが想定どおりの形式であることを確認する: レスポンス本文について、Braze は有効な JSON を Liquid オブジェクトとして解析します。それ以外の場合、レスポンスはプレーンテキスト (HTML を含む) として扱われます。:content_type オプションはリクエストの送信 Content-Type ヘッダーと Accept ヘッダーを設定するもので、レスポンスの解析には影響しません。リクエストの :body について、JSON にスペースが含まれる場合は、JSON 本文の指定セクションのガイダンスに従ってください。
• データが正しく解析されていることを確認する: Liquid が想定するフィールドを正しく参照していることを確認します。ネストされた JSON の場合は、{{sampleresult.data[0].sample_field}} を使用して目的のネストされたフィールドを指定します。RESPONSE:{{sampleresult.data}} で想定される結果を出力すると、ネストされた JSON のプロパティを確認できます。
• レスポンスのステータスコードを確認する: レスポンスのステータスコードは 2XX コードである必要があります。コードが 2XX 以外の場合、コネクテッドコンテンツはレスポンスを利用できません。

プレビューとテストでプレビューを生成し、詳細を表示を選択して コネクテッドコンテンツデバッガーを開きます。デバッガーには、コネクテッドコンテンツタグのヘッダーが一覧表示されます。Braze が送信リクエストに追加するヘッダーについては、送信リクエストヘッダーを参照してください。

また、Liquid タグにエンドポイントが想定するパラメーター (例: :method、:headers、:content_type、:body、必要に応じて :basic_auth) が含まれていることも確認できます。保存した JSON オブジェクトの HTTP ステータスコードキーを利用する場合、エンドポイントは JSON オブジェクトと 2XX ステータスを返す必要があります。

ホストからのエラー率が高い場合は、異常なホストの検出とコネクテッドコンテンツの呼び出し量を確認してください。

メールの POST リクエストにおけるアンパサンドのエンコーディング

メールメッセージでは、HTML の解析により {% capture %} ブロック内のアンパサンド (&) が自動的に & に変換されます。application/x-www-form-urlencoded の POST リクエストでは、これによりパラメーター名に amp; プレフィックスが付いた状態 (例: amp;username) で送信され、API 呼び出しが失敗する可能性があります。

この問題を回避するには、本文を :body に渡す前に replace フィルターを使用して amp; プレフィックスを削除します。

1
2
3
4
5
6
7
8
9

{% capture body_with_amps %}
grant_type=client_credentials&username=test&password=test
{% endcapture %}
{% connected_content https://api.example.com/token
   :method post
   :body {{body_with_amps | replace: "amp;", ""}}
   :content_type application/x-www-form-urlencoded
   :save token
%}

よくある質問

エンドポイントがリダイレクト (301 または 302) を返すと Connected Content が失敗するのはなぜですか？

リダイレクトが発生すると、Connected Content がプレビューや送信時に空白で表示されたり、HTTP ステータスコード 301 または 302 を含むエラーがメッセージアクティビティログに記録されたりすることがあります。Postman などのクライアントはリダイレクトを自動的にたどることが多いため、Postman では動作する URL でも Braze では失敗する場合があります。

Braze が呼び出す URL で、レスポンス本文とともに 2xx レスポンス (通常は 200) を返すようにエンドポイントを設定してください。その URL 自体がリダイレクトを返す場合は、最終的なリダイレクト先の URL に置き換えてください。

コンテンツが空白で表示される場合の関連チェックについては、Connected Content がレスポンス本文を返さないを参照してください。

Connected Content の呼び出し回数がユーザー数や送信数より多いのはなぜですか？

Braze は、メッセージペイロードをレンダリングするために、受信者ごとに同じ Connected Content API 呼び出しを複数回行うことがあります。メッセージペイロードは、検証、再試行ロジック、その他の内部的な目的のために、受信者ごとに複数回レンダリングされる場合があります。ただし、メッセージに反映されるのは Connected Content 呼び出しのうち 1 回のみである点に注意してください。

呼び出しで再試行ロジックを使用していない場合でも、受信者ごとに Connected Content API 呼び出しが複数回行われることは想定された動作です。Connected Content を含むメッセージにはレート制限を設定するか、メッセージ送信ごとに複数の Connected Content 呼び出しが行われることを考慮した想定ボリュームに対応できるようサーバーを構成することをお勧めします。

詳細と対策については、Connected Content の呼び出しボリュームについておよび大量のリクエストを受けるエンドポイントのベストプラクティスを参照してください。

Connected Content ではレート制限はどのように機能しますか？

Connected Content には独自のレート制限はありません。代わりに、レート制限はメッセージの送信レートに基づきます。送信されるメッセージよりも Connected Content の呼び出しが多い場合は、メッセージングのレート制限を、想定する Connected Content のレート制限よりも高く設定することをお勧めします。

キャッシュの動作はどうなっていますか？

GET リクエストはデフォルトでキャッシュされます (レスポンスのキャッシュを参照)。POST リクエストはデフォルトではキャッシュされませんが、Connected Content 呼び出しに :cache_max_age を追加することでキャッシュを有効にできます。これにより、同じ POST (トークンやコンテンツのリクエストなど) がキャッシュ期間内に繰り返し行われる場合に、エンドポイントの負荷を軽減できます。

1

{% connected_content https://api.example.com/token :method post :body grant_type=client_credentials :cache_max_age 900 :save token %}

キャッシュは重複する Connected Content 呼び出しの削減に役立ちますが、ユーザーごとに呼び出しが 1 回になることを保証するものではありません。キャッシュ期間は 5 分から 4 時間の間です。詳細については、レスポンスのキャッシュを参照してください。

Connected Content の HTTP のデフォルト動作はどうなっていますか？

デフォルトでは、Connected Contentは GET HTTPリクエストのContent-TypeヘッダーをAccept: */*付きのapplication/jsonに設定します。別のコンテンツタイプが必要な場合は、タグに:content_type your/content-typeを追加して明示的に指定してください。Brazeは、指定したタイプにContent-TypeヘッダーとAcceptヘッダーの両方を設定します。

1

{% connected_content https://api.sunrise-sunset.org/v2?lat=40.7128&lng=-74.0060&date=today :content_type application/json %}

デフォルトでは、Connected Contentは指定されたURLにHTTP GETリクエストを送信します。代わりにPOSTリクエストを行うには、:method postを指定します。

オプションで:bodyの後にkey1=value1&key2=value2&...形式のクエリ文字列またはキャプチャされた値への参照を指定することで、POSTボディを提供できます。Content-Typeのデフォルトはapplication/x-www-form-urlencodedです。:content_type application/jsonを指定し、key1=value1&key2=value2のようなフォームURLエンコードされたボディを提供すると、Brazeは送信前に自動的にボディをJSONエンコードします。

また、Connected ContentはデフォルトではPOST呼び出しをキャッシュしません。Connected ContentのPOST呼び出しに:cache_max_ageを追加することで、この動作を変更できます。

• デフォルトのcontent-type
• application/json content-type

1

{% connected_content https://example.com/api/endpoint :method post :body key1=value1&key2=value2 %}

1

{% connected_content https://example.com/api/endpoint :method post :body key1=value1&key2=value2 :content_type application/json %}

同じ Connected Content 呼び出しを複数の場所で使用するとどうなりますか？

複数のタグが同じ URL とパラメーターを使用している場合でも、各 Connected Content タグは個別に評価されます。URL とキャッシュ設定が許す場合は、同一のリクエストが新たな送信リクエストを発生させずにキャッシュから提供されることがあります (詳細については、レスポンスのキャッシュを参照してください)。