Dokument zawiera informacje o tym, jak uzyskiwać dostęp do danych o ścieżkach wielokanałowych, korzystając z interfejsu API do raportowania ścieżek wielokanałowych.
Wprowadzenie
Interfejs API do raportowania ścieżek wielokanałowych zapewnia dostęp do danych tabelarycznych w raportach standardowych i niestandardowych ścieżek wielokanałowych. Aby uzyskać dostęp do danych, utwórz zapytanie, które określa: widok (profil), daty rozpoczęcia i zakończenia oraz wymiary i dane, które składają się na nagłówki kolumn w tabeli. To zapytanie jest wysyłane do interfejsu API do raportowania ścieżek wielokanałowych, a interfejs API do raportowania ścieżek wielokanałowych zwraca wszystkie dane w formie tabeli.
Jeśli dopiero zaczynasz korzystać z tego interfejsu API, przeczytaj wprowadzenie do interfejsu API do raportowania ścieżek wielokanałowych, aby dowiedzieć się więcej o jego przeznaczeniu i zawartych w nim danych.
Zanim zaczniesz
Ten przewodnik korzysta z biblioteki klienta w języku Java w celu uzyskania dostępu do interfejsu API do raportowania ścieżek wielokanałowych. Każda biblioteka klienta udostępnia pojedynczy obiekt usługi Analytics, który wywołuje interfejs API raportowania ścieżek wielokanałowych. Jeśli nie używasz biblioteki klienta do uzyskania dostępu do interfejsu API, przeczytaj Przewodnik po interfejsach ścieżek wielokanałowych – przewodnik.
Aby utworzyć obiekt usługi Analytics:
- Zarejestruj aplikację w konsoli Google API.
- Autoryzuj dostęp do danych Google Analytics.
- Zapisz kod, aby utworzyć obiekt usługi Analytics.
Jeśli nie wykonasz jeszcze tych czynności, zatrzymaj i przeczytaj samouczek dotyczący interfejsu Hello Analytics API, z którego dowiesz się, jak utworzyć aplikację interfejsu Google Analytics API. Po ukończeniu samouczka przeczytaj dalej ten przewodnik.
Na przykład ten kod tworzy autoryzowany obiekt usługi Analytics:
Java
Analytics analytics = initializeAnalytics();
Użyj obiektu usługi Analytics analytics
do wywołania interfejsu API raportowania ścieżek wielokanałowych.
Przegląd
Aby korzystać z interfejsu API do raportowania wielokanałowego w celu pobierania danych, napisz aplikację, aby:
- Wyślij zapytanie do interfejsu API do raportowania ścieżek wielokanałowych.
- Pracuj nad wynikami zwracanymi przez interfejs API.
Tworzenie zapytań dotyczących interfejsu API do raportowania ścieżek wielokanałowych
Aby poprosić o dostęp do danych z interfejsu API do raportowania ścieżek wielokanałowych:
- utworzyć obiekt zapytania w interfejsie API do raportowania ścieżek wielokanałowych.
- Używaj obiektu zapytania, aby żądać danych z serwerów ścieżek wielokanałowych.
Utwórz zapytanie do interfejsu API do raportowania ścieżek wielokanałowych
Aby utworzyć obiekt zapytania w interfejsie API ścieżek wielokanałowych, wywołaj tę metodę:
analytics.data.mcf.get() // analytics is the Analytics service object
Pierwszy parametr przekazywany do metody to niepowtarzalny identyfikator tabeli w postaci ga:XXXX
, gdzie XXXX
to identyfikator widoku danych Analytics (profilu) zawierający żądane dane.
Za pomocą obiektu zapytania określ parametry zapytania (np. setDimensions
). Na przykład:
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);
Listę wszystkich parametrów zapytania znajdziesz w artykule Podsumowanie parametrów zapytania. Dane i wymiary pozwalają określić, jakie dane ze ścieżek wielokanałowych można pobierać. Listę wszystkich wymiarów i danych znajdziesz w artykule o wymiarach i danych.
Tworzenie żądania danych interfejsu API raportowania ścieżek wielokanałowych
Po utworzeniu obiektu zapytania wywołaj w nim metodę execute
, aby zażądać danych z serwerów ścieżek wielokanałowych. Przykład:
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(); }
Jeśli wolisz uzyskać dostęp do nieprzetworzonej odpowiedzi interfejsu API, wywołaj metodę executeUnparsed()
w obiekcie zapytania:
HttpResponse response = apiQuery.executeUnparsed();
Jeśli zapytanie się powiedzie, zwróci wymagane dane. Jeśli wystąpi błąd, metoda execute
zwraca wyjątek zawierający kod stanu wraz z opisem błędu. Aplikacja powinna wykrywać i obsługiwać wyjątek.
Praca z wynikami interfejsu API
Jeśli zapytanie do interfejsu API do raportowania ścieżek wielokanałowych wykona żądanie, zwróci dane raportowania i informacje o tych danych.
Dane raportowania o ścieżkach wielokanałowych
Zapytanie zwraca te dane z tabeli:
- Dane nagłówka kolumny
- Dane wiersza
Dane nagłówka kolumny
Odpowiedź na zapytanie zawiera pole nagłówka kolumny z informacjami o nagłówku tabeli. To jest lista (lub tablica) obiektów ColumnHeaders
, z których każdy zawiera nazwę kolumny, typ kolumny i typ danych kolumn. Kolejność kolumn to kolumny wymiarów, a następnie kolumny danych w takiej samej kolejności jak w pierwotnym zapytaniu. Na przykład ta metoda wyświetla nagłówki kolumn:
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()); } }
Dane wiersza
Główne dane zwracane przez interfejs API są zwracane jako dwuwymiarowy List
z McfData.Rows
. Każda McfData.Rows
odpowiada 1 komórce, która jest wartością podstawową typu String
lub wartością ścieżki konwersji typu McfData.Rows.ConversionPathValue
. Kolejność komórek w wierszu jest taka sama jak liczba pól w obiekcie nagłówka kolumny opisanych powyżej.
Dane w każdej komórce są zwracane jako ciąg znaków lub w postaci sekwencji ścieżki, dlatego pole DataType
w każdym obiekcie nagłówka kolumny jest szczególnie przydatne do analizowania wartości w odpowiednich typach.
Wszystkie możliwe typy danych znajdziesz w przewodniku.
Na przykład ta metoda powoduje drukowanie nagłówków i wierszy tabeli:
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"); } }
Poniższy przykład pokazuje, jak analizować obiekt Typ sekwencji ścieżek wielokanałowych i przekształcać go w ciąg znaków:
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(); }
Zgłoś informacje
Oprócz danych do raportu zapytanie to zwraca informacje o nich (np. identyfikator raportu). Na przykład ta metoda drukuje informacje z raportu:
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()); }
Pole containsSampledData
informuje o próbkowanej odpowiedzi na zapytanie.
Próbkowanie może wpływać na wyniki zapytania, dlatego próbkowane wartości zwracane przez zapytanie (interfejs API) nie są zgodne z tymi wyświetlanymi w interfejsie internetowym. Więcej informacji znajdziesz w sekcji dotyczącej próbkowania.
Wyświetlanie informacji (profil)
Odpowiedź na zapytanie zawiera identyfikator usługi internetowej, nazwę (identyfikator) i identyfikator widoku danych oraz identyfikator konta Analytics zawierającego ten widok. Na przykład ta metoda wyświetla je w terminalu (standardowe dane wyjściowe):
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()); }
Informacje o zapytaniu
Odpowiedź na zapytanie zawiera obiekt Query
zawierający wartości wszystkich parametrów zapytania o dane. Na przykład ta metoda wyświetla wartości takich parametrów:
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()); }
Metody inne niż query.getMetrics()
, query.getDimensions()
i query.getSort()
zwracają wartość String
. Na przykład query.getStartDate()
zwraca datę rozpoczęcia raportu (String
).
Informacje o podziału na strony
Każde żądanie API do raportowania ścieżek wielokanałowych może odpowiadać setkom tysięcy wierszy danych ścieżek wielokanałowych. Interfejs API do raportowania ścieżek wielokanałowych w danym momencie zwróci tylko podzbiór danych, określany jako pojedyncza strona danych. Aby pobrać wszystkie strony z danymi, użyj pola podziału na strony. Informacje o podziale na strony są drukowane przy użyciu tej metody:
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()); }
Metoda mcfData.getTotalResults()
zwraca łączną liczbę wierszy zapytania, która może być większa niż łączna liczba wierszy zwróconych przez zapytanie. Natomiast metoda mcfData.getItemsPerPage()
zwraca maksymalną liczbę wierszy, jakie może zawierać odpowiedź na zapytanie.
Metoda mcfData.getPreviousLink()
zwraca link do poprzedniej strony, a mcfData.getNextLink()
zwraca link do następnej strony.
Łącznie dla wszystkich wyników
Aby uzyskać łączne wartości żądanych danych we wszystkich wynikach, a nie tylko w wynikach zwróconych w odpowiedzi na zapytanie, wywołaj metodę getTotalsForAllResults()
w odpowiedzi na obiekt obiektem McfData
. Użyj wartości całkowitych, aby obliczyć średnie.
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()); } }
Próbka do pracy
Java
Biblioteka klienta Java w interfejsie API Google Przykład interfejsu API raportowania ścieżek wielokanałowych