Skip to content

ユーザーの作成と更新（一括）

post

/users/track/bulk

core endpoint

このエンドポイントを使用して、カスタムイベントと購入を記録し、ユーザープロファイル属性を一括で更新します。

このエンドポイントを使用するタイミング

/users/trackエンドポイントと同様に、このエンドポイントを使用してユーザープロファイルを更新できます。このエンドポイントは一括更新に適しています。

  • より大きなリクエスト: 1リクエストあたり最大1,000ユーザーを送信できるため、大規模なバックフィルや同期に必要なリクエスト数を減らせます。
  • 優先順位付け: ピークトラフィック時には、/users/trackへのリクエストが/users/track/bulkへのリクエストよりも優先されます。

オンボーディング中に多数のユーザープロファイルをバックフィルする場合や、日次同期の一部として大量のプロファイルを同期する場合に、このエンドポイントを使用してください。

前提条件

このエンドポイントを使用するには、users.track.bulk権限を持つAPIキーが必要です。

ファイアウォールの背後でサーバー間呼び出しを行う場合は、Braze RESTエンドポイント（例: rest.iad-01.braze.com）を許可リストに追加する必要がある場合があります。詳細については、APIエンドポイントを参照してください。

レート制限

ほとんどの顧客の場合、このエンドポイントの基本速度制限は1秒あたり50リクエストです。

新しい契約の顧客は、契約された月間アクティブユーザー数に基づくバースト（秒単位）およびステディ（時間単位）の制限が適用される場合があります。

各/users/track/bulkリクエストのペイロード制限は2 MBで、アカウントの一括レート制限ポリシーに応じて、属性、イベント、購入全体で最大1,000オブジェクトを含めることができます。

各オブジェクトは1人のユーザーを更新できるため、1回のリクエストでアカウントのリクエストオブジェクト制限までの異なるユーザーを更新できます。さらに、各リクエストには、属性、イベント、購入全体でユーザープロファイルあたり最大100オブジェクトを含めることができます。

リクエスト本文

1
2

Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5

{
  "attributes": (optional, array of attributes object),
  "events": (optional, array of event object),
  "purchases": (optional, array of purchase object)
}

リクエストパラメーター

リクエスト例

1回のリクエストでユーザープロファイルを一括更新する

1回のリクエストで、アカウントのリクエストオブジェクト制限までのユーザープロファイルを更新します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

curl --location --request POST 'https://rest.iad-01.braze.com/users/track/bulk' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "attributes": [
    {
      "external_id": "user1",
      "string_attribute": "fruit",
      "boolean_attribute_1": true,
      "integer_attribute": 25,
      "array_attribute": [
        "banana",
        "apple"
      ]
    },
    {
      "external_id": "user2",
      "string_attribute": "vegetables",
      "boolean_attribute_1": false,
      "integer_attribute": 25,
      "array_attribute": [
        "broccoli",
        "asparagus"
      ]
    }
  ]
}'

1回のリクエストで属性とイベントを送信する

アカウントの合計オブジェクト制限まで、同じリクエストに属性とイベントを含めます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

curl --location --request POST 'https://rest.iad-01.braze.com/users/track/bulk' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "attributes": [
    {
      "external_id": "user1",
      "string_attribute": "fruit",
      "boolean_attribute_1": true,
      "integer_attribute": 25,
      "array_attribute": [
        "banana",
        "apple"
      ]
    }
  ],
  "events": [
    {
      "external_id": "user2",
      "app_id": "your_app_identifier",
      "name": "rented_movie",
      "time": "2022-12-06T19:20:45+01:00",
      "properties": {
        "release": {
          "studio": "FilmStudio",
          "year": "2022"
        },
        "cast": [
          {
            "name": "Actor1"
          },
          {
            "name": "Actor2"
          }
        ]
      }
    }
  ]
}'

応答

成功メッセージ

成功メッセージは次の応答を返します。

1
2
3
4
5
6

{
  "message": "success",
  "attributes_processed": (optional, integer), if attributes are included in the request, this returns an integer of the number of external IDs with attributes that Braze queued for processing,
  "events_processed": (optional, integer), if events are included in the request, this returns an integer of the number of events that Braze queued for processing,
  "purchases_processed": (optional, integer), if purchases are included in the request, this returns an integer of the number of purchases that Braze queued for processing
}

非致命的エラーを含む成功メッセージ

リクエストが成功したが非致命的エラーがある場合（例: 大きなバッチ内の1つの無効なイベントオブジェクト）、次の応答を受け取ります。

1
2
3
4
5
6
7
8

{
  "message": "success",
  "errors": [
    {
      <minor error message>
    }
  ]
}

致命的エラーを含むメッセージ

リクエストに致命的エラーがある場合、次の応答を受け取ります。

1
2
3
4
5
6
7
8

{
  "message": <fatal error message>,
  "errors": [
    {
      <fatal error message>
    }
  ]
}

致命的エラーの応答コード

リクエストに致命的エラーがある場合にBrazeが返すステータスコードと関連するエラーメッセージについては、致命的エラーと応答を参照してください。

「provided external_id is blacklisted and disallowed」というエラーを受け取った場合、リクエストに「ダミーユーザー」が含まれている可能性があります。詳細については、スパムブロックを参照してください。

よくある質問

このエンドポイントと/users/trackのどちらを使用すべきですか？

ユースケースに基づいて両方のエンドポイントを使用してください。

  • 大規模なバックフィルや同期には、/users/track/bulkを使用します。
  • リアルタイムのユースケースには、/users/trackを使用します。

/users/track/bulkで使用できる識別子は何ですか？

各リクエストオブジェクトに、external_id、braze_id、user_alias、email、またはphoneのいずれかを含めてください。

1回のリクエストに属性、イベント、購入を含めることはできますか？

はい。アカウントの合計リクエストオブジェクト制限まで、属性、イベント、購入を任意に組み合わせて含めることができます。
New Stuff!