계산된 속성 API 끝점
계산된 속성은 이벤트 수준 데이터를 프로필 수준 속성으로 집계하는 데 사용되는 함수입니다. 이러한 함수는 세그먼테이션, 활성화 및 개인화에서 사용할 수 있도록 자동으로 계산됩니다. 이 안내서에는 /attributes
끝점을 사용하여 기본 CRUD 작업을 수행하기 위한 샘플 API 호출이 포함되어 있습니다.
계산된 특성에 대해 자세히 알아보려면 계산된 특성 개요를 읽는 것부터 시작하십시오.
시작하기
이 가이드에 사용된 API 끝점은 실시간 고객 프로필 API의 일부입니다.
계속하기 전에 프로필 API 시작 안내서에서 권장 설명서에 대한 링크, 이 설명서에 표시되는 샘플 API 호출 읽기 지침 및 Experience Platform API를 성공적으로 호출하는 데 필요한 필수 헤더에 대한 중요 정보를 검토하십시오.
또한 다음 서비스에 대한 설명서를 검토하십시오.
- Experience Data Model (XDM) System: Experience Platform에서 고객 경험 데이터를 구성하는 표준화된 프레임워크입니다.
- 스키마 레지스트리 시작 안내서: 이 안내서 전체의 응답에 표시되는
{TENANT_ID}
에 대한 정보가 제공됩니다.
- 스키마 레지스트리 시작 안내서: 이 안내서 전체의 응답에 표시되는
계산된 속성 목록 검색 list
/attributes
끝점에 대한 GET 요청을 수행하여 조직에 대해 계산된 모든 특성 목록을 검색할 수 있습니다.
API 형식
/attributes
끝점은 결과를 필터링하는 데 도움이 되는 몇 가지 쿼리 매개 변수를 지원합니다. 이러한 매개 변수는 선택 사항이지만 리소스를 나열할 때 비싼 오버헤드를 줄이는 데 도움이 되도록 사용하는 것이 좋습니다. 매개 변수 없이 이 끝점을 호출하면 조직에서 사용할 수 있는 모든 계산된 특성이 검색됩니다. 여러 매개 변수를 포함할 수 있으며 앰퍼샌드(&
)로 구분됩니다.
GET /attributes
GET /attributes?{QUERY_PARAMETERS}
계산된 속성 목록을 검색할 때 다음 쿼리 매개 변수를 사용할 수 있습니다.
limit
limit=20
offset
offset=5
sortBy
name
, status
, updateEpoch
및 createEpoch
입니다. 정렬 옵션 앞에 -
을(를) 포함하지 않거나 포함하여 오름차순으로 정렬할지 내림차순으로 정렬할지 선택할 수도 있습니다. 기본적으로 항목은 updateEpoch
별로 내림차순으로 정렬됩니다.sortBy=name
property
다양한 계산된 속성 필드를 필터링할 수 있는 매개변수. 지원되는 속성은 name
, createEpoch
, mergeFunction.value
, updateEpoch
및 status
입니다. 지원되는 작업은 나열된 속성에 따라 다릅니다.
name
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contains()),NOT_CONTAINS
(=!contains())createEpoch
:GREATER_THAN_OR_EQUALS
(<=),LESS_THAN_OR_EQUALS
(>=)mergeFunction.value
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contains()),NOT_CONTAINS
(=!contains())updateEpoch
:GREATER_THAN_OR_EQUALS
(<=),LESS_THAN_OR_EQUALS
(>=)status
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contains()),NOT_CONTAINS
(=!contains())
property=updateEpoch>=1683669114845
property=name!=testingrelease
property=status=contains(new,processing,disabled)
요청
다음 요청은 조직에서 업데이트된 마지막 3개의 계산된 속성을 검색합니다.
code language-shell |
---|
|
응답
성공적인 응답은 조직 및 샌드박스에 속한 최근 3개의 업데이트된 계산된 속성 목록과 함께 HTTP 상태 200을 반환합니다.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
속성 | 설명 |
_links |
결과의 마지막 페이지, 결과의 다음 페이지, 결과의 이전 페이지 또는 결과의 현재 페이지에 액세스하는 데 필요한 페이지 매김 정보를 포함하는 객체입니다. |
computedAttributes |
쿼리 매개 변수를 기반으로 하여 계산된 속성을 포함하는 배열입니다. 계산된 특성 배열에 대한 자세한 내용은 특정 계산된 특성 검색 섹션에서 확인할 수 있습니다. |
_page |
반환된 결과에 대한 메타데이터를 포함하는 객체입니다. 여기에는 현재 오프셋, 반환되는 계산된 속성 수, 반환되는 계산된 속성의 총 수 및 반환되는 계산된 속성 제한에 대한 정보가 포함됩니다. |
계산된 속성 만들기 create
계산된 특성을 만들려면 먼저 만들려는 계산된 특성의 세부 정보가 포함된 요청 본문으로 /attributes
끝점에 대한 POST 요청을 시작합니다.
API 형식
POST /attributes
요청
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2 | |
---|---|
속성 | 설명 |
name |
계산된 속성 필드의 이름(문자열)입니다. 계산된 속성의 이름은 공백 또는 밑줄 없이 영숫자로만 구성할 수 있습니다. 이 값 must 은(는) 계산된 모든 특성 중에서 고유합니다. 이 이름은 displayName 의 camelCase 버전이어야 합니다. |
description |
계산된 속성에 대한 설명입니다. 이 기능은 조직 내의 다른 사용자가 사용할 올바른 계산된 속성을 결정하는 데 도움이 되므로 여러 계산된 속성이 정의된 경우에 특히 유용합니다. |
displayName |
계산된 속성의 표시 이름입니다. Adobe Experience Platform UI 내에서 계산된 속성을 나열할 때 표시되는 이름입니다. |
expression |
만들려는 계산된 속성의 쿼리 표현식을 나타내는 개체입니다. |
expression.type |
표현식의 유형입니다. 현재는 PQL만 지원됩니다. |
expression.format |
표현식의 형식입니다. 현재 pql/text 만 지원됩니다. |
expression.value |
표현식의 값입니다. |
keepCurrent |
빠른 새로 고침을 사용하여 계산된 속성 값을 최신 상태로 유지할지 여부를 결정하는 부울입니다. 현재 이 값은 false (으)로 설정해야 합니다. |
duration |
계산된 속성에 대한 전환 확인 기간을 나타내는 개체입니다. 전환 확인 기간은 계산된 속성을 계산하기 위해 되돌릴 수 있는 기간을 나타냅니다. |
duration.count |
전환 확인 기간 기간을 나타내는 숫자입니다. 가능한 값은
|
duration.unit |
전환 확인 기간에 사용할 시간 단위를 나타내는 문자열입니다. 가능한 값은 HOURS , DAYS , WEEKS 및 MONTHS 입니다. |
status |
계산된 속성의 상태입니다. 가능한 값은 DRAFT 및 NEW 입니다. |
응답
성공적인 응답은 새로 생성된 계산된 속성에 대한 정보와 함께 HTTP 상태 200을 반환합니다.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 | |
---|---|
속성 | 설명 |
id |
새로 만든 계산된 속성에 대한 시스템 생성 ID입니다. |
status |
계산된 속성의 상태입니다. DRAFT 또는 NEW 일 수 있습니다. |
createEpoch |
계산된 속성이 생성된 시간(초)입니다. |
updateEpoch |
계산된 속성이 마지막으로 업데이트된 시간(초)입니다. |
createdBy |
계산된 속성을 만든 사용자의 ID입니다. |
특정 계산된 속성 검색 get
/attributes
끝점에 GET 요청을 하고 요청 경로에서 검색하려는 계산된 특성의 ID를 제공하여 특정 계산된 특성에 대한 자세한 정보를 검색할 수 있습니다.
API 형식
GET /attributes/{ATTRIBUTE_ID}
요청
code language-shell |
---|
|
응답
성공적인 응답은 지정된 계산된 속성에 대한 자세한 정보와 함께 HTTP 상태 200을 반환합니다.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2 13-row-2 14-row-2 15-row-2 16-row-2 17-row-2 | |
---|---|
속성 | 설명 |
id |
다른 API 작업 중에 계산된 속성을 참조하는 데 사용할 수 있는 고유한 읽기 전용 시스템 생성 ID입니다. |
type |
반환된 객체가 계산된 속성임을 보여 주는 문자열입니다. |
name |
계산된 속성의 이름입니다. |
displayName |
계산된 속성의 표시 이름입니다. Adobe Experience Platform UI 내에서 계산된 속성을 나열할 때 표시되는 이름입니다. |
description |
계산된 속성에 대한 설명입니다. 이 기능은 조직 내의 다른 사용자가 사용할 올바른 계산된 속성을 결정하는 데 도움이 되므로 여러 계산된 속성이 정의된 경우에 특히 유용합니다. |
imsOrgId |
계산된 속성이 속한 조직의 ID입니다. |
sandbox |
샌드박스 객체에는 계산된 속성이 구성된 샌드박스의 세부 정보가 포함됩니다. 이 정보는 요청에서 전송된 샌드박스 헤더에서 가져옵니다. 자세한 내용은 샌드박스 개요를 참조하세요. |
path |
계산된 특성에 대한 path 입니다. |
keepCurrent |
빠른 새로 고침을 사용하여 계산된 속성 값을 최신 상태로 유지할지 여부를 결정하는 부울입니다. |
expression |
계산된 속성의 표현식이 포함된 객체입니다. |
mergeFunction |
계산된 속성에 대한 병합 함수를 포함하는 객체입니다. 이 값은 계산된 속성의 표현식 내에서 해당 집계 매개변수를 기반으로 합니다. 가능한 값은 SUM , MIN , MAX 및 MOST_RECENT 입니다. |
status |
계산된 속성의 상태입니다. DRAFT , NEW , INITIALIZING , PROCESSING , PROCESSED , FAILED 또는 DISABLED 값 중 하나일 수 있습니다. |
schema |
표현식이 평가되는 스키마에 대한 정보를 포함하는 객체입니다. 현재 _xdm.context.profile 만 지원됩니다. |
lastEvaluationTs |
계산된 속성이 마지막으로 평가된 시기를 나타내는 타임스탬프입니다. |
createEpoch |
계산된 속성이 생성된 시간(초)입니다. |
updateEpoch |
계산된 속성이 마지막으로 업데이트된 시간(초)입니다. |
createdBy |
계산된 속성을 만든 사용자의 ID입니다. |
특정 계산된 속성 삭제 delete
/attributes
끝점에 DELETE 요청을 하고 요청 경로에 삭제하려는 계산된 특성의 ID를 제공하여 특정 계산된 특성을 삭제할 수 있습니다.
DRAFT
) 상태의 계산된 특성만 삭제하는 데 사용할 수 있습니다. 이 끝점 은(는) 다른 상태에서 계산된 특성을 삭제하는 데 사용할 수 없습니다.API 형식
DELETE /attributes/{ATTRIBUTE_ID}
{ATTRIBUTE_ID}
id
값입니다.요청
code language-shell |
---|
|
응답
성공적인 응답은 삭제된 계산된 속성에 대한 세부 정보와 함께 HTTP 상태 202를 반환합니다.
code language-json |
---|
|
특정 계산된 속성 업데이트
/attributes
끝점에 PATCH 요청을 하고 요청 경로에 업데이트하려는 계산된 특성의 ID를 제공하여 특정 계산된 특성을 업데이트할 수 있습니다.
- 현재 상태가
NEW
인 경우 상태를DISABLED
(으)로만 변경할 수 있습니다. - 현재 상태가
DRAFT
인 경우name
,description
,keepCurrent
,expression
및duration
필드의 값을 변경할 수 있습니다. 상태를DRAFT
에서NEW
(으)로 변경할 수도 있습니다.mergeFunction
또는path
과(와) 같은 시스템 생성 필드를 변경하면 오류가 반환됩니다. - 현재 상태가
PROCESSING
또는PROCESSED
인 경우 상태를DISABLED
(으)로만 변경할 수 있습니다.
API 형식
PATCH /attributes/{ATTRIBUTE_ID}
{ATTRIBUTE_ID}
id
값입니다.요청
다음 요청은 계산된 특성의 상태를 DRAFT
에서 NEW
(으)로 업데이트합니다.
code language-shell |
---|
|
응답
성공적인 응답은 새로 업데이트된 계산된 속성에 대한 정보와 함께 HTTP 상태 200을 반환합니다.
code language-json |
---|
|
다음 단계
이제 계산된 속성에 대한 기본 사항을 배웠으므로 조직에 대해 속성 정의를 시작할 준비가 되었습니다. Experience Platform UI에서 계산된 특성을 사용하는 방법에 대해 알아보려면 계산된 특성 UI 안내서를 읽어 보십시오.