Metadata API – Entwicklerleitfaden

In diesem Dokument werden wichtige Konzepte der Verwendung der Metadata API für den Zugriff auf die Liste und die Attribute von Google Analytics-Spalten erläutert.

Einführung

Die Metadata API gibt die Liste der Spalten (d.h. Dimensionen und Messwerte) zurück, die in den Google Analytics Reporting APIs und deren Attributen verfügbar sind. Wenn du noch nicht mit der API vertraut bist, findest du unter Metadata API eine Einführung in die Metadata API.

Vorbereitung

Der Zugriff auf alle Google Analytics APIs erfolgt auf ähnliche Weise. Bevor Sie mit der Metadata API beginnen, sollten Sie Folgendes tun:

  • Eine vollständige Liste der Programmiersprachen-spezifischen Clientbibliotheken, die mit der API funktionieren, finden Sie auf der Seite Clientbibliotheken.
  • Im Referenzleitfaden erfahren Sie mehr über die API-Schnittstelle und den Zugriff auf Daten ohne Clientbibliothek.

Jede Clientbibliothek stellt ein einzelnes Analysedienstobjekt bereit, um auf alle Metadata API-Daten zuzugreifen. Zum Erstellen des Dienstobjekts zur Verwendung mit der Metadata API müssen Sie im Allgemeinen die folgenden Schritte ausführen:

  1. Registrieren Sie Ihre Anwendung in der Google API Console.
  2. Erstellen Sie ein Analytics-Dienstobjekt und legen Sie den API-Schlüssel fest.

Registrierung und API-Schlüssel

Ihre Anwendung muss sich bei jeder Anfrage an die Analytics API identifizieren, indem sie jeder Anfrage einen API-Schlüssel hinzufügt.

API-Schlüssel erhalten und nutzen

So erhalten Sie einen API-Schlüssel:

  1. Öffnen Sie in der API Console die Seite „Anmeldedaten“.
  2. Diese API unterstützt zwei Arten von Anmeldedaten. Erstellen Sie die Anmeldedaten, die für Ihr Projekt geeignet sind:

    • OAuth 2.0: Wenn Ihre Anwendung private Nutzerdaten anfordert, muss sie zusammen mit der Anfrage ein OAuth 2.0-Token senden. Die Anwendung sendet zuerst eine Client-ID und möglicherweise einen Clientschlüssel, um ein Token zu erhalten. Sie können OAuth 2.0-Anmeldedaten für Webanwendungen, Dienstkonten oder installierte Anwendungen generieren.

      Hinweis:Da diese API keine Methoden enthält, die eine OAuth 2.0-Autorisierung erfordern, müssen Sie möglicherweise nur API-Schlüssel anfordern, die unten beschrieben sind. Wenn Ihre Anwendung jedoch andere APIs aufruft, die eine Nutzerautorisierung erfordern, benötigen Sie weiterhin OAuth 2.0-Anmeldedaten.

      Weitere Informationen finden Sie in der OAuth 2.0-Dokumentation.

    • API-Schlüssel: Eine Anfrage, die kein OAuth 2.0-Token bereitstellt, muss einen API-Schlüssel senden. Mit diesem Schlüssel werden Ihr Projekt identifiziert sowie der API-Zugriff, das Kontingent und Berichte bereitgestellt.

      Die API unterstützt mehrere Arten von Einschränkungen für API-Schlüssel. Wenn der erforderliche API-Schlüssel noch nicht vorhanden ist, erstellen Sie in der Console einen API-Schlüssel. Klicken Sie dazu auf Anmeldedaten erstellen > API-Schlüssel. Sie können den Schlüssel einschränken, bevor Sie ihn in der Produktionsumgebung verwenden. Klicken Sie dazu auf Schlüssel einschränken und wählen Sie eine der Einschränkungen aus.

Folgen Sie zur Wahrung der Sicherheit Ihrer API-Schlüssel den Best Practices zur sicheren Verwendung von API-Schlüsseln.

Nachdem Sie einen API-Schlüssel haben, kann Ihre Anwendung den Abfrageparameter key=yourAPIKey an alle Anfrage-URLs anhängen.

Der API-Schlüssel lässt sich sicher in URLs einbetten. Eine Codierung ist nicht notwendig.

Die folgenden Code-Snippets veranschaulichen, wie der API-Schlüssel für verschiedene Clientbibliotheken festgelegt wird:

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>

Spaltenattribute

Die Metadata API-Antwort enthält das Attribut attributeNames, das alle gültigen Spaltenattribute auflistet. Jede Spalte hat das Attribut attributes, das eine Teilmenge von Attributen enthält, die für die Spalte gelten.

In der folgenden Tabelle finden Sie die vollständige Liste der gültigen Attribute:

Anwendungsbeispiele

Die Metadata API kann zur Lösung der folgenden Anwendungsfälle verwendet werden:

Eingestellte Spalten

Wenn eine Spalte (d.h. eine Dimension oder ein Messwert) eingestellt wurde, wird das Attribut status auf DEPRECATED gesetzt.

Das folgende Snippet zeigt, wie Sie mit dem Attribut status prüfen, ob eine Spalte verworfen wurde:

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

Wenn eine Spalte umbenannt/entfernt wird, wird ihr status-Attribut auf DEPRECATED gesetzt und es kann sein, dass ein replacedBy-Attribut auf Id der Ersatzspalte festgelegt ist.

Das folgende Snippet zeigt, wie Sie mit dem Attribut replacedBy die ID der Ersatzspalte abrufen:

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

Spaltennamen

Das uiName-Attribut ist der Dimensions- oder Messwertname, der in Google Analytics-Benutzeroberflächen (z.B. der Weboberfläche) verwendet wird.

Im folgenden Snippet sehen Sie, wie der UI-Name einer Spalte abgerufen wird:

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

Vorlagenisierte Spalten

Vorlagenvorlagen enthalten Dimensionen oder Messwerte mit numerischem Index. Beispiel: ga:goalXXStarts, ga:dimensionXX, ga:metricXX usw. Eine Vorlagenspalte hat die Attribute minTemplateIndex und maxTemplateIndex, die den Indexbereich definieren.

Im folgenden Snippet sehen Sie, wie Sie prüfen, ob eine Spalte in Vorlagen steht:

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

Das folgende Snippet zeigt, wie eine Liste mit gültigen IDs für eine Vorlagenspalte abgerufen wird:

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

Berechnete Spalten

Eine Spalte, die aus einer Berechnung anderer Spalten abgeleitet wird, hat das Attribut calculation. Die Berechnung für ga:percentNewSessions lautet beispielsweise ga:newSessions / ga:sessions.

Im folgenden Beispiel sehen Sie, wie Sie prüfen, ob eine Spalte berechnet ist, und die Berechnung für eine Spalte abrufen:

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

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

Spalten und Segmente

Mit dem Attribut allowedInSegments können Sie prüfen, ob eine Spalte im Abfrageparameter für Segmente verwendet werden kann.

Das folgende Beispiel zeigt, wie ermittelt werden kann, ob eine Spalte in Segmenten verwendet werden kann:

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

In API-Version hinzugefügt

Mit dem Attribut addedInApiVersion prüfen Sie, ob eine Spalte in einer Reporting API einer bestimmten Version verwendet werden kann. Rufen Sie beispielsweise die folgende Funktion auf, um zu prüfen, ob die Spalte in der Core Reporting API V3 verwendet werden kann: 

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

ETag

In jeder Metadata API-Antwort ist ein ETag enthalten. Das ETag ist eine Kennung, mit der Metadata API-Antworten im Cache gespeichert und aktualisiert werden können. Dies ist wichtig, da Daten aus Spalten (d. h. Dimensionen und Messwerten) über einen längeren Zeitraum unverändert bleiben können. Außerdem ist es nicht effizient, unnötige Anfragen und Aktualisierungen zu stellen, wenn Daten im Cache verwendet werden können.

Wenn Sie das ETag einer Spaltensammlung speichern, kann es hauptsächlich auf zwei Arten verwendet werden, um zu prüfen, ob eine im Cache gespeicherte Metadata API-Antwort auf dem neuesten Stand ist, und um sie in eine Metadata API-Anfrage aufzunehmen.

Im Cache gespeicherte Antwort prüfen

Wenn Sie den ETag-Wert vergleichen, der von einer Metadata API-Antwort zurückgegeben wird, und dieser Wert dem ETag für eine im Cache gespeicherte Ressource entspricht, ist die im Cache gespeicherte Version aktuell. Wenn die ETags nicht äquivalent sind, aktualisieren Sie die Anwendung und aktualisieren Sie den Cache mit der neuesten Antwort.

Wenn Sie nur den ETag-Wert aus der Metadata API abrufen möchten, setzen Sie den Abfrageparameter fields bei der Anfrage auf etag. Beispiel ansehen

ETag mit einer API-Anfrage verwenden

Wenn Sie eine im Cache gespeicherte Version einer Spaltensammlung haben, können Sie ihren ETag-Wert in eine Metadata API-Anfrage einfügen. Dazu geben Sie das HTTP-Headerfeld If-None-Match an. Die Metadata API prüft den ETag-Wert und antwortet entweder mit einer aktualisierten Version der Ressource und einem 200 OK-HTTP-Status oder einer leeren Antwort mit dem Status 304 Not Modified, wenn deine im Cache gespeicherte Version aktuell ist.