コンテンツにスキップ

データオブジェクトエンドポイント

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

オブジェクトエンドポイント

オブジェクトリレーションシップエンドポイント

ユーザーリレーションシップエンドポイント

ベース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の読み取り 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_types
    • GET /data_objects/types/{type_name}/object_relationship_types
  • 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 をマージします。

実践例

この例では、一般的なアカウントのワークフローを示します。

  1. account/acct-123 を作成します。
  2. 子アカウントとして account/acct-456 を作成します。
  3. rel_kind: account_user を使用して、ユーザーを acct-123 にリンクします。
  4. 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

一括エンドポイント

一括エンドポイントを使用すると、自社システムのデータオブジェクト、オブジェクトの関係、ユーザーの関係をバッチで同期できます。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 は、リクエストが製品の制限を超えることを意味します。デフォルトの制限値は、会社の契約によって異なります。

New Stuff!