Metadata API - Geliştirici Kılavuzu

Bu belgede, Google Analytics sütunlarının listesine ve özelliklerine erişmek için Metadata API'yi kullanmayla ilgili önemli kavramlar açıklanmaktadır.

Giriş

Metadata API, Google Analytics raporlama API'lerinde gösterilen sütunların (yani boyutlar ve metrikler) listesini ve özelliklerini döndürür. API'yi kullanmaya yeni başladıysanız Metadata API'ye giriş için Metadata API'ye Genel Bakış'ı okuyun.

Başlamadan Önce

Tüm Google Analytics API'lerine benzer şekilde erişilir. Metadata API'sini kullanmaya başlamadan önce şunları yapmanız gerekir:

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

Her istemci kitaplığı, tüm Metadata API verilerine erişmek için tek bir analiz hizmeti nesnesi sağlar. Metadata API ile kullanmak üzere hizmet nesnesi 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ı

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

API anahtarı edinme ve kullanma

API anahtarı edinmek 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 öncelikle bir istemci kimliği ve muhtemelen jeton almak için 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 herhangi bir yöntem bulunmadığından, yalnızca aşağıda açıklanan API anahtarlarını edinmeniz gerekebilir. Ancak uygulamanız kullanıcı yetkilendirmesi gerektiren diğer API'leri çağırırsa yine de OAuth 2.0 kimlik bilgilerine ihtiyacınız olur.

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

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

      API, API anahtarlarında çeşitli kısıtlama türlerini destekler. İhtiyacınız olan API anahtarı zaten mevcut değilse Kimlik bilgileri oluştur > API anahtarı'nı tıklayarak Console'da 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 kullanma konusundaki 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'lerinde, çeşitli istemci kitaplıkları için API Anahtarı'nın nasıl ayarlanacağı gösterilmektedir:

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ütunun (ör. boyut veya metrik) desteği sonlandırılırsa status özelliği DEPRECATED olarak ayarlanır.

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

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

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

Aşağıdaki snippet'te, değiştirme 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ın nasıl alınacağı gösterilmektedir:

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

Şablonize Sütunlar

Şablon haline getirilmiş sütunlar sayısal dizini olan boyutları veya metrikleri içerir. Örneğin, ga:goalXXStarts, ga:dimensionXX, ga:metricXX vb. Şablonlara sahip bir sütunda dizin aralığını tanımlayan minTemplateIndex ve maxTemplateIndex özellikleri bulunur.

Aşağıdaki snippet'te bir sütunun şablonlu olup olmadığını nasıl kontrol edeceğiniz gösterilmektedir:

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

Aşağıdaki snippet'te, şablonlu bir sütun için geçerli kimliklerin listesinin nasıl alınacağı gösterilmektedir:

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ütunda calculation özelliği bulunur. Ör. ga:percentNewSessions için hesaplama ga:newSessions / ga:sessions şeklinde hesaplanır.

Aşağıdaki örnekte, bir sütunun hesaplanıp hesaplanmadığının nasıl kontrol edileceği ve bir sütuna ilişkin 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, bir sütunun segment sorgu parametresinde kullanılıp kullanılamayacağını kontrol etmenizi sağlar.

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

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

API Sürümüne Eklendi

Bir sütunun, belirli bir sürümün raporlama API'sinde kullanılıp kullanılamayacağını kontrol etmek için addedInApiVersion özelliğini kullanın. Örneğin, sütunun Temel Raporlama API'sı 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ütun (yani boyutlar ve metrikler) verileri uzun süre aynı kalabileceği ve önbelleğe alınan veriler kullanılabildiğinde gereksiz istekler ve güncellemeler yapılmasının bir etkisi olmadığı için bu önemlidir.

Bir sütun koleksiyonunun ETag'ini depoluyorsanız öncelikle 2 şekilde kullanılabilir: önbelleğe alınmış bir Metadata API yanıtının güncel olup olmadığını kontrol etmek ve bunu bir Metadata API isteğinin parçası olarak eklemek.

Önbelleğe Alınan Yanıtları 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 ile eşdeğerse önbelleğe alınan sürüm güncel olur. ETag'ler eşdeğer değilse uygulamanızı güncelleyip önbelleği en son yanıtı ekleyerek yenileyin.

Metadata API'sinden yalnızca ETag değerini almak isterseniz istek yaparken 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ış sürümüne sahipseniz If-None-Match HTTP üstbilgi alanını ayarlayarak koleksiyon ETag değerini bir Metadata API isteğine ekleyebilirsiniz. Metadata API, ETag değerini kontrol eder ve kaynağın güncellenmiş sürümü ve 200 OK HTTP durumu ile birlikte ya da önbelleğe alınan sürümünüz güncelse 304 Not Modified durumuyla boş bir yanıtla yanıt verir.