콘텐츠로 건너뛰기

데이터 오브젝트 일괄 생성 또는 교체

put

/data_objects/objects

이 엔드포인트를 사용하면 유형에 관계없이 최대 50개의 데이터 오브젝트를 한 번의 요청으로 생성하거나 교체할 수 있습니다.

Braze는 요청을 수락한 후 백그라운드에서 처리합니다. 202 응답은 배치가 적용된 것이 아니라 대기줄에 추가되었음을 의미합니다. 데이터 오브젝트 하나를 변경하고 변경 사항을 바로 확인하려면 데이터 오브젝트 교체를 사용하세요. 각 엔드포인트를 언제 사용해야 하는지는 일괄 엔드포인트를 참조하세요.

사전 요구 사항

이 엔드포인트를 사용하려면 data_objects.bulk_upsert 권한이 있는 API 키가 필요합니다. data_objects.create 같은 단일 레코드 권한으로는 이 엔드포인트에 액세스할 수 없습니다.

사용량 제한

이 엔드포인트는 데이터 오브젝트 일괄 쓰기 버킷에 속하며, 기본 제한은 워크스페이스당 분당 1,000회 요청입니다. 이 제한은 6개의 일괄 엔드포인트 전체 및 데이터 오브젝트의 클라우드 데이터 수집 동기화와 공유되며, 단일 레코드 쓰기 제한과는 별도로 적용됩니다.

요청 매개변수

다음 표에는 /data_objects/objects 엔드포인트의 JSON 요청 본문 매개변수가 나와 있습니다.

매개변수 필수 데이터 유형 설명
records 필수 배열 생성하거나 교체할 데이터 오브젝트입니다. 1~50개의 레코드를 포함해야 합니다. Braze는 다른 최상위 필드를 모두 거부합니다.
records[].type_name 필수 문자열 데이터 오브젝트 유형의 머신 이름입니다. 유형이 이미 존재해야 합니다. 이 엔드포인트는 유형을 생성하지 않습니다.
records[].object_id 필수 문자열 오브젝트에 대한 식별자로, 단일 레코드 엔드포인트 경로의 object_id와 같은 값입니다.
records[].attributes 필수 오브젝트 필드 이름을 키로 하는 오브젝트 속성입니다. 각 필드는 해당 유형에 이미 정의되어 있어야 합니다. 날짜 필드는 2026-11-03T00:00:00Z처럼 시간과 시간대를 포함하는 RFC 3339 날짜-시간 문자열이어야 합니다. Braze는 배치를 처리할 때 속성을 확인하므로 2026-11-03처럼 날짜만 있는 값이 포함된 요청도 202를 반환하며, Braze는 해당 레코드에 대해 data-object-schema-mismatch 처리 실패를 기록합니다. 자세한 내용은 날짜 필드 형식을 참조하세요.

Braze가 배치를 처리하는 방식

  • 유효성 검사는 전부 아니면 전무 방식입니다. 레코드 하나라도 유효성 검사에 실패하면 Braze는 400과 함께 전체 요청을 거부하고, 아무것도 저장하지 않으며, 모든 오류를 나열합니다. 오류를 수정한 후 전체 요청을 다시 보내세요.
  • 조회는 처리 중에 이루어집니다. Braze는 배치를 처리할 때 각 유형이 존재하는지, 속성이 유형의 필드와 일치하는지 확인합니다. 따라서 202를 반환한 요청도 나중에 개별 레코드에서 실패가 발생할 수 있습니다. 처리 실패를 참조하세요.
  • 레코드는 수신 시간 순서로 정렬됩니다. Braze는 요청을 받은 시간을 모든 레코드에 기록하므로 updated_at을 보내지 마세요. Braze는 이 필드가 포함된 요청을 거부합니다. 두 요청이 같은 오브젝트를 변경하면 Braze가 나중에 받은 요청이 적용되며, 그 이후에 도착한 더 오래된 쓰기는 건너뜁니다.
  • 업서트는 대기하지 않습니다. 오브젝트 업서트는 다른 레코드를 기다리지 않습니다. 같은 오브젝트가 삭제된 후 수신된 업서트는 해당 오브젝트를 다시 생성합니다.

요청 예시

이 섹션에는 샘플 JSON 페이로드와 샘플 cURL 요청이 포함되어 있습니다.

샘플 요청 페이로드

{
  "records": [
    {"type_name": "account", "object_id": "acct-001", "attributes": {"name": "Acme"}},
    {"type_name": "opportunity", "object_id": "opp-001", "attributes": {"amount": 10}}
  ]
}

샘플 cURL 요청

이 예시는 같은 요청에서 account 레코드 하나와 opportunity 레코드 하나를 생성하거나 교체합니다.

curl --location --request PUT 'https://rest.iad-01.braze.com/data_objects/objects' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "records": [
    {"type_name": "account", "object_id": "acct-001", "attributes": {"name": "Acme"}},
    {"type_name": "opportunity", "object_id": "opp-001", "attributes": {"amount": 10}}
  ]
}'

응답

이 섹션에는 성공 응답 샘플과 응답 필드가 포함되어 있습니다.

성공 응답 예시

상태 코드 202는 다음과 같은 응답 본문을 반환할 수 있습니다.

{
  "source_import_id": "api-20261022T153012123456-9f3a1c2b",
  "status": "queued",
  "record_count": 2
}

응답 매개변수

다음 표에는 성공 응답의 필드가 나와 있습니다.

매개변수 필수 데이터 유형 설명
source_import_id 필수 문자열 Braze가 이 요청에 대해 생성한 식별자입니다. 모든 요청은 각각 별도의 가져오기입니다.
status 필수 문자열 항상 queued입니다. 배치가 수락되어 처리 대기 중입니다.
record_count 필수 정수 요청에 포함된 레코드 수

처리 실패

Braze는 엔드포인트에서 이 코드들을 반환하지 않습니다. 대기 중인 배치를 처리할 때 개별 레코드에 대해 기록합니다.

코드 의미
data-object-type-not-found type_name이 워크스페이스의 활성 유형과 일치하지 않습니다.
data-object-schema-mismatch attributes가 유형의 필드와 일치하지 않습니다. 메시지에 문제가 있는 모든 속성이 표시됩니다.
data-object-ingestion-rejected 거부된 object_id 등 그 밖의 모든 거부입니다.

오류

400 응답은 Braze가 아무것도 저장하지 않았음을 의미합니다. 각 오류에는 id, message, 문제가 있는 경우 해당 parameter, 그리고 레코드 수준 오류의 경우 레코드의 index(records 내에서 0부터 시작하는 위치)가 포함됩니다.

다음 표에는 이 엔드포인트의 일반적인 오류와 해결 방법이 나와 있습니다.

상태 원인 해결 방법
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 포함)가 있거나, 필드 유형이 잘못되었거나 빈 문자열인 경우 나열된 모든 레코드를 수정하고 전체 요청을 다시 보내세요.
401 REST API 키가 없거나 유효하지 않음 Authorization 헤더가 Bearer YOUR_REST_API_KEY를 사용하는지, 키가 활성 상태인지 확인하세요.
403 API 키에 권한이 없거나 허용 목록에 의해 요청이 차단됨 키에 data_objects.bulk_upsert 권한이 있는지, 그리고 허용 목록이 구성된 경우 소스 IP가 키 허용 목록에 있는지 확인하세요.
404 회사에 데이터 오브젝트가 활성화되지 않음 워크스페이스에 Accounts가 프로비저닝되어 있는지 확인하세요.
429 사용량 제한 초과 X-RateLimit-Reset 이후에 다시 시도하고 요청 빈도를 줄이세요.
500 배치를 수락할 수 없음(internal-error) Braze가 아무것도 수락하지 않았으므로 요청을 안전하게 다시 시도할 수 있습니다.
New Stuff!