コンテンツにスキップ

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

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

タイプエンドポイント

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

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

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

ベース 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分あたり1000リクエスト
データオブジェクトの書き込み 1分あたり1000リクエスト

すべてのレスポンスには、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文字
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
リレーションシップタイプあたりのフィールド数 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!