개발자 가이드

이 문서에서는 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 Analytics 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가 특정 상태 코드와 오류를 설명하는 메시지를 반환합니다. 모든 애플리케이션은 오류를 포착하고 처리해야 합니다. 자세한 오류 목록 및 재시도 권장사항은 오류 응답 을 참조하세요.

코드 예시

실시간 데이터: get 페이지의 예시 섹션에서는 다양한 프로그래밍 언어로 된 샘플 코드를 제공하여 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:activeUsersrt:minutesAgo가 0임을 암시합니다.

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

할당량 관리

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

다음은 할당량이 매우 빠르게 소진될 수 있는 구현의 예입니다.

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

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

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

예: 새로고침 간격 계산

실시간 데이터를 정기적으로 요청할 경우 예상 사용량을 기준으로 적절한 새로고침 간격을 선택해야 합니다.

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

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