Metadata API – przewodnik dla programistów

W tym dokumencie opisujemy ważne zagadnienia dotyczące uzyskiwania dostępu do listy i atrybutów kolumn Google Analytics za pomocą interfejsu Metadata API.

Wstęp

Interfejs Metadata API zwraca listę kolumn (np. wymiarów i danych) widocznych w interfejsach API do raportowania Google Analytics oraz ich atrybutów. Jeśli nie masz doświadczenia z tym interfejsem API, przeczytaj wprowadzenie do interfejsu Metadata API w sekcji Metadata API.

Zanim zaczniesz

Dostęp do wszystkich interfejsów API Google Analytics uzyskuje się w podobny sposób. Zanim zaczniesz korzystać z interfejsu Metadata API:

  • Pełną listę bibliotek klienta dla poszczególnych języków programowania, które obsługują interfejs API, znajdziesz na stronie bibliotek klienta.
  • Przeczytaj Przewodnik, aby dowiedzieć się więcej o interfejsie API i dostępie do danych bez użycia biblioteki klienta.

Każda biblioteka klienta udostępnia jeden obiekt usługi analitycznej, który zapewnia dostęp do wszystkich danych interfejsu Metadata API. Aby utworzyć obiekt usługi do użycia z interfejsem Metadata API, musisz zwykle wykonać te czynności:

  1. Zarejestruj aplikację w Konsoli interfejsów API Google.
  2. Utwórz obiekt usługi Analytics i ustaw klucz interfejsu API.

Rejestracja i klucz interfejsu API

Aplikacja musi identyfikować się za każdym razem, gdy wysyła żądanie do interfejsu Analytics API, umieszczając w każdym żądaniu klucz interfejsu API.

Uzyskiwanie i używanie klucza interfejsu API

Aby uzyskać klucz interfejsu API:

  1. Otwórz stronę Dane logowania w Konsoli interfejsów API.
  2. Ten interfejs API obsługuje 2 rodzaje danych logowania. Utwórz dane logowania odpowiednie dla Twojego projektu:

    • OAuth 2.0: za każdym razem, gdy Twoja aplikacja żąda prywatnych danych użytkownika, razem z tym żądaniem musi wysłać token OAuth 2.0. Aplikacja najpierw wysyła identyfikator klienta, a być może tajny klucz klienta, aby uzyskać token. Dane logowania OAuth 2.0 możesz generować dla aplikacji internetowych, kont usługi lub zainstalowanych aplikacji.

      Uwaga: ten interfejs API nie ma żadnych metod, które wymagałyby autoryzacji OAuth 2.0, więc może być konieczne uzyskanie tylko kluczy interfejsu API opisanych poniżej. Jeśli jednak aplikacja wywołuje inne interfejsy API, które wymagają autoryzacji użytkownika, i tak potrzebujesz danych uwierzytelniających OAuth 2.0.

      Więcej informacji znajdziesz w dokumentacji protokołu OAuth 2.0.

    • Klucze interfejsu API: żądanie, które nie zawiera tokena OAuth 2.0, musi wysłać klucz interfejsu API. Klucz identyfikuje projekt oraz zapewnia dostęp do interfejsu API, limit i raporty.

      Interfejs API obsługuje kilka typów ograniczeń kluczy interfejsu API. Jeśli klucz interfejsu API, którego potrzebujesz, jeszcze nie istnieje, utwórz klucz interfejsu API w konsoli, klikając Utwórz dane logowania > Klucz interfejsu API. Możesz wprowadzić ograniczenia przed użyciem klucza w środowisku produkcyjnym, klikając Ogranicz klucz i wybierając jedno z ograniczeń.

Aby zabezpieczyć klucze interfejsu API, postępuj zgodnie ze sprawdzonymi metodami korzystania z kluczy interfejsu API.

Gdy uzyskasz klucz interfejsu API, Twoja aplikacja może dołączać parametr zapytania key=yourAPIKey do adresów URL wszystkich żądań.

Klucz interfejsu API można bezpiecznie umieszczać w adresach URL, więc nie trzeba go kodować.

Poniższe fragmenty kodu pokazują, jak ustawić klucz interfejsu API dla różnych bibliotek klienta:

Java

import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.http.javanet.NetHttpTransport;

import com.google.api.services.analytics.Analytics;
import com.google.api.services.analytics.AnalyticsRequestInitializer;

public class ApiKeySample {
  private static final String API_KEY = "YOUR API KEY";

  public static void main(String[] args) {
    NetHttpTransport netHttpTransport = new NetHttpTransport();
    JacksonFactory jacksonFactory = new JacksonFactory();

    // Set the API Key
    AnalyticsRequestInitializer analyticsInitializer = new AnalyticsRequestInitializer(API_KEY);

    // Build the Analytics Service object
    Analytics analytics = new Analytics.Builder(netHttpTransport, jacksonFactory, null)
        .setAnalyticsRequestInitializer(analyticsInitializer)
        .setApplicationName("ApiKeySample")
        .build();

    // Start coding cool things.
  }
}

Python

from apiclient.discovery import build

API_KEY = 'YOUR API KEY'

def main(argv):
  # Set the API Key and build the Analytics service object.
  service = build('analytics', 'v3', developerKey=API_KEY)

  # Start coding cool things.

PHP

require_once 'google-api-php-client/src/Google_Client.php';
require_once 'google-api-php-client/src/contrib/Google_AnalyticsService.php';

const API_KEY = 'YOUR API KEY'

$client = new Google_Client();

// Set the API Key
$client->setDeveloperKey($API_KEY);

// Build the Analytics Service object.
$analytics = new google_AnalyticsService($client);

// Start coding cool things.

JavaScript

<!--
  Method 1:
  Using the Google APIs Client Library for JavaScript
-->
<script>
var apiKey = 'YOUR API KEY';

function handleClientLoad() {
  gapi.client.setApiKey(apiKey);
  gapi.client.load('analytics', 'v3', makeRequest);
}

function makeRequest() {
  // Start coding cool things.
}
</script>
<script src="//apis.google.com/js/client.js?onload=handleClientLoad"></script>


<!--
  Method 2:
  Using REST and callback parameter
-->
<script>
function render() {
  // Place your awesome code here.
}
</script>

<!-- Replace RESOURCE with the path to the Google Analytics resource you're querying. -->
<script src="https://www.googleapis.com/analytics/v3/RESOURCE/?key=YOUR_API_KEY&callback=render"></script>

Atrybuty kolumn

Odpowiedź interfejsu Metadata API zawiera właściwość attributeNames, która zawiera wszystkie prawidłowe atrybuty kolumn. Każda kolumna ma właściwość attributes, która obejmuje podzbiór atrybutów, które mają do niej zastosowanie.

Poniższa tabela zawiera pełną listę prawidłowych atrybutów:

Przykłady zastosowania

Interfejs Metadata API może służyć do tych celów:

Wycofane kolumny

Jeśli kolumna (tj. wymiar lub dane) została wycofana, jej atrybut status zostanie ustawiony na DEPRECATED.

Ten fragment kodu pokazuje, jak za pomocą atrybutu status sprawdzić, czy kolumna nie została wycofana:

function isDeprecated(column) {
  return column.attributes.status == 'DEPRECATED';
}

Jeśli zmienisz nazwę lub usuniesz kolumnę, jej atrybut status zostanie ustawiony na DEPRECATED, a atrybut replacedBy może mieć wartość Id kolumny zastępczej.

Ten fragment kodu pokazuje, jak za pomocą atrybutu replacedBy uzyskać identyfikator kolumny zastępczej:

function getReplacementId(column) {
  return column.attributes.replacedBy;
}

Nazwy kolumn

Atrybut uiName to nazwa wymiaru lub danych używane w interfejsach użytkownika Google Analytics (np. w interfejsie internetowym).

Ten fragment kodu pokazuje, jak pobrać nazwę interfejsu kolumny:

function getColumnName(column) {
  return column.attributes.uiName;
}

Kolumny szablonowe

Kolumny skrócone zawierają wymiary lub dane z indeksem liczbowym. Na przykład ga:goalXXStarts, ga:dimensionXX, ga:metricXX itp. Szablonowa kolumna będzie miała atrybuty minTemplateIndex i maxTemplateIndex, które określają zakres indeksu.

Ten fragment kodu pokazuje, jak sprawdzić, czy kolumna jest szablonem:

function isTemplatized(column) {
  return !!column.attributes.minTemplateIndex ||
         !!column.attributes.maxTemplateIndex;
}

Ten fragment kodu pokazuje, jak pobrać listę prawidłowych identyfikatorów dla szablonu kolumny:

function getTemplatizedIdList(column) {
  var columnIdList = [];
  var columnId = column.id;

  if (isTemplatized(column)) {
    minIndex = parseInt(column.attributes.minTemplateIndex);
    maxIndex = parseInt(column.attributes.maxTemplateIndex);

    for (var i = minIndex; i <= maxIndex; i++) {
      columnIdList.push(columnId.replace('XX', i));
    }
  }
  return columnIdList;
}

Obliczone kolumny

Kolumna, która pochodzi z obliczeń innych kolumn, będzie miała atrybut calculation. Przykład: obliczona wartość ga:percentNewSessions wynosi ga:newSessions / ga:sessions.

Z przykładu poniżej dowiesz się, jak sprawdzić, czy kolumna została obliczona, i jak pobrać dla niej obliczenia:

function isCalculated(column) {
  return !!column.attributes.calculation;
}

function getCalculation(column) {
  return column.attributes.calculation;
}

Kolumny i segmenty

Atrybut allowedInSegments pozwala sprawdzić, czy danej kolumny można użyć w parametrze zapytania dotyczącym segmentu.

Z przykładu poniżej dowiesz się, jak sprawdzić, czy kolumny można używać w segmentach:

function isAllowedInSegments(column) {
  return !!column.attributes.allowedInSegments;
}

Dodano w wersji interfejsu API

Użyj atrybutu addedInApiVersion, aby sprawdzić, czy kolumny można używać w interfejsie API do raportowania w określonej wersji. Wywołaj na przykład tę funkcję, aby sprawdzić, czy kolumny można użyć w interfejsie Core Reporting API w wersji 3: 

function isAllowedInV3(column) {
  return column.attributes.addedInApiVersion < 4;
}

ETag

Każda odpowiedź interfejsu Metadata API zawiera ETag. ETag to identyfikator, który może służyć do zapisywania w pamięci podręcznej i aktualizowania odpowiedzi interfejsu Metadata API. To ważne, ponieważ dane w kolumnach (tj.wymiarach i wskaźnikach) mogą pozostawać niezmienione przez długi czas, a przesyłanie niepotrzebnych żądań i aktualizacji, gdy można użyć danych z pamięci podręcznej, jest nieefektywne.

Jeśli przechowujesz element ETag kolekcji kolumn, możesz go używać głównie na 2 sposoby: do sprawdzania, czy odpowiedź interfejsu Metadata API w pamięci podręcznej jest aktualna, i uwzględniania jej w żądaniu do interfejsu Metadata API.

Sprawdzanie odpowiedzi w pamięci podręcznej

Jeśli porównujesz wartość ETag zwracaną z odpowiedzi interfejsu Metadata API i odpowiada ona wartości ETag zasobu przechowywanego w pamięci podręcznej, wersja z pamięci podręcznej jest aktualna. Jeśli tagi ETag nie są równoważne, zaktualizuj aplikację i odśwież pamięć podręczną, korzystając z najnowszej odpowiedzi.

Jeśli z interfejsu Metadata API chcesz pobierać tylko wartość ETag, podczas tworzenia żądania ustaw parametr zapytania fields na etag. Zobacz przykład

Używanie elementu ETag z żądaniem interfejsu API

Jeśli masz wersję kolekcji kolumn zapisaną w pamięci podręcznej, możesz uwzględnić jej wartość ETag w żądaniu interfejsu Metadata API, ustawiając pole nagłówka HTTP If-None-Match. Interfejs Metadata API sprawdzi wartość ETag i w odpowiedzi otrzyma zaktualizowaną wersję zasobu oraz stan HTTP 200 OK lub pustą odpowiedź ze stanem 304 Not Modified, jeśli wersja przechowywana w pamięci podręcznej jest aktualna.