개발자 가이드

이 문서에서는 Real Time Reporting API를 사용하여 Google 애널리틱스 데이터를 가져오는 방법을 설명합니다.

소개

Real Time Reporting API를 사용하면 속성에서 발생하는 활동을 실시간으로 보고할 수 있습니다. 실시간 데이터에 액세스하려면 뷰 (프로필)와 하나 이상의 측정항목을 지정하는 쿼리를 만듭니다. 또한 쿼리를 상세검색하기 위해 측정기준 및 필터와 같은 추가 쿼리 매개변수를 제공할 수도 있습니다. 이 쿼리는 Real Time Reporting API로 전송되어 테이블 형태로 데이터를 반환합니다.

API를 처음 사용하는 경우 Real Time Reporting API 개요에서 Real Time Reporting API에 대한 소개와 API가 제공하는 데이터를 확인하세요.

선행 조건

Real Time Reporting API를 사용하여 Google 애널리틱스 데이터를 가져오기 전에 다음을 수행하세요.

  • API와 호환되는 프로그래밍 언어별 클라이언트 라이브러리의 전체 목록은 클라이언트 라이브러리 페이지를 참조하세요.
  • 클라이언트 라이브러리를 사용하지 않고 API만 사용하여 Google 애널리틱스 데이터를 가져오는 방법은 참조 가이드를 참고하세요.

각 클라이언트 라이브러리는 모든 Real Time Reporting API 데이터에 액세스하는 단일 분석 서비스 객체를 제공합니다. 서비스 객체를 만들려면 다음 안내를 따르세요.

  1. Google API 콘솔에 애플리케이션을 등록합니다.
  2. Google 애널리틱스 데이터에 대한 액세스를 승인합니다.
  3. 애널리틱스 서비스 객체를 만듭니다.

이 단계를 완료하지 않았다면 Google 애널리틱스 API 애플리케이션을 빌드하는 초기 단계를 설명하는 Hello Google Analytics API 가이드를 읽어 보세요. 그런 다음 API를 사용하여 Google 애널리틱스 데이터를 가져오는 방법을 학습합니다.

Real Time Reporting API 사용

Real Time Reporting API를 사용하려면 애플리케이션이 다음을 충족해야 합니다.

  1. Real Time Reporting API를 쿼리합니다.
  2. API 응답을 처리합니다.

Real Time Reporting API 쿼리

분석 서비스 객체는 Real Time Reporting API 쿼리를 빌드하는 메서드를 제공합니다. API에 사용할 수 있는 쿼리 매개변수 및 데이터에 대한 자세한 내용은 다음을 참조하세요.

쿼리를 정의한 후 execute 메서드를 호출하여 Google 애널리틱스 서버로 쿼리를 전송합니다.

API 응답 처리

Real Time Reporting API에 대한 쿼리가 성공하면 API에서 요청된 데이터를 실시간 데이터 리소스의 일부로 반환합니다. API 응답 구조 및 형식에 관한 자세한 내용은 Real Time Reporting API 참조를 확인하세요.

오류가 발생하면 API는 특정 상태 코드와 오류를 설명하는 메시지를 반환합니다. 모든 애플리케이션은 오류를 포착하고 처리해야 합니다. 자세한 오류 목록 및 재시도 권장사항은 오류 응답을 참조하세요.

코드 예시

실시간 데이터: 가져오기 페이지의 예시 섹션에서 Real Time Reporting API를 쿼리하고 API 응답을 처리하는 다양한 프로그래밍 언어로 된 샘플 코드를 제공합니다.

쿼리 제약조건

Real Time API 쿼리에 대한 제한사항은 다음과 같습니다.

  • 다음 측정항목 필터가 있는 쿼리에 rt:activeUsers 측정항목이 포함된 경우 AND 연산자와 일치 일치 유형 (==)만 지원됩니다.
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    rt:activeUsers 측정항목은 현재 사이트에서 활성 상태인 사용자 수만 검색하므로 rt:activeUsers와 함께 rt:minutesAgo를 사용하지 마세요. 즉 rt:activeUsers는 rt:minutesAgo가 0임을 나타냅니다.

  • 측정항목 필터는 지원되지 않습니다.
  • fields 매개변수는 지원되지 않습니다.

할당량 관리

한도 및 할당량에 설명된 대로 다른 Google 애널리틱스 API와 공유되는 Real Time Reporting API의 일일 할당량이 있습니다. Real Time Reporting API를 짧은 시간 동안 폴링하면 일일 할당량 한도에 매우 빠르게 도달할 수 있습니다. 이 경우 할당량을 새로고침할 때까지 다른 Google 애널리틱스 API의 요청도 중단됩니다.

할당량을 매우 빨리 소진할 수 있는 구현 예는 다음과 같습니다.

  • 단일 Google 애널리틱스 보기 (프로필)의 데이터를 매일 아주 짧은 간격으로 쿼리하는 실시간 대시보드가 여러 개 있습니다.
  • 사용자가 많은 속성이 있고 실시간 위젯을 구현했습니다. 위젯이 사용자에게 표시될 때마다 캐시를 사용하는 대신 Google 애널리틱스를 직접 쿼리하게 됩니다.

할당량 사용량을 최소화하고 효율적으로 관리하려면 다음 안내를 따르세요.

  • 서버 측 캐싱 구현 여러 사용자가 동일한 실시간 데이터를 요청하면 각 사용자의 요청에 대해 Real Time Reporting API를 직접 쿼리하는 대신 캐시된 응답을 반환해야 합니다. 그런 다음 합당한 할당량 간격으로 최신 실시간 데이터로 주기적으로 캐시를 새로고침하여 일일 할당량 한도를 초과하지 않도록 합니다.
  • 추가 측정기준을 지정하여 여러 쿼리를 결합하고 서버 또는 클라이언트 측에서 응답을 파싱합니다.
  • 실시간 데이터를 요청하는 시간 간격을 늘립니다.

예: 새로고침 간격 계산

실시간 데이터에 대한 정기적인 요청을 실행한다면 예상 사용량에 따라 합당한 새로고침 간격을 선택해야 합니다.

예를 들어 Google 애널리틱스 보기 (프로필) 1개에 대한 일일 할당량 한도는 일일 요청 10,000건입니다. 하루 동안 Core View API에 단일 뷰 (프로필)에 대해 6,000개의 쿼리가 예상되는 경우 해당 뷰 (프로필)에 대해 4,000개의 요청이 남아 있게 됩니다.

Real Time Reporting API를 사용하여 하루 종일 동일한 뷰 (프로필)의 실시간 데이터 쿼리를 실행하는 3개의 실시간 대시보드를 구현하기로 했다고 가정해 보겠습니다. 각 대시보드는 하루에 약 1,333개의 쿼리를 수행할 수 있습니다 (쿼리 4,000개 / 대시보드 3개). 하루 86,400초입니다. 따라서 각 대시보드의 새로고침 간격은 65초(86,400 / 1,333)보다 커야 하므로, 보기(프로필)의 총 일일 요청 수가 4,000시간 한도를 초과하지 않습니다.