Metadata API - 개발자 가이드

이 문서에서는 Metadata API를 사용하여 Google 애널리틱스 열의 목록과 속성에 액세스하는 방법에 관한 중요한 개념을 설명합니다.

소개

Metadata API는 Google 애널리틱스 Reporting API에 노출된 열 (즉, 측정기준 및 측정항목)과 해당 속성을 반환합니다. API를 처음 사용하는 경우 Metadata API 개요에서 Metadata API 소개를 확인하세요.

시작하기 전에

모든 Google 애널리틱스 API는 비슷한 방식으로 액세스됩니다. Metadata API를 시작하기 전에 다음을 수행해야 합니다.

  • API와 호환되는 프로그래밍 언어별 클라이언트 라이브러리의 전체 목록은 클라이언트 라이브러리 페이지를 참조하세요.
  • API 참조 및 클라이언트 라이브러리 없이 데이터에 액세스하는 방법은 참조 가이드를 참고하세요.

각 클라이언트 라이브러리는 모든 Metadata API 데이터에 액세스하기 위한 단일 분석 서비스 객체를 제공합니다. Metadata API에서 사용할 서비스 객체를 만들려면 일반적으로 다음 단계를 거쳐야 합니다.

  1. Google API 콘솔에 애플리케이션을 등록합니다.
  2. 애널리틱스 서비스 객체를 만들고 API 키를 설정합니다.

등록 및 API 키

애플리케이션은 각 요청에 API 키를 포함하여 애널리틱스 API에 요청을 전송할 때마다 자신을 식별해야 합니다.

API 키 획득 및 사용

API 키를 획득하려면 다음 안내를 따르세요.

  1. API 콘솔에서 사용자 인증 정보 페이지를 엽니다.
  2. 이 API는 두 가지 유형의 사용자 인증 정보를 지원합니다. 프로젝트에 적합한 사용자 인증 정보를 만듭니다.
    • OAuth 2.0: 애플리케이션에서 비공개 사용자 데이터를 요청할 때마다 요청과 함께 OAuth 2.0 토큰을 보내야 합니다. 애플리케이션은 먼저 토큰을 획득하기 위해 클라이언트 ID나 클라이언트 보안 비밀번호를 보냅니다. 웹 애플리케이션, 서비스 계정, 설치된 애플리케이션의 OAuth 2.0 사용자 인증 정보를 생성할 수 있습니다.

      참고: 이 API에는 OAuth 2.0 승인이 필요한 메서드가 없으므로 아래에 설명된 API 키만 가져오면 됩니다. 하지만 애플리케이션이 사용자 승인이 필요한 다른 API를 호출하는 경우에는 OAuth 2.0 사용자 인증 정보가 필요합니다.

      자세한 내용은 OAuth 2.0 문서를 참조하세요.

    • API 키: OAuth 2.0 토큰을 제공하지 않는 요청은 API 키를 전송해야 합니다. 키는 프로젝트를 식별하고 API 액세스, 할당량, 보고서를 제공합니다.

      API는 여러 유형의 API 키 제한 사항을 지원합니다. 필요한 API 키가 아직 없는 경우 사용자 인증 정보 만들기 > API 키를 클릭하여 Console에서 API 키를 만듭니다. 프로덕션 단계에서 사용하기 전에 키 제한을 클릭하고 제한사항 중 하나를 선택하여 키를 제한할 수 있습니다.

API 키를 안전하게 보호하려면 API 키를 안전하게 사용하기 위한 권장사항을 따르세요.

API 키가 있으면 애플리케이션은 모든 요청 URL에 쿼리 매개변수 key=yourAPIKey를 추가할 수 있습니다.

API 키는 URL에 포함하기에 안전합니다. 인코딩이 전혀 필요하지 않습니다.

다음 코드 스니펫은 다양한 클라이언트 라이브러리의 API 키를 설정하는 방법을 보여줍니다.

자바

import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.http.javanet.NetHttpTransport;

import com.google.api.services.analytics.Analytics;
import com.google.api.services.analytics.AnalyticsRequestInitializer;

public class ApiKeySample {
  private static final String API_KEY = "YOUR API KEY";

  public static void main(String[] args) {
    NetHttpTransport netHttpTransport = new NetHttpTransport();
    JacksonFactory jacksonFactory = new JacksonFactory();

    // Set the API Key
    AnalyticsRequestInitializer analyticsInitializer = new AnalyticsRequestInitializer(API_KEY);

    // Build the Analytics Service object
    Analytics analytics = new Analytics.Builder(netHttpTransport, jacksonFactory, null)
        .setAnalyticsRequestInitializer(analyticsInitializer)
        .setApplicationName("ApiKeySample")
        .build();

    // Start coding cool things.
  }
}

Python

from apiclient.discovery import build

API_KEY = 'YOUR API KEY'

def main(argv):
  # Set the API Key and build the Analytics service object.
  service = build('analytics', 'v3', developerKey=API_KEY)

  # Start coding cool things.

PHP

require_once 'google-api-php-client/src/Google_Client.php';
require_once 'google-api-php-client/src/contrib/Google_AnalyticsService.php';

const API_KEY = 'YOUR API KEY'

$client = new Google_Client();

// Set the API Key
$client->setDeveloperKey($API_KEY);

// Build the Analytics Service object.
$analytics = new google_AnalyticsService($client);

// Start coding cool things.

자바스크립트

<!--
  Method 1:
  Using the Google APIs Client Library for JavaScript
-->
<script>
var apiKey = 'YOUR API KEY';

function handleClientLoad() {
  gapi.client.setApiKey(apiKey);
  gapi.client.load('analytics', 'v3', makeRequest);
}

function makeRequest() {
  // Start coding cool things.
}
</script>
<script src="//apis.google.com/js/client.js?onload=handleClientLoad"></script>


<!--
  Method 2:
  Using REST and callback parameter
-->
<script>
function render() {
  // Place your awesome code here.
}
</script>

<!-- Replace RESOURCE with the path to the Google Analytics resource you're querying. -->
<script src="https://www.googleapis.com/analytics/v3/RESOURCE/?key=YOUR_API_KEY&callback=render"></script>

열 속성

Metadata API 응답에는 유효한 모든 열 속성을 나열하는 attributeNames 속성이 포함됩니다. 각 열에는 열에 적용할 수 있는 속성의 하위 집합이 포함된 attributes 속성이 있습니다.

다음 표에는 유효한 속성의 전체 목록이 나와 있습니다.

사용 사례

Metadata API를 사용하면 다음과 같은 사용 사례를 해결할 수 있습니다.

지원 중단된 열

열 (측정기준 또는 측정항목)이 지원 중단되면 status 속성이 DEPRECATED로 설정됩니다.

다음 스니펫은 status 속성을 사용하여 열이 지원 중단되었는지 확인하는 방법을 보여줍니다.

function isDeprecated(column) {
  return column.attributes.status == 'DEPRECATED';
}

열 이름이 변경되거나 삭제되면 status 속성이 DEPRECATED로 설정되고 대체 속성의 Id로 설정된 replacedBy 속성이 있을 수 있습니다.

다음 스니펫은 replacedBy 속성을 사용하여 대체 열의 ID를 가져오는 방법을 보여줍니다.

function getReplacementId(column) {
  return column.attributes.replacedBy;
}

열 이름

uiName 속성은 Google 애널리틱스 사용자 인터페이스 (예: 웹 인터페이스)에서 사용되는 측정기준 또는 측정항목 이름입니다.

다음 스니펫은 열의 UI 이름을 검색하는 방법을 보여줍니다.

function getColumnName(column) {
  return column.attributes.uiName;
}

템플릿화된 열

템플릿화된 열에는 숫자 색인이 있는 측정기준 또는 측정항목이 포함됩니다. 예: ga:goalXXStarts, ga:dimensionXX, ga:metricXX 등. 템플릿화된 열에는 색인 범위를 정의하는 minTemplateIndexmaxTemplateIndex 속성이 있습니다.

다음 스니펫은 열이 템플릿화되었는지 확인하는 방법을 보여줍니다.

function isTemplatized(column) {
  return !!column.attributes.minTemplateIndex ||
         !!column.attributes.maxTemplateIndex;
}

다음 스니펫은 템플릿화된 열의 유효한 ID 목록을 검색하는 방법을 보여줍니다.

function getTemplatizedIdList(column) {
  var columnIdList = [];
  var columnId = column.id;

  if (isTemplatized(column)) {
    minIndex = parseInt(column.attributes.minTemplateIndex);
    maxIndex = parseInt(column.attributes.maxTemplateIndex);

    for (var i = minIndex; i <= maxIndex; i++) {
      columnIdList.push(columnId.replace('XX', i));
    }
  }
  return columnIdList;
}

계산된 열

다른 열의 계산에서 파생된 열에는 calculation 속성이 있습니다. 예를 들어 ga:percentNewSessions의 계산은 ga:newSessions / ga:sessions입니다.

다음 예시에서는 열의 계산 여부를 확인하고 열의 계산을 검색하는 방법을 보여줍니다.

function isCalculated(column) {
  return !!column.attributes.calculation;
}

function getCalculation(column) {
  return column.attributes.calculation;
}

열 및 세그먼트

allowedInSegments 속성을 사용하면 세그먼트 쿼리 매개변수에서 열을 사용할 수 있는지 확인할 수 있습니다.

다음 예는 열을 세그먼트에서 사용할 수 있는지 확인하는 방법을 보여줍니다.

function isAllowedInSegments(column) {
  return !!column.attributes.allowedInSegments;
}

API 버전에 추가됨

addedInApiVersion 속성을 사용하여 지정된 버전의 보고서 API에서 열을 사용할 수 있는지 확인합니다. 예를 들어 Core Reporting API V3에서 열을 사용할 수 있는지 확인하려면 다음 함수를 호출합니다.

function isAllowedInV3(column) {
  return column.attributes.addedInApiVersion < 4;
}

ETag

모든 Metadata API 응답에 ETag가 포함되어 있습니다. ETag는 Metadata API 응답을 캐시하고 업데이트하는 데 사용할 수 있는 식별자입니다. 열 (측정기준 및 측정항목) 데이터가 장기간 변경되지 않고 유지될 수 있으며, 캐시된 데이터를 사용할 수 있을 때 불필요한 요청과 업데이트를 할 수 없기 때문에 이는 중요합니다.

열 컬렉션의 ETag를 저장하는 경우 주로 2가지 방법으로 사용할 수 있습니다. 즉, 캐시된 Metadata API 응답이 최신 상태인지 확인하고 Metadata API 요청의 일부로 포함합니다.

캐시된 응답 확인

Metadata API 응답에서 반환된 ETag 값을 비교하고 캐시된 리소스의 ETag와 동등한 경우 캐시된 버전은 현재 버전입니다. ETag가 동등하지 않으면 애플리케이션을 업데이트하고 캐시를 최신 응답으로 새로고침합니다.

Metadata API에서 ETag 값만 검색하려면 요청 시 필드 쿼리 매개변수를 etag로 설정합니다. 예시 보기

API 요청에 ETag 사용

열 컬렉션의 캐시된 버전이 있는 경우 If-None-Match HTTP 헤더 필드를 설정하여 Metadata API 요청에 ETag 값을 포함할 수 있습니다. Metadata API는 ETag 값을 확인하고 리소스의 업데이트된 버전과 200 OK HTTP 상태를 사용하여 응답하거나 캐시된 버전이 현재인 경우 304 Not Modified 상태의 빈 응답을 반환합니다.