사용자 관계 일괄 삭제
/data_objects/user_relationships
이 엔드포인트를 사용하면 한 번의 요청으로 최대 50개의 사용자-오브젝트 관계를 삭제할 수 있습니다.

Data Objects는 정식 출시되었지만, 이 엔드포인트를 사용하려면 먼저 워크스페이스에 Accounts(계정)가 프로비저닝되어 있어야 합니다. 프로비저닝을 요청하려면 데이터 설정 > 계정으로 이동하여 설문지를 작성하세요. 자세한 내용은 Accounts 활성화를 참조하세요.
Braze는 요청을 수락한 후 백그라운드에서 처리합니다. 202 응답은 배치가 적용되었다는 뜻이 아니라 대기줄에 추가되었다는 의미입니다. 관계 하나를 삭제하고 변경 사항을 바로 확인하려면 사용자 관계 삭제를 사용하세요. 각 엔드포인트를 언제 사용해야 하는지는 일괄 엔드포인트를 참조하세요.
전제 조건
이 엔드포인트를 사용하려면 data_objects.user_relationships.bulk_delete 권한이 있는 API 키가 필요합니다. data_objects.user_relationships.delete 같은 단일 레코드 권한으로는 이 엔드포인트에 액세스할 수 없습니다.
사용량 제한
이 엔드포인트는 Data Objects 일괄 쓰기 버킷에 속하며, 기본 제한은 워크스페이스당 분당 1,000건의 요청입니다. 이 제한은 6개의 일괄 엔드포인트 전체와 데이터 오브젝트의 Cloud Data Ingestion 동기화가 함께 공유하며, 단일 레코드 쓰기 제한과는 별개입니다.
요청 매개변수
다음 표에는 /data_objects/user_relationships 엔드포인트의 JSON 요청 본문 매개변수가 나와 있습니다.
| 매개변수 | 필수 | 데이터 유형 | 설명 |
|---|---|---|---|
records |
필수 | 배열 | 삭제할 사용자 관계입니다. 1~50개의 레코드를 포함해야 합니다. Braze는 그 외의 최상위 필드를 모두 거부합니다. |
records[].type_name |
필수 | 문자열 | 사용자가 연결된 오브젝트의 유형 |
records[].object_id |
필수 | 문자열 | 사용자가 연결된 오브젝트의 식별자 |
records[].rel_kind |
필수 | 문자열 | 관계 유형의 이름 |
records[].user |
필수 | 객체 | 연결된 사용자입니다. external_id, braze_id, email, phone, alias 중 정확히 하나만 포함해야 합니다. 하나도 보내지 않거나 둘 이상 보내면 오류가 발생합니다. |
records[].user.external_id |
선택 사항 | 문자열 | 사용자의 외부 ID |
records[].user.braze_id |
선택 사항 | 문자열 | Braze 사용자 ID |
records[].user.email |
선택 사항 | 문자열 | 사용자의 이메일 주소 |
records[].user.phone |
선택 사항 | 문자열 | 사용자의 전화번호 |
records[].user.alias |
선택 사항 | 객체 | alias_name과 alias_label이 포함된 사용자 별칭 객체(사용 시 둘 다 필수) |
이메일 주소나 전화번호가 둘 이상의 사용자와 일치하는 경우, 표준 Braze 프로필 선택 규칙에 따라 영향을 받는 사용자가 결정됩니다.
Braze의 배치 처리 방식
- 유효성 검사는 전부 아니면 전무 방식입니다. 레코드 하나라도 유효성 검사에 실패하면 Braze는 전체 요청을
400으로 거부하고, 아무것도 저장하지 않으며, 모든 오류를 나열합니다. 오류를 수정한 후 전체 요청을 다시 보내세요. - 조회는 처리 중에 이루어집니다. Braze는 배치를 처리할 때 유형, 관계 유형, 오브젝트, 사용자, 관계가 존재하는지 확인합니다. 따라서
202를 반환한 요청이라도 나중에 개별 레코드에서 실패가 발생할 수 있습니다. 처리 실패를 참조하세요. - 레코드는 수신 시간 순으로 정렬됩니다. Braze는 요청을 받은 시간을 모든 레코드에 기록하므로
updated_at을 보내지 마세요. 이 필드가 포함된 요청은 거부됩니다. 두 요청이 같은 관계를 변경하는 경우 Braze가 나중에 받은 요청이 적용되며, 그 이후에 도착한 이전 쓰기는 건너뜁니다. - 삭제는 대기할 수 있습니다. 아직 존재하지 않는 관계를 삭제하면 즉시 실패하지 않고 대기합니다. Braze는 약 40시간 동안(10회) 재시도합니다. 그 후에도 관계가 존재하지 않으면 해당 레코드는
data-object-dependency-not-found로 실패합니다.
요청 예시
이 섹션에는 JSON 페이로드 샘플과 cURL 요청 샘플이 포함되어 있습니다.
요청 페이로드 샘플
{
"records": [
{"type_name": "account", "object_id": "acct-001", "rel_kind": "owns", "user": {"external_id": "user-1"}}
]
}
cURL 요청 샘플
이 예시는 외부 ID가 user-1인 사용자와 acct-001 사이의 owns 관계를 제거합니다. 고객 프로필과 계정 레코드는 모두 그대로 유지됩니다.
curl --location --request DELETE 'https://rest.iad-01.braze.com/data_objects/user_relationships' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"records": [
{"type_name": "account", "object_id": "acct-001", "rel_kind": "owns", "user": {"external_id": "user-1"}}
]
}'
응답
이 섹션에는 성공 응답 샘플과 응답 필드가 포함되어 있습니다.
성공 응답 예시
상태 코드 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이 워크스페이스의 활성 유형과 일치하지 않습니다. |
data-object-relationship-type-not-found |
rel_kind가 이 유형의 활성 관계 유형과 일치하지 않습니다. |
data-object-invalid-user-identifier |
사용자 식별자로 사용자를 찾을 수 없습니다. |
data-object-ingestion-rejected |
그 밖의 모든 거부입니다. |
data-object-dependency-not-found |
약 40시간 동안 재시도한 후에도 관계가 여전히 존재하지 않습니다. |
오류
400 응답은 Braze가 아무것도 저장하지 않았다는 의미입니다. 각 오류에는 id, message, 문제가 된 parameter(해당하는 경우), 그리고 레코드 수준 오류의 경우 레코드의 index(records 내 0부터 시작하는 위치)가 포함됩니다. parameter에는 user.external_id처럼 요청에 사용한 이름이 그대로 표시됩니다.
다음 표에는 이 엔드포인트의 일반적인 오류와 해결 방법이 나와 있습니다.
| 상태 | 원인 | 안내 |
|---|---|---|
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 포함)가 있거나, 유형이 잘못되었거나 빈 문자열인 필드가 있거나, user 객체에 식별자가 둘 이상 있는 경우 |
나열된 모든 레코드를 수정한 후 전체 요청을 다시 보내세요. |
400 |
사용자 식별자 누락(missing-user-identifier): 레코드의 user에 식별자가 없는 경우 |
각 레코드의 user에 식별자를 정확히 하나만 보내세요. |
401 |
REST API 키가 없거나 유효하지 않음 | Authorization 헤더가 Bearer YOUR_REST_API_KEY를 사용하는지, 키가 활성 상태인지 확인하세요. |
403 |
API 키에 권한이 없거나 허용 목록에 의해 요청이 차단됨 | 키에 data_objects.user_relationships.bulk_delete 권한이 있는지, 그리고 허용 목록이 구성된 경우 소스 IP가 키 허용 목록에 있는지 확인하세요. |
404 |
회사에 Data Objects가 활성화되어 있지 않음 | 워크스페이스에 Accounts가 프로비저닝되어 있는지 확인하세요. |
429 |
사용량 제한 초과 | X-RateLimit-Reset 이후에 재시도하고 요청 빈도를 줄이세요. |
500 |
배치를 수락할 수 없음(internal-error) |
Braze가 아무것도 수락하지 않았으므로 요청을 안전하게 재시도할 수 있습니다. |