Metadata API – Entwicklerleitfaden

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

Einleitung

Die Metadata API gibt eine Liste der Spalten (d.h. Dimensionen und Messwerte) zurück, die in den Google Analytics Reporting APIs verfügbar sind, und deren Attribute. Wenn Sie die API noch nicht kennen, finden Sie unter Metadata API – Übersicht 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:

• Auf der Seite Clientbibliotheken finden Sie eine vollständige Liste der programmiersprachenspezifischen Clientbibliotheken, die mit der API funktionieren.
• Im Referenzhandbuch erhalten Sie Informationen zur API-Oberfläche und zum Zugriff auf Daten ohne Clientbibliothek.

Jede Clientbibliothek stellt ein einzelnes Analysedienstobjekt für den Zugriff auf alle Metadata API-Daten bereit. Zum Erstellen des Dienstobjekts für die Verwendung mit der Metadata API müssen Sie normalerweise 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.

Registrierungs- und API-Schlüssel

Ihre Anwendung muss sich jedes Mal identifizieren, wenn sie eine Anfrage an die Analytics API sendet. Dazu müssen Sie für jede Anfrage einen API-Schlüssel angeben.

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 für Ihr Projekt geeigneten Anmeldedaten:

   • 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 hat, die eine OAuth 2.0-Autorisierung erfordern, müssen Sie möglicherweise nur die API-Schlüssel abrufen. Diese werden unten beschrieben. Wenn Ihre Anwendung jedoch andere APIs aufruft, die eine Nutzerautorisierung erfordern, benötigen Sie trotzdem 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. Falls der API-Schlüssel, den Sie benötigen, noch nicht vorhanden ist, erstellen Sie ihn in der Console. Klicken Sie dazu auf Anmeldedaten erstellen > API-Schlüssel. Sie können Einschränkungen für den Schlüssel festlegen, bevor Sie ihn in der Produktion 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:

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

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.

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>

Spaltenattribute

Die Metadata API-Antwort enthält das Attribut attributeNames, das alle gültigen Spaltenattribute auflistet. Jede Spalte hat das Attribut attributes mit einer Teilmenge von Attributen, die auf die Spalte anwendbar sind.

Die folgende Tabelle enthält die vollständige Liste der gültigen Attribute:

Anwendungsbereiche

Die Metadata API eignet sich für die folgenden Anwendungsfälle:

• Verworfene Spalten
• Spaltennamen
• Vorlagen für Spalten
• Berechnete Spalten
• Spalten und Segmente
• API-Versionen
• ETags

Verworfene Spalten

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

Das folgende Snippet zeigt, wie Sie mit dem Attribut status prüfen können, ob eine Spalte veraltet ist:

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

Wenn eine Spalte umbenannt oder entfernt wird, wird das Attribut status auf DEPRECATED gesetzt und das Attribut replacedBy kann auf Id der Ersatzspalte festgelegt sein.

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

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

Spaltennamen

Das Attribut uiName ist der Name der Dimension oder des Messwerts, der in Google Analytics-Benutzeroberflächen (z.B. der Weboberfläche) verwendet wird.

Das folgende Snippet zeigt, wie der UI-Name einer Spalte abgerufen wird:

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

Vorlagenspalten

Vorlagenspalten enthalten Dimensionen oder Messwerte mit einem numerischen Index. Beispiel: ga:goalXXStarts, ga:dimensionXX, ga:metricXX usw. Eine vorlagenbasierte Spalte hat die Attribute minTemplateIndex und maxTemplateIndex, die den Indexbereich definieren.

Das folgende Snippet zeigt, wie Sie prüfen können, ob eine Spalte vorlagenbasiert ist:

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

Das folgende Snippet zeigt, wie eine Liste gültiger IDs für eine vorlagenbasierte Spalte 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 ein calculation-Attribut. Beispiel: Die Berechnung für ga:percentNewSessions ist ga:newSessions / ga:sessions.

Das folgende Beispiel zeigt, wie geprüft wird, ob eine Spalte berechnet wurde, und wie die Berechnung für eine Spalte abgerufen wird:

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.

Im folgenden Beispiel wird gezeigt, wie Sie ermitteln, ob eine Spalte in Segmenten verwendet werden kann:

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

In API-Version hinzugefügt

Mit dem Attribut addedInApiVersion können Sie prüfen, 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

Jede Metadata API-Antwort enthält ein ETag. Das ETag ist eine Kennung, mit der Metadata API-Antworten im Cache gespeichert und aktualisiert werden können. Das ist wichtig, da Daten in Spalten (d. h. Dimensionen und Messwerte) über einen längeren Zeitraum unverändert bleiben können und es nicht sinnvoll ist, unnötige Anfragen und Aktualisierungen vorzunehmen, wenn im Cache gespeicherte Daten 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 Antwort der Metadata API aktuell ist, und um sie in eine Metadata API-Anfrage aufzunehmen.

Im Cache gespeicherte Antwort prüfen

Wenn Sie den von einer Metadata API-Antwort zurückgegebenen ETag-Wert vergleichen und er 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 Ihre Anwendung und aktualisieren Sie den Cache mit der neuesten Antwort.

Wenn du nur den ETag-Wert aus der Metadata API abrufen möchtest, setze den Abfrageparameter fields bei einer Anfrage auf etag. Beispiel ansehen

ETag mit einer API-Anfrage verwenden

Wenn Sie eine im Cache gespeicherte Version einer Spaltensammlung haben, können Sie deren ETag-Wert in eine Metadata API-Anfrage aufnehmen. Legen Sie dazu das HTTP-Header-Feld If-None-Match fest. Die Metadata API prüft den ETag-Wert und antwortet entweder mit einer aktualisierten Version der Ressource und dem HTTP-Status 200 OK oder einer leeren Antwort mit dem Status 304 Not Modified, wenn die im Cache gespeicherte Version aktuell ist.