ユーザーリレーションシップを一括で作成または置換
/data_objects/user_relationships
このエンドポイントを使用して、1 回のリクエストで最大 50 件のユーザーとオブジェクト間のリレーションシップを作成または置換します。

Data Objectsは一般提供されていますが、このエンドポイントを使用するには、ワークスペースでAccountsがプロビジョニングされている必要があります。プロビジョニングをリクエストするには、データ設定 > Accounts に移動し、アンケートに回答してください。詳細については、Accounts を有効にするを参照してください。
Brazeはリクエストを受け付け、バックグラウンドで処理します。202 応答は、バッチがキューに追加されたことを意味し、適用されたことを意味するものではありません。1 件のリレーションシップを変更してすぐに変更を確認するには、ユーザーリレーションシップを置換を使用します。それぞれをどのような場合に使用するかについては、一括エンドポイントを参照してください。
前提条件
このエンドポイントを使用するには、data_objects.user_relationships.bulk_upsert 権限を持つ API キーが必要です。data_objects.user_relationships.create などの単一レコード用の権限では、このエンドポイントへのアクセスは許可されません。
レート制限
このエンドポイントはData Objectsの一括書き込みバケットに属しており、デフォルトの制限はワークスペースごとに 1 分あたり 1,000 リクエストです。この制限は 6 つの一括エンドポイントすべて、およびデータオブジェクトの Cloud Data Ingestion 同期と共有され、単一レコードの書き込み制限とは別に管理されます。
リクエストパラメーター
次の表に、/data_objects/user_relationships エンドポイントの JSON リクエスト本文パラメーターを示し、説明します。
| パラメーター | 必須 | データ型 | 説明 |
|---|---|---|---|
records |
必須 | 配列 | 作成または置換するユーザーリレーションシップ。1~50 件のレコードを含める必要があります。Brazeはその他のトップレベルフィールドをすべて拒否します。 |
records[].type_name |
必須 | 文字列 | ユーザーがリンクされるオブジェクトのタイプ |
records[].object_id |
必須 | 文字列 | ユーザーがリンクされるオブジェクトの識別子 |
records[].rel_kind |
必須 | 文字列 | リレーションシップタイプの名前。有効な値を一覧表示するには、ユーザーリレーションシップタイプを一覧表示を使用します。 |
records[].user |
必須 | オブジェクト | リンクするユーザー。external_id、braze_id、email、phone、alias のいずれか 1 つだけを含める必要があります。0 個または複数個を送信するとエラーになります。 |
records[].user.external_id |
オプション | 文字列 | ユーザーの external ID |
records[].user.braze_id |
オプション | 文字列 | Braze ユーザー ID |
records[].user.email |
オプション | 文字列 | ユーザーのメールアドレス |
records[].user.phone |
オプション | 文字列 | ユーザーの電話番号 |
records[].user.alias |
オプション | オブジェクト | alias_name と alias_label を含むユーザーエイリアスオブジェクト (使用する場合は両方とも必須) |
records[].attributes |
必須 | オブジェクト | フィールド名をキーとするリレーションシップ属性。リレーションシップタイプに属性がない場合は {} を送信します。 |
メールアドレスまたは電話番号が複数のユーザーに一致する場合は、Brazeの標準的なプロファイル選択ルールによってリンクされるユーザーが決まります。
Brazeがバッチを処理する方法
- 検証はオールオアナッシングです。いずれかのレコードが検証に失敗すると、Brazeはリクエスト全体を
400で拒否し、何も保存せず、すべてのエラーを一覧表示します。エラーを修正し、リクエスト全体を再送信してください。 - ルックアップは処理中に行われます。Brazeはバッチを処理する際に、タイプ、リレーションシップタイプ、オブジェクト、ユーザーが存在するかどうか、および属性がリレーションシップタイプのフィールドと一致するかどうかを確認します。
202を返したリクエストでも、後で個々のレコードが失敗する場合があります。処理エラーを参照してください。 - レコードは受信時刻順に並べられます。Brazeはすべてのレコードにリクエストを受信した時刻を付与するため、
updated_atは送信しないでください。これを含むリクエストはBrazeによって拒否されます。2 つのリクエストが同じリレーションシップを変更する場合、Brazeが後に受信したリクエストが優先され、その後に届いた古い書き込みはスキップされます。 - リレーションシップはオブジェクトとユーザーを待機できます。オブジェクトまたはユーザーがまだ存在しないリレーションシップは、すぐに失敗せずに待機します。Brazeは約 40 時間 (10 回) 再試行します。それでもオブジェクトまたはユーザーが存在しない場合、レコードは
data-object-dependency-not-foundで失敗します。
リクエスト例
このセクションには、JSON ペイロードのサンプルと cURL リクエストのサンプルが含まれています。
リクエストペイロードのサンプル
{
"records": [
{
"type_name": "account",
"object_id": "acct-001",
"rel_kind": "owns",
"user": {"external_id": "user-1"},
"attributes": {"role": "admin"}
}
]
}
cURL リクエストのサンプル
この例では、external ID が user-1 のユーザーを owns リレーションシップタイプで acct-001 にリンクし、その role を admin として記録します。
curl --location --request PUT 'https://rest.iad-01.braze.com/data_objects/user_relationships' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"records": [
{
"type_name": "account",
"object_id": "acct-001",
"rel_kind": "owns",
"user": {"external_id": "user-1"},
"attributes": {"role": "admin"}
}
]
}'
応答
このセクションには、成功時の応答のサンプルと応答フィールドが含まれています。
成功時の応答例
ステータスコード 202 は、次の応答本文を返す可能性があります。
{
"source_import_id": "api-20261022T153012123456-9f3a1c2b",
"status": "queued",
"record_count": 1
}
応答パラメーター
次の表に、成功時の応答に含まれるフィールドを示し、説明します。
| パラメーター | 必須 | データ型 | 説明 |
|---|---|---|---|
source_import_id |
必須 | 文字列 | このリクエストに対してBrazeが生成した識別子。各リクエストはそれぞれ独立したインポートです。 |
status |
必須 | 文字列 | 常に queued です。バッチは受け付けられ、処理を待機しています。 |
record_count |
必須 | 整数 | リクエストに含まれるレコードの数 |
処理エラー
Brazeはこれらのコードをエンドポイントから返しません。キューに追加されたバッチを処理する際に、個々のレコードについて記録します。
| コード | 意味 |
|---|---|
data-object-type-not-found |
type_name がワークスペース内のアクティブなタイプを指していません。 |
data-object-relationship-type-not-found |
rel_kind がこのタイプのアクティブなリレーションシップタイプを指していません。 |
data-object-schema-mismatch |
attributes がリレーションシップタイプのフィールドと一致しません。メッセージには、問題のあるすべての属性が示されます。 |
data-object-invalid-user-identifier |
ユーザー識別子を使用してユーザーを検索できません。 |
data-object-ingestion-rejected |
その他の拒否。 |
data-object-dependency-not-found |
約 40 時間再試行した後も、オブジェクトまたはユーザーが存在しませんでした。 |
エラー
400 応答は、Brazeが何も保存しなかったことを意味します。各エラーには、id、message、問題のある parameter (該当する場合)、およびレコードレベルのエラーの場合はレコードの index (records 内での 0 から始まる位置) が含まれます。parameter には、user.external_id のように、リクエストで使用した名前が使われます。
{
"errors": [
{"index": 0, "id": "schema-mismatch", "parameter": "rel_kind", "message": "rel_kind is required"}
]
}
次の表に、このエンドポイントでよく発生するエラーとその解決方法を示します。
| ステータス | 原因 | 対処方法 |
|---|---|---|
400 |
無効なリクエスト (invalid-request): 本文が JSON オブジェクトではないか不正な形式の JSON である、records が存在しないかエントリが 1 件未満または 50 件超である、または本文にBrazeが設定するフィールド (source_type、source_import_id、source_chunk_id、record_type) が含まれている |
唯一のフィールドが records で、1~50 件のレコードを含む JSON オブジェクトを送信してください。 |
400 |
スキーマの不一致 (schema-mismatch): レコードに必須フィールドがない、認識されないフィールド (updated_at を含む) がある、フィールドの型が間違っているか空の文字列である、または user オブジェクトに複数の識別子がある |
一覧表示されたすべてのレコードを修正し、リクエスト全体を再送信してください。 |
400 |
ユーザー識別子の欠落 (missing-user-identifier): レコードの user に識別子がない |
各レコードの user に識別子を 1 つだけ送信してください。 |
401 |
REST API キーが存在しないか無効 | Authorization ヘッダーで Bearer YOUR_REST_API_KEY が使用されていること、およびキーがアクティブであることを確認してください。 |
403 |
API キーに権限がないか、リクエストが許可リストによってブロックされている | キーに data_objects.user_relationships.bulk_upsert 権限があること、および許可リストが設定されている場合は送信元IPがキーの許可リストに含まれていることを確認してください。 |
404 |
会社でData Objectsが有効になっていない | ワークスペースでAccountsがプロビジョニングされていることを確認してください。 |
429 |
レート制限を超過した | X-RateLimit-Reset の後に再試行し、リクエストの頻度を減らしてください。 |
500 |
バッチを受け付けられなかった (internal-error) |
Brazeは何も受け付けていないため、リクエストを安全に再試行できます。 |