데이터 객체 엔드포인트

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

중요

데이터 객체는 정식 출시되었지만, 이 엔드포인트를 사용하려면 먼저 워크스페이스에 계정이 프로비저닝되어 있어야 합니다. 프로비저닝을 요청하려면 데이터 설정 > 계정으로 이동하여 설문지를 작성하세요. 프로비저닝이 완료되면 데이터 객체 API 키 권한이 설정 > API 키에 표시됩니다. 자세한 내용은 계정 활성화를 참조하세요.

유형 엔드포인트

• 

  GET: 데이터 객체 유형 목록 조회
• 

  GET: 데이터 객체 유형 조회
• 

  GET: 사용자 관계 유형 목록 조회
• 

  GET: 객체 관계 유형 목록 조회

객체 엔드포인트

• 

  GET: 데이터 객체 목록 조회
• 

  GET: 데이터 객체 조회
• 

  POST: 데이터 객체 생성
• 

  PUT: 데이터 객체 교체
• 

  PATCH: 데이터 객체 업데이트
• 

  DELETE: 데이터 객체 삭제

객체 관계 엔드포인트

• 

  GET: 객체 관계 목록 조회
• 

  POST: 객체 관계 생성
• 

  PUT: 객체 관계 교체
• 

  PATCH: 객체 관계 업데이트
• 

  DELETE: 객체 관계 삭제

사용자 관계 엔드포인트

• 

  GET: 사용자 관계 목록 조회
• 

  POST: 사용자 관계 생성
• 

  PUT: 사용자 관계 교체
• 

  PATCH: 사용자 관계 업데이트
• 

  DELETE: 사용자 관계 삭제

기본 URL 및 인증

워크스페이스의 REST 엔드포인트를 사용하고 Authorization: Bearer YOUR_REST_API_KEY를 함께 전송하세요. 이 섹션에서는 데이터 객체 엔드포인트가 호스팅되는 위치와 요청을 인증하는 방법을 설명합니다.

• 엔드포인트 호스트는 Braze API 개요를 참조하세요.
• 모든 요청 및 응답 페이로드는 JSON 형식입니다.
• 요청 범위는 API 키를 소유한 워크스페이스로 한정됩니다.
• API 키에 IP 허용 목록이 설정된 경우, 허용 목록에 없는 IP 주소에서 보낸 요청은 403을 반환합니다.

API 키 권한

이 섹션에서는 각 엔드포인트에 필요한 권한을 매핑하므로 API 키의 범위를 안전하게 지정할 수 있습니다.

참고

객체 관계 읽기에는 data_objects.read 권한을 사용합니다. data_objects.object_relationships.read 권한은 없습니다.

사용량 제한

이 섹션에서는 읽기 및 쓰기 트래픽 모두에 대한 기본 요청 할당량과 응답 헤더를 설명합니다.

모든 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset이 포함됩니다.

요청이 제한되면 Braze는 429와 함께 id 및 message가 포함된 오류 페이로드를 반환합니다.

1
2
3
4
5
6
7
8

{
  "errors": [
    {
      "id": "rate-limit-exceeded",
      "message": "You have exceeded your limit of 1000 requests per minute."
    }
  ]
}

제품 제한

이 섹션에서는 Braze가 데이터 객체에 적용하는 제한과 제한에 도달했을 때 어떤 일이 발생하는지 설명합니다. 이러한 제한이 계정 레코드에 어떻게 적용되는지 알아보려면 계정 객체 제한을 참조하세요.

개수 제한

별도로 명시되지 않는 한 이러한 제한은 회사 전체에 적용됩니다. 아래 값은 기본 시작 용량입니다. 더 많은 레코드나 더 높은 제한이 필요하면 Braze 계정 팀에 문의하여 상향을 요청하세요.

필드 및 값 제한

이러한 제한은 모든 회사에 고정적으로 적용됩니다.

제한에 도달하면 어떻게 되나요?

개수 제한을 초과하게 되는 요청은 해당 제한을 식별하는 오류 id와 함께 422를 반환합니다.

1
2
3
4
5
6
7
8

{
  "errors": [
    {
      "id": "data-object-record-limit-exceeded",
      "message": "This company has reached its data object record limit"
    }
  ]
}

기존 레코드와 관계는 그대로 유지되며, 제한을 초과하게 되는 요청만 거부됩니다. 제한 내에서 여유 공간을 확보하려면 더 이상 필요하지 않은 레코드를 삭제하거나 사용하지 않는 관계를 제거하세요. 개수 제한을 높이려면 Braze 계정 팀에 문의하세요.

너무 긴 object_id나 속성 값처럼 유효성 검사에 실패한 요청은 400을 반환합니다. 사용량 제한을 초과한 요청은 429를 반환합니다.

핵심 개념

이 섹션에서는 모든 데이터 객체 엔드포인트에서 사용되는 주요 식별자를 정의합니다.

• type_name: 데이터 객체 유형 머신 이름으로, 워크스페이스 내에서 고유합니다.
• object_id: 객체 식별자로, 유형 내에서 고유합니다.
• braze_id: 사용자 관계 엔드포인트에서 사용되는 Braze 사용자 ID입니다.
• 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_types
  • GET /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 관점에서 같은 엣지를 생성하더라도 대상은 하나의 기본 관계입니다. 같은 엣지에 대해 두 번째로 생성 호출을 하면 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를 병합합니다.

활용 예시

이 예시는 일반적인 계정 워크플로를 보여줍니다.

1. account/acct-123을 생성합니다.
2. 하위 계정으로 account/acct-456을 생성합니다.
3. rel_kind: account_user로 사용자를 acct-123에 연결합니다.
4. 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 요청 본문이 필요합니다.

페이지네이션 및 데이터 최신성

이 섹션에서는 목록 페이지네이션 동작과 쓰기 작업 후 데이터가 조회에 반영되기까지 예상되는 시간을 다룹니다.

• 목록 엔드포인트는 limit과 offset을 지원합니다.
• limit의 기본값은 100이며, 1에서 250 사이의 값으로 제한됩니다.
• offset의 기본값은 0이며, 음수 값은 0으로 조정됩니다.
• 쓰기 작업은 읽기 및 Liquid 개인화에 즉시 반영됩니다.
• 계산된 필터는 매시간 새로 고쳐지므로, 데이터 객체를 기반으로 한 Segment 멤버십은 최대 1시간까지 지연될 수 있습니다.

오류 동작

이 섹션에서는 데이터 객체 엔드포인트 전반에서 사용되는 상태 및 오류 응답 패턴을 요약합니다.

• 404, 409, 422, 429는 id와 message가 포함된 errors 배열을 반환합니다.
• 400, 401, 403은 단일 error 문자열을 반환합니다.
• 422는 요청이 제품 한도를 초과하게 된다는 의미입니다. 기본 한도 값은 회사 계약에 따라 다릅니다.