コンテンツにスキップ

オブジェクトリレーションシップを一括で作成または置換

put

/data_objects/object_relationships

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

Brazeはリクエストを受け付け、バックグラウンドで処理します。202 応答は、バッチがキューに追加されたことを意味し、適用されたことを意味するものではありません。1件のリレーションシップを変更してすぐに変更を確認するには、オブジェクトリレーションシップを置換を使用してください。それぞれの使い分けについては、一括エンドポイントを参照してください。

前提条件

このエンドポイントを使用するには、data_objects.object_relationships.bulk_upsert 権限を持つ API キーが必要です。data_objects.object_relationships.create などの単一レコード用の権限では、このエンドポイントへのアクセスは許可されません。

レート制限

このエンドポイントはData Objectsの一括書き込みバケットに含まれ、デフォルトの制限はワークスペースごとに毎分1,000リクエストです。この制限は6つの一括エンドポイントすべて、およびデータオブジェクトのCloud Data Ingestion同期で共有され、単一レコードの書き込み制限とは別に設定されています。

リクエストパラメーター

次の表は、/data_objects/object_relationships エンドポイントの JSON リクエスト本文パラメーターの一覧と説明です。

パラメーター 必須 データタイプ 説明
records 必須 配列 作成または置換するオブジェクトリレーションシップ。1~50件のレコードを含める必要があります。Brazeはその他のトップレベルフィールドをすべて拒否します。
records[].type_name 必須 文字列 ソースオブジェクトのタイプ
records[].object_id 必須 文字列 ソースオブジェクトの識別子
records[].rel_kind 必須 文字列 リレーションシップタイプの名前。有効な値を一覧表示するには、オブジェクトリレーションシップタイプの一覧表示を使用します。
records[].related_type_name 必須 文字列 ターゲットオブジェクトのタイプ
records[].related_object_id 必須 文字列 ターゲットオブジェクトの識別子
records[].attributes 必須 オブジェクト フィールド名をキーとするリレーションシップ属性。リレーションシップタイプに属性がない場合は {} を送信します。

Brazeによるバッチの処理方法

  • 検証はオールオアナッシングです。いずれかのレコードが検証に失敗すると、Brazeはリクエスト全体を 400 で拒否し、何も保存せず、すべてのエラーを一覧表示します。エラーを修正し、リクエスト全体を再送信してください。
  • ルックアップは処理中に行われます。Brazeは、バッチの処理時に、タイプ、リレーションシップタイプ、オブジェクトが存在するかどうか、および属性がリレーションシップタイプのフィールドと一致するかどうかを確認します。202 を返したリクエストでも、後で個々のレコードが失敗する場合があります。処理エラーを参照してください。
  • レコードは受信時刻順に並べられます。Brazeはすべてのレコードにリクエストを受信した時刻を付与するため、updated_at は送信しないでください。これを含むリクエストはBrazeによって拒否されます。2つのリクエストが同じリレーションシップを変更する場合、Brazeが後に受信したリクエストが優先され、その後に到着した古い書き込みはスキップされます。
  • リレーションシップはオブジェクトを待機できます。ソースまたはターゲットのオブジェクトがまだ存在しないリレーションシップは、すぐに失敗せずに待機します。Brazeは約40時間 (10回) 再試行します。それでもオブジェクトが存在しない場合、レコードは data-object-dependency-not-found で失敗します。

リクエスト例

このセクションでは、JSON ペイロードのサンプルと cURL リクエストのサンプルを紹介します。

リクエストペイロードのサンプル

{
  "records": [
    {
      "type_name": "contact",
      "object_id": "contact-001",
      "rel_kind": "works_at",
      "related_type_name": "account",
      "related_object_id": "acct-001",
      "attributes": {"since": "2024-01-15T00:00:00Z"}
    }
  ]
}

cURL リクエストのサンプル

この例では、works_at リレーションシップタイプで contact-001 を acct-001 にリンクし、リレーションシップの開始日時を記録します。

curl --location --request PUT 'https://rest.iad-01.braze.com/data_objects/object_relationships' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "records": [
    {
      "type_name": "contact",
      "object_id": "contact-001",
      "rel_kind": "works_at",
      "related_type_name": "account",
      "related_object_id": "acct-001",
      "attributes": {"since": "2024-01-15T00:00:00Z"}
    }
  ]
}'

応答

このセクションでは、成功時の応答のサンプルと応答フィールドを紹介します。

成功応答の例

ステータスコード 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 または related_type_name が、ワークスペース内のアクティブなタイプを指していません。
data-object-relationship-type-not-found rel_kind が、これらのタイプのアクティブなリレーションシップタイプを指していません。
data-object-schema-mismatch attributes がリレーションシップタイプのフィールドと一致しません。メッセージには問題のあるすべての属性が示されます。
data-object-ingestion-rejected その他の拒否です。
data-object-dependency-not-found 約40時間の再試行後も、ソースまたはターゲットのオブジェクトが存在しませんでした。

エラー

400 応答は、Brazeが何も保存しなかったことを意味します。各エラーには id、message、問題のある parameter (存在する場合)、およびレコードレベルのエラーの場合はレコードの index (records 内の0から始まる位置) が含まれます。

{
  "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 を含む) がある、またはフィールドの型が誤っているか空の文字列である 一覧表示されたすべてのレコードを修正し、リクエスト全体を再送信してください。
401 REST API キーがないか無効 Authorization ヘッダーで Bearer YOUR_REST_API_KEY が使用されていること、およびキーがアクティブであることを確認してください。
403 API キーに権限がないか、リクエストが許可リストによってブロックされている キーに data_objects.object_relationships.bulk_upsert 権限があること、および許可リストが設定されている場合は送信元 IP がキーの許可リストに含まれていることを確認してください。
404 会社でData Objectsが有効になっていない ワークスペースでAccountsがプロビジョニングされていることを確認してください。
429 レート制限を超過した X-RateLimit-Reset の時刻以降に再試行し、リクエストの頻度を減らしてください。
500 バッチを受け付けられなかった (internal-error) Brazeは何も受け付けていないため、リクエストを安全に再試行できます。
New Stuff!