Metadata API – przewodnik dla programistów

W tym dokumencie opisujemy ważne zagadnienia dotyczące korzystania z interfejsu Metadata API w celu uzyskania dostępu do listy i atrybutów kolumn Google Analytics.

Wprowadzenie

Interfejs Metadata API zwraca listę kolumn (np. wymiary i dane) ujawnione w interfejsach API raportowania Google Analytics i ich atrybutach. Jeśli dopiero zaczynasz korzystać z tego interfejsu, zapoznaj się z artykułem o metadanych interfejsu API, aby dowiedzieć się o nim więcej.

Zanim zaczniesz

Dostęp do wszystkich interfejsów API Google Analytics wygląda podobnie. Zanim zaczniesz korzystać z interfejsu Metadata API, wykonaj te czynności:

  • Pełną listę bibliotek klienckich języków programowania, które obsługują interfejs API, znajdziesz na stronie Biblioteki klienta.
  • Więcej informacji o interfejsie API i uzyskiwaniu dostępu do danych bez biblioteki klienta znajdziesz w przewodniku.

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 wykonać te czynności:

  1. Zarejestruj aplikację w konsoli Google API.
  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żdej z nich klucz interfejsu API.

Uzyskiwanie i używanie klucza interfejsu API

Aby uzyskać klucz interfejsu API:

  1. Otwórz stronę Dane logowania w konsoli interfejsu API.
  2. Ten interfejs API obsługuje 2 typy danych logowania. Utwórz odpowiednie dane logowania do swojego projektu:
    • OAuth 2.0: gdy aplikacja żąda prywatnych danych użytkownika, musi wraz z żądaniem wysłać token OAuth 2.0. Aplikacja najpierw wysyła identyfikator klienta, a być może także klucz klienta, aby uzyskać token. Możesz wygenerować dane logowania OAuth 2.0 dla aplikacji internetowych, kont usługi lub zainstalowanych aplikacji.

      Uwaga: nie ma żadnych metod wymagających autoryzacji OAuth 2.0 w interfejsie API, 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, dane logowania OAuth 2.0 będą nadal potrzebne.

      Więcej informacji znajdziesz w dokumentacji OAuth 2.0.

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

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

Aby zapewnić bezpieczeństwo kluczy API, postępuj zgodnie ze sprawdzonymi metodami korzystania z kluczy interfejsu API.

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

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

Poniżej znajdziesz fragmenty kodu pokazujące, jak ustawić klucz interfejsu API w przypadku 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 kolumny

Odpowiedź interfejsu Metadata API zawiera właściwość attributeNames, która zawiera listę wszystkich prawidłowych atrybutów kolumn. Każda kolumna ma właściwość attributes, która zawiera podzbiór atrybutów odnoszących się do kolumny.

Poniżej znajdziesz pełną listę prawidłowych atrybutów:

Przykłady zastosowania

Interfejs Metadata API może być używany w tych przypadkach użycia:

Nieużywane kolumny

Jeśli kolumna (np. wymiar lub dane) zostanie wycofana, jej atrybut status zostanie ustawiony na DEPRECATED.

Ten fragment kodu pokazuje, jak za pomocą atrybutu status sprawdzić, czy kolumna 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 w kolumnie zastępczej.

Ten fragment kodu pokazuje, jak użyć atrybutu replacedBy do uzyskania identyfikatora kolumny zastępczej:

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

Nazwy kolumn

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

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

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

Kolumny moderowane

Kolumny moderowane zawierają wymiary lub dane z indeksem liczbowym. Na przykład ga:goalXXStarts, ga:dimensionXX, ga:metricXX itd. kolumna tymczasowa będzie zawierać atrybuty minTemplateIndex i maxTemplateIndex, które definiują zakres indeksu.

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

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

Ten fragment kodu pokazuje, jak pobrać listę prawidłowych identyfikatorów ostatniej 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 wygenerowana na podstawie obliczeń innych kolumn będzie miała atrybut calculation. Na przykład obliczenie dla: ga:percentNewSessions wynosi ga:newSessions / ga:sessions.

Poniższy przykład pokazuje, jak sprawdzić, czy kolumna jest obliczana i jak to zrobić:

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

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

Kolumny i segmenty

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

Poniższy przykład pokazuje, jak określić, czy kolumna może być używana 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 przypadku określonej wersji. Możesz na przykład wywołać tę funkcję w celu sprawdzenia, czy kolumny można użyć w interfejsie Core Reporting API V3:

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

ETag

ETag jest zawarty w każdej odpowiedzi interfejsu Metadata API. ETag to identyfikator, który służy do zapisywania w pamięci podręcznej i aktualizacji odpowiedzi interfejsu Metadata API. Ta wartość jest ważna, ponieważ dane (kolumny (wymiary i dane)) mogą pozostawać bez zmian przez dłuższy czas i nieskuteczne będzie wysyłanie niepotrzebnych żądań i aktualizacji w przypadku użycia danych w pamięci podręcznej.

Jeśli przechowujesz tag ETag kolekcji kolumn, możesz go używać głównie na 2 sposoby: aby sprawdzić, czy odpowiedź interfejsu Metadata API jest aktualna i uwzględnić ją w żądaniu interfejsu Metadata API.

Sprawdzanie odpowiedzi z pamięci podręcznej

Jeśli porównasz wartość tagu ETag zwróconego w odpowiedzi interfejsu Metadata API i jest ona zgodna z tagiem ETag zasobu 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ą z najnowszą odpowiedzią.

Jeśli chcesz pobrać tylko wartość ETag z interfejsu Metadata API, ustaw parametr zapytania fields na etag. Zobacz przykład

Używanie tagu ETag z żądaniem interfejsu API

Jeśli masz kolekcję kolumn 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 wyśle odpowiedź ze zaktualizowaną wersją zasobu i stanem HTTP 200 OK lub pustą odpowiedzią ze stanem 304 Not Modified, jeśli wersja w pamięci podręcznej jest aktualna.