コンテンツにスキップ

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

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

タイプエンドポイント

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

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

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

ベース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（デフォルト） 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 で受信オブジェクトリンクを取得

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

このセクションでは、一覧取得のページネーション動作と、書き込み後のデータ反映タイミングについて説明します。

  • 一覧取得エンドポイントは 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!