사용자 생성 및 업데이트 (대량)

이 엔드포인트를 사용하여 커스텀 이벤트와 구매를 기록하고 사용자 프로필 속성을 대량으로 업데이트할 수 있습니다.

이 엔드포인트를 사용해야 하는 경우

/users/track 엔드포인트와 마찬가지로, 이 엔드포인트를 사용하여 사용자 프로필을 업데이트할 수 있습니다. 이 엔드포인트는 대량 업데이트에 더 적합합니다:

• 더 큰 요청: 요청당 최대 1,000명의 사용자를 전송할 수 있으므로, 대규모 백필 및 동기화 시 더 적은 요청으로 처리할 수 있습니다.
• 우선순위 지정: 트래픽이 많은 상황에서 /users/track 요청이 /users/track/bulk 요청보다 우선적으로 처리됩니다.

온보딩 중 많은 사용자 프로필을 백필하거나, 일일 동기화의 일부로 대량의 프로필을 동기화할 때 이 엔드포인트를 사용하세요.

필수 조건

이 엔드포인트를 사용하려면 users.track.bulk 권한이 있는 API 키가 필요합니다.

방화벽 뒤에서 서버 간 호출을 수행하는 경우, Braze REST 엔드포인트(예: rest.iad-01.braze.com)를 허용 목록에 추가해야 할 수 있습니다. 자세한 내용은 API 엔드포인트를 참조하세요.

사용량 제한

대부분의 고객에게 이 엔드포인트의 기본 속도 제한은 초당 50건의 요청입니다.

최신 계약을 사용하는 고객은 계약된 월간 활성 사용자 수에 따라 버스트(초당) 및 정상(시간당) 제한이 적용될 수 있습니다.

각 /users/track/bulk 요청의 페이로드 제한은 2MB이며, 계정의 대량 사용량 제한 정책에 따라 속성, 이벤트, 구매 전체에 걸쳐 최대 1,000개의 오브젝트를 포함할 수 있습니다.

각 오브젝트는 한 명의 사용자를 업데이트할 수 있으므로, 단일 요청으로 계정의 요청 오브젝트 제한까지 서로 다른 사용자를 업데이트할 수 있습니다. 또한 각 요청에는 사용자 프로필당 속성, 이벤트, 구매 전체에 걸쳐 최대 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
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
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
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 중 하나를 포함하세요.

하나의 요청에 속성, 이벤트, 구매를 모두 포함할 수 있나요?

네. 계정의 결합된 요청 오브젝트 제한까지 속성, 이벤트, 구매를 자유롭게 조합하여 포함할 수 있습니다.