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

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:

  1. Zarejestruj aplikację w konsoli Google API.
  2. Autoryzuj dostęp do danych Google Analytics.
  3. 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:

  1. Wyślij zapytanie do interfejsu API do raportowania ścieżek wielokanałowych.
  2. 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:

  1. utworzyć obiekt zapytania w interfejsie API do raportowania ścieżek wielokanałowych.
  2. 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