In diesem Dokument wird erläutert, wie Sie mit der Multi-Channel Trichter Reporting API auf Multi-Channel-Trichterdaten zugreifen können.
Einführung
Die Multi-Channel-Trichter-Berichterstellungs-API bietet Zugriff auf die tabellarischen Daten in Standard- und benutzerdefinierten Berichten zu Multi-Channel-Trichtern. Für den Zugriff auf Daten erstellen Sie eine Abfrage, die Folgendes enthält: die Ansicht (Profil), das Start- und Enddatum sowie die Dimensionen und Messwerte, aus denen sich die Spaltenüberschriften in der Tabelle zusammensetzen. Diese Abfrage wird an die Multi-Channel Trichter Reporting API gesendet und die Multi-Channel Trichter Reporting API gibt alle Daten in Form einer Tabelle zurück.
Wenn Sie noch nicht mit der API vertraut sind, lesen Sie die Übersicht über die Multi-Channel Trichter Reporting API. Sie enthält eine Einführung in die Multi-Channel Trichter Reporting API und die darin enthaltenen Daten.
Vorbereitung
In diesem Leitfaden wird die Java-Clientbibliothek für den Zugriff auf die Multi-Channel Trichter Reporting API verwendet. Jede Clientbibliothek stellt ein einzelnes Analytics-Dienstobjekt bereit, um die Multi-Channel Trichter Reporting API zum Abrufen der Daten aufzurufen. Wenn Sie für den Zugriff auf die API keine Clientbibliothek verwenden, lesen Sie die Referenzdokumentation zur Multi-Channel-Trichter-API.
So erstellen Sie das Analytics-Dienstobjekt:
- Registrieren Sie Ihre Anwendung in der Google API Console.
- Zugriff auf Google Analytics-Daten autorisieren
- Schreiben Sie Code, um das Analytics-Dienstobjekt zu erstellen.
Wenn Sie diese Schritte nicht ausgeführt haben, beenden und lesen Sie die Anleitung zur Hello Analytics API, die Sie durch die ersten Schritte zum Erstellen einer Google Analytics API-Anwendung führt. Nachdem Sie die Anleitung abgeschlossen haben, lesen Sie die folgende Anleitung weiter.
Mit dem folgenden Code wird beispielsweise ein autorisiertes Analytics-Dienstobjekt erstellt:
Java
Analytics analytics = initializeAnalytics();
Verwenden Sie das Analytics-Dienstobjekt analytics, um die Multi-Channel Trichter Reporting API aufzurufen.
Übersicht
Schreiben Sie eine Anwendung in die Multi-Channel Trichter Reporting API, um Daten abzurufen:
- Abfrage der Multi-Channel-Trichter-Berichterstellungs-API
- Mit den von der API zurückgegebenen Ergebnissen arbeiten.
Multi-Channel-Trichter-Berichterstellungs-API abfragen
So fordern Sie Daten von der Multi-Channel Trichter Reporting API an:
- Erstellen Sie ein Abfrageobjekt für die Multi-Channel Trichter Reporting API.
- Verwenden Sie das Abfrageobjekt, um die Daten von den Multi-Channel-Trichterservern anzufordern.
Abfrage für die API für die Multi-Channel-Trichter-Berichterstellung erstellen
Rufen Sie zum Erstellen eines Abfrageobjekts für die Multi-Channel-Trichter-Berichterstellung die folgende Methode auf:
analytics.data.mcf.get() // analytics is the Analytics service object
Der erste Parameter, der an die Methode übergeben wird, ist eine eindeutige Tabellen-ID im Format ga:XXXX, wobei XXXX die ID einer Analytics-Datenansicht (Profil) mit den angeforderten Daten ist.
Verwenden Sie das Abfrageobjekt, um Abfrageparameter anzugeben (d.h. setDimensions). Beispiel:
Java
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 Zusammenfassung der Abfrageparameter. Mit den Parametern und Dimensionen können Sie festlegen, welche Daten aus Multi-Channel-Trichtern abgerufen werden sollen. Eine Liste aller Dimensionen und Messwerte finden Sie in der Referenz zu Dimensionen und Messwerten.
Anfrage zu API-Daten für Multi-Channel-Trichter-Berichterstellung stellen
Nachdem Sie das Abfrageobjekt erstellt haben, rufen Sie die Methode execute für das Objekt auf, um Daten von Multi-Channel-Trichterservern anzufordern. Beispiel:
Java
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();
}
Wenn Sie stattdessen auf die Roh-API-Antwort zugreifen möchten, rufen Sie die Methode executeUnparsed() für das Abfrageobjekt auf:
HttpResponse response = apiQuery.executeUnparsed();
Wenn die Abfrage erfolgreich war, werden die angeforderten Daten zurückgegeben. Wenn ein Fehler auftritt, löst die Methode execute eine Ausnahme aus, die einen Statuscode und eine Beschreibung des Fehlers enthält. Die Anwendung sollte die Ausnahme abfangen und verarbeiten.
Mit den API-Ergebnissen arbeiten
Wenn die Multi-Channel-Trichter-API für die API-Abfrage erfolgreich ist, werden die Berichtsdaten und -informationen zurückgegeben.
Berichtsdaten zu Multi-Channel-Trichtern
Die Abfrage gibt die folgenden tabellarischen Berichtsdaten zurück:
- Daten der Spaltenüberschrift
- Zeilendaten
Daten der Spaltenüberschrift
Die Abfrageantwort hat eine Spaltenüberschrift, die Informationen zur Tabellenüberschrift enthält. Das Feld ist eine Liste (oder ein Array) von ColumnHeaders-Objekten, von denen jedes den Spaltennamen, den Spaltentyp und den Spaltendatentyp enthält. Die Spaltenreihenfolge besteht aus den Spalten mit den Dimensionen und den Messwerten in der Reihenfolge der ursprünglichen Abfrage. Die folgende Methode gibt beispielsweise die Spaltenüberschriften aus:
Java
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 zweidimensionale List von McfData.Rows zurückgegeben. Jede McfData.Rows stellt eine einzelne Zelle dar, die entweder ein primärer Wert des Typs String oder ein Conversion-Pfadwert des Typs McfData.Rows.ConversionPathValue ist. Die Reihenfolge der Zellen in einer Zeile entspricht der oben beschriebenen Felder in der Spaltenüberschrift.
Da Daten in jeder Zelle entweder als String oder als Multi-Channel-Trichter-Sequenztyp zurückgegeben werden, ist das Feld DataType in jedem Spaltenheaderobjekt besonders hilfreich, um Werte in geeignete Typen zu parsen.
Alle verfügbaren Datentypen finden Sie im Referenzleitfaden.
Mit der folgenden Methode werden beispielsweise die Kopfzeilen und Zeilen der Tabelle ausgegeben:
Java
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 konvertiert wird:
Java
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 (z. B. Berichts-ID) zu den Daten zurück. Mit der folgenden Methode werden beispielsweise die Berichtsdaten ausgegeben:
Java
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 die Abfrageantwort eine Stichprobe enthält.
Da sich die Verwendung von Stichproben auf die Abfrageergebnisse auswirken kann, stimmen die von der Abfrage zurückgegebenen API-Werte nicht mit denen auf der Weboberfläche überein. Weitere Informationen finden Sie unter Stichproben.
Informationen (Profil) ansehen
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. Sie werden beispielsweise mit der folgenden Methode im Terminal ausgegeben (Standardausgabe):
Java
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 Datenanfrage-Abfrageparameter enthält. Mit der folgenden Methode werden beispielsweise die Werte solcher Parameter ausgegeben:
Java
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 String zurück. Beispiel: query.getStartDate() gibt das Startdatum (a String) des Berichts zurück.
Informationen zur Paginierung
Jede Anfrage für die Multi-Channel Trichter Reporting API kann Hunderttausende von Zeilen mit Multi-Channel-Trichterdaten verarbeiten. Die Multi-Channel-Trichter-Berichterstellungs-API gibt nur einen Teil der Daten zurück, die jeweils als einzelne Seite der Daten bezeichnet werden. Mit dem Paginierungsfeld können Sie alle Datenseiten abrufen. Mit der folgenden Methode werden die Paginierungsinformationen ausgegeben:
Java
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. Und 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.
Gesamtergebnisse
Rufen Sie die Methode getTotalsForAllResults() für die Abfrageantwort auf, ein McfData-Objekt, um die Gesamtwerte für die angeforderten Messwerte über alle Ergebnisse hinweg zu erhalten, nicht nur über die in der Abfrageantwort zurückgegebenen Ergebnisse. Verwenden Sie die Gesamtwerte, um die Durchschnittswerte zu berechnen.
Java
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());
}
}
Arbeitsprobe
Java
Google API-Java-Clientbibliothek Beispiel für Multi-Channel-Trichter-API