コンテンツにスキップ

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

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

タイプエンドポイント

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

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

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

ベースURLと認証

ワークスペースのRESTエンドポイントを使用し、Authorization: Bearer YOUR_REST_API_KEY を送信します。このセクションでは、データオブジェクトエンドポイントのホスト先とリクエストの認証方法について説明します。

  • エンドポイントのホストについては、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 オブジェクトリレーションシップの削除

レート制限

このセクションでは、読み取りおよび書き込みトラフィックのデフォルトのリクエストクォータとレスポンスヘッダーについて説明します。

バケット デフォルト制限
データオブジェクト読み取り 1分あたり50リクエスト
データオブジェクト書き込み 1分あたり50リクエスト

すべてのレスポンスには 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 50 requests per minute."
    }
  ]
}

製品の制限

このセクションでは、Brazeがデータオブジェクトに適用する制限と、制限に達した場合の挙動について説明します。

数量の制限

これらの制限は、特に記載がない限り、企業全体に適用されます。Brazeアカウントチームがデフォルト値を調整できます。

制限 デフォルト値
企業あたりのデータオブジェクトレコード数（全ワークスペース合計） 1,000,000
データオブジェクトタイプあたりのフィールド数 500
1人のユーザーにリンクされるデータオブジェクト数 1,000
1つのデータオブジェクトにリンクされるユーザー数 10,000
1つのデータオブジェクトのオブジェクト関係数 1,000

フィールドと値の制限

これらの制限はすべての企業に対して固定です。

制限 値
属性値の長さ 255文字
object_id の長さと形式 250文字。英字、数字、ハイフン、アンダースコアのみ使用可能です。
フィールド名の長さと形式 250文字。英字、数字、アンダースコアのみ使用可能で、アンダースコアで始めることはできません。
予約フィールド名 id、external_id、object_id、display_name はカスタムフィールド名として使用できません。

制限に達した場合の挙動

数量の制限を超えるリクエストは、制限を識別するエラー 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
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: オブジェクト識別子。タイプ内で一意です。
  • braze_id: ユーザーリレーションシップエンドポイントで使用されるBrazeユーザーIDです。
  • 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（デフォルト） 差出人側（発信エッジ） to_data_object
target 宛先側（着信エッジ） 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 — 着信オブジェクトリンクの取得

ページネーションとデータの鮮度

このセクションでは、一覧のページネーション動作と、書き込み後にデータが表示されるまでの想定タイミングについて説明します。

  • 一覧エンドポイントは limit と offset をサポートしています。
  • limit のデフォルトは 100 で、1 から 250 の範囲に制限されます。
  • offset のデフォルトは 0 で、負の値は 0 に切り上げられます。
  • 書き込みは、読み取りおよびLiquidパーソナライゼーションに即座に反映されます。
  • データオブジェクトに基づくセグメントメンバーシップは、計算フィルターが1時間ごとに更新されるため、最大1時間の遅延が発生する可能性があります。

エラーの動作

このセクションでは、データオブジェクトエンドポイント全体で使用されるステータスとエラーレスポンスのパターンについてまとめます。

  • 404、409、422、429 は id と message を含む errors 配列を返します。
  • 400、401、403 は単一の error 文字列を返します。
  • 422 は、リクエストが製品の制限を超えることを意味します。デフォルトの制限値は会社の契約によって異なります。

Brazeカスタマーエンゲージメントプラットフォームのドキュメント。

リソース
法的情報
会社情報
© 2026 Braze, Inc. All rights reserved.
Braze ステータスの確認
New Stuff!