사용자 관계 대체
/data_objects/objects/{type_name}/{object_id}/users
이 엔드포인트를 사용하여 사용자 관계 하나를 생성하거나 대체할 수 있습니다.

데이터 오브젝트는 정식 출시되었지만, 이 엔드포인트를 사용하려면 먼저 워크스페이스에 계정 기능이 프로비저닝되어 있어야 합니다. 프로비저닝을 요청하려면 데이터 설정 > 계정으로 이동하여 설문지를 작성하세요. 자세한 내용은 계정 활성화를 참조하세요.
전제 조건
이 엔드포인트를 사용하려면 data_objects.user_relationships.update 권한이 있는 API 키가 필요합니다.
사용량 제한
이 엔드포인트는 데이터 오브젝트 쓰기 버킷에 속하며, 기본 제한은 분당 1,000회 요청입니다.
경로 매개변수
다음 표에는 /data_objects/objects/{type_name}/{object_id}/users 엔드포인트의 경로 매개변수와 그 설명이 나와 있습니다.
| 매개변수 | 필수 | 데이터 유형 | 설명 |
|---|---|---|---|
type_name |
필수 | 문자열 | 오브젝트 유형 |
object_id |
필수 | 문자열 | 오브젝트 식별자 |
요청 매개변수
다음 표에는 /data_objects/objects/{type_name}/{object_id}/users 엔드포인트의 JSON 요청 본문 매개변수와 그 설명이 나와 있습니다.
| 매개변수 | 필수 | 데이터 유형 | 설명 |
|---|---|---|---|
user |
필수 | 오브젝트 | 오브젝트와 연결할 사용자입니다. external_id, braze_id, alias, email, phone 중 정확히 하나를 포함해야 합니다. |
user.external_id |
선택 사항 | 문자열 | 사용자의 외부 ID입니다. |
user.braze_id |
선택 사항 | 문자열 | Braze 사용자 ID입니다. |
user.alias |
선택 사항 | 오브젝트 | alias_name 및 alias_label을 포함하는 사용자 별칭 오브젝트입니다(사용 시 둘 다 필수). |
user.email |
선택 사항 | 문자열 | 사용자의 이메일 주소입니다. |
user.phone |
선택 사항 | 문자열 | 사용자의 전화번호입니다. E.164 형식으로 변환할 수 있어야 합니다. |
rel_kind |
필수 | 문자열 | 관계 종류 |
attributes |
선택 사항 | 오브젝트 | 관계 속성 |
사용자 식별
user에는 식별자를 정확히 하나만 전달하세요. null이 아닌 식별자가 없거나 두 개 이상이면400이 반환됩니다. 유효한 식별자 하나와 함께 null 식별자 필드를 보내는 것은 허용됩니다.- 이메일 또는 전화번호가 두 개 이상의 고객 프로필과 일치하면 Braze는 식별된 사용자(
external_id가 있는 사용자)를 선택합니다. 그래도 동률이면 Braze는 가장 최근에 업데이트된 프로필을 선택합니다. - 가능하면
external_id를 사용하세요.
요청 예시
이 섹션에는 샘플 JSON 페이로드와 샘플 cURL 요청이 포함되어 있습니다.
샘플 요청 페이로드
{
"user": {
"external_id": "user-123"
},
"rel_kind": "account_user",
"attributes": {
"role": "admin"
}
}
사용자 별칭을 사용하는 다른 예시:
{
"user": {
"alias": {
"alias_name": "[email protected]",
"alias_label": "crm_email"
}
},
"rel_kind": "account_user",
"attributes": {
"role": "admin"
}
}
샘플 cURL 요청
이 예시는 사용자와 acct-123 사이의 account_user 관계에 설정된 속성을 대체하며, 이전에 저장된 속성은 모두 덮어씁니다.
curl --location --request PUT 'https://rest.iad-01.braze.com/data_objects/objects/account/acct-123/users' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"user": {
"external_id": "user-123"
},
"rel_kind": "account_user",
"attributes": {
"role": "admin"
}
}'
응답
이 섹션에는 샘플 성공 응답과 응답 필드가 포함되어 있습니다.
성공 응답 예시
상태 코드 200은 다음과 같은 응답 본문을 반환할 수 있습니다.
{
"user_relationship": {
"type_name": "account",
"object_id": "acct-123",
"rel_kind": "account_user",
"user": {
"external_id": "user-123",
"braze_id": "507f1f77bcf86cd799439011"
},
"attributes": { "role": "admin" }
}
}
응답 매개변수
다음 표에는 성공 응답에 포함되는 필드와 그 설명이 나와 있습니다.
| 매개변수 | 필수 | 데이터 유형 | 설명 |
|---|---|---|---|
user_relationship |
필수 | 오브젝트 | 생성되거나 대체된 사용자 관계 레코드 |
user_relationship.type_name |
필수 | 문자열 | 데이터 오브젝트 유형의 머신 이름 |
user_relationship.object_id |
필수 | 문자열 | 데이터 오브젝트 식별자 |
user_relationship.rel_kind |
필수 | 문자열 | 관계 종류 값 |
user_relationship.user |
필수 | 오브젝트 | 전송된 식별자와 braze_id를 포함하는 연결된 사용자 오브젝트 |
user_relationship.attributes |
필수 | 오브젝트 | 관계 속성(항상 포함되며, 속성이 없으면 빈 오브젝트) |
오류
다음 표에는 이 엔드포인트에서 자주 발생하는 오류와 해결 방법이 나와 있습니다.
| 상태 | 원인 | 안내 |
|---|---|---|
400 |
user가 누락되었거나 비어 있음, 식별자 없음, 식별자가 두 개 이상, 빈 식별자, 형식이 잘못된 braze_id, email 또는 alias, E.164로 변환할 수 없는 전화번호, 또는 이전 방식의 최상위 braze_id 본문 |
유효한 식별자를 정확히 하나 포함한 user 오브젝트를 전송하세요. |
400 |
해당 유형에 대해 알 수 없는 rel_kind 또는 스키마 유효성 검사 오류 |
rel_kind가 해당 오브젝트 유형에 유효한지, attributes가 관계 스키마와 일치하는지 확인하세요. |
404 |
관계, 오브젝트 또는 사용자를 찾을 수 없음(user-not-found 또는 data-object-relationship-not-found) |
오브젝트, 사용자, 관계 키 값이 모두 존재하는지 확인하세요. |
422 |
사용자당 오브젝트 제한 도달(data-objects-per-user-limit-exceeded) 또는 오브젝트당 사용자 제한 도달(users-per-data-object-limit-exceeded) |
해당 사용자 또는 오브젝트의 관계 수를 줄이거나, 워크스페이스 제한에 대해 Braze 지원팀에 문의하세요. |
401 |
REST API 키가 누락되었거나 유효하지 않음 | Authorization 헤더에 Bearer YOUR_REST_API_KEY가 사용되었는지, 해당 키가 활성 상태인지 확인하세요. |
403 |
API 키에 권한이 없거나 허용 목록에 의해 요청이 차단됨 | 해당 키에 data_objects.user_relationships.update 권한이 있는지, 그리고 허용 목록을 구성한 경우 소스 IP가 키 허용 목록에 포함되어 있는지 확인하세요. |
429 |
사용량 제한 초과 | X-RateLimit-Reset 이후에 다시 시도하고 요청 빈도를 줄이세요. |