コンテンツにスキップ

データオブジェクトを一括で作成または置換

put

/data_objects/objects

このエンドポイントを使用して、任意のタイプを組み合わせた最大50個のデータオブジェクトを1回のリクエストで作成または置換します。

Brazeはリクエストを受け付け、バックグラウンドで処理します。202 応答は、バッチがキューに入ったことを意味し、適用済みであることを意味するものではありません。1つのデータオブジェクトを変更してその変更をすぐに確認するには、データオブジェクトを置換を使用してください。それぞれの使い分けについては、一括エンドポイントを参照してください。

前提条件

このエンドポイントを使用するには、data_objects.bulk_upsert 権限を持つ API キーが必要です。data_objects.create などの単一レコード用の権限では、このエンドポイントにアクセスできません。

レート制限

このエンドポイントはData Objectsの一括書き込みバケットに含まれ、デフォルトの制限はワークスペースごとに毎分1,000リクエストです。この制限は6つの一括エンドポイントすべて、およびデータオブジェクトのCloud Data Ingestion同期の間で共有され、単一レコードの書き込み制限とは別に適用されます。

リクエストパラメーター

次の表に、/data_objects/objects エンドポイントのJSONリクエスト本文パラメーターとその説明を示します。

パラメーター 必須 データ型 説明
records 必須 配列 作成または置換するデータオブジェクト。1~50個のレコードを含める必要があります。Brazeはその他のトップレベルフィールドをすべて拒否します。
records[].type_name 必須 文字列 データオブジェクトタイプのマシン名。タイプはすでに存在している必要があります。このエンドポイントがタイプを作成することはありません。
records[].object_id 必須 文字列 オブジェクトの識別子。単一レコードエンドポイントのパスにおける object_id と同じ値です。
records[].attributes 必須 オブジェクト フィールド名をキーとするオブジェクトの属性。各フィールドは、タイプにすでに定義されている必要があります。

Brazeによるバッチの処理方法

  • 検証はオールオアナッシングです。いずれかのレコードが検証に失敗した場合、Brazeはリクエスト全体を 400 で拒否し、何も保存せず、すべてのエラーを一覧表示します。エラーを修正し、リクエスト全体を再送信してください。
  • ルックアップは処理中に行われます。Brazeはバッチを処理する際に、各タイプが存在するかどうか、および属性がタイプのフィールドと一致するかどうかを確認します。そのため、202 を返したリクエストでも、後で個々のレコードが失敗する場合があります。処理の失敗を参照してください。
  • レコードは受信時刻順に処理されます。Brazeはすべてのレコードにリクエストを受信した時刻を記録するため、updated_at は送信しないでください。これを含むリクエストはBrazeにより拒否されます。2つのリクエストが同じオブジェクトを変更する場合、Brazeが後に受信したほうが優先され、その後に到着した古い書き込みはスキップされます。
  • アップサートは待機しません。オブジェクトのアップサートが他のレコードを待つことはありません。同じオブジェクトの削除後に受信したアップサートは、そのオブジェクトを再作成します。

リクエスト例

このセクションには、JSONペイロードのサンプルとcURLリクエストのサンプルが含まれています。

リクエストペイロードのサンプル

{
  "records": [
    {"type_name": "account", "object_id": "acct-001", "attributes": {"name": "Acme"}},
    {"type_name": "opportunity", "object_id": "opp-001", "attributes": {"amount": 10}}
  ]
}

cURLリクエストのサンプル

この例では、同じリクエスト内で account レコード1件と opportunity レコード1件を作成または置換します。

curl --location --request PUT 'https://rest.iad-01.braze.com/data_objects/objects' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "records": [
    {"type_name": "account", "object_id": "acct-001", "attributes": {"name": "Acme"}},
    {"type_name": "opportunity", "object_id": "opp-001", "attributes": {"amount": 10}}
  ]
}'

応答

このセクションには、成功時の応答のサンプルと応答フィールドが含まれています。

成功時の応答例

ステータスコード 202 は、次の応答本文を返す可能性があります。

{
  "source_import_id": "api-20261022T153012123456-9f3a1c2b",
  "status": "queued",
  "record_count": 2
}

応答パラメーター

次の表に、成功時の応答に含まれるフィールドとその説明を示します。

パラメーター 必須 データ型 説明
source_import_id 必須 文字列 Brazeがこのリクエストに対して生成した識別子。各リクエストはそれぞれ独立したインポートです。
status 必須 文字列 常に queued です。バッチは受け付けられ、処理を待っています。
record_count 必須 整数 リクエスト内のレコード数

処理の失敗

Brazeはこれらのコードをエンドポイントから返しません。キューに入ったバッチを処理する際に、個々のレコードに対して記録します。

コード 意味
data-object-type-not-found type_name で指定されたアクティブなタイプがワークスペースに存在しません。
data-object-schema-mismatch attributes がタイプのフィールドと一致しません。メッセージには、問題のあるすべての属性が示されます。
data-object-ingestion-rejected 拒否された object_id など、その他の拒否。

エラー

400 応答は、Brazeが何も保存しなかったことを意味します。各エラーには、id、message、問題のある parameter (該当する場合)、およびレコードレベルのエラーの場合はレコードの index (records 内の0から始まる位置) が含まれます。

次の表に、このエンドポイントの一般的なエラーとその解決方法を示します。

ステータス 原因 対処方法
400 無効なリクエスト (invalid-request):本文がJSONオブジェクトではないか形式が正しくないJSONである、records が欠落しているかエントリ数が1未満または50を超えている、または本文にBrazeが設定するフィールド (source_type、source_import_id、source_chunk_id、または record_type) が含まれている records のみをフィールドとし、1~50個のレコードを含むJSONオブジェクトを送信してください。
400 スキーマの不一致 (schema-mismatch):レコードに必須フィールドが欠落している、認識されないフィールド (updated_at を含む) がある、またはフィールドの型が正しくないか空の文字列である 一覧表示されたすべてのレコードを修正し、リクエスト全体を再送信してください。
401 REST API キーが欠落しているか無効 Authorization ヘッダーで Bearer YOUR_REST_API_KEY が使用されていること、およびキーが有効であることを確認してください。
403 API キーに権限がないか、リクエストが許可リストによってブロックされている キーに data_objects.bulk_upsert があること、および許可リストが設定されている場合は送信元IPがキーの許可リストに含まれていることを確認してください。
404 会社でData Objectsが有効になっていない ワークスペースでAccountsがプロビジョニングされていることを確認してください。
429 レート制限を超過した X-RateLimit-Reset の後に再試行し、リクエストの頻度を減らしてください。
500 バッチを受け付けられなかった (internal-error) Brazeは何も受け付けていないため、リクエストを安全に再試行できます。
New Stuff!