データオブジェクトエンドポイント
これらのエンドポイントを使用して、データオブジェクトタイプの一覧取得、データオブジェクトレコードの管理、オブジェクトとユーザーのリレーションシップの管理を行います。

データオブジェクトは一般提供されていますが、これらのエンドポイントを使用する前に、ワークスペースでアカウントのプロビジョニングを完了しておく必要があります。プロビジョニングをリクエストするには、データ設定 > アカウントに移動し、アンケートに回答してください。プロビジョニングが完了すると、データオブジェクトの API キー権限が設定 > API キーに表示されます。詳細については、アカウントを有効にするを参照してください。
タイプエンドポイント
オブジェクトエンドポイント
オブジェクトリレーションシップエンドポイント
ユーザーリレーションシップエンドポイント
ベースURLと認証
ワークスペースのRESTエンドポイントを使用し、Authorization: Bearer YOUR_REST_API_KEY を送信します。このセクションでは、Data Objectsエンドポイントのホスト先と、リクエストの認証方法について説明します。
- エンドポイントのホストについては、Braze APIの概要を参照してください。
- すべてのリクエストとレスポンスのペイロードはJSONです。
- リクエストの対象範囲は、API キーを所有するワークスペースに限定されます。
- キーにIP許可リストが設定されている場合、許可リストにないIPアドレスからのリクエストには
403が返されます。
API キーの権限
このセクションでは、各エンドポイントと必要な権限の対応を示します。API キーのスコープを安全に設定する際に活用してください。
| 権限 | エンドポイントグループ |
|---|---|
data_objects.read |
タイプとオブジェクトの読み取り、およびオブジェクトの関係の読み取り |
data_objects.create |
オブジェクトの作成 |
data_objects.update |
オブジェクトの置換と更新 |
data_objects.delete |
オブジェクトの削除 |
data_objects.user_relationships.read |
ユーザーの関係の読み取り |
data_objects.user_relationships.create |
ユーザーの関係の作成 |
data_objects.user_relationships.update |
ユーザーの関係の置換と更新 |
data_objects.user_relationships.delete |
ユーザーの関係の削除 |
data_objects.object_relationships.create |
オブジェクトの関係の作成 |
data_objects.object_relationships.update |
オブジェクトの関係の置換と更新 |
data_objects.object_relationships.delete |
オブジェクトの関係の削除 |
data_objects.bulk_upsert |
オブジェクトの一括作成または置換 |
data_objects.bulk_delete |
オブジェクトの一括削除 |
data_objects.object_relationships.bulk_upsert |
オブジェクトの関係の一括作成または置換 |
data_objects.object_relationships.bulk_delete |
オブジェクトの関係の一括削除 |
data_objects.user_relationships.bulk_upsert |
ユーザーの関係の一括作成または置換 |
data_objects.user_relationships.bulk_delete |
ユーザーの関係の一括削除 |

オブジェクトの関係の読み取りには data_objects.read を使用します。data_objects.object_relationships.read という権限はありません。
一括エンドポイントは専用の権限を使用し、アップサートと削除はそれぞれ別の権限です。data_objects.create などの単一レコード用の権限では、一括エンドポイントへのアクセスは許可されません。
レート制限
このセクションでは、読み取りと書き込みの両方のトラフィックに適用されるデフォルトのリクエストクォータとレスポンスヘッダーについて説明します。
| バケット | デフォルトの制限 |
|---|---|
| Data Objectsの読み取り | 1分あたり1000リクエスト |
| Data Objectsの書き込み | 1分あたり1000リクエスト |
| Data Objectsの一括書き込み | 1分あたり1000リクエスト。6つの一括エンドポイント、およびデータオブジェクトのCloud Data Ingestion同期の間で共有されます |
一括書き込みの制限はワークスペースごとに適用され、単一レコードの書き込み制限とは別に適用されます。
すべてのレスポンスには、X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset が含まれます。
制限を超えたリクエストに対しては、Brazeは 429 と、id および message を含むエラーペイロードを返します。
{
"errors": [
{
"id": "rate-limit-exceeded",
"message": "You have exceeded your limit of 1000 requests per minute."
}
]
}
製品の制限
このセクションでは、Brazeがデータオブジェクトに適用する制限と、制限に達したときの動作について説明します。これらの制限がアカウントレコードにどのように適用されるかについては、アカウントオブジェクトの制限を参照してください。
件数の制限
特に記載がない限り、これらの制限は会社全体に適用されます。これらは初期の上限値です。より多くのレコードや、より高い制限が必要な場合は、Brazeのアカウントチームに連絡して引き上げをリクエストしてください。
| 制限 | デフォルト値 |
|---|---|
| 会社あたりのデータオブジェクトレコード数 (すべてのワークスペースの合計) | 50,000 |
| データオブジェクトタイプあたりのフィールド数 | 500 |
| 1人のユーザーにリンクされたデータオブジェクト数 | 1,000 |
| 1つのデータオブジェクトにリンクされたユーザー数 | 10,000 |
| 1つのデータオブジェクトのオブジェクトの関係の数 | 1,000 |
フィールドと値の制限
これらの制限はすべての会社で固定されています。
| 制限 | 値 |
|---|---|
| 関係タイプあたりのフィールド数 (ユーザーの関係とオブジェクトの関係) | 25。関係フィールドは、データオブジェクトタイプあたりのフィールド数の制限にはカウントされません。 |
| 属性値の長さ | 255文字 |
| 日付フィールド | 時刻とタイムゾーンを含むRFC 3339形式の日時文字列 (2026-11-03T00:00:00Z など)。2026-11-03 のような日付のみの値は、Brazeによって拒否されます。詳細については、日付フィールドの形式を参照してください。 |
object_id の長さと形式 |
250文字。英字、数字、ハイフン、アンダースコアのみ使用できます。 |
| フィールド名の長さと形式 | 250文字。英字、数字、アンダースコアのみ使用でき、アンダースコアで始めることはできません。 |
| 予約済みのフィールド名 | id、external_id、object_id、display_name はカスタムフィールド名として使用できません。 |
日付フィールドの形式
日付フィールドには、時刻とタイムゾーンの両方を含むRFC 3339形式の日時文字列のみを指定できます。Brazeが時刻やタイムゾーンを推測する必要がないように、完全な値が必要です。データウェアハウス内の更新日や契約日など、ソースに日付のみの値が保存されている場合は、送信前に (たとえばウェアハウスの変換処理で) 変換してください。
| 値 | 結果 |
|---|---|
2026-11-03T00:00:00Z |
受け付けられます |
2026-11-03T00:00:00-05:00 |
受け付けられます |
2026-11-03 |
時刻とタイムゾーンがないため拒否されます |
2026-11-03T00:00:00 |
タイムゾーンがないため拒否されます |
この形式は、データオブジェクト、ユーザーの関係、オブジェクトの関係の日付フィールドに適用されます。拒否された値をBrazeがどのように報告するかは、送信方法によって異なります。
- 単一レコードの作成、置換、更新の各エンドポイントは
400を返します。複数の属性が無効な場合、エラーには最初の1つのみが示されます。 - 一括アップサートエンドポイントは
202でリクエストを受け付けた後、そのレコードについてdata-object-schema-mismatchの処理エラー (attributes: renewal_date is not valid for its fieldなど) を記録します。 - Cloud Data Ingestionの同期は一括エンドポイントと同じ処理を使用するため、Brazeは日付のみの値を含む行を適用せず、エラーは同期ログに表示されます。
たとえば、renewal_date 日付フィールドに 2026-11-03 を送信する単一レコードのリクエストは、次の 400 レスポンスを返します。
{
"error": "Validation failed: Attrs do not conform to field definitions: The property '#/renewal_date' must be a valid RFC3339 date/time string"
}
制限に達した場合の動作
件数の制限を超えるリクエストは、該当する制限を示すエラー id とともに 422 を返します。
{
"errors": [
{
"id": "data-object-record-limit-exceeded",
"message": "This company has reached its data object record limit"
}
]
}
| 制限 | エラー id |
|---|---|
| 会社あたりのデータオブジェクトレコード数 | data-object-record-limit-exceeded |
| データオブジェクトタイプあたりのフィールド数 | data-object-field-limit-exceeded |
| 関係タイプあたりのフィールド数 | data-object-field-limit-exceeded |
| 1人のユーザーにリンクされたデータオブジェクト数 | data-objects-per-user-limit-exceeded |
| 1つのデータオブジェクトにリンクされたユーザー数 | users-per-data-object-limit-exceeded |
| 1つのデータオブジェクトのオブジェクトの関係の数 | data-object-relationship-limit-exceeded |
既存のレコードと関係はそのまま保持され、制限を超えるリクエストのみが拒否されます。制限内に空きを作るには、不要になったレコードを削除するか、使用していない関係を削除してください。件数の制限を引き上げるには、Brazeのアカウントチームに連絡してください。
object_id や属性値が長すぎるなど、検証に失敗したリクエストは 400 を返します。レート制限を超えたリクエストは 429 を返します。
主要な概念
このセクションでは、すべてのデータオブジェクトエンドポイントで使用される主要な識別子について説明します。
type_name: データオブジェクトタイプのマシン名。ワークスペース内で一意です。object_id: オブジェクトの識別子。タイプ内で一意です。user: ユーザーリレーションシップの書き込みリクエストにおけるユーザー。external_id、braze_id、alias、email、phoneのいずれか1つだけで識別します。attributes: フィールド名をキーとするオブジェクトまたはリレーションシップのデータ。設定されたスキーマに基づいて検証されます。
リレーションシップの仕組み
このセクションでは、エンドポイントのリファレンスページを使用する前に知っておくべき、リレーションシップタイプ、リレーションシップエッジ、および anchor の動作について説明します。
リレーションシップモデルの概要
この図では、タイプ、レコード、リレーションシップの関係と、それらをリンクすることでBrazeで何ができるようになるかを示しています。タイプはダッシュボードで定義し、レコードとレコード間のリンクはこれらのエンドポイントを通じて書き込みます。
%%{init: {"flowchart": {"wrappingWidth": 400}} }%%
flowchart LR
subgraph define["Set up in the dashboard"]
objtype["Data object types define<br/>the fields a record has"]
reltype["Relationship types determine<br/>which links are allowed"]
end
subgraph write["Write with the API"]
person["A person you<br/>send messages to"]
record["A business record<br/>they belong to"]
related["Another record<br/>connected to it"]
person -- "A user relationship links<br/>a person to a record" --> record
record -- "An object relationship links<br/>one record to another" --> related
end
subgraph unlock["What it unlocks"]
segment["Segment people by the<br/>records they belong to"]
liquid["Personalize messages with<br/>data from those records"]
end
define -- "decides what you<br/>are allowed to link" --> write
write -- "makes these<br/>possible" --> unlock
タイプとエッジは別物です
- リレーションシップタイプは、どのリンクが有効かを定義するもので、ダッシュボードで管理します。
- リレーションシップエッジはレコード間の実際のリンクで、これらのAPIエンドポイントを通じて作成、更新、削除します。
- リレーションシップを書き込む前に、次のエンドポイントで有効な
rel_kindの値を一覧取得してください。GET /data_objects/types/{type_name}/user_relationship_typesGET /data_objects/types/{type_name}/object_relationship_types
オブジェクトのリレーションシップに related_type_name が必要な理由
rel_kindは、すべてのオブジェクトタイプのペアにわたって一意であるとは限りません。たとえば、あるオブジェクトタイプのペアではrel_kindがsubaccountで、別のペアではpartner_accountになる場合があります。- そのため、オブジェクトのリレーションシップを書き込む際には、
rel_kindとrelated_type_nameの両方を指定して、意図したリレーションシップタイプと、関連付けのもう一方のオブジェクトタイプを特定する必要があります。 related_type_nameがそのrel_kindのリレーションシップタイプと一致しない場合、リクエストは400を返します。
anchor はリレーションシップの方向を制御します
オブジェクトのリレーションシップには方向があります。URLのオブジェクトは anchor に基づいて解釈されます。
anchor |
URLオブジェクトの役割 | レスポンス内の関連オブジェクトのキー |
|---|---|---|
source (デフォルト) |
From側 (送信エッジ) | to_data_object |
target |
To側 (受信エッジ) | from_data_object |
反対側の anchor の視点から同じエッジを作成しても、対象となるのは基になる1つのリレーションシップです。同じエッジに対して2回目の作成呼び出しを行うと、409 (duplicate-object-relationship) が返されます。
ユーザーのリレーションシップにおけるパスの非対称性
ユーザーのリレーションシップの読み取りと書き込みでは、意図的に異なるエンドポイントパスを使用します。
- 読み取り:
GET /data_objects/objects/{type_name}/{object_id}/user_relationships - 書き込み:
POST|PUT|PATCH|DELETE /data_objects/objects/{type_name}/{object_id}/users
リレーションシップの属性はオブジェクトの属性とは別です
- リレーションシップのエンドポイントは、エッジレベルの属性をトップレベルの
attributesフィールドで返します。 - オブジェクトの属性は、
to_data_objectまたはfrom_data_objectの下にネストされたままです。 PUTはリレーションシップのattributesを置き換え、PATCHはリレーションシップのattributesをマージします。
実践例
この例では、一般的なアカウントのワークフローを示します。
account/acct-123を作成します。- 子アカウントとして
account/acct-456を作成します。 rel_kind: account_userを使用して、ユーザーをacct-123にリンクします。rel_kind: subaccountを使用して、acct-123をacct-456にリンクします。
リンクを読み取るには、次のエンドポイントを使用します。
- リンクされたユーザーの場合:
GET /data_objects/objects/account/acct-123/user_relationships - 送信側のオブジェクトリンクの場合:
GET /data_objects/objects/account/acct-123/object_relationships - 受信側のオブジェクトリンクの場合:
GET /data_objects/objects/account/acct-456/object_relationships?anchor=target

オブジェクトのリレーションシップとユーザーのリレーションシップの DELETE エンドポイントには、JSONリクエスト本文が必要です。
一括エンドポイント
一括エンドポイントを使用すると、自社システムのデータオブジェクト、オブジェクトの関係、ユーザーの関係をバッチで同期できます。1回のリクエストで最大50件のレコードを作成、置換、または削除でき、Brazeはそのバッチをバックグラウンドで処理します。
| メソッド | エンドポイント | 目的 |
|---|---|---|
PUT |
/data_objects/objects |
最大50件のデータオブジェクト (タイプの混在も可) を作成または置換します |
DELETE |
/data_objects/objects |
最大50件のデータオブジェクト (タイプの混在も可) を削除します |
PUT |
/data_objects/object_relationships |
最大50件のオブジェクト間の関係を作成または置換します |
DELETE |
/data_objects/object_relationships |
最大50件のオブジェクト間の関係を削除します |
PUT |
/data_objects/user_relationships |
最大50件のユーザーとオブジェクトの関係を作成または置換します |
DELETE |
/data_objects/user_relationships |
最大50件のユーザーとオブジェクトの関係を削除します |
一括エンドポイントを使用する場面
自社システムから多数のレコードを同期し、レスポンスが返る前に各変更が適用されている必要がない場合は、一括エンドポイントを使用します。変更をすぐに反映させる必要がある場合、レコードを読み取る必要がある場合、または PATCH でレコードの一部の属性だけを更新したい場合は、単一レコード用のエンドポイントを使用します。
一括エンドポイントは、単一レコード用のエンドポイントと次の点で異なります。
- 処理は非同期です。
202レスポンスは、Brazeがバッチを受け付けてキューに追加したことを意味し、レコードが適用されたことを意味するものではありません。Brazeは、バッチの処理時に、タイプ、関係タイプ、オブジェクト、ユーザーが存在するかどうか、および属性がタイプのフィールドと一致するかどうかを確認します。202が返されたリクエストでも、後から個々のレコードで失敗が発生する場合があります。 - 検証はすべて成功するか、すべて失敗するかのいずれかです。リクエスト内のいずれかのレコードが検証に失敗した場合、Brazeはリクエスト全体を
400で拒否し、何も保存せずに、すべてのエラーを一覧で返します。 - レコードは受信時刻の順に処理されます。Brazeはすべてのレコードにリクエストを受信した時刻を記録するため、
updated_atは送信しないでください。2つのリクエストが同じレコードを変更する場合、Brazeが後に受信したリクエストが優先されます。 - レコードは依存関係を待機することがあります。まだ存在しないオブジェクトや関係の削除、およびオブジェクトやユーザーがまだ存在しない関係は、すぐに失敗せずに待機します。Brazeは約40時間 (10回) 再試行します。オブジェクトのアップサートが待機することはありません。
- 一括エンドポイントは独自の API キー権限を使用し、ワークスペースごとに1分あたり1,000リクエストのレート制限を共有します。
- 一括エンドポイントがデータオブジェクトタイプを作成することはありません。すべての
type_nameが事前に存在している必要があります。
製品の制限は、単一レコード用のエンドポイントと同様に一括エンドポイントにも適用されます。
ページネーションとデータの鮮度
このセクションでは、一覧取得時のページネーションの動作と、書き込み後にデータが参照可能になるまでの想定タイミングについて説明します。
- 一覧取得エンドポイントは
limitとoffsetをサポートしています。 limitのデフォルトは100で、1から250の範囲に制限されます。offsetのデフォルトは0で、負の値は0に補正されます。- 単一レコードの書き込みは、読み取りとLiquidによるパーソナライゼーションにすぐに反映されます。一括書き込みは、Brazeがキューに入ったバッチを処理した時点で適用されます。
- データオブジェクトに基づくセグメントのメンバーシップは、計算フィルターが1時間ごとに更新されるため、最大1時間遅れる場合があります。
エラーの動作
このセクションでは、Data Objectsエンドポイント全体で使用されるステータスとエラーレスポンスのパターンをまとめています。
404、409、422、429は、idとmessageを含むerrors配列を返します。400、401、403は、単一のerror文字列を返します。- 一括エンドポイントは、
400および500エラーを、idとmessageを含むerrors配列として返します。400エラーには、原因となったparameterがある場合はそれも含まれ、レコードレベルのエラーの場合はそのレコードのindexも含まれます。 422は、リクエストが製品の制限を超えることを意味します。デフォルトの制限値は、会社の契約によって異なります。