Metadata API - Geliştirici Kılavuzu

Bu dokümanda, Google Analytics sütunlarının listesine ve özelliklerine erişmek için Metadata API'sinin kullanımıyla ilgili önemli kavramlar açıklanmaktadır.

Giriş

Metadata API'si, Google Analytics raporlama API'lerinde sunulan sütunların (ör. boyutlar ve metrikler) listesini ve özelliklerini döndürür. API'de yeniyseniz Metadata API'sine giriş için Meta Veri API'sına Genel Bakış'ı okuyun.

Başlamadan Önce

Tüm Google Analytics API'lerine benzer bir şekilde erişilir. Metadata API'sini kullanmaya başlamadan önce:

  • API ile çalışan programlama diline özel istemci kitaplıklarının tam listesi için istemci kitaplıkları sayfasını okuyun.
  • API arayüzü ve verilere istemci kitaplığı olmadan erişme hakkında bilgi edinmek için Referans Kılavuzu'nu okuyun.

Her istemci kitaplığı, tüm Meta Veri API verilerine erişmek için tek bir analiz hizmet nesnesi sağlar. Metadata API ile kullanılacak hizmet nesnesini oluşturmak için genellikle aşağıdaki adımları uygulamanız gerekir:

  1. Uygulamanızı Google API Konsolu'na kaydedin.
  2. Bir Analytics hizmet nesnesi oluşturun ve API Anahtarı'nı ayarlayın.

Kayıt ve API Anahtarı

Uygulamanızın Analytics API'ye her istek gönderişinde, her isteğe bir API anahtarı ekleyerek kendini tanımlaması gerekir.

API anahtarı edinme ve kullanma

API anahtarı almak için:

  1. API Konsolu'nda Kimlik bilgileri sayfası'nı açın.
  2. Bu API iki tür kimlik bilgisini destekler. Projeniz için uygun kimlik bilgilerini oluşturun:
    • OAuth 2.0: Uygulamanız gizli kullanıcı verileri istediğinde, istekle birlikte bir OAuth 2.0 jetonu göndermelidir. Uygulamanız, önce jeton almak için bir istemci kimliği ve muhtemelen bir istemci gizli anahtarı gönderir. Web uygulamaları, hizmet hesapları veya yüklü uygulamalar için OAuth 2.0 kimlik bilgileri oluşturabilirsiniz.

      Not: Bu API'de OAuth 2.0 yetkilendirmesi gerektiren hiçbir yöntem bulunmadığından, yalnızca aşağıda açıklanan API anahtarlarını almanız gerekebilir. Ancak, uygulamanız kullanıcı yetkilendirmesi gerektiren diğer API'leri çağırıyorsa yine de OAuth 2.0 kimlik bilgilerine ihtiyacınız vardır.

      Daha fazla bilgi için OAuth 2.0 dokümanlarına bakın.

    • API anahtarları: OAuth 2.0 jetonu sağlamayan bir istek API anahtarı göndermelidir. Anahtar, projenizi tanımlar ve API erişimi, kotası ve raporları sağlar.

      API, API anahtarlarıyla ilgili çeşitli kısıtlama türlerini destekler. İhtiyacınız olan API anahtarı henüz yoksa Console'da Kimlik bilgisi oluştur > API anahtarı'nı tıklayarak bir API anahtarı oluşturun. Anahtarı, üretimde kullanmadan önce Anahtarı kısıtla'yı tıklayıp Kısıtlamalar'dan birini seçerek kısıtlayabilirsiniz.

API anahtarlarınızı güvende tutmak için API anahtarlarını güvenli bir şekilde kullanmakla ilgili en iyi uygulamaları takip edin.

Bir API anahtarınız olduktan sonra, uygulamanız key=yourAPIKey sorgu parametresini tüm istek URL'lerine ekleyebilir.

API anahtarı, URL'lere yerleştirmek için güvenlidir; herhangi bir kodlama yapmanız gerekmez.

Aşağıdaki kod snippet'leri, API İstemcisinin çeşitli istemci kitaplıkları için nasıl ayarlanacağını göstermektedir:

Java

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.

JavaScript

<!--
  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>

Sütun Özellikleri

Metadata API yanıtı, geçerli tüm sütun özelliklerini listeleyen bir attributeNames özelliği içerir. Her sütunda, sütun için geçerli olan özelliklerin bir alt kümesini içeren bir attributes özelliği bulunur.

Geçerli özelliklerin tam listesi aşağıdaki tabloda verilmiştir:

Kullanım Alanları

Metadata API'si aşağıdaki kullanım alanlarını çözmek için kullanılabilir:

Kullanımdan Kaldırılan Sütunlar

Bir sütun (yani boyut veya metrik) kullanımdan kaldırılırsa status özelliği DEPRECATED olarak ayarlanır.

Aşağıdaki snippet'te, bir sütunun kullanımdan kaldırıldığını kontrol etmek için status özelliğinin nasıl kullanılacağı gösterilmektedir:

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

Bir sütun yeniden adlandırılır/kaldırılırsa status özelliği DEPRECATED olarak ayarlanır ve replacedBy özelliği, değişim sütununun Id değerine ayarlanmış olabilir.

Aşağıdaki snippet'te, değişim sütununun kimliğini almak için replacedBy özelliğinin nasıl kullanılacağı gösterilmektedir:

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

Sütun Adları

uiName özelliği, Google Analytics kullanıcı arayüzlerinde (ör. web arayüzü) kullanılan boyut veya metrik adıdır.

Aşağıdaki snippet'te bir sütunun kullanıcı arayüzü adını nasıl alacağınızı görebilirsiniz:

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

Şablonlu Sütunlar

Şablon uygulanan sütunlar, sayısal bir dizine sahip boyut veya metrikleri içerir. Örneğin, ga:goalXXStarts, ga:dimensionXX, ga:metricXX vb. Şablonlu bir sütun, dizin aralığını tanımlayan minTemplateIndex ve maxTemplateIndex özelliklerine sahip olur.

Aşağıdaki snippet'te bir sütunun şablonu oluşturulup oluşturulmadığı nasıl kontrol edileceği gösterilmektedir:

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

Aşağıdaki snippet, şablonlu bir sütun için geçerli kimlikler listesinin nasıl alınacağını göstermektedir:

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;
}

Hesaplanmış Sütunlar

Diğer sütunların hesaplanmasından türetilen bir sütun calculation özelliğine sahip olur. Örneğin ga:percentNewSessions için hesaplama ga:newSessions / ga:sessions şeklindedir.

Aşağıdaki örnekte, bir sütunun hesaplanıp hesaplanmadığı nasıl kontrol edileceği ve bir sütun için hesaplamanın nasıl alınacağı gösterilmektedir:

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

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

Sütunlar ve Segmentler

allowedInSegments özelliği, segment sorgusu parametresinde bir sütunun kullanılıp kullanılamayacağını kontrol etmenize olanak tanır.

Aşağıdaki örnekte, bir sütunun segmentlerde kullanılıp kullanılamayacağı nasıl belirleneceği gösterilmektedir:

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

API Sürümünde Eklendi

Bir sütunun belirtilen sürümdeki bir raporlama API'sinde kullanılıp kullanılamayacağını kontrol etmek için addedInApiVersion özelliğini kullanın. Örneğin, sütunun Core Reporting API V3'te kullanılabileceğini doğrulamak için aşağıdaki işlevi çağırın:

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

ETag

Her Metadata API yanıtına bir ETag eklenir. ETag, Metadata API yanıtlarını önbelleğe almak ve güncellemek için kullanılabilecek bir tanımlayıcıdır. Sütunlar (yani boyutlar ve metrikler) verileri uzun süre değişmeyebilir ve önbelleğe alınan verilerin kullanılabileceği durumlarda gereksiz istekler ve güncellemeler yapmak yetersiz olduğundan bu önemlidir.

Bir sütun koleksiyonunun ETag'ünü depolarsanız bunu birincil olarak 2 şekilde kullanabilirsiniz: önbelleğe alınan bir Meta Veri API yanıtının güncel olup olmadığını kontrol etmek ve bunu bir Meta Veri API isteğinin parçası olarak eklemek.

Önbelleğe alınan yanıtı kontrol etme

Bir Metadata API yanıtından döndürülen ETag değerini karşılaştırırsanız ve bu değer, önbelleğe alınan bir kaynak için ETag'e eş değerse, önbelleğe alınan sürüm geçerli olur. ETag'ler eşdeğer değilse uygulamanızı güncelleyin ve en yeni yanıtla önbelleği yenileyin.

Metadata API'sinden yalnızca ETag değerini almak istiyorsanız istekte bulunurken fields sorgu parametresini etag olarak ayarlayın. Örneğe göz atın.

API İsteğiyle ETag Kullanma

Bir sütun koleksiyonunun önbelleğe alınmış bir sürümüne sahipseniz If-None-Match HTTP üst bilgisi alanını ayarlayarak EGA değerini Meta Veri API isteğine ekleyebilirsiniz. Metadata API'si ETag değerini kontrol eder ve kaynağın güncel bir sürümüyle ve 200 OK HTTP durumu ile ya da önbelleğe alınmış sürümünüz geçerliyse 304 Not Modified durumu ile boş bir yanıt ile yanıt verir.