API Metadata - Guida per gli sviluppatori

Questo documento spiega concetti importanti sull'utilizzo dell'API Metadata per accedere all'elenco e agli attributi delle colonne di Google Analytics.

Introduzione

L'API Metadata restituisce un elenco di colonne (ad esempio dimensioni e metriche) esposte nelle API dei report di Google Analytics e dei relativi attributi. Se non hai mai utilizzato l'API, consulta la Panoramica dell'API Metadata per un'introduzione all'API Metadata.

Prima di iniziare

L'accesso a tutte le API di Google Analytics è simile. Prima di iniziare a utilizzare l'API Metadata, devi:

  • Consulta la pagina Librerie client per un elenco completo delle librerie client specifiche per i vari linguaggi di programmazione che funzionano con l'API.
  • Leggi la Guida di riferimento per ulteriori informazioni sull'interfaccia dell'API e sull'accesso ai dati senza una libreria client.

Ogni libreria client fornisce un singolo oggetto di servizio di analisi per accedere a tutti i dati dell'API Metadata. Per creare l'oggetto di servizio da utilizzare con l'API di metadati, in genere devi eseguire i seguenti passaggi:

  1. Registra l'applicazione nella console API di Google.
  2. Crea un oggetto di servizio Analytics e imposta la chiave API.

Registrazione e chiave API

L'applicazione deve identificarsi ogni volta che invia una richiesta all'API di Analytics, includendo una chiave API in ogni richiesta.

Acquisire e utilizzare una chiave API

Per acquisire una chiave API:

  1. Apri la pagina Credenziali nella console API.
  2. Questa API supporta due tipi di credenziali. Crea le credenziali appropriate per il tuo progetto:
    • OAuth 2.0: ogni volta che l'applicazione richiede dati utente privati, deve inviare un token OAuth 2.0 insieme alla richiesta. L'applicazione invia prima un ID client e, eventualmente, un client secret per ottenere un token. Puoi generare le credenziali OAuth 2.0 per applicazioni web, account di servizio o applicazioni installate.

      Nota: poiché questa API non ha metodi che richiedono l'autorizzazione OAuth 2.0, potrebbe essere necessario ottenere solo le chiavi API, descritte di seguito. Tuttavia, se l'applicazione chiama altre API che richiedono l'autorizzazione dell'utente, saranno comunque necessarie le credenziali OAuth 2.0.

      Per scoprire di più, consulta la documentazione relativa a OAuth 2.0.

    • Chiavi API: Una richiesta che non fornisce un token OAuth 2.0 deve inviare una chiave API. La chiave identifica il progetto e fornisce accesso, quota e rapporti API.

      L'API supporta diversi tipi di restrizioni sulle chiavi API. Se la chiave API necessaria non esiste già, crea una chiave API nella console facendo clic su Crea credenziali > chiave API. Puoi limitare la chiave prima di utilizzarla in produzione facendo clic su Limita chiave e selezionando una delle Restrizioni.

Per proteggere le tue chiavi API, segui le best practice per l'utilizzo sicuro delle chiavi API.

Dopo aver creato una chiave API, l'applicazione può aggiungere il parametro di ricerca key=yourAPIKey a tutti gli URL della richiesta.

La chiave API è sicura per l'incorporamento negli URL; non ha bisogno di codifica.

I seguenti snippet di codice illustrano come impostare la chiave API per varie librerie client:

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>

Attributi colonna

La risposta dell'API Metadata include una proprietà attributeNames in cui sono elencati tutti gli attributi di colonna validi. Ogni colonna ha una proprietà attributes che include un sottoinsieme di attributi applicabili alla colonna.

La seguente tabella è l'elenco completo degli attributi validi:

Casi d'uso

L'API Metadata può essere utilizzata per risolvere i seguenti casi d'uso:

Colonne deprecate

Se una colonna (ad esempio una dimensione o una metrica) viene ritirata, l'attributo status verrà impostato su DEPRECATED.

Il seguente snippet mostra come utilizzare l'attributo status per verificare se una colonna è deprecata:

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

Se una colonna viene rinominata/rimossa, l'attributo status verrà impostato su DEPRECATED e potrebbe avere un attributo replacedBy impostato su Id della colonna sostitutiva.

Il seguente snippet mostra come utilizzare l'attributo replacedBy per ottenere l'ID della colonna sostitutiva:

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

Nomi delle colonne

L'attributo uiName è il nome della dimensione o della metrica utilizzato nelle interfacce utente di Google Analytics (ad es. l'interfaccia web).

Lo snippet che segue mostra come recuperare il nome UI di una colonna:

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

Colonne con modello

Le colonne modello includono dimensioni o metriche con un indice numerico. Ad esempio, ga:goalXXStarts, ga:dimensionXX, ga:metricXX e così via. Una colonna con modello avrà attributi minTemplateIndex e maxTemplateIndex che definiscono l'intervallo di indici.

Lo snippet che segue mostra come verificare se una colonna è modellizzata:

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

Il seguente snippet mostra come recuperare un elenco di ID validi per una colonna con modello:

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

Colonne calcolate

Una colonna derivata da un calcolo di altre colonne avrà un attributo calculation. Ad esempio, il calcolo di ga:percentNewSessions è ga:newSessions / ga:sessions.

Il seguente esempio mostra come verificare se una colonna è calcolata e come recuperare il calcolo per una colonna:

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

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

Colonne e segmenti

L'attributo allowedInSegments consente di verificare se una colonna può essere utilizzata nel parametro di ricerca del segmento.

L'esempio seguente mostra come determinare se una colonna può essere utilizzata nei segmenti:

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

Aggiunta in versione API

Utilizza l'attributo addedInApiVersion per verificare se una colonna può essere utilizzata in un'API di reporting di una versione specificata. Ad esempio, chiama la seguente funzione per verificare che la colonna possa essere utilizzata nell'API Core Reporting V3:

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

ETag

In ogni risposta dell'API Metadata è incluso un ETag. L'ETag è un identificatore che può essere utilizzato per memorizzare nella cache e aggiornare le risposte dell'API Metadata. Ciò è importante perché i dati delle colonne (ovvero dimensioni e metriche) possono rimanere invariati per lunghi periodi di tempo e non è sufficiente effettuare richieste e aggiornamenti non necessari quando è possibile utilizzare dati memorizzati nella cache.

Se archivi l'ETag di una raccolta di colonne, puoi utilizzarlo principalmente in due modi: per verificare se una risposta dell'API Metadata memorizzata nella cache è aggiornata e per includerla in una richiesta API Metadata.

Controllare una risposta memorizzata nella cache

Se confronti il valore ETag restituito da una risposta dell'API Metadata ed è equivalente all'ETag per una risorsa memorizzata nella cache, la versione memorizzata nella cache è corrente. Se i tag ETag non sono equivalenti, aggiorna l'applicazione e aggiorna la cache con la risposta più recente.

Se vuoi recuperare solo il valore ETag dall'API Metadata, imposta il parametro di ricerca fields su etag quando effettui una richiesta. Visualizza un esempio.

Utilizzo di un ETag con una richiesta API

Se hai una versione memorizzata nella cache di una raccolta di colonne, puoi includere il relativo valore ETag in una richiesta API Metadata impostando il campo di intestazione HTTP If-None-Match. L'API Metadata verificherà il valore ETag e risponderà con una versione aggiornata della risorsa e uno stato HTTP 200 OK oppure una risposta vuota con stato 304 Not Modified se la versione memorizzata nella cache è corrente.