コンテンツにスキップ
View in Postman (opens in new tab)

ユーザーの作成と更新

post

/users/track

このエンドポイントを使用して、カスタムイベントと購入を記録し、ユーザープロファイル属性を更新します。

BrazeはAPIを通じて渡されたデータをそのまま処理します。不要なデータポイントの記録を最小限に抑えるため、差分(変更されたデータ)のみを渡してください。

ユーザーを一括更新する必要がありますか?

/users/track/bulkエンドポイントを使用すると、より大きなバッチを送信し、リクエスト量を削減できます。

リクエスト処理ステータスの追跡

Brazeは/users/trackリクエストを非同期で処理します。成功レスポンスは、Brazeがリクエストを受信して処理キューに追加したことを意味しますが、データがまだユーザープロファイルに反映されていない場合があります。処理が完了したタイミングを確認するには、リクエストにgroup_idを追加し、/users/track/statusエンドポイントでそのグループのステータスを確認してください。

リクエスト処理ステータスは、以下の用途に使用できます。

  • 属性や購読の更新に依存するキャンバスやキャンペーンをトリガーする前に、それらの更新がプロファイルに反映されたことを確認する
  • 対象ユーザーへのメッセージングを開始する前に、バックフィルやインポートが完了したことを確認する
  • 同意変更などの優先度の高い更新の処理が完了したことを記録しておく

仕組み

  1. 関連するリクエストのセットに対してgroup_idを選択します。たとえば、バックフィル内のすべてのリクエストに1つのgroup_idを使用するか、確認したい単一のリクエストに固有のgroup_idを使用します。
  2. 各/users/trackリクエスト本文のトップレベルにgroup_idを含めます。Brazeは、受け入れた各リクエストをグループにカウントします。
  3. group_idを指定して/users/track/statusエンドポイントを呼び出します。グループのstatusがcompletedの場合、Brazeはグループ内のすべてのリクエストの処理を完了しています。

グループがcompletedになった後に同じgroup_idで別のリクエストを送信すると、Brazeが新しいリクエストの処理を完了するまで、グループのステータスはprocessingに戻ります。

Brazeは各グループのステータスを全体として追跡します。Brazeがグループ内のすべてのリクエスト(一部のオブジェクトが拒否されたリクエストを含む)の処理を完了すると、グループはcompletedになります。拒否されたオブジェクトは、各/users/trackレスポンスのerrors配列に記載されます。

ステータス追跡は/users/trackエンドポイントでのみ使用できます。Brazeは/users/track/bulkエンドポイントや/users/track/syncエンドポイントへのリクエストのステータスは追跡しません。

グループIDの要件

group_idは1〜128文字で、英字、数字、ピリオド(.)、アンダースコア(_)、チルダ(~)、ハイフン(-)のみを使用できます。

グループIDはワークスペース単位で管理されます。2つのワークスペースで同じgroup_idを使用した場合、それぞれ別のグループを参照します。

追跡したいリクエストのセットごとに新しいgroup_idを使用してください。group_idを再利用すると、既存のグループにリクエストが追加されますが、保持期間は延長されません。

制限と保持

制限 値
保持期間 24時間

Brazeは、group_idを含む最初のリクエストの時点から24時間、グループステータスを保持します。保持期間の終了後、/users/track/statusエンドポイントはそのgroup_idに対して空のresults配列を返します。
グループあたりのリクエスト数 6,000,000
ワークスペースあたりのアクティブグループ数 100,000。グループは保持期間が終了するまでアクティブです。
/users/track/statusのレート制限 ワークスペースあたり毎分1,500リクエスト。この制限は/users/trackのレート制限とは別です。

ステータス追跡のエラー

ワークスペースがアクティブグループの最大数に達した場合など、Brazeがリクエストのステータスを追跡できない場合があります。この場合でも、/users/trackレスポンスは成功し、Brazeはリクエストの属性、イベント、購入を処理します。レスポンスのerrors配列には、Brazeがリクエストを追跡していない理由を説明するエントリが含まれます。

{
  "message": "success",
  "errors": [
    {
      "type": "request_status_group_full"
    }
  ]
}
エラータイプ 説明
invalid_group_id group_idが文字列ではない、空である、128文字を超えている、または許可されていない文字を含んでいます。詳細については、グループIDの要件を参照してください。
request_status_active_group_limit_exceeded ワークスペースがアクティブグループの上限に達しています。既存のグループの有効期限が切れるまで待つか、group_idなしでリクエストを送信してください。
request_status_group_full グループがリクエストの上限に達しています。追加のリクエストには新しいgroup_idを使用してください。
request_status_not_tracked Brazeがリクエストを追跡できませんでした。たとえば、グループの保持期間が終了しているか、ワークスペースでステータス追跡が有効になっていません。

よくある質問

同じメールアドレスを持つ複数のプロファイルが見つかった場合はどうなりますか?

external_idが存在する場合、Brazeはexternal IDを持つプロファイルのうち、最も最近更新されたものを優先して更新します。external_idが存在しない場合、Brazeは最も最近更新されたプロファイルを優先して更新します。

メールアドレスを持つプロファイルが存在しない場合はどうなりますか?

Brazeはプロファイルとメールのみのユーザーを作成し、メールアドレスによるユーザープロファイルの更新リクエスト例で示したように、メールフィールドを[email protected]に設定します。Brazeはエイリアスを作成しません。

/users/trackを使用してレガシーユーザーデータをインポートするにはどうすればよいですか?

まだモバイルアプリを使用していないユーザーについても、Braze APIを通じてデータを送信し、ユーザープロファイルを生成できます。その後ユーザーがアプリケーションを使用すると、SDKによる識別以降のすべての情報は、APIコールで作成した既存のユーザープロファイルにマージされます。識別前にSDKによって匿名で記録されたユーザー行動は、APIで生成された既存のユーザープロファイルとのマージ時に失われます。

セグメンテーションツールには、アプリとのエンゲージメントの有無にかかわらず、これらのユーザーが含まれます。ユーザーAPI経由でアップロードされたものの、まだアプリを使用していないユーザーを除外する場合は、Session Count > 0フィルターを追加してください。

重複するユーザープロファイルの作成を避けるにはどうすればよいですか?

重複プロファイルは、リクエストに既存のプロファイルと一致しないプライマリ識別子(external_idなど)が含まれ、同時に既存のプロファイルと一致するemailまたはphoneの値が含まれている場合に発生する可能性があります。プライマリ識別子はユーザー検索に使用されるため、Brazeは既存のメールのみまたは電話番号のみのプロファイルを更新する代わりに、認識されないexternal_idに対して新しいプロファイルを作成します。

重複を避けるには、次のようにします。

  • メールのみまたは電話番号のみのプロファイルから識別済みプロファイルにユーザーを移行する場合は、/users/trackに両方を送信するのではなく、/users/identifyエンドポイントを使用して既存のプロファイルにexternal_idを割り当ててください。
  • 重複がすでに存在する場合は、/users/mergeエンドポイントを使用してマージしてください。

/users/trackは重複イベントをどのように処理しますか?

イベント配列内の各イベントオブジェクトは、指定された時刻にユーザーが行ったカスタムイベントの1回の発生を表します。つまり、Brazeに取り込まれる各イベントには独自のイベントIDがあるため、「重複」イベントは別々の固有のイベントとして扱われます。

/users/trackは無効な階層化カスタム属性をどのように処理しますか?

階層化カスタム属性に無効な値(無効な時刻形式やnull値など)が含まれる場合、Brazeはリクエスト内のすべての階層化カスタム属性の更新を処理から除外します。これは、その特定の属性内のすべての階層化構造に適用されます。処理を確実に成功させるために、送信前に階層化カスタム属性内のすべての値が有効であることを確認してください。

/users/trackへのリクエストは順序通りに処理されることが保証されていますか?

/users/trackに対して複数の個別のAPIコールを短時間に連続して行う場合、Brazeはリクエストが送信または受信された正確な順序で処理されることを保証できません。これは、Brazeが速度と柔軟性を最大化するために非同期処理を使用しているためです。

たとえば、同じユーザーに対して数秒以内に複数の更新リクエストを送信した場合(一部はnull属性値、他は有効な値を含む)、null値を含むリクエストが、先に送信されたにもかかわらず、有効な値を含むリクエストの後に処理される可能性があります。これにより、属性値が元に戻ったように見えたり、最後に送信された更新が反映されていないように見えたりすることがあります。

ユーザーデータの更新時に競合を避けるには、次のようにします。

  • 単一のリクエストに更新をまとめる:個別の連続したコールを行うのではなく、ユーザーのすべての属性更新を1つのAPIコールに含めてください。
  • リクエスト間に遅延を追加する:同じユーザーに対して個別のコールを行う必要がある場合は、次のリクエストを送信する前に最初のリクエストの処理が完了するよう、リクエスト間に遅延(数秒)を追加してください。
  • 同じフィールドの重複更新を避ける:2つのリクエストが同じ属性を異なる値で更新する場合、それらの更新を1つのリクエストにまとめるか、遅延を挟んで分離し、順序が前後する可能性を減らしてください。
  • 次のリクエスト前に処理を確認する(ベータ):最初のリクエストにgroup_idを含め、/users/track/statusエンドポイントがcompletedを返すまで待ってから、依存するリクエストを送信してください。詳細については、リクエスト処理ステータスの追跡を参照してください。

競合とベストプラクティスの詳細については、競合を参照してください。

Brazeがリクエストの処理を完了したタイミングをどのように確認できますか?

/users/trackリクエストにgroup_idを含め、そのgroup_idを指定して/users/track/statusエンドポイントを呼び出してください。グループのstatusがcompletedの場合、Brazeはグループ内のすべてのリクエストの処理を完了しています。この機能はベータ版です。詳細については、リクエスト処理ステータスの追跡を参照してください。

グループのステータスはどのくらいの頻度で確認すべきですか?

/users/track/statusエンドポイントを定期的な間隔(数秒ごとなど)でポーリングし、グループのstatusがcompletedになったら停止してください。ポーリングは、エンドポイントのレート制限(ワークスペースあたり毎分1,500リクエスト)内に収めてください。

グループがまだ処理中なのはなぜですか?

グループは、Brazeがグループ内で受け入れたすべてのリクエストの処理を完了するまでprocessingのままです。処理中にリクエストが失敗した場合、Brazeはそれをリトライし、リトライが成功するまでグループはprocessingのままです。グループがcompletedになった後にリクエストを追加すると、ステータスはprocessingに戻ります。まれに、保持期間が終了するまでグループがprocessingのままになることがあります。通常の処理時間よりもかなり長くグループがprocessingのままである場合は、Brazeサポートにお問い合わせください。

/users/track/statusが空のresults配列を返すのはなぜですか?

results配列は、Brazeがワークスペース内でグループを見つけられない場合に空になります。これは、グループの24時間の保持期間が終了した場合、group_idがリクエストで使用したものと一致しない場合、または別のワークスペースにリクエストを送信した場合に発生します。また、Brazeがそのgroup_idに対してリクエストを1件も追跡しなかった場合にも発生します。各/users/trackレスポンスでステータス追跡のエラーを確認してください。

/users/trackのレスポンスが予想より遅いのはなぜですか?

成功した/users/trackコールは通常すぐに受け入れられますが、Brazeは属性、イベント、購入の更新を非同期で処理します。ペイロードが大きい場合や、RESTエンドポイントへのネットワークルーティングが遅い場合、体感レイテンシーが増加することがあります。ユーザーごとの同期的な確認応答やコール間のより厳密な順序付けが必要な場合は、/users/track/sync(限定ベータ)を参照してください。

/users/trackが429 Too Many Requestsを返すのはなぜですか?

リクエスト量がレート制限を超えると、/users/trackはHTTP 429 Too Many Requestsレスポンスを返します。リクエストの送信を再開するには、次のようにします。

  1. X-RateLimit-Retry-Afterレスポンスヘッダーで指定された秒数だけリクエストを一時停止します。
  2. 再び429レスポンスが返される可能性を減らすために、より低いレートでリクエストを再開します。
  3. 可能な場合は更新をまとめ、アカウントのリクエストオブジェクト制限に従います。
  4. API使用状況ダッシュボードを使用して、リクエストのスパイクと429レスポンスの傾向を特定します。ワークスペースのデフォルトやその他のエンドポイント制限については、APIレート制限を参照してください。

サポートされている契約での429以外のレスポンスについては、CY 24-25の月間アクティブユーザー数、ユニバーサルMAU、Web MAU、モバイルMAUのレート制限ヘッダーに記載されているX-RateLimit-*レスポンスヘッダーを使用して、現在の時間枠の残りリクエスト数を確認できます。

400 Bad Requestで構文エラーまたはパースエラーが返されるのはなぜですか?

構文エラーまたはパースエラーを伴うHTTP 400は、通常、リクエスト本文が有効なJSONではないことを意味します。一般的な原因には、末尾のカンマ、JSON内のコメント、シングルクォートの文字列、ペイロードの前の余分な開き{、Content-Typeヘッダーがapplication/jsonであるにもかかわらず非JSON本文を送信していることなどがあります。送信前にJSONリンターでペイロードを検証し、HTTPクライアントが(生の文字列を連結するのではなく)オブジェクトをJSONエンコードしていること、本文がUTF-8でエンコードされていることを確認してください。その他の400レスポンス(ペイロードサイズやリクエストごとのオブジェクト制限など)については、致命的エラーとレスポンスおよびこのページのエンドポイント固有のエラーの表を参照してください。

CY 24-25の月間アクティブユーザー数、ユニバーサルMAU、Web MAU、モバイルMAU

新価格体系の顧客の場合、レート制限は会社レベルで適用されます。顧客はワークスペースごとに1時間あたりのレート制限を設定できますが、バースト制限は引き続きすべてのワークスペース間で共有されます。

CY 24-25の月間アクティブユーザー数、ユニバーサルMAU、Web MAU、またはモバイルMAUを購入した顧客の場合、Brazeは/users/trackエンドポイントで異なるレート制限を管理しています。

  • 1時間あたりのレート制限は、アカウントで予想されるデータ取り込みアクティビティに応じて設定されます。このアクティビティは、購入した月間アクティブユーザー数、業界、季節性、またはその他の要因に対応する場合があります。
  • 1時間あたりの制限に加えて、Brazeは3秒ごとに送信できるリクエスト数にバースト制限を適用します。
  • 各リクエストでは、属性、イベント、購入オブジェクトを合わせて最大75件の更新をまとめて送信できます。

予想される取り込みに基づく現在の制限は、ダッシュボードの設定 > APIと識別子 > API使用状況ダッシュボードで確認できます。システムの安定性を保護するため、またはアカウントのデータスループットを向上させるために、レート制限を変更する場合があります。1時間あたりまたは1秒あたりのリクエスト制限やビジネスのニーズに関するご質問やご不明な点については、Brazeサポートまたはカスタマーサクセスマネージャーまでお問い合わせください。

CY 24-25の月間アクティブユーザー数、ユニバーサルMAU、Web MAU、モバイルMAUのレート制限ヘッダー

レート制限されていない(429以外などの)すべてのレスポンスには、1時間あたりのレート制限時間枠の状態をクライアントに示す以下のHTTPレスポンスヘッダーが含まれます。これらのヘッダーを使用してリクエストレートを管理してください。

ヘッダー名 説明
X-RateLimit-Limit 期間ごとに許可されるリクエスト数
X-RateLimit-Remaining 時間枠内に残っているおおよそのリクエスト数
X-RateLimit-Reset 現在の時間枠がリセットされるまでの残り秒数

HTTP 429エラーが発生した場合、RateLimit-Limit、RateLimit-Remaining、RateLimit-Resetヘッダーは返されないことに注意してください。エラーが発生すると、これらのヘッダーはX-RateLimit-Retry-Afterヘッダーに置き換えられ、リクエストを再開できるまでの秒数を示す整数が返されます。

OpenAPIドキュメントをダウンロードして、スキーマの検証に使用できます。方法については、リクエスト検証にOpenAPIスキーマを使用するを参照してください。

New Stuff!