콘텐츠로 건너뛰기

사용자 관계 대체

put

/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 이후에 다시 시도하고 요청 빈도를 줄이세요.
New Stuff!