권한 부여 서비스 모니터링 API entitlement-service-monitoring-api

API 개요 api-overview

ESM(자격 서비스 모니터링)은 WOLAP(웹 기반 온라인 분석 처리) 프로젝트로 구현됩니다. ESM은 데이터 웨어하우스에서 지원하는 일반적인 비즈니스 보고 웹 API입니다. 일반 OLAP 작업을 RESTfully로 수행할 수 있도록 하는 HTTP 쿼리 언어 역할을 합니다.

ESM API는 기본 OLAP 큐브의 계층 구조 보기를 제공합니다. 각 리소스(차원, URL 경로 세그먼트로 매핑됨)는 현재 선택 항목에 대해 지표이(가) 포함된(집계된) 보고서를 생성합니다. 각 리소스는 상위 리소스(롤업용)와 하위 리소스(드릴다운용)를 가리킵니다. 슬라이싱 및 다이싱은 특정 값 또는 범위에 차원을 고정하는 쿼리 문자열 매개 변수를 통해 수행됩니다.

REST API는 차원 경로, 제공된 필터 및 선택한 지표에 따라 요청에 지정된 시간 간격(제공되지 않은 경우 기본값으로 폴백) 내에 사용 가능한 데이터를 제공합니다. 시간 차원 (연도, 월, 일, 시간, 분, 초)이 포함되지 않은 보고서에는 시간 범위가 적용되지 않습니다.

끝점 URL 루트 경로는 사용 가능한 드릴다운 옵션에 대한 링크와 함께 단일 레코드 내에서 전체 집계된 지표를 반환합니다. API 버전은 끝점 URI 경로의 후행 세그먼트로 매핑됩니다. 예를 들어 https://mgmt.auth.adobe.com/*v2*은(는) 클라이언트가 WOLAP 버전 2에 액세스함을 의미합니다.

사용 가능한 URL 경로는 응답에 포함된 링크를 통해 검색할 수 있습니다. 유효한 URL 경로는 집계된 지표를 보유하는 기본 드릴다운 트리 내의 경로를 매핑하기 위해 유지됩니다. /dimension1/dimension2/dimension3 형식의 경로는 이러한 세 차원의 사전 집계를 반영합니다(dimension1, dimension2, dimension3의 SQL clause GROUP에 해당). 이러한 사전 집계가 존재하지 않고 시스템이 즉시 계산할 수 없는 경우, API는 404 Not Found 응답을 반환합니다.

드릴다운 트리 drill-down-tree

다음 드릴다운 트리는 프로그래머 및 MVPD에 대해 ESM 2.0에서 사용할 수 있는 차원(리소스)을 보여 줍니다.

프로그래머가 사용할 수 있는 Dimension progr-dimensions

일

시간

분

MVPD에 사용 가능한 Dimension mvpd-dimensions

https://mgmt.auth.adobe.com/v2 API 끝점에 대한 GET이 다음을 포함하는 표현을 반환합니다.

드릴다운 경로(단계별) 수행:
/dimensionA/year/month/day/dimensionX은(는) 다음을 검색합니다
응답:

필터

날짜/시간 차원을 제외하고, 현재 투영(치수 경로)에 사용할 수 있는 모든 치수는 해당 이름을 쿼리 문자열 매개 변수로 사용하여 필터링할 수 있습니다.

다음 필터링 옵션을 사용할 수 있습니다.

쿼리 문자열의 차원 이름에 대한 특별한 용도가 있습니다. 차원 이름이 값 없이 쿼리 문자열 매개 변수로 사용되는 경우 API에 보고서에 해당 차원을 포함하는 프로젝션을 반환하도록 지시합니다.

예제 ESM 쿼리

다음 쿼리 문자열 매개 변수에는 API에 대해 예약된 의미가 있습니다(따라서 차원 이름으로 사용할 수 없거나 해당 차원에 대해 필터링할 수 없음).

ESM API 예약 쿼리 문자열 매개 변수

현재 사용 가능한 HTTP 메서드는 GET 뿐입니다. OPTIONS 지원 /
HEAD 방법은 이후 버전에서 제공될 수 있습니다.

ESM API 상태 코드 esm-api-status-codes

데이터 형식 data-formats

데이터는 다음 형식으로 사용할 수 있습니다.

클라이언트가 사용할 수 있는 콘텐츠 협상 전략은 다음과 같습니다(우선 순위는 목록의 위치에 의해 지정됩니다.).

"확장" 및 쿼리 매개 변수는 모두 다음 값을 지원합니다.

어느 전략에서도 미디어 유형을 지정하지 않은 경우 API는 기본적으로 JSON 콘텐츠를 생성합니다.

하이퍼텍스트 응용 프로그램 언어 hypertext-application-language

JSON 및 XML의 경우 페이로드는 http://stateless.co/hal_specification.html에 설명된 대로 HAL로 인코딩됩니다.

실제 보고서("report"라는 중첩된 태그/속성)는 선택한/적용할 수 있는 모든 차원과 지표가 포함된 실제 레코드 목록으로 구성되며, 해당 값은 다음과 같이 인코딩됩니다.

JSON

 "report": [
  {
    "dimension1": "d1",
    ...
    "metric1": "m1",
    ...
  }, {
    ...
  }
]

XML

 <report>
  <record dimension1="d1" ... metric1="m1" ... />
  ...
</report

XML 및 JSON 형식의 경우 레코드 내의 필드(차원 및 지표) 순서가 지정되지 않지만 일관됩니다(모든 레코드에서 순서가 동일함). 그러나 클라이언트는 레코드 내의 특정 필드 순서에 의존해서는 안 됩니다.

리소스 링크(JSON의 "self" rel 및 XML의 "href" 리소스 속성)에는 인라인 보고서에 사용되는 현재 경로 및 쿼리 문자열이 포함되어 있습니다. 쿼리 문자열은 암시적 및 명시적 매개 변수를 모두 표시하므로 페이로드는 사용된 시간 간격, 암시적 필터(있는 경우) 등을 명시적으로 지정합니다. 리소스 내의 나머지 링크에는 현재 데이터에서 드릴다운하기 위해 따를 수 있는 사용 가능한 모든 세그먼트가 포함됩니다. 롤업에 대한 링크도 제공되며 상위 경로(있는 경우)를 가리킵니다. 드릴다운/롤업 링크의 href 값에는 URL 경로만 포함됩니다. 여기에는 쿼리 문자열이 포함되지 않으므로 필요한 경우 클라이언트가 추가해야 합니다. 현재 리소스에서 사용(또는 암시적)한 모든 쿼리 문자열 매개 변수를 "롤업" 또는 "드릴다운" 링크에 적용할 수 있는 것은 아닙니다(예: 하위 또는 상위 리소스에는 필터가 적용되지 않을 수 있음).

예(clients이라는 단일 지표가 있고 year/month/day/...에 대한 사전 집계가 있다고 가정):

   <resource href="/esm/v2/year/month?start=2012-07-20T00:00:00&end=2012-08-20T14:35:21">
   <links>
   <link rel="roll-up" href="/esm/v2/year"/>
   <link rel="drill-down" href="/esm/v2/year/month/day"/>
   </links>
   <report>
   <record month="6" year="2012" clients="205"/>
   <record month="7" year="2012" clients="466"/>
   </report>
   </resource>

CSV

CSV 데이터 형식에서는 링크 또는 기타 메타데이터(헤더 행 제외)가 인라인으로 제공되지 않습니다. 대신 선택 메타데이터가 파일 이름으로 제공되며, 이 파일 이름은 다음 패턴을 따릅니다.

    esm__<start-date>_<end-date>_<filter-values,...>.csv

CSV에는 머리글 행이 포함된 다음 보고서 데이터가 후속 행으로 포함됩니다. 머리글 행에는 모든 차원이 포함되며 그 뒤에는 모든 지표가 포함됩니다. 보고서 데이터의 정렬 순서는 차원 순서로 반영됩니다. 따라서 데이터를 D1별로 정렬한 다음 D2별로 정렬하면 CSV 헤더는 D1, D2, ...metrics...과(와) 같이 표시됩니다.

머리글 행의 필드 순서는 테이블 데이터의 정렬 순서를 반영합니다.

예: https://mgmt.auth.adobe.com/v2/year/month.csv은 다음 내용이 포함된 report__2012-07-20_2012-08-20_1000.csv 파일을 생성합니다.

데이터 새로 고침 data-freshness

성공적인 HTTP 응답에는 본문의 보고서가 마지막으로 업데이트된 시간을 나타내는 Last-Modified 헤더가 포함되어 있습니다. Last-Modified 헤더가 없다는 것은 보고서 데이터가 실시간으로 계산됨을 나타냅니다.

일반적으로 조악한 데이터는 세분화된 데이터보다 덜 자주 업데이트됩니다(예: 분 단위 값 또는 시간별 값은 일별 값보다 더 최신일 수 있으며, 특히 고유 카운트와 같이 더 작은 세부기간을 기반으로 계산할 수 없는 지표의 경우).

향후 버전의 ESM에서는 표준 "If-Modified-Since" 헤더를 제공하여 클라이언트가 조건부 GET을 수행할 수 있습니다.

GZIP 압축 gzip-compression

Adobe은 ESM 보고서를 가져오는 클라이언트에서 gzip 지원을 활성화할 것을 강력히 권장합니다. 이렇게 하면 응답 크기가 크게 줄어들어 응답 시간이 줄어듭니다. (ESM 데이터의 압축 비율은 20~30 범위 내에 있습니다.)

클라이언트에서 gzip 압축을 사용하려면 Accept-Encoding: 헤더를 다음과 같이 설정합니다.