사용자 생성 및 업데이트 (동기)
이 엔드포인트를 사용하여 사용자 지정 이벤트와 구매를 기록하고 사용자 프로필 속성을 동기식으로 업데이트할 수 있습니다. 이 엔드포인트는 비동기식으로 고객 프로필을 업데이트하는
/users/track엔드포인트와 유사한 기능을 합니다.
이 엔드포인트는 현재 제한된 베타 상태입니다. 현재 베타에 새로운 고객을 추가하고 있지 않지만, 이 기능이 귀하의 Braze 통합에 유용할 것 같다면 Braze 계정 매니저에게 알려주십시오.
동기 및 비동기 API 호출
비동기 호출에서 API는 상태 코드 201을 반환하여 요청이 성공적으로 수신되고 이해되었으며 수락되었음을 나타냅니다. 그러나 이것이 요청이 완전히 완료되었다는 것을 의미하지는 않습니다.
동기 호출에서 API는 상태 코드 201을 반환하여 요청이 성공적으로 수신되고 이해되었으며 수락되고 완료되었음을 나타냅니다. 호출 응답은 작업의 결과로 선택된 사용자 프로필 필드를 보여줍니다.
이 엔드포인트는 /users/track 엔드포인트보다 요금 한도가 낮습니다(아래 요금 한도 참조). 각 /users/track/sync 요청에는 하나의 이벤트 객체, 하나의 속성 객체 또는 하나의 구매 객체만 포함할 수 있습니다. 이 엔드포인트는 동기 호출이 필요한 사용자 프로필 업데이트를 위해 예약해야 합니다. 정상적인 구현을 위해 /users/track/sync 및 /users/track을 함께 사용하는 것이 좋습니다.
예를 들어 동일한 사용자에 대해 짧은 시간 동안 연속적인 요청을 보내는 경우 비동기식 /users/track 엔드포인트를 사용하면 경합 조건이 가능하지만 /users/track/sync 엔드포인트를 사용하면 2XX 응답을 받은 후 각각 요청을 순차적으로 보낼 수 있습니다.
필수 조건
이 엔드포인트를 사용하려면 users.track.sync 권한이 있는 API 키가 필요합니다.
서버 간 호출에 API를 사용하는 고객이 방화벽 뒤에 있는 경우 rest.iad-01.braze.com 허용 목록에 추가해야 할 수 있습니다.
사용량 제한
모든 고객에 대해 이 엔드포인트에 분당 500건의 기본 요청 속도 제한을 적용합니다. 각 /users/track/sync 요청에는 최대 하나의 이벤트 객체, 하나의 속성 객체 또는 하나의 구매 객체가 포함될 수 있습니다. 각 개체(이벤트, 속성 및 구매 배열)는 각각 한 명의 사용자를 업데이트할 수 있습니다.
요청 본문
1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
1
2
3
4
5
{
"attributes": (optional, one attributes object),
"events": (optional, one event object),
"purchases": (optional, one purchase object),
}
요청 매개변수
다음 표에 나열된 각 요청 구성 요소에 대해 external_id, user_alias, braze_id, email 또는 phone 중 하나를 포함해야 합니다.
| 매개변수 | 필수 | 데이터 유형 | 설명 |
|---|---|---|---|
attributes |
선택 사항 | 하나의 속성 개체 | 사용자 속성 개체 보기 |
events |
선택 사항 | 하나의 이벤트 객체 | 이벤트 개체 보기 |
purchases |
선택 사항 | 하나의 구매 개체 | 구매 개체 보기 |
응답
이 엔드포인트의 요청 매개변수를 사용할 때는 성공 메시지 또는 치명적인 오류가 있는 메시지 중 하나의 응답을 받아야 합니다.
성공 메시지
성공적인 메시지는 Braze가 업데이트한 사용자 프로필 데이터에 대한 정보를 포함하는 다음 응답을 반환합니다.
1
2
3
4
5
6
7
{
"users": (optional, object), the identifier of the user in the request. May be empty if no users are found and _update_existing_only key is set to true,
"custom_attributes": (optional, object), the custom attributes as a result of the request. Braze lists only custom attributes from the request,
"custom_events": (optional, object), the custom events as a result of the request. Braze lists only custom events from the request,
"purchase_events": (optional, object), the purchase events as a result of the request. Braze lists only purchase events from the request,
},
"message": "success"
치명적인 오류가 있는 메시지
메시지에 치명적인 오류가 있는 경우 다음과 같은 응답이 표시됩니다:
1
2
3
4
5
6
7
8
{
"message": <fatal error message>,
"errors": [
{
<fatal error message>
}
]
}
요청 및 응답 예시
외부 ID로 사용자 지정 속성 업데이트
요청
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl --location --request POST 'https://rest.iad-01.braze.com/users/track/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
"attributes": [
{
"external_id": "xyz123",
"string_attribute": "fruit",
"boolean_attribute_1": true,
"integer_attribute": 25,
"array_attribute": [
"banana",
"apple"
]
}
]
}'
응답
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"users": [
{
"external_id": "xyz123",
"custom_attributes": {
"string_attribute": "fruit",
"boolean_attribute_1": true,
"integer_attribute": 25,
"array_attribute": [
"banana",
"apple",
]
}
}
],
"message": "success"
}
이메일로 사용자 지정 이벤트 업데이트
요청
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/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
"events": [
{
"email": "[email protected]",
"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
7
8
9
10
11
12
13
14
15
16
{
"users": [
{
"email": "[email protected]",
"custom_events": [
{
"name": "rented_movie",
"first": "2022-01-001T00:00:00.000Z",
"last": "2022-12-06T18:20:45.000Z",
"count": 10
}
]
}
],
"message": "success"
}
사용자 별칭으로 구매 이벤트 업데이트
요청
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
curl --location --request POST 'https://rest.iad-01.braze.com/users/track/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
"purchases" : [
{
"user_alias" : {
"alias_name" : "device123",
"alias_label" : "my_device_identifier"
}
"app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
"product_id" : "Completed Order",
"currency" : "USD",
"price" : 219.98,
"time" : "2022-12-06T19:20:45+01:00",
"properties" : {
"products" : [
{
"name": "Monitor",
"category": "Gaming",
"product_amount": 19.99
},
{
"name": "Gaming Keyboard",
"category": "Gaming ",
"product_amount": 199.99
}
]
}
}
]
}'
응답
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"users": [
{
"user_alias" : {
"alias_name" : "device123",
"alias_label" : "my_device_identifier"
},
"purchase_events": [
{
"product_id": "Completed Order",
"first": "2013-07-16T19:20:30+01:00",
"last": "2022-12-06T18:20:45.000Z",
"count": 3
}
]
}
],
"message": "success"
}
자주 묻는 질문
비동기식 엔드포인트와 동기식 엔드포인트 중 무엇을 사용해야 하나요?
대부분의 프로필 업데이트의 경우 /users/track 엔드포인트가 더 높은 비율 제한과 요청을 배치할 수 있는 유연성 덕분에 가장 잘 작동합니다. 그러나 /users/track/sync 엔드포인트는 동일한 사용자에 대한 빠른 연속 요청으로 인해 경합 조건이 발생하는 경우 유용합니다.
응답 시간이 /users/track 엔드포인트와 다른가요?
동기 호출에서는 API가 Braze가 요청을 완료할 때까지 응답을 반환하지 않습니다. 그 결과, 동기 요청은 평균적으로 /users/track에 대한 비동기 요청보다 더 오래 걸립니다. 대부분의 요청에 대해 몇 초 내에 응답을 받을 수 있습니다.
동시에 여러 요청을 보낼 수 있나요?
예, 요청이 서로 다른 사용자를 대상으로 하거나 각 요청이 한 사용자에 대해 서로 다른 속성, 이벤트, 구매를 업데이트하는 경우에만 가능합니다.
동일한 속성, 이벤트 또는 구매에 대해 사용자에 대해 여러 요청을 전송하는 경우, Braze는 경합 조건이 발생하지 않도록 각 요청 사이에 성공적인 응답을 기다릴 것을 권장합니다.
응답 값이 원래 요청의 값과 일치하지 않는 이유는 무엇인가요?
요청이 완료되었지만 사용자 지정 속성 값이 업데이트되지 않았을 수 있습니다. 이는 커스텀 속성 업데이트가 최대 문자 수를 초과하거나 배열 제한을 초과하거나 사용자가 Braze에 존재하지 않는데 _update_existing_only = true인 경우에 발생할 수 있습니다.
이러한 경우 응답을 요청이 완료되었지만 원하는 업데이트가 이루어지지 않았다는 표시로 간주하세요. 위에서 이러한 문제가 발생할 수 있는 이유를 살펴보세요.
GitHub 에서 이 페이지를 편집합니다.