보고서 만들기

애널리틱스 Reporting API v4 개발자 가이드입니다. API의 자세한 참조는 API 참조를 확인하세요.

보고서

Analytics Reporting API v4는 Reports 리소스에 액세스할 수 있는 batchGet 메서드를 제공합니다. 다음 섹션에서는 batchGet요청 본문 구조와 batchGet응답 본문 구조를 설명합니다.

요청 본문

Analytics Reporting API v4를 사용하여 데이터를 요청하려면 다음과 같은 최소 요구사항이 포함된 ReportRequest 객체를 구성해야 합니다.

  • viewId 필드의 유효한 뷰 ID
  • dateRanges 필드에 유효한 항목이 하나 이상 있습니다.
  • metrics 입력란에 유효한 항목이 하나 이상 있어야 합니다.

뷰 ID를 찾으려면 계정 요약 메서드를 쿼리하거나 계정 탐색기를 사용합니다. 기간을 제공하지 않으면 기본 기간은 {"startDate": "7daysAgo", "endDate": "yesterday"}입니다.

다음은 최소 필수 입력란이 포함된 샘플 요청입니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:users"}]
    }
  ]
}

batchGet 메서드는 최대 5개의 ReportRequest 객체를 허용합니다. 모든 요청의 dateRange, viewId, segments, samplingLevel, cohortGroup가 동일해야 합니다.

응답 본문

API 요청의 응답 본문보고서 객체의 배열입니다. 보고서 구조는 보고서의 측정기준 및 측정항목과 그 데이터 유형을 설명하는 ColumnHeader 객체에 정의됩니다. 측정기준과 측정항목의 값은 data 필드에 지정됩니다.

다음은 위의 샘플 요청에 대한 샘플 응답입니다.

{
    "reports": [
        {
            "columnHeader": {
                "metricHeader": {
                    "metricHeaderEntries": [
                        {
                            "name": "ga:users",
                            "type": "INTEGER"
                        }
                    ]
                }
            },
            "data": {
                "isDataGolden": true,
                "maximums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "minimums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "rowCount": 1,
                "rows": [
                    {
                        "metrics": [
                            {
                                "values": [
                                    "98"
                                ]
                            }
                        ]
                    }
                ],
                "totals": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ]
            }
        }
    ]
}

측정항목

측정항목은 정량적 측정 결과입니다. 모든 요청에는 하나 이상의 Metric 객체가 필요합니다.

다음 예시에서는 지정된 기간의 총 세션수를 가져오기 위해 Sessions 측정항목이 batchGet 메서드에 제공됩니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:sessions"}]
    }
  ]
}

측정기준 및 측정항목 탐색기 또는 Metadata API를 사용하여 사용 가능한 측정기준 및 측정항목의 목록을 가져올 수 있습니다.

필터링

batchGet 요청을 제출할 때 특정 기준을 충족하는 측정항목만 반환하도록 요청할 수 있습니다. 측정항목을 필터링하려면 요청 본문에 하나 이상의 MetricFilterClauses를 지정하고 각 MetricFilterClause에서 하나 이상의 MetricFilters를 정의합니다. 각 MetricFilter에서 다음 값을 지정합니다.

  • metricName
  • not
  • operator
  • comparisonValue

{metricName}가 측정항목을 나타내고 {operator}operator, {comparisonValue}comparisonValue를 나타냅니다. 그러면 필터가 다음과 같이 작동합니다.

if {metricName} {operator} {comparisonValue}
   return the metric

nottrue를 지정하면 필터는 다음과 같이 작동합니다.

if {metricName} {operator} {comparisonValue}
   do not return the metric

다음 예에서 batchGet는 값이 2보다 큰 페이지 조회만 반환합니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "metricFilterClauses": [{
          "filters": [{
              "metricName": "ga:pageviews",
              "operator": "GREATER_THAN",
              "comparisonValue": "2"
          }]
      }]
  }]
}

표현식

측정항목 표현식은 기존 측정항목에 정의하는 수학 표현식입니다. 동적 계산된 측정항목처럼 작동합니다. 다음과 같이 측정항목 표현식을 나타내는 별칭을 정의할 수 있습니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {
          "expression": "ga:goal1completions/ga:users",
          "alias": "completions per user"
        }
      ]
    }
  ]
}

주문

측정항목 값을 기준으로 결과를 정렬하는 방법은 다음과 같습니다.

  • fieldName 필드를 통해 이름 또는 별칭을 입력합니다.
  • sortOrder 필드를 통해 정렬 순서 (ASCENDING 또는 DESCENDING)를 지정합니다.

다음 예에서 batchGet는 먼저 세션별로 정렬된 측정항목을 반환한 후 페이지 조회수를 기준으로 내림차순으로 정렬합니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "orderBys":
      [
        {"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
        {"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
      ]
    }
  ]
}

크기

측정기준은 사용자, 사용자 세션 및 액션의 특성을 설명합니다. 예를 들어 도시 측정기준은 세션의 특성을 설명하며 각 세션이 발생한 도시 ('파리' 또는 '뉴욕')를 나타냅니다. batchGet 요청에서 0개 이상의 측정기준 객체를 지정할 수 있습니다. 예를 들면 다음과 같습니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges":
      [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics":
      [
        {"expression": "ga:users"}
      ],
      "dimensions":
      [
        {"name": "ga:city"}
      ]
    }
  ]
}

필터링

batchGet 요청을 제출할 때 특정 기준을 충족하는 측정기준만 반환하도록 요청할 수 있습니다. 측정기준을 필터링하려면 요청 본문에서 DimensionsFilterClauses를 하나 이상 지정하고 각 DimensionsFilterClause에서 DimensionsFilters를 하나 이상 정의합니다. 각 DimensionsFilters에서 다음 값을 지정합니다.

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

{dimensionName}가 차원을 나타내고 {operator}operator, {expressions}expressions를 나타냅니다. 그러면 필터가 다음과 같이 작동합니다.

if {dimensionName} {operator} {expressions}
    return the dimension

nottrue를 지정하면 필터는 다음과 같이 작동합니다.

if {dimensionName} {operator} {expressions}
    do not return the dimension

다음 예에서 batchGet는 Chrome 브라우저의 페이지 조회수 및 세션을 반환합니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
      "dimensionFilterClauses": [
        {
          "filters": [
            {
              "dimensionName": "ga:browser",
              "operator": "EXACT",
              "expressions": ["Chrome"]
            }
          ]
        }
      ]
    }
  ]
}

주문

측정기준 값을 기준으로 결과를 정렬하는 방법은 다음과 같습니다.

  • fieldName 필드를 통해 이름을 입력합니다.
  • sortOrder 필드를 사용하여 정렬 순서 (ASCENDING 또는 DESCENDING)를 지정합니다.

예를 들어 다음 batchGet는 국가별로 정렬된 다음 브라우저별로 정렬된 측정기준을 반환합니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
      "orderBys": [
        {"fieldName": "ga:country"},
        {"fieldName": "ga:browser"}
      ]
    }
  ]
}

히스토그램 버킷

정수 값이 있는 차원의 경우 값을 범위로 버케팅하여 특성을 더 쉽게 이해할 수 있습니다. histogramBuckets 필드를 사용하여 결과 버킷의 범위를 정의하고 HISTOGRAM_BUCKET를 주문 유형으로 지정합니다. 예를 들면 다음과 같습니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [
        {
          "name": "ga:sessionCount",
          "histogramBuckets": ["1","10","100","200","400"]
        }
      ],
      "orderBys": [
        {
          "fieldName": "ga:sessionCount",
          "orderType": "HISTOGRAM_BUCKET"
        }
      ]
    }
  ]
}

여러 기간

Google 애널리틱스 Reporting API v4를 사용하면 단일 요청으로 여러 기간의 데이터를 가져올 수 있습니다. 요청에서 기간을 1개 또는 2개 지정했는지 여부에 관계없이 데이터는 dateRangeValue 객체에 반환됩니다. 예를 들면 다음과 같습니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}]
    }
  ]
}

델타 정렬

두 기간의 측정항목 값을 요청할 때는 해당 기간에 포함된 측정항목 값의 차이를 기준으로 결과를 정렬할 수 있습니다. 예를 들면 다음과 같습니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}],
      "orderBys": [
        {
          "fieldName": "ga:sessions",
          "orderType": "DELTA"
        }
      ]
    }
  ]
}

날짜 측정기준 동작

날짜 또는 시간 관련 측정기준을 요청하는 경우 DateRangeValue 객체에는 각 범위에 속하는 날짜의 값만 포함됩니다. 지정된 기간에 속하지 않는 다른 모든 값은 0이 됩니다.

예를 들어 1월과 2월이라는 두 기간의 ga:date 측정기준과 ga:sessions 측정항목에 대한 요청을 생각해 보세요. 1월의 요청된 데이터에 대한 응답에서 2월의 값은 0이 되고, 2월에 요청된 데이터에 대한 응답에서 1월의 값은 0가 됩니다.

1월 보고서

{
    "dimensions": [
        "20140101" # `ga:date` dimension value for January 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "8"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "0"
            ]
        }
    ]
},
...

2월 보고서

{
    "dimensions": [
        "20140201"  # `ga:date` dimension value for February 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "0"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "7"
            ]
        }
    ]
},
...

세그먼트

애널리틱스 데이터의 하위 집합을 요청하려면 세그먼트를 사용하세요. 예를 들어 한 세그먼트에서 특정 국가 또는 도시의 사용자를 정의할 수 있고, 다른 세그먼트에서 사이트의 특정 부분을 방문하는 사용자를 정의할 수 있습니다. 필터는 조건을 충족하는 행만 반환하지만 세그먼트는 세그먼트가 포함된 조건을 충족하는 사용자, 세션 또는 이벤트의 하위 집합을 반환합니다.

세그먼트로 요청할 때 다음 사항을 확인하세요.

  • batchGet 메서드 내의 모든 ReportRequest에는 동일한 세그먼트 정의가 포함되어야 합니다.
  • 측정기준 목록에 ga:segment를 추가합니다.

예를 들면 다음과 같습니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
      "metrics": [{"expression": "ga:sessions"}],
      "segments": [
        {
          "dynamicSegment":
          {
            "name": "Sessions with Safari browser",
            "userSegment":
            {
              "segmentFilters": [
                {
                  "simpleSegment":
                  {
                    "orFiltersForSegment": [
                      {
                        "segmentFilterClauses": [
                          {
                            "dimensionFilter":
                            {
                              "dimensionName": "ga:browser",
                              "operator": "EXACT",
                              "expressions": ["Safari"]
                            }
                        }]
                    }]
                  }
              }]
            }
          }
      }]
  }]
}

세그먼트가 포함된 요청 예를 더 보려면 샘플을 참고하세요.

세그먼트 ID

segmentId 필드를 사용하여 세그먼트를 요청합니다. 세그먼트를 요청하는 데 segmentIddynamicSegment을 모두 사용할 수는 없습니다.

예를 들면 다음과 같습니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
      "metrics": [{"expression": "ga:users"}],
      "segments":  [{"segmentId": "gaid::-3"}]
    }
  ]
}

샘플링

샘플링은 데이터 결과에 영향을 줄 수 있으며, 이는 API에서 반환된 값이 웹 인터페이스와 일치하지 않는 일반적인 이유입니다. samplingLevel 필드를 사용하여 원하는 샘플 크기를 설정합니다.

  • 샘플링 크기를 줄여 응답을 빠르게 얻으려면 값을 SMALL로 설정합니다.
  • 더 정확하지만 더 느린 응답을 받으려면 값을 LARGE로 설정하세요.
  • 속도와 정확성의 균형을 이루는 응답의 경우 값을 DEFAULT로 설정합니다.

예를 들면 다음과 같습니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}],
      "metrics": [{"expression": "ga:sessions"}],
      "samplingLevel":  "LARGE"
    }
  ]
}

보고서에 샘플링된 데이터가 포함되어 있으면 Analytics Reporting API v4에서 samplesReadCountssamplingSpaceSizes 필드를 반환합니다. 결과가 샘플링되지 않으면 이 필드가 정의되지 않습니다.

다음은 두 기간의 요청에서 샘플링된 데이터가 포함된 응답의 예입니다. 결과는 약 1,500만 세션의 샘플링 공간 규모의 약 500,000개의 샘플로 계산되었습니다.

{
  "reports":
  [
    {
      "columnHeader": {
        ...
      },
      "data": {
        ...
        "samplesReadCounts": [ "499630","499630"],
        "samplingSpaceSizes": ["15328013","15328013"],
      }
    }
  ]
}

페이지로 나누기

Analytics Reporting API v4는 pageTokenpageSize 필드를 사용하여 여러 페이지에 걸쳐 응답 결과를 페이지로 나눕니다. reports.batchGet 요청에 대한 응답의 nextPageToken 매개변수에서 pageToken를 가져옵니다.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    # Taken from `nextPageToken` of a previous response.
    "pageToken": "10000",
    "pageSize": "10000",
  }]
}

다음 단계

지금까지 보고서 만들기의 기본 사항을 살펴보았으므로 이제 API v4의 고급 기능에 대해 알아보세요.