데이터 객체 엔드포인트
이 엔드포인트를 사용하여 데이터 객체 유형을 나열하고, 데이터 객체 레코드를 관리하며, 객체 관계와 사용자 관계를 관리할 수 있습니다.

데이터 객체는 정식 출시되었지만, 이 엔드포인트를 사용하려면 먼저 워크스페이스에 계정이 프로비저닝되어 있어야 합니다. 프로비저닝을 요청하려면 데이터 설정 > 계정으로 이동하여 설문지를 작성하세요. 프로비저닝이 완료되면 데이터 객체 API 키 권한이 설정 > API 키에 표시됩니다. 자세한 내용은 계정 활성화를 참조하세요.
유형 엔드포인트
객체 엔드포인트
객체 관계 엔드포인트
사용자 관계 엔드포인트
기본 URL 및 인증
워크스페이스 REST 엔드포인트를 사용하고 Authorization: Bearer YOUR_REST_API_KEY를 전송하세요. 이 섹션에서는 데이터 오브젝트 엔드포인트가 호스팅되는 위치와 요청이 인증되는 방식을 설명합니다.
- 엔드포인트 호스트는 Braze API 개요를 참조하세요.
- 모든 요청 및 응답 페이로드는 JSON 형식입니다.
- 요청은 API 키를 소유한 워크스페이스로 범위가 지정됩니다.
- 키에 IP 허용 목록이 설정되어 있는 경우, 허용 목록에 없는 IP 주소에서 보낸 요청은
403을 반환합니다.
API 키 권한
이 섹션에서는 각 엔드포인트에 필요한 권한을 정리합니다. 이를 참고하여 API 키의 권한 범위를 안전하게 설정할 수 있습니다.
| 권한 | 엔드포인트 그룹 |
|---|---|
data_objects.read |
유형 및 오브젝트 읽기, 오브젝트 관계 읽기 |
data_objects.create |
오브젝트 생성 |
data_objects.update |
오브젝트 교체 및 업데이트 |
data_objects.delete |
오브젝트 삭제 |
data_objects.user_relationships.read |
사용자 관계 읽기 |
data_objects.user_relationships.create |
사용자 관계 생성 |
data_objects.user_relationships.update |
사용자 관계 교체 및 업데이트 |
data_objects.user_relationships.delete |
사용자 관계 삭제 |
data_objects.object_relationships.create |
오브젝트 관계 생성 |
data_objects.object_relationships.update |
오브젝트 관계 교체 및 업데이트 |
data_objects.object_relationships.delete |
오브젝트 관계 삭제 |
data_objects.bulk_upsert |
오브젝트 일괄 생성 또는 교체 |
data_objects.bulk_delete |
오브젝트 일괄 삭제 |
data_objects.object_relationships.bulk_upsert |
오브젝트 관계 일괄 생성 또는 교체 |
data_objects.object_relationships.bulk_delete |
오브젝트 관계 일괄 삭제 |
data_objects.user_relationships.bulk_upsert |
사용자 관계 일괄 생성 또는 교체 |
data_objects.user_relationships.bulk_delete |
사용자 관계 일괄 삭제 |

오브젝트 관계 읽기에는 data_objects.read 권한을 사용합니다. data_objects.object_relationships.read 권한은 존재하지 않습니다.
일괄 엔드포인트는 별도의 권한을 사용하며, 업서트와 삭제 권한도 서로 분리되어 있습니다. data_objects.create와 같은 단일 레코드 권한으로는 일괄 엔드포인트에 액세스할 수 없습니다.
사용량 제한
이 섹션에서는 읽기 및 쓰기 트래픽의 기본 요청 할당량과 응답 헤더에 대해 설명합니다.
| 버킷 | 기본 제한 |
|---|---|
| 데이터 오브젝트 읽기 | 분당 1,000건의 요청 |
| 데이터 오브젝트 쓰기 | 분당 1,000건의 요청 |
| 데이터 오브젝트 일괄 쓰기 | 분당 1,000건의 요청. 6개의 일괄 엔드포인트 및 데이터 오브젝트의 클라우드 데이터 수집 동기화와 함께 공유됩니다 |
일괄 쓰기 제한은 워크스페이스별로 적용되며, 단일 레코드 쓰기 제한과는 별도로 적용됩니다.
모든 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset이 포함됩니다.
요청이 제한되면 Braze는 429와 함께 id 및 message가 포함된 오류 페이로드를 반환합니다.
{
"errors": [
{
"id": "rate-limit-exceeded",
"message": "You have exceeded your limit of 1000 requests per minute."
}
]
}
제품 제한
이 섹션에서는 Braze가 데이터 오브젝트에 적용하는 제한과 제한에 도달했을 때 어떤 일이 발생하는지 설명합니다. 이러한 제한이 계정 레코드에 어떻게 적용되는지는 계정 오브젝트 제한을 참조하세요.
개수 제한
별도로 명시되지 않는 한 이 제한은 회사 전체에 적용됩니다. 표의 값은 기본 제공 용량입니다. 더 많은 레코드나 더 높은 제한이 필요하면 Braze 계정 팀에 연락하여 상향을 요청하세요.
| 제한 | 기본값 |
|---|---|
| 회사당 데이터 오브젝트 레코드 수(모든 워크스페이스 합계) | 50,000 |
| 데이터 오브젝트 유형당 필드 수 | 500 |
| 사용자 한 명에게 연결된 데이터 오브젝트 수 | 1,000 |
| 데이터 오브젝트 하나에 연결된 사용자 수 | 10,000 |
| 데이터 오브젝트 하나의 오브젝트 관계 수 | 1,000 |
필드 및 값 제한
이 제한은 모든 회사에 동일하게 고정 적용됩니다.
| 제한 | 값 |
|---|---|
| 관계 유형당 필드 수(사용자 관계 및 오브젝트 관계) | 25. 관계 필드는 데이터 오브젝트 유형당 필드 수 제한에 포함되지 않습니다. |
| 속성 값 길이 | 255자 |
| 날짜 필드 | 2026-11-03T00:00:00Z처럼 시간과 시간대를 포함하는 RFC 3339 날짜-시간 문자열입니다. Braze는 2026-11-03과 같이 날짜만 있는 값을 거부합니다. 자세한 내용은 날짜 필드 형식을 참조하세요. |
object_id 길이 및 형식 |
250자. 문자, 숫자, 하이픈, 밑줄만 사용할 수 있습니다. |
| 필드 이름 길이 및 형식 | 250자. 문자, 숫자, 밑줄만 사용할 수 있으며 밑줄로 시작할 수 없습니다. |
| 예약된 필드 이름 | id, external_id, object_id, display_name은 커스텀 필드 이름으로 사용할 수 없습니다. |
날짜 필드 형식
날짜 필드에는 시간과 시간대를 모두 포함하는 RFC 3339 날짜-시간 문자열만 사용할 수 있습니다. Braze는 시간이나 시간대를 추측하지 않도록 전체 값을 요구합니다. 데이터 웨어하우스에 저장된 갱신일이나 계약일처럼 소스에 날짜만 있는 값이 저장되어 있다면, 전송하기 전에 웨어하우스 변환 단계 등에서 값을 변환하세요.
| 값 | 결과 |
|---|---|
2026-11-03T00:00:00Z |
허용됨 |
2026-11-03T00:00:00-05:00 |
허용됨 |
2026-11-03 |
시간 또는 시간대가 없으므로 거부됨 |
2026-11-03T00:00:00 |
시간대가 없으므로 거부됨 |
이 형식은 데이터 오브젝트, 사용자 관계, 오브젝트 관계의 날짜 필드에 적용됩니다. Braze가 거부된 값을 보고하는 방식은 값을 전송하는 방법에 따라 다릅니다.
- 단일 레코드 생성, 교체, 업데이트 엔드포인트는
400을 반환합니다. 유효하지 않은 속성이 여러 개인 경우 오류에는 첫 번째 속성만 표시됩니다. - 일괄 업서트 엔드포인트는
202로 요청을 수락한 다음, 해당 레코드에 대해attributes: renewal_date is not valid for its field와 같은data-object-schema-mismatch처리 실패를 기록합니다. - 클라우드 데이터 수집 동기화는 일괄 엔드포인트와 동일한 처리 방식을 사용하므로, Braze는 날짜만 있는 값이 포함된 행을 적용하지 않으며 실패 내역은 동기화 로그에 표시됩니다.
예를 들어 renewal_date 날짜 필드에 2026-11-03을 전송하는 단일 레코드 요청은 다음과 같은 400 응답을 반환합니다.
{
"error": "Validation failed: Attrs do not conform to field definitions: The property '#/renewal_date' must be a valid RFC3339 date/time string"
}
제한에 도달하면 어떻게 되나요
개수 제한을 초과하는 요청은 해당 제한을 식별하는 오류 id와 함께 422를 반환합니다.
{
"errors": [
{
"id": "data-object-record-limit-exceeded",
"message": "This company has reached its data object record limit"
}
]
}
| 제한 | 오류 id |
|---|---|
| 회사당 데이터 오브젝트 레코드 수 | data-object-record-limit-exceeded |
| 데이터 오브젝트 유형당 필드 수 | data-object-field-limit-exceeded |
| 관계 유형당 필드 수 | data-object-field-limit-exceeded |
| 사용자 한 명에게 연결된 데이터 오브젝트 수 | data-objects-per-user-limit-exceeded |
| 데이터 오브젝트 하나에 연결된 사용자 수 | users-per-data-object-limit-exceeded |
| 데이터 오브젝트 하나의 오브젝트 관계 수 | data-object-relationship-limit-exceeded |
기존 레코드와 관계는 그대로 유지되며, 제한을 초과하는 요청만 거부됩니다. 제한 내에서 여유 공간을 확보하려면 더 이상 필요하지 않은 레코드를 삭제하거나 사용하지 않는 관계를 제거하세요. 개수 제한을 상향하려면 Braze 계정 팀에 문의하세요.
object_id 또는 속성 값이 너무 긴 경우처럼 유효성 검사에 실패한 요청은 400을 반환합니다. 사용량 제한을 초과한 요청은 429를 반환합니다.
핵심 개념
이 섹션에서는 모든 데이터 오브젝트 엔드포인트에서 사용하는 주요 식별자를 정의합니다.
type_name: 데이터 오브젝트 유형의 머신 이름으로, 워크스페이스 내에서 고유합니다.object_id: 오브젝트 식별자로, 유형 내에서 고유합니다.user: 사용자 관계 쓰기 요청의 대상 사용자로,external_id,braze_id,alias,email,phone중 정확히 하나로 식별합니다.attributes: 필드 이름을 키로 하는 오브젝트 또는 관계 데이터로, 구성된 스키마를 기준으로 유효성을 검사합니다.
관계 작동 방식
이 섹션에서는 엔드포인트 참조 페이지를 사용하기 전에 알아야 할 관계 유형, 관계 엣지, anchor 동작을 설명합니다.
관계 모델 개요
이 다이어그램은 유형, 레코드, 관계가 서로 어떻게 연결되는지, 그리고 이들을 연결하면 Braze에서 무엇을 할 수 있는지 보여줍니다. 유형은 대시보드에서 정의하고, 레코드와 레코드 간의 링크는 이 엔드포인트를 통해 작성합니다.
%%{init: {"flowchart": {"wrappingWidth": 400}} }%%
flowchart LR
subgraph define["Set up in the dashboard"]
objtype["Data object types define<br/>the fields a record has"]
reltype["Relationship types determine<br/>which links are allowed"]
end
subgraph write["Write with the API"]
person["A person you<br/>send messages to"]
record["A business record<br/>they belong to"]
related["Another record<br/>connected to it"]
person -- "A user relationship links<br/>a person to a record" --> record
record -- "An object relationship links<br/>one record to another" --> related
end
subgraph unlock["What it unlocks"]
segment["Segment people by the<br/>records they belong to"]
liquid["Personalize messages with<br/>data from those records"]
end
define -- "decides what you<br/>are allowed to link" --> write
write -- "makes these<br/>possible" --> unlock
유형과 엣지는 별개입니다
- 관계 유형은 어떤 링크가 유효한지 정의하며 대시보드에서 관리합니다.
- 관계 엣지는 레코드 간의 실제 링크이며, 이 API 엔드포인트를 통해 생성, 업데이트, 삭제합니다.
- 관계를 작성하기 전에 다음 엔드포인트로 유효한
rel_kind값 목록을 조회하세요.GET /data_objects/types/{type_name}/user_relationship_typesGET /data_objects/types/{type_name}/object_relationship_types
객체 관계에 related_type_name이 필요한 이유
rel_kind는 모든 객체 유형 쌍에 걸쳐 전역적으로 고유하지 않습니다. 예를 들어rel_kind는 한 객체 유형 쌍에서는subaccount이고 다른 쌍에서는partner_account일 수 있습니다.- 따라서 객체 관계를 작성할 때는 의도한 관계 유형과 연결의 상대편 객체 유형을 식별하기 위해
rel_kind와related_type_name이 모두 필요합니다. related_type_name이 해당rel_kind의 관계 유형과 일치하지 않으면 요청은400을 반환합니다.
anchor는 관계 방향을 제어합니다
객체 관계에는 방향이 있습니다. URL 객체는 anchor에 따라 해석됩니다.
anchor |
URL 객체 역할 | 응답의 관련 객체 키 |
|---|---|---|
source (기본값) |
시작 측(나가는 엣지) | to_data_object |
target |
대상 측(들어오는 엣지) | from_data_object |
반대쪽 anchor 관점에서 같은 엣지를 생성해도 하나의 기본 관계를 대상으로 합니다. 같은 엣지에 대해 두 번째 생성 호출을 하면 409(duplicate-object-relationship)를 반환합니다.
사용자 관계의 경로 비대칭
사용자 관계 읽기와 쓰기는 의도적으로 서로 다른 엔드포인트 경로를 사용합니다.
- 읽기:
GET /data_objects/objects/{type_name}/{object_id}/user_relationships - 쓰기:
POST|PUT|PATCH|DELETE /data_objects/objects/{type_name}/{object_id}/users
관계 속성은 객체 속성과 별개입니다
- 관계 엔드포인트는 엣지 수준 속성을 최상위
attributes필드에 반환합니다. - 객체 속성은
to_data_object또는from_data_object아래에 중첩되어 유지됩니다. PUT은 관계attributes를 교체하고,PATCH는 관계attributes를 병합합니다.
실습 예제
이 예제는 일반적인 계정 워크플로를 보여줍니다.
account/acct-123을 생성합니다.account/acct-456을 하위 계정으로 생성합니다.rel_kind: account_user로 사용자를acct-123에 연결합니다.rel_kind: subaccount로acct-123을acct-456에 연결합니다.
링크를 다시 조회하려면 다음을 사용하세요.
- 연결된 사용자:
GET /data_objects/objects/account/acct-123/user_relationships - 나가는 객체 링크:
GET /data_objects/objects/account/acct-123/object_relationships - 들어오는 객체 링크:
GET /data_objects/objects/account/acct-456/object_relationships?anchor=target

객체 관계 및 사용자 관계의 DELETE 엔드포인트에는 JSON 요청 본문이 필요합니다.
일괄 엔드포인트
일괄 엔드포인트를 사용하면 자체 시스템의 데이터 오브젝트, 객체 관계, 사용자 관계를 배치 단위로 동기화할 수 있습니다. 각 요청으로 최대 50개의 레코드를 생성, 교체 또는 삭제할 수 있으며, Braze는 배치를 백그라운드에서 처리합니다.
| 메서드 | 엔드포인트 | 용도 |
|---|---|---|
PUT |
/data_objects/objects |
유형에 관계없이 최대 50개의 데이터 오브젝트 생성 또는 교체 |
DELETE |
/data_objects/objects |
유형에 관계없이 최대 50개의 데이터 오브젝트 삭제 |
PUT |
/data_objects/object_relationships |
최대 50개의 오브젝트 간 관계 생성 또는 교체 |
DELETE |
/data_objects/object_relationships |
최대 50개의 오브젝트 간 관계 삭제 |
PUT |
/data_objects/user_relationships |
최대 50개의 사용자-오브젝트 관계 생성 또는 교체 |
DELETE |
/data_objects/user_relationships |
최대 50개의 사용자-오브젝트 관계 삭제 |
일괄 엔드포인트를 사용해야 하는 경우
자체 시스템에서 많은 레코드를 동기화하고, 응답이 반환되기 전에 각 변경 사항이 적용될 필요가 없다면 일괄 엔드포인트를 사용하세요. 변경 사항을 바로 확인해야 하거나, 레코드를 읽어야 하거나, PATCH로 레코드 속성의 일부만 업데이트하려는 경우에는 단일 레코드 엔드포인트를 사용하세요.
일괄 엔드포인트는 단일 레코드 엔드포인트와 다음과 같은 점에서 다릅니다.
- 처리가 비동기적으로 이루어집니다.
202응답은 Braze가 배치를 수락하고 대기줄에 추가했다는 의미이며, 레코드가 적용되었다는 의미는 아닙니다. Braze는 배치를 처리할 때 유형, 관계 유형, 오브젝트, 사용자가 존재하는지, 그리고 속성이 해당 유형의 필드와 일치하는지 확인합니다.202를 반환한 요청이라도 나중에 개별 레코드에서 실패가 발생할 수 있습니다. - 유효성 검사는 전부 아니면 전무 방식입니다. 요청에 포함된 레코드 중 하나라도 유효성 검사에 실패하면, Braze는 전체 요청을
400으로 거부하고 아무것도 저장하지 않으며 모든 오류를 나열합니다. - 레코드는 수신 시간 순서로 정렬됩니다. Braze는 요청을 받은 시간을 모든 레코드에 기록하므로
updated_at을 보내지 마세요. 두 요청이 같은 레코드를 변경하면 Braze가 나중에 받은 요청이 우선합니다. - 레코드는 종속 항목을 기다릴 수 있습니다. 아직 존재하지 않는 오브젝트나 관계의 삭제, 그리고 오브젝트나 사용자가 아직 존재하지 않는 관계는 바로 실패하지 않고 대기합니다. Braze는 약 40시간 동안(10회 시도) 재시도합니다. 오브젝트 업서트는 대기하지 않습니다.
- 일괄 엔드포인트는 자체 API 키 권한을 사용하며, 워크스페이스당 분당 1,000건의 요청이라는 사용량 제한을 공유합니다.
- 일괄 엔드포인트는 데이터 오브젝트 유형을 생성하지 않습니다. 모든
type_name이 이미 존재해야 합니다.
제품 제한은 단일 레코드 엔드포인트와 동일한 방식으로 일괄 엔드포인트에도 적용됩니다.
페이지 매김 및 데이터 최신성
이 섹션에서는 목록 페이지 매김 방식과 쓰기 작업 후 데이터가 조회되기까지 걸리는 예상 시간을 설명합니다.
- 목록 엔드포인트는
limit및offset을 지원합니다. limit의 기본값은100이며,1에서250사이의 값으로 제한됩니다.offset의 기본값은0이며, 음수 값은0으로 조정됩니다.- 단일 레코드 쓰기는 읽기 작업과 Liquid 개인화에 즉시 반영됩니다. 일괄 쓰기는 Braze가 대기줄에 추가된 배치를 처리할 때 적용됩니다.
- 계산된 필터는 매시간 새로 고쳐지므로, 데이터 오브젝트를 기반으로 한 Segment 멤버십은 최대 1시간까지 지연될 수 있습니다.
오류 동작
이 섹션에서는 데이터 오브젝트 엔드포인트 전반에서 사용되는 상태 및 오류 응답 패턴을 요약합니다.
404,409,422,429는id와message가 포함된errors배열을 반환합니다.400,401,403은 단일error문자열을 반환합니다.- 일괄 엔드포인트는
400및500오류를id와message가 포함된errors배열로 반환합니다.400오류에는 문제가 되는parameter가 있는 경우 해당 매개변수도 포함되며, 레코드 수준 오류의 경우 해당 레코드의index도 포함됩니다. 422는 요청이 제품 한도를 초과한다는 의미입니다. 기본 한도 값은 회사 계약에 따라 다릅니다.