Multi-Channel-Trichter Reporting API – Entwicklerleitfaden

In diesem Dokument erfahren Sie, wie Sie mit der Multi-Channel-Trichter Reporting API auf Multi-Channel-Trichterdaten zugreifen.

Einleitung

Die Multi-Channel-Trichter Reporting API bietet Zugriff auf die tabellarischen Daten in Standard- und benutzerdefinierten Multi-Channel-Trichterberichten. Um auf Daten zuzugreifen, erstellen Sie eine Abfrage, die Folgendes angibt: die Datenansicht (Profil), das Start- und Enddatum sowie die Dimensionen und Messwerte, aus denen die Spaltenüberschriften in der Tabelle bestehen. Diese Abfrage wird an die Multi-Channel-Trichter Reporting API gesendet. Diese gibt alle Daten in Form einer Tabelle zurück.

Wenn Sie die API noch nicht kennen, erhalten Sie in der Übersicht über die Multi-Channel Trichter Reporting API eine Einführung in den Zweck der API und die darin bereitgestellten Daten.

Vorbereitung

In diesem Leitfaden wird für den Zugriff auf die Multi-Channel Trichter Reporting API die Java-Clientbibliothek verwendet. Jede Clientbibliothek stellt ein einzelnes Analytics-Dienstobjekt bereit, über das die Multi-Channel-Trichter Reporting API für den Datenabruf aufgerufen wird. Wenn Sie keine Clientbibliothek für den Zugriff auf die API verwenden, lesen Sie das Referenzhandbuch zur Multi-Channel Trichter Reporting API.

So erstellen Sie das Analytics-Dienstobjekt:

1. Registrieren Sie Ihre Anwendung in der Google API Console.
2. Autorisieren Sie den Zugriff auf Google Analytics-Daten.
3. Schreiben Sie Code, um das Analytics-Dienstobjekt zu erstellen.

Wenn Sie diese Schritte noch nicht ausgeführt haben, beenden Sie die Anleitung zur Hello Analytics API, die Sie durch die ersten Schritte zum Erstellen einer Google Analytics API-Anwendung führt. Lesen Sie nach Abschluss des Tutorials den folgenden Leitfaden.

Beispielsweise wird mit dem folgenden Code ein autorisiertes Analytics-Dienstobjekt erstellt:

Analytics analytics = initializeAnalytics();

Verwenden Sie das Analytics-Dienstobjekt analytics, um die Multi-Channel-Trichter Reporting API aufzurufen.

Überblick

Wenn Sie die Multi-Channel-Trichter-Report-API zum Abrufen von Daten verwenden möchten, schreiben Sie eine Anwendung für:

1. Fragen Sie die Multi-Channel-Trichter Reporting API ab.
2. Mit den von der API zurückgegebenen Ergebnissen arbeiten.

Multi-Channel-Trichter Reporting API abfragen

So fordern Sie Daten über die Multi-Channel-Trichter Reporting API an:

1. Erstellen Sie ein Multi-Channel-Trichter Reporting API-Abfrageobjekt.
2. Verwenden Sie das Abfrageobjekt, um die Daten von den Servern für Multi-Channel-Trichter anzufordern.

Abfrage für die Multi-Channel-Trichter Reporting API erstellen

Rufen Sie zum Erstellen eines Abfrageobjekts für die Multi-Channel-Trichter-Report-API diese Methode auf:

analytics.data.mcf.get()    // analytics is the Analytics service object

Der erste Parameter, der der Methode bereitgestellt wird, ist eine eindeutige Tabellen-ID im Format ga:XXXX, wobei XXXX die ID einer Analytics-Datenansicht bzw. eines Analytics-Profils ist, das die angeforderten Daten enthält. Verwenden Sie das Abfrageobjekt, um Abfrageparameter (z.B. setDimensions). Beispiel:

Get apiQuery = analytics.data().mcf()
    .get(tableId,
        "2012-01-01",              // Start date
        "2012-03-31",              // End date
        "mcf:totalConversions")    // Metrics
    .setDimensions("mcf:sourcePath")
    .setSort("-mcf:totalConversions")
    .setMaxResults(25);

Eine Liste aller Abfrageparameter finden Sie in der Übersicht der Abfrageparameter. Mit Messwert- und Dimensionsparametern können Sie angeben, welche Daten aus Multi-Channel-Trichtern abgerufen werden sollen. Eine Liste aller Dimensionen und Messwerte finden Sie im Referenztool für Dimensionen und Messwerte.

Multi-Channel Trichter Reporting API-Datenanfrage stellen

Rufen Sie nach dem Erstellen des Abfrageobjekts die Methode execute für das Objekt auf, um Daten von Multi-Channel-Trichter-Servern anzufordern. Beispiel:

try {
  apiQuery.execute();
  // Success. Do something cool!

} catch (GoogleJsonResponseException e) {
  // Catch API specific errors.
  handleApiError(e);

} catch (IOException e) {
  // Catch general parsing network errors.
  e.printStackTrace();
}

HttpResponse response = apiQuery.executeUnparsed();

Wenn die Abfrage erfolgreich ist, werden die angeforderten Daten zurückgegeben. Wenn ein Fehler auftritt, gibt die Methode execute eine Ausnahme mit einem Statuscode für den Fehler und einer Fehlerbeschreibung aus. Die Anwendung sollte die Ausnahme abfangen und verarbeiten.

Mit den API-Ergebnissen arbeiten

Wenn die Abfrage der Multi-Channel Trichter Reporting API erfolgreich ist, werden die Berichtsdaten und Daten zu den Daten zurückgegeben.

Berichtsdaten zu Multi-Channel-Trichtern

Die Abfrage gibt die folgenden tabellarischen Berichtsdaten zurück:

• Daten zu Spaltenüberschriften
• Zeilendaten

Daten zu Spaltenüberschriften

Die Abfrageantwort enthält ein Feld mit der Spaltenüberschrift mit den Informationen zur Kopfzeile der Tabelle. Das Feld ist eine Liste (oder ein Array) von ColumnHeaders-Objekten, die jeweils den Spaltennamen, den Spaltentyp und den Spaltendatentyp enthalten. Die Spaltenreihenfolge entspricht den Dimensionsspalten, gefolgt von den Messwertspalten, in derselben Reihenfolge wie in der ursprünglichen Abfrage angegeben. Die folgende Methode gibt beispielsweise die Spaltenüberschriften aus:

private static void printColumnHeaders(McfData mcfData) {
  System.out.println("Column Headers:");

  for (ColumnHeaders header : mcfData.getColumnHeaders()) {
    System.out.println("Column Name: " + header.getName());
    System.out.println("Column Type: " + header.getColumnType());
    System.out.println("Column Data Type: " + header.getDataType());
  }
}

Zeilendaten

Die von der API zurückgegebenen Hauptdaten werden als zweidimensionaler List von McfData.Rows zurückgegeben. Jeder McfData.Rows steht für eine einzelne Zelle, die entweder ein primitiver Wert vom Typ String oder ein Conversion-Pfadwert vom Typ McfData.Rows.ConversionPathValue ist. Die Reihenfolge der Zellen in einer Zeile entspricht der Reihenfolge der Felder im oben beschriebenen Spaltenüberschriftsobjekt.

Da die Daten in jeder Zelle entweder als String oder als Sequenztyp für Multi-Channel-Trichter zurückgegeben werden, ist das Feld DataType in den Spaltenüberschriften besonders nützlich, um Werte in geeignete Typen zu parsen. Weitere Informationen zu allen möglichen Datentypen finden Sie im Referenzhandbuch.

Mit der folgenden Methode werden beispielsweise die Tabellenüberschriften und -zeilen ausgegeben:

private static void printDataTable(McfData mcfData) {
  System.out.println("Data Table:");
  if (mcfData.getTotalResults() > 0) {
    // Print the column names.
    List<ColumnHeaders> headers = mcfData.getColumnHeaders();
    for (ColumnHeaders header : headers) {
      System.out.print(header.getName());
    }
    System.out.println();

    // Print the rows of data.
    for (List<McfData.Rows> row : mcfData.getRows()) {
      for (int columnIndex = 0; columnIndex < row.size(); ++columnIndex) {
        ColumnHeaders header = headers.get(columnIndex);
        McfData.Rows cell = row.get(columnIndex);
        if (header.getDataType().equals("MCF_SEQUENCE")) {
          System.out.print(getStringFromMcfSequence(cell.getConversionPathValue()));
        } else {
          System.out.print(cell.getPrimitiveValue());
        }
      }
      System.out.println();
    }
  } else {
    System.out.println("No rows found");
  }
}

Das folgende Beispiel zeigt, wie ein Sequenztyp für Multi-Channel-Trichter geparst und in einen String umgewandelt wird:

private static String getStringFromMcfSequence(List<McfData.Rows.ConversionPathValue> path) {
  StringBuilder stringBuilder = new StringBuilder();
  for (McfData.Rows.ConversionPathValue pathElement : path) {
    if (stringBuilder.length() > 0)
      stringBuilder.append(" > ");
    stringBuilder.append(pathElement.getNodeValue());
  }
  return stringBuilder.toString();
}

Berichtsinformationen

Zusätzlich zu den Berichtsdaten gibt die Abfrage Informationen zu den Daten zurück (z. B. Berichts-ID). Mit der folgenden Methode werden beispielsweise die Berichtsinformationen ausgegeben:

private static void printReportInfo(McfData mcfData) {
  System.out.println("Report Info:");
  System.out.println("ID:" + mcfData.getId());
  System.out.println("Self link: " + mcfData.getSelfLink());
  System.out.println("Kind: " + mcfData.getKind());
  System.out.println("Contains Sampled Data: " + mcfData.getContainsSampledData());
}

Im Feld containsSampledData sehen Sie, ob eine Stichprobe der Abfrageantwort erhoben wurde. Da die Stichprobenerhebung die Abfrageergebnisse beeinflussen kann, stimmen die von der Abfrage (API) zurückgegebenen Stichprobenwerte nicht mit den auf der Weboberfläche angezeigten Werten überein. Weitere Informationen finden Sie unter Stichproben.

(Profil-)Informationen abrufen

Die Abfrageantwort enthält die Web-Property-ID, den Namen und die ID der Datenansicht (Profil) sowie die ID des Analytics-Kontos, das die Datenansicht (Profil) enthält. Mit der folgenden Methode werden sie beispielsweise im Terminal ausgegeben (Standardausgabe):

private static void printProfileInfo(McfData mcfData) {
  ProfileInfo profileInfo = mcfData.getProfileInfo();

  System.out.println("View (Profile) Info:");
  System.out.println("Account ID: " + profileInfo.getAccountId());
  System.out.println("Web Property ID: " + profileInfo.getWebPropertyId());
  System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId());
  System.out.println("View (Profile) ID: " + profileInfo.getProfileId());
  System.out.println("View (Profile) Name: " + profileInfo.getProfileName());
  System.out.println("Table ID: " + profileInfo.getTableId());
}

Abfrageinformationen

Die Abfrageantwort enthält ein Query-Objekt, das die Werte aller Abfrageparameter für Datenanfragen enthält. Die folgende Methode gibt beispielsweise die Werte solcher Parameter aus:

private static void printQueryInfo(McfData mcfData) {
  Query query = mcfData.getQuery();

  System.out.println("Query Info:");
  System.out.println("Ids: " + query.getIds());
  System.out.println("Start Date: " + query.getStartDate());
  System.out.println("End Date: " + query.getEndDate());
  System.out.println("Metrics: " + query.getMetrics());       // List of Analytics metrics
  System.out.println("Dimensions: " + query.getDimensions()); // List of Analytics dimensions
  System.out.println("Sort: " + query.getSort());             // List of sorte metrics or dimensions
  System.out.println("Segment: " + query.getSegment());
  System.out.println("Filters: " + query.getFilters());
  System.out.println("Start Index: " + query.getStartIndex());
  System.out.println("Max Results: " + query.getMaxResults());
}

Andere Methoden als query.getMetrics(), query.getDimensions() und query.getSort() geben ein String zurück. query.getStartDate() gibt beispielsweise das Startdatum (String) des Berichts zurück.

Paginierungsinformationen

Jede Anfrage an die Multi-Channel Trichter Reporting API kann mit Hunderttausenden von Zeilen mit Multi-Channel-Trichterdaten übereinstimmen. Die Multi-Channel Trichter Reporting API gibt zu einem bestimmten Zeitpunkt nur einen Teil der Daten zurück. Dieser wird als einzelne Seite der Daten bezeichnet. Verwenden Sie das Paginierungsfeld, um alle Seiten mit Daten abzurufen. Mit der folgenden Methode werden die Paginierungsinformationen ausgegeben:

private static void printPaginationInfo(McfData mcfData) {
  System.out.println("Pagination Info:");
  System.out.println("Previous Link: " + mcfData.getPreviousLink());
  System.out.println("Next Link: " + mcfData.getNextLink());
  System.out.println("Items Per Page: " + mcfData.getItemsPerPage());
  System.out.println("Total Results: " + mcfData.getTotalResults());
}

Der Methodenaufruf mcfData.getTotalResults() gibt die Gesamtzahl der Zeilen für die Abfrage zurück, die größer sein kann als die Gesamtzahl der von der Abfrage zurückgegebenen Zeilen. Der Methodenaufruf mcfData.getItemsPerPage() gibt die maximale Anzahl von Zeilen zurück, die die Abfrageantwort enthalten kann.

Der Methodenaufruf mcfData.getPreviousLink() gibt den Link zur vorherigen Seite zurück und mcfData.getNextLink() gibt den Link zur nächsten Seite zurück.

Summen für alle Ergebnisse

Wenn Sie die Gesamtwerte für die angeforderten Messwerte für alle Ergebnisse und nicht nur für die in der Abfrageantwort zurückgegebenen Ergebnisse abrufen möchten, rufen Sie die Methode getTotalsForAllResults() für die Abfrageantwort auf, ein McfData-Objekt. Verwenden Sie die Gesamtwerte, um die Durchschnittswerte zu berechnen.

private static void printTotalsForAllResults(McfData mcfData) {
  System.out.println("Metric totals over all results:");
  Map<String, String> totalsMap = mcfData.getTotalsForAllResults();
  for (Map.Entry<String, String> entry : totalsMap.entrySet()) {
    System.out.println(entry.getKey() + " : " + entry.getValue());
  }
}

Arbeitsbeispiel