Interfejs API do raportowania ścieżek wielokanałowych – przewodnik dla programistów

Ten dokument wyjaśnia, jak korzystać z interfejsu API do raportowania ścieżek wielokanałowych, aby uzyskać dostęp do danych ścieżek wielokanałowych.

Wstęp

Interfejs API do raportowania ścieżek wielokanałowych zapewnia dostęp do danych tabelarycznych w standardowych i niestandardowych raportach ś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 składające 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 korzystasz z interfejsu API po raz pierwszy, przeczytaj omówienie interfejsu API do raportowania ścieżek wielokanałowych, aby dowiedzieć się, do czego służy ten interfejs i jakie dane dostarcza.

Zanim zaczniesz

Ten przewodnik wykorzystuje bibliotekę klienta w Javie, by uzyskać dostęp do interfejsu API do raportowania ścieżek wielokanałowych. Każda biblioteka klienta zawiera pojedynczy obiekt usługi Analytics, który służy do wywoływania interfejsu API do raportowania ścieżek wielokanałowych w celu pobrania danych. Jeśli nie korzystasz z biblioteki klienta, aby uzyskać dostęp do interfejsu API, przeczytaj artykuł Przewodnik po interfejsie API do raportowania ścieżek wielokanałowych.

Aby utworzyć obiekt usługi Analytics:

  1. Zarejestruj aplikację w Konsoli interfejsów API Google.
  2. Autoryzacja dostępu do danych Google Analytics.
  3. Napisz kod, by utworzyć obiekt usługi Analytics.

Jeśli nie udało Ci się wykonać tych czynności, zatrzymaj się i przeczytaj samouczek Hello Analytics API, z którego dowiesz się, jak rozpocząć tworzenie aplikacji interfejsu Google Analytics API. Po ukończeniu samouczka przeczytaj dalszą część przewodnika.

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 do raportowania ścieżek wielokanałowych.

Przegląd

Aby używać interfejsu API do raportowania ścieżek wielokanałowych do pobierania danych, napisz aplikację, która:

  1. Wyślij zapytanie do interfejsu API do raportowania ścieżek wielokanałowych.
  2. Pracuj nad wynikami zwróconymi przez interfejs API.

Wysyłanie zapytań do interfejsu API do raportowania ścieżek wielokanałowych

Aby wysłać żądanie danych do interfejsu API do raportowania ścieżek wielokanałowych:

  1. Utwórz obiekt zapytania w interfejsie API do raportowania ścieżek wielokanałowych.
  2. Użyj obiektu zapytania, aby zażądać danych z serwerów ścieżek wielokanałowych.

Tworzenie zapytania w interfejsie API do raportowania ścieżek wielokanałowych

Aby utworzyć obiekt zapytania w interfejsie API do raportowania ścieżek wielokanałowych, wywołaj tę metodę:

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

Pierwszy parametr przekazywany do tej metody to unikalny identyfikator tabeli w postaci ga:XXXX, gdzie XXXX to identyfikator widoku danych (profilu) Analytics zawierającego żądane dane. Obiekt zapytania służy do określania parametrów zapytania (np. setDimensions). 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. Parametry danych i wymiarów pozwalają określić, które dane ze ścieżek wielokanałowych chcesz pobierać. Listę wszystkich wymiarów i danych znajdziesz w dokumentacji wymiarów i danych.

Tworzenie żądania danych do interfejsu API do raportowania ścieżek wielokanałowych

Po utworzeniu obiektu zapytania wywołaj w nim metodę execute, aby zażądać danych od serwerów ścieżek wielokanałowych. Na 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 surowej odpowiedzi interfejsu API, wywołaj metodę executeUnparsed() w obiekcie zapytania:

HttpResponse response = apiQuery.executeUnparsed();

Jeśli zapytanie zakończy się powodzeniem, zwróci żądane dane. Jeśli wystąpi błąd, metoda execute zgłasza wyjątek zawierający kod stanu błędu i jego opis. Aplikacja powinna wychwytywać i obsługiwać wyjątek.

Praca z wynikami interfejsu API

Jeśli zapytanie do interfejsu API do raportowania ścieżek wielokanałowych zakończy się powodzeniem, zwróci dane raportowania i informacje o nich.

Dane raportowania ścieżek wielokanałowych

Zapytanie zwróci te tabelaryczne dane raportowania:

  • Dane nagłówka kolumny
  • Dane w wierszach

Dane nagłówka kolumny

Odpowiedź na zapytanie ma pole nagłówka kolumny zawierające informacje o nagłówku tabeli. Pole to lista (lub tablica) obiektów ColumnHeaders, z których każdy zawiera nazwę kolumny, typ kolumny i typ danych kolumny. Kolejność kolumn to kolumny wymiarów, po których występują kolumny danych, w kolejności określonej w oryginalnym zapytaniu. Poniższa metoda wyświetla np. 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 w wierszach

Główne dane zwracane przez interfejs API są zwracane jako dwuwymiarowe dane List z wartością McfData.Rows. Każdy element McfData.Rows reprezentuje jedną komórkę będącą wartością podstawową typu String lub wartością ścieżki konwersji typu McfData.Rows.ConversionPathValue. Kolejność komórek w wierszu jest taka sama jak pola w obiekcie nagłówka kolumny opisanym powyżej.

Dane w każdej komórce są zwracane jako ciąg znaków lub typ sekwencji ścieżek wielokanałowych, dlatego pole DataType w każdym obiekcie nagłówka kolumny jest szczególnie przydatne do analizowania wartości na odpowiednie typy. Wszystkie możliwe typy danych znajdziesz w przewodniku.

Na przykład nagłówki i wiersze tabeli są wyświetlane w następujący sposób:

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 przeanalizować obiekt typu sekwencji ścieżek wielokanałowych i przekształcić 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();
}

Informacje o raporcie

Oprócz danych raportowania zapytanie zwraca informacje o nich (np. identyfikator raportu). Na przykład ta metoda wyświetla 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, czy odpowiedź na zapytanie została próbkowana. Próbkowanie może wpływać na wyniki zapytania, dlatego próbkowane wartości zwrócone przez zapytanie (API) nie są zgodne z tymi, które wyświetlają się w interfejsie internetowym. Więcej informacji znajdziesz w sekcji Próbkowanie.

Wyświetl informacje (profil)

Odpowiedź na zapytanie zawiera identyfikator usługi internetowej, nazwę i identyfikator widoku danych (profilu) oraz identyfikator konta Analytics zawierającego ten widok (profil). Można np. użyć tej metody, aby wyświetlić je na 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. Poniższa metoda wyświetla np. 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 (a String) raportu.

Informacje o podziale na strony

Każde żądanie interfejsu API do raportowania ścieżek wielokanałowych może odpowiadać setkom tysięcy wierszy danych dotyczących ścieżek wielokanałowych. Interfejs API do raportowania ścieżek wielokanałowych zwraca w danym momencie tylko podzbiór danych, nazywany jedną stroną danych. Aby pobrać wszystkie strony danych, użyj pola podziału na strony. Poniższa metoda wyświetla informacje o podziale na strony:

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

Wywołanie metody mcfData.getTotalResults() zwraca łączną liczbę wierszy w zapytaniu, która może być większa niż łączna liczba wierszy zwróconych przez zapytanie. Wywołanie metody mcfData.getItemsPerPage() zwraca maksymalną liczbę wierszy, jaką może zawierać odpowiedź na zapytanie.

Wywołanie metody mcfData.getPreviousLink() zwraca link do poprzedniej strony, a pole mcfData.getNextLink() zwraca link do następnej strony.

Sumy dla wszystkich wyników

Aby uzyskać łączne wartości żądanych danych we wszystkich wynikach, a nie tylko wyniki zwracane w odpowiedzi na zapytanie, wywołaj w odpowiedzi na zapytanie metodę getTotalsForAllResults(), czyli obiekt McfData. Użyj sumy do obliczenia średnich.

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 robocza

Java

Biblioteka klienta interfejsu API Google w języku Java Przykład interfejsu API do raportowania ścieżek wielokanałowych