동시성 모니터링 사용 API cmu-api-usage
API 개요 api-overview
CMU(동시성 모니터링 사용)는 WOLAP(웹 기반 온라인 분석 처리) 프로젝트로 구현됩니다. CMU는 Data Warehouse에서 지원하는 일반적인 비즈니스 보고 웹 API입니다. 일반 OLAP 작업을 RESTfully로 수행할 수 있도록 하는 HTTP 쿼리 언어 역할을 합니다.
CMU API는 기본 OLAP 큐브의 계층 구조 보기를 제공합니다. 각 리소스(차원, URL 경로 세그먼트로 매핑됨)는 현재 선택 항목에 대해 지표이(가) 포함된(집계된) 보고서를 생성합니다. 각 리소스는 상위 리소스(롤업용)와 하위 리소스(드릴다운용)를 가리킵니다. 슬라이싱 및 다이싱은 특정 값 또는 범위에 차원을 고정하는 쿼리 문자열 매개 변수를 통해 수행됩니다.
REST API는 차원 경로, 제공된 필터 및 선택한 지표에 따라 요청에 지정된 시간 간격(제공되지 않은 경우 기본값으로 폴백) 내에 사용 가능한 데이터를 제공합니다. 시간 차원 (연도, 월, 일, 시간, 분, 초)이 포함되지 않은 보고서에는 시간 범위가 적용되지 않습니다.
끝점 URL 루트 경로는 사용 가능한 드릴다운 옵션에 대한 링크와 함께 단일 레코드 내에서 전체 집계된 지표를 반환합니다. API 버전은 끝점 URI 경로의 후행 세그먼트로 매핑됩니다. 예를 들어 https://mgmt.auth.adobe.com/cmu/v2은(는) 클라이언트가 WOLAP 버전 2에 액세스함을 의미합니다.
사용 가능한 URL 경로는 응답에 포함된 링크를 통해 검색할 수 있습니다. 유효한 URL 경로는 집계된 지표를 보유하는 기본 드릴다운 트리 내의 경로를 매핑하기 위해 유지됩니다. /dimension1/dimension2/dimension3 형식의 경로는 이러한 세 차원의 사전 집계를 반영합니다(SQL 절 GROUP BY dimension1, dimension2, dimension3과 동일). 이러한 사전 집계가 존재하지 않고 시스템이 즉시 계산할 수 없는 경우, API는 404 Not Found 응답을 반환합니다.
드릴다운 트리 drill-down-tree
다음 드릴다운 트리는 CMU 2.0에서 사용할 수 있는 차원(리소스)을 보여 줍니다.
CM 테넌트에서 사용할 수 있는 차원
GET API 끝점에 대한 https://mgmt.auth.adobe.com/cmu/v2이(가) 다음을 포함하는 표현을 반환합니다.
-
사용 가능한 루트 드릴다운 경로 링크:
code language-html <link rel="drill-down" href="/cmu/v2/dimensionA"/> <link rel="drill-down" href="/cmu/v2/dimensionB"/> -
모든 지표에 대한 요약(집계된 값)입니다(기본 간격에서 쿼리 문자열 매개 변수가 제공되지 않았으므로 아래 참조).
드릴다운 경로(단계별): /dimensionA/year/month/day/dimensionX는 다음 응답을 검색합니다.
- "dimensionY" 및 "dimensionZ" 드릴다운 옵션에 대한 링크
- 각 dimensionX 값에 대한 일별 합계를 포함하는 보고서
필터
날짜/시간 차원을 제외하고, 현재 투영(치수 경로)에 사용할 수 있는 모든 치수는 해당 이름을 쿼리 문자열 매개 변수로 사용하여 필터링할 수 있습니다.
다음 필터링 옵션을 사용할 수 있습니다.
- 쿼리 문자열에서 차원 이름을 특정 값으로 설정하여 같음 필터를 제공합니다.
- IN 필터는 다른 값으로 동일한 차원 이름 매개 변수를 여러 번 추가하여 지정할 수 있습니다. dimension=value1&dimension=value2
- 같지 않음 필터는 '!'를 사용해야 합니다. 치수 이름 뒤에 기호가 있으면 '!=' "operator": 차원!=value
- NOT IN 필터에는 '!=' 연산자를 집합에 있는 각 값에 대해 한 번씩 여러 번 사용합니다. 차원!=value1&dimension!=value2&…
쿼리 문자열의 차원 이름에 대한 특별한 용도가 있습니다. 차원 이름이 값 없이 쿼리 문자열 매개 변수로 사용되는 경우 API에 보고서에 해당 차원을 포함하는 프로젝션을 반환하도록 지시합니다.
CMU 쿼리 예:
/dimension1?dimension3
다음 쿼리 문자열 매개 변수에는 API에 대해 예약된 의미가 있습니다(따라서 차원 이름으로 사용할 수 없거나 해당 차원에 대해 필터링할 수 없음).
CMU API 예약 쿼리 문자열 매개 변수:
현재 사용 가능한 HTTP 메서드는 GET 뿐입니다. OPTIONS/HEAD 메서드에 대한 지원은 이후 버전에서 제공될 수 있습니다.
CMU API 상태 코드 cmu-api-status-codes
데이터 형식 data-formats
데이터는 다음 형식으로 사용할 수 있습니다.
- JSON(기본값)
- XML
- CSV
- HTML (데모 목적)
클라이언트가 사용할 수 있는 콘텐츠 협상 전략은 다음과 같습니다(우선 순위는 목록의 위치에 의해 지정됩니다.).
- URL 경로의 마지막 세그먼트에 추가된 "파일 확장명"(예: /cmu/v2/tenant/year/month/day.xml). URL에 쿼리 문자열이 포함된 경우 확장명은 물음표 앞에 와야 합니다.
/cmu/v2/tenant/year/month/day.csv?mvpd=SomeMVPD - 형식 쿼리 문자열 매개 변수(예:
/cmu/report?format=json) - 표준 HTTP Accept 헤더(예:
Accept: application/xml)
"확장" 및 쿼리 매개 변수는 모두 다음 값을 지원합니다.
- xml
- json
- csv
- html
어느 전략에서도 미디어 유형을 지정하지 않은 경우 API는 기본적으로 JSON 콘텐츠를 생성합니다.
HAL(하이퍼텍스트 응용 프로그램 언어) hypertext-app-lang
JSON 및 XML의 경우 페이로드는 http://stateless.co/hal_specification.html에 설명된 대로 HAL로 인코딩됩니다.
실제 보고서("report"라는 중첩된 태그/속성)는 선택한/적용할 수 있는 모든 차원과 지표가 포함된 실제 레코드 목록으로 구성되며, 해당 값은 다음과 같이 인코딩됩니다.
JSON json
"report": [
{
"dimension1": "d1",
...
"metric1": "m1",
...
}, {
...
}
]
XML xml
<report>
<record dimension1="d1" ... metric1="m1" ... />
...
</report>
XML 및 JSON 형식의 경우 레코드 내의 필드(차원 및 지표) 순서가 지정되지 않지만 일관됩니다(모든 레코드에서 순서가 동일함). 그러나 클라이언트는 레코드 내의 특정 필드 순서에 의존해서는 안 됩니다.
리소스 링크(JSON의 "self" rel 및 XML의 "href" 리소스 속성)에는 인라인 보고서에 사용되는 현재 경로 및 쿼리 문자열이 포함되어 있습니다. 쿼리 문자열은 암시적 및 명시적 매개 변수를 모두 표시하므로 페이로드는 사용된 시간 간격, 암시적 필터(있는 경우) 등을 명시적으로 지정합니다. 리소스 내의 나머지 링크에는 현재 데이터에서 드릴다운하기 위해 따를 수 있는 사용 가능한 모든 세그먼트가 포함됩니다. 롤업에 대한 링크도 제공되며 상위 경로(있는 경우)를 가리킵니다. 드릴다운/롤업 링크의 href 값에는 URL 경로만 포함됩니다. 여기에는 쿼리 문자열이 포함되지 않으므로 필요한 경우 클라이언트가 추가해야 합니다. 현재 리소스에서 사용(또는 암시적)한 모든 쿼리 문자열 매개 변수를 "롤업" 또는 "드릴다운" 링크에 적용할 수 있는 것은 아닙니다(예: 하위 또는 상위 리소스에는 필터가 적용되지 않을 수 있음).
예(클라이언트라는 단일 지표가 있고 year/month/day/...에 대한 사전 집계가 있다고 가정):
-
https://mgmt.auth.adobe.com/cmu/v2/year/month.xmlcode language-xml <resource href="/cmu/v2/year/month?start=2012-07-20T00:00:00&end=2012-08-20T14:35:21"> <links> <link rel="roll-up" href="/cmu/v2/year"/> <link rel="drill-down" href="/cmu/v2/year/month/day"/> </links> <report> <record month="6" year="2012" clients="205"/> <record month="7" year="2012" clients="466"/> </report> </resource> -
https://mgmt.auth.adobe.com/cmu/v2/year/month.jsoncode language-js { "_links" : { "self" : { "href" : "/cmu/v2/year/month?start=2012-07-20T00:00:00&end=2012-08-20T14:35:21" }, "roll-up" : { "href" : "/cmu/v2/year" }, "drill-down" : { "href" : "/cmu/v2/year/month/day" } }, "report" : [ { "month" : "6", "year" : "2012", "clients" : "205" }, { "month" : "7", "year" : "2012", "clients" : "466" } ] }
CSV csv
CSV 데이터 형식에서는 링크 또는 기타 메타데이터(헤더 행 제외)가 인라인으로 제공되지 않습니다. 대신 선택 메타데이터가 파일 이름으로 제공되며, 이 파일 이름은 다음 패턴을 따릅니다.
report__<start-date>_<end-date>_<filter-values,...>.csv
CSV에는 머리글 행이 포함된 다음 보고서 데이터가 후속 행으로 포함됩니다. 머리글 행에는 모든 차원이 포함되며 그 뒤에는 모든 지표가 포함됩니다. 보고서 데이터의 정렬 순서는 차원 순서로 반영됩니다. 따라서 데이터를 D1을 기준으로 정렬한 다음 D2를 기준으로 정렬하면 CSV 헤더는 D1, D2, ...metrics....과(와) 같이 표시됩니다.
머리글 행의 필드 순서는 테이블 데이터의 정렬 순서를 반영합니다.
예: https://mgmt.auth.adobe.com/cmu/v2/year/month.csv은 다음 내용이 포함된 report__2012-07-20_2012-08-20_1000.csv 파일을 생성합니다.
데이터 새로 고침 data-freshness
요청에 Last-Modified 헤더가 포함되어 있지만 본문의 보고서가 마지막으로 업데이트된 시간을 DOES이(가) 반영하지 않습니다. 일반 보고서는 다음 규칙을 사용하여 정기적으로 계산됩니다.
- 시간 세부기간이 년 또는 개월인 경우 보고서는 2일마다 업데이트됩니다
- 시간 세부기간이 일인 경우 보고서는 3시간마다 업데이트됩니다
- 시간 세부기간이 시간이면 보고서가 매시간 업데이트됩니다
- 시간 세부기간이 분인 경우 보고서는 매 분마다 업데이트됩니다
활동 수준 및 동시성 수준 보고서는 시간 세부기간에 관계없이 매일 업데이트됩니다.
GZIP 압축 gzip-compression
Adobe은 CMU 보고서를 가져오는 클라이언트에서 gzip 지원을 활성화할 것을 강력히 권장합니다. 이렇게 하면 응답 크기가 크게 줄어들어 응답 시간이 줄어듭니다. (CMU 데이터의 압축 비율은 20~30입니다.)
클라이언트에서 gzip 압축을 활성화하려면 Accept-Encoding: 헤더를 다음과 같이 설정합니다.
Accept-Encoding: gzip, deflate