이 문서에서는 다채널 유입경로 Reporting API의 쿼리와 응답에 대한 전체 참조를 제공합니다.
소개
다채널 유입경로 Reporting API를 사용하면 Google 애널리틱스 다채널 유입경로 보고서 데이터를 요청할 수 있습니다. 모든 보고서는 추적 코드가 애널리틱스로 다시 전송하는 데이터에서 파생된 통계로, 측정기준과 측정항목으로 구성됩니다. 측정기준과 측정항목의 조합을 직접 선택하면 Reporting API를 사용하여 사양에 맞게 맞춤설정된 보고서를 만들 수 있습니다.
API에는 보고서 데이터를 요청하는 단일 메서드인 report.get이 포함되어 있습니다. 이 메서드를 사용하면 데이터를 검색하려는 뷰(프로필)에 해당하는 테이블 ID를 제공할 수 있습니다. 또한 다음을 지정합니다.
- 측정기준과 측정항목의 조합입니다.
- 기간.
- 반환되는 데이터를 제어하는 옵션 매개변수 집합
API는 REST 엔드포인트( https://www.googleapis.com/analytics/v3/data/mcf)에서 report.get 메서드를 사용할 수 있도록 합니다. 다음 섹션에서는 샘플 요청을 보여주고 각 매개변수를 설명합니다.
요청
API는 데이터를 요청하는 단일 메서드를 제공합니다.
analytics.data.mcf.get()
API를 REST 엔드포인트로 쿼리할 수도 있습니다.
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/mcf ?ids=ga:12345 &metrics=mcf:totalConversions,mcf:totalConversionValue &start-date=2011-10-01 &end-date=2011-10-31
각 URL 쿼리 매개변수는 URL로 인코딩되어야 하는 API 쿼리 매개변수를 지정합니다.
다채널 유입경로 Reporting API에 대한 모든 요청은 OAuth 2.0을 통해 승인되어야 합니다.
쿼리 매개변수 요약
다음 표에는 다채널 유입경로 Reporting API에서 허용하는 모든 쿼리 매개변수가 요약되어 있습니다. 각 매개변수 이름을 클릭하면 자세한 설명을 확인할 수 있습니다.
| 이름 | 값 | 필수 | 요약 |
|---|---|---|---|
ids |
string |
예 | ga:XXXX 형식의 고유한 테이블 ID입니다. 여기서 XXXX는 쿼리를 통해 데이터를 검색할 애널리틱스 보기 (프로필) ID입니다. |
start-date |
string |
예 |
애널리틱스 데이터를 가져오는 시작일입니다. 요청에서 시작일을 YYYY-MM-DD 또는 상대 날짜(예: today, yesterday 또는 NdaysAgo). 여기서 N은 양의 정수입니다.
|
end-date |
string |
예 |
애널리틱스 데이터를 가져오는 종료일입니다. 요청은 YYYY-MM-DD 또는 상대 날짜 (예:
today, yesterday 또는 NdaysAgo)여야 합니다. 여기서 N은 양의 정수입니다.
|
metrics |
string |
예 | 쉼표로 구분된 측정항목 목록입니다(예: mcf:totalConversions,mcf:totalConversionValue).
유효한 쿼리는 하나 이상의 측정항목을 지정해야 합니다. |
dimensions |
string |
아니요 | 다채널 유입경로 보고서의 쉼표로 구분된 측정기준 목록입니다(예: mcf:source,mcf:keyword). |
sort |
string |
아니요 | 반환된 데이터의 정렬 순서와 정렬 방향을 나타내는 쉼표로 구분된 측정기준 및 측정항목의 목록입니다. |
filters |
string |
아니요 | 요청에 대해 반환되는 데이터를 제한하는 측정기준 또는 측정항목 필터입니다. |
samplingLevel |
string |
아니요 | 원하는 샘플링 수준입니다. 허용되는 값:
|
start-index |
integer |
아니요 | 검색할 데이터의 첫 번째 행이며 1부터 시작합니다.
이 매개변수를 max-results 매개변수와 함께 페이지로 나누기 메커니즘으로 사용합니다. |
max-results |
integer |
아니요 | 응답에 포함할 최대 행 수입니다. |
쿼리 매개변수 세부정보
ids
ids=ga:12345
ga: 네임스페이스를 보고서의 보기 (프로필) ID와 연결한 것입니다.
Google Analytics Management API의 보기 (프로필) 리소스에 id를 제공하는 analytics.management.profiles.list 메서드를 사용하여 보고서의 보기 (프로필) ID를 가져올 수 있습니다.
시작일
start-date=2011-10-01
start-date 및 end-date 매개변수를 포함하지 않으면 서버에서 오류를 반환합니다.
날짜 값은 YYYY-MM-DD 패턴을 사용하여 특정 날짜를 대상으로 하거나 today, yesterday 또는 NdaysAgo 패턴을 사용하여 상대적일 수 있습니다.
값은 [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)과 일치해야 합니다.
start-date는 2011-01-01입니다.
start-date의 상한선은 없습니다.상대 날짜를 사용한 지난 7일 (어제 시작) 기간의 예는 다음과 같습니다.
&start-date=7daysAgo &end-date=yesterday
종료일
end-date=2011-10-31
start-date 및 end-date 매개변수를 포함하지 않으면 서버에서 오류를 반환합니다.
날짜 값은 YYYY-MM-DD 패턴을 사용하여 특정 날짜를 대상으로 하거나 today, yesterday 또는 NdaysAgo 패턴을 사용하여 상대적일 수 있습니다.
값은 [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)과 일치해야 합니다.
end-date는 2005-01-01입니다. end-date의 상한선은 없습니다. 상대 날짜를 사용한 지난 10일 (오늘 시작) 기간의 예는 다음과 같습니다.
&start-date=9daysAgo &end-date=today
측정기준
dimensions=mcf:source,mcf:keyword
측정기준 매개변수는 다채널 유입경로 보고서의 기본 데이터 키(예: mcf:source 또는 mcf:medium)를 정의합니다.
측정기준을 사용하여 전환 측정항목을 분류합니다. 예를 들어 사이트로
발생한 총 전환수를 물어볼 수 있지만, 매체별로 분류된 전환수를
요청하는 것이 더 흥미로울 수 있습니다.
이 경우 자연 검색, 추천, 이메일 등에서 발생한 전환이
표시됩니다.
데이터 요청에 dimensions를 사용할 때는 다음 제약 조건에 유의하세요.
- 모든 쿼리에 최대 7개의 측정기준을 제공할 수 있습니다.
- 측정기준으로만 구성된 쿼리는 전송할 수 없습니다. 요청된 측정기준을 하나 이상의 측정항목과 결합해야 합니다.
사용할 수 없는 값
측정기준 값을 확인할 수 없는 경우 애널리틱스에서는 특수 문자열 (not set)을 사용합니다.
metrics
metrics=mcf:totalConversions,mcf:totalConversionValue
총 전환수 또는 총 전환 가치와 같이 사이트에 대한 사용자 활동에 대해 집계된 통계입니다.
쿼리에 dimensions 매개변수가 없으면 반환된 측정항목이 총 전환 가치와 같이 요청된 기간의 집계 값을 제공합니다. 하지만 측정기준이 요청되면 값이 측정기준 값을 기준으로 분류됩니다.
예를 들어 mcf:source로 요청된 mcf:totalConversions는 소스당 총 전환수를 반환합니다.
측정항목을 요청할 때는 다음 사항에 유의하세요.
- 모든 요청은 측정항목을 하나 이상 제공해야 합니다. 요청은 측정기준으로만 구성될 수 없습니다.
- 모든 쿼리에 최대 10개의 측정항목을 제공할 수 있습니다.
sort
sort=mcf:source,mcf:medium
반환된 데이터의 정렬 순서와 정렬 방향을 나타내는 측정항목 및 측정기준의 목록입니다.
- 정렬 순서는 나열된 측정항목 및 측정기준의 왼쪽에서 오른쪽 순서로 지정됩니다.
- direction 정렬은 기본적으로 오름차순으로 되어 있으며 요청된 필드에 빼기 기호 (
-) 프리픽스를 사용하여 내림차순으로 변경할 수 있습니다.
쿼리 결과를 정렬하면 데이터에 대해 다양한 질문을 할 수 있습니다. 예를 들어 '상위 전환 소스는 무엇이며 어떤 매체를 사용하는가?'라는 질문에 대한 답을 찾을 수 있습니다.
다음 매개변수를 사용하여 쿼리를 만들 수 있습니다. 먼저 mcf:source, mcf:medium를 기준으로 모두 오름차순으로 정렬됩니다.
sort=mcf:source,mcf:medium
'상위 전환 매체는 무엇이며 어떤 소스에서 유입되는지'와 관련된 질문에 답하려면 다음 매개변수를 사용하여 쿼리를 만들면 됩니다. 먼저 mcf:medium, mcf:source를 기준으로 모두 오름차순으로 정렬됩니다.
sort=mcf:medium,mcf:source
sort 매개변수를 사용할 때는 다음 사항에 유의하세요.
dimensions또는metrics매개변수에서 사용한 측정기준 또는 측정항목 값만 기준으로 정렬합니다. 측정기준 또는 측정항목 매개변수에 표시되지 않는 필드를 기준으로 요청이 정렬되면 오류가 발생합니다.- 기본적으로 문자열은 en-US 언어에서 알파벳 오름차순으로 정렬됩니다.
- 숫자는 기본적으로 오름차순으로 정렬됩니다.
- 날짜는 기본적으로 오름차순으로 정렬됩니다.
필터
filters=mcf:medium%3D%3Dreferral
filters 쿼리 문자열 매개변수는 요청에서 반환되는 데이터를 제한합니다. filters 매개변수를 사용하려면 필터링할 측정기준 또는 측정항목과 이어서 필터 표현식을 입력합니다. 예를 들어 다음 쿼리는 뷰 (프로필) 12134에 대해 mcf:totalConversions 및 mcf:source를 요청합니다. 여기서 mcf:medium 측정기준은 referral 문자열입니다.
https://www.googleapis.com/analytics/v3/data/mcf ?ids=mcf:12134 &dimensions=mcf:source &metrics=mcf:totalConversions &filters=mcf:medium%3D%3Dreferral &start-date=2011-10-01 &end-date=2011-10-31
자세한 내용은 Core Reporting API 참조를 참고하세요.
samplingLevel
samplingLevel=DEFAULT
DEFAULT- 속도와 정확성이 균형을 이루는 샘플 크기와 함께 응답을 반환합니다.FASTER- 더 작은 샘플 크기로 빠른 응답을 반환합니다.HIGHER_PRECISION- 큰 샘플 크기를 사용하여 더 정확한 응답을 반환하지만 이로 인해 응답이 느려질 수 있습니다.
DEFAULT 샘플링 수준이 사용됩니다.max-results
max-results=100
이 응답에 포함할 최대 행 수입니다. 이를 start-index와 함께 사용하여 요소의 하위 집합을 검색하거나, 이 요소만 사용하여 반환되는 요소 수를 제한할 수 있습니다(첫 번째 요소부터 시작).
max-results가 제공되지 않으면 쿼리는 기본값인 최대 1, 000개의 행을 반환합니다.
다채널 유입경로 Reporting API는 요청 횟수에 관계없이 요청당 최대 10,000개의 행을 반환합니다. 또한 측정기준 세그먼트가 예상한 만큼 많지 않은 경우 요청된 것보다 적은 수의 행이 반환될 수도 있습니다. 예를 들어 mcf:medium에서 사용할 수 있는 값은 300개 미만이므로 매체별로만 세분화할 경우 max-results을 더 높은 값으로 설정해도 행을 300개 이상 가져올 수 없습니다.
대응
성공하면 이 요청은 아래에 정의된 JSON 구조로 응답 본문을 반환합니다.
참고: '결과'라는 용어는 쿼리와 일치하는 전체 행 집합을 나타내고 '응답'은 현재 결과 페이지에서 반환되는 행 집합을 나타냅니다. itemsPerPage에 설명된 것처럼 총 결과 수가 현재 응답의 페이지 크기보다 크면 결과가 다를 수 있습니다.
응답 형식
{
"kind": "analytics#mcfData",
"id": string,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"sort": [
string
],
"filters": string,
"samplingLevel": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"selfLink": string,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"containsSampledData": boolean,
"sampleSize": string,
"sampleSpace": string,
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"totalsForAllResults": [
{
metricName: string,
...
}
]
"rows": [
[
McfData.Rows
]
],
}
응답 필드
응답 본문 구조의 속성은 다음과 같이 정의됩니다.
| 속성 이름 | 값 | 설명 |
|---|---|---|
kind |
string |
리소스 유형입니다. 값은 'analytics#mcfData'입니다. |
id |
string |
이 데이터 응답의 ID입니다. |
query |
object |
이 객체에는 쿼리에 매개변수로 전달된 모든 값이 포함됩니다. 각 필드의 의미는 해당 쿼리 매개변수에 대한 설명에 설명되어 있습니다. |
query.start-date |
string |
시작일 |
query.end-date |
string |
종료일 |
query.ids |
string |
고유한 테이블 ID입니다. |
query.dimensions[] |
list |
애널리틱스 측정기준의 목록입니다. |
query.metrics[] |
list |
애널리틱스 측정항목 목록입니다. |
query.sort[] |
list |
데이터가 정렬되는 측정항목 또는 측정기준의 목록입니다. |
query.filters |
string |
쉼표로 구분된 측정항목 또는 측정기준 필터 목록입니다. |
query.samplingLevel |
string |
Requested sampling level. |
query.start-index |
integer |
행의 시작 색인입니다. 기본값은 1입니다. |
query.max-results |
integer |
페이지당 최대 결과 수입니다. |
startIndex |
integer |
start-index 쿼리 매개변수로 지정된 행의 시작 색인입니다. 기본값은 1입니다. |
itemsPerPage |
integer |
반환된 실제 행 수와 관계없이 응답에 포함할 수 있는 최대 행 수입니다. max-results 쿼리 매개변수가 지정된 경우 itemsPerPage 값은 max-results와 10,000 중에서 더 작은 값입니다. itemsPerPage의 기본값은 1,000입니다.
|
totalResults |
integer |
응답에 반환된 행 수와 관계없이 쿼리 결과의 총 행 수입니다. 행 수가 많아지는 쿼리의 경우 totalResults이 itemsPerPage보다 클 수 있습니다.
대규모 쿼리의 totalResults 및 itemsPerPage에 관한 자세한 설명은 Paging을 참조하세요.
|
selfLink |
string |
이 데이터 쿼리에 대한 결과 페이지의 링크 |
previousLink |
string |
이 데이터 쿼리에 대한 이전 결과 페이지 링크입니다. |
nextLink |
string |
이 데이터 쿼리에 대한 결과의 다음 페이지 링크 |
profileInfo |
object |
데이터가 요청된 뷰 (프로필)에 관한 정보입니다. 보기 (프로필) 데이터는 Google Analytics Management API를 통해 사용할 수 있습니다. |
profileInfo.profileId |
string |
보기(프로필) ID(예: 1174). |
profileInfo.accountId |
string |
이 보기(프로필)가 속한 계정 ID입니다(예: 30481). |
profileInfo.webPropertyId |
string |
이 보기(프로필)가 속한 웹 속성 ID입니다(예: UA-30481-1). |
profileInfo.internalWebPropertyId |
string |
이 보기(프로필)가 속한 웹 속성의 내부 ID입니다(예: UA-30481-1). |
profileInfo.profileName |
string |
뷰 (프로필)의 이름입니다. |
profileInfo.tableId |
string |
뷰 (프로필)의 테이블 ID로, 'ga:' 뒤에 뷰 (프로필) ID가 옵니다. |
containsSampledData |
boolean |
응답에 샘플링된 데이터가 포함되어 있으면 참입니다. |
sampleSize |
string |
샘플링된 데이터를 계산하는 데 사용되는 샘플의 수입니다. |
sampleSpace |
string |
총 샘플링 공간 크기입니다. 샘플이 선택된 사용 가능한 총 샘플 공간 크기를 나타냅니다. |
columnHeaders[] |
list |
측정기준 이름 뒤에 측정항목 이름이 오는 열 헤더 측정기준 및 측정항목의 순서는 metrics 및 dimensions 매개변수를 통해 요청에 지정된 순서와 동일합니다. 헤더 수는 측정기준의 수와
측정항목의 수를 합한 값입니다. |
columnHeaders[].name |
string |
측정기준 또는 측정항목의 이름입니다. |
columnHeaders[].columnType |
string |
열 유형. 'DIMENSION' 또는 'METRIC'입니다. |
columnHeaders[].dataType |
string |
데이터 유형입니다. 측정기준 열 헤더에는 데이터 유형으로 "STRING" 또는 "MCF_SEQUENCE"만 있습니다.
측정항목 열 헤더에는 "INTEGER", "DOUBLE", "CURRENCY" 등의 측정항목 값에 대한 데이터 유형이 있습니다. |
totalsForAllResults |
object |
측정항목 이름 및 값의 키-값 쌍으로 구성된 요청된 측정항목의 총 값입니다. 측정항목 총계의 순서는 요청에 지정된 측정항목 순서와 동일합니다. |
rows[] |
list |
보고서 데이터 행. 각 행에는
{
"primitiveValue": "2183"
}
{
"conversionPathValue": [
{
"interactionType" : "CLICK",
"nodeValue" : "google"
},
{
"interactionType" : "CLICK",
"nodeValue" : "google"
}
]
}
|
오류 코드
요청이 성공하면 다채널 유입경로 Reporting API가 200 HTTP 상태 코드를 반환합니다. 쿼리를 처리하는 동안 오류가 발생하면 API에서 오류 코드와 설명을 반환합니다.
분석 API를 사용하는 각 애플리케이션은 적절한 오류 처리 로직을 구현해야 합니다. 오류 코드 및 오류 처리 방법에 대한 자세한 내용은
오류 응답 참조 가이드를 참조하세요.
사용해 보기
아래의 API 탐색기를 사용하여 실시간 데이터를 대상으로 이 메소드를 호출하고 응답을 확인해 보세요.
샘플링
Google 애널리틱스는 측정기준과 측정항목의 특정 조합을 즉시 계산합니다. Google 애널리틱스에서는 합리적인 시간 내에 데이터를 반환하기 위해 데이터의 샘플만 처리할 수 있습니다.
samplingLevel 매개변수를 설정하여 요청에 사용할 샘플링 수준을 지정할 수 있습니다.
MCF Reporting API 응답에 샘플링된 데이터가 포함되어 있으면 containsSampledData 응답 필드는 true가 됩니다.
또한 sampleSize 및 sampleSpace의 두 가지 속성은 쿼리의 샘플링 수준에 대한 정보를 제공합니다.
이 두 값을 사용하여 쿼리에 사용된 세션의 비율을 계산할 수 있습니다. 예를 들어 sampleSize가 201,000이고 sampleSpace이 220,000이면 보고서는 세션의 (201,000 / 220,000) * 100 = 91.36% 를 기반으로 합니다.
샘플링에 대한 일반적인 설명과 Google 애널리틱스에서 샘플링이 사용되는 방식은 샘플링을 참조하세요.
대규모 데이터 결과 처리
쿼리가 큰 결과 집합을 반환할 것으로 예상되는 경우 아래 가이드라인을 사용하여 API 쿼리를 최적화하고, 오류를 방지하고, 할당량 초과를 최소화하세요. Google에서는 API 요청 하나에 최대 7개의 측정기준과 10개의 측정항목을 허용하여 실적 기준을 설정합니다. 많은 수의 측정항목과 측정기준을 지정하는 일부 쿼리는 다른 쿼리보다 처리 시간이 더 오래 걸릴 수 있지만 요청된 측정항목의 수를 제한하는 것만으로는 쿼리 성능을 향상시키는 데 충분하지 않을 수 있습니다. 대신 다음 기법을 사용하면 최상의 성능 결과를 얻을 수 있습니다.
검색어당 측정기준 줄이기
API를 사용하면 요청 하나에 최대 7개의 측정기준을 지정할 수 있습니다. Google 애널리틱스는 이렇게 복잡한 쿼리의 결과를 즉시 계산해야 하는 경우가 많습니다. 결과 행 수가 많은 경우 특히 시간이 오래 걸릴 수 있습니다. 예를 들어 도시별로 키워드를 쿼리하면 수백만 개의 데이터 행과 일치할 수 있습니다. 쿼리의 측정기준 수를 제한하여 Google 애널리틱스에서 처리해야 하는 행 수를 줄여 성능을 개선할 수 있습니다.
기간별로 쿼리 분할
하나의 긴 기간에 대해 날짜로 입력된 결과를 페이징하는 대신 일주일(또는 하루)에 대해 한 번에 별도의 쿼리를 만드는 것이 좋습니다. 물론 대규모 데이터 세트의 경우 하루의 데이터를 요청해도 max-results 이상을 반환할 수 있으며, 이 경우 페이징을 피할 수 없습니다. 그러나 어떠한 경우든 쿼리에서 일치하는 행 수가 max-results보다 클 경우, 기간을 분할하면 총 결과를 검색하는 시간이 줄어들 수 있습니다. 이 접근 방식을 사용하면 단일 스레드 및 병렬 쿼리의 성능을 모두 개선할 수 있습니다.
Paging
결과를 페이징하면 대규모 결과 세트를 관리 가능한 청크로 나누는 데 유용한 방법이 될 수 있습니다. totalResults 필드는 일치하는 행 수를 알려주고 itemsPerPage는 결과에 반환될 수 있는 최대 행 수를 제공합니다.
totalResults 대 itemsPerPage의 비율이 높으면 개별 쿼리가 필요 이상으로 오래 걸릴 수 있습니다. 표시 목적과 같이 제한된 수의 행만 필요한 경우 max-results 매개변수를 통해 응답 크기에 명시적인 제한을 설정하는 것이 편리할 수 있습니다. 하지만 애플리케이션에서 대량의 결과 집합을 전부 처리해야 하는 경우에는 허용되는 최대 행을 요청하는 것이 더 효율적일 수 있습니다.
gzip 사용
각 요청에 필요한 대역폭을 줄이는 쉽고 편리한 방법은 gzip 압축을 사용 설정하는 것입니다. 결과의 압축을 풀려면 CPU 시간이 추가로 필요하지만 네트워크 비용을 감안하면 매우 유용합니다. gzip으로 인코딩된 응답을 받으려면 Accept-Encoding 헤더를 설정하고 gzip 문자열을 포함하도록 사용자 에이전트를 수정해야 합니다.
다음은 gzip 압축을 사용할 수 있도록 올바르게 구성된 HTTP 헤더의 예입니다.
Accept-Encoding: gzip User-Agent: my program (gzip)