API Metadata - Guida per gli sviluppatori

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

Introduzione

L'API Metadata restituisce l'elenco di colonne (ad es. dimensioni e metriche) esposte nelle API di reporting di Google Analytics e i relativi attributi. Se non hai mai utilizzato l'API, leggi la panoramica dell'API Metadata per un'introduzione all'API Metadata.

Prima di iniziare

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

  • Leggi la pagina relativa alle librerie client per un elenco completo delle librerie client specifiche dei linguaggi di programmazione che funzionano con l'API.
  • Leggi la guida di riferimento per scoprire di più sull'interfaccia API e sull'accesso ai dati senza una libreria client.

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

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

Chiave API e di registrazione

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

Acquisizione e utilizzo di una chiave API

Per acquisire una chiave API:

  1. Apri la pagina Credenziali nell'API Console.
  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, possibilmente, un client secret per ottenere un token. Puoi generare 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, potresti dover 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 ulteriori informazioni, 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 API, quota e report.

      L'API supporta diversi tipi di limitazioni per le chiavi API. Se la chiave API che ti serve non esiste già, creane una 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 chiavi API, segui le best practice per l'utilizzo sicuro delle chiavi API.

Dopo che hai ottenuto una chiave API, la tua applicazione può aggiungere il parametro di query key=yourAPIKey a tutti gli URL delle richieste.

La chiave API è sicura per l'incorporamento negli URL, non richiede alcuna 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 che elenca tutti gli attributi di colonna validi. Ogni colonna ha una proprietà attributes che include un sottoinsieme di attributi applicabili alla colonna.

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

Casi d'uso

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

Colonne obsolete

Se una colonna (ovvero una dimensione o una metrica) è deprecata, il relativo attributo status verrà impostato su DEPRECATED.

Lo snippet seguente 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, il suo attributo status verrà impostato su DEPRECATED e potrebbe avere un attributo replacedBy impostato su Id della colonna sostitutiva.

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

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

Nomi colonna

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

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

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

Colonne templatizzate

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

Lo snippet seguente mostra come verificare se una colonna è costituita da modelli:

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

Il seguente snippet mostra come recuperare un elenco di ID validi per una colonna 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.

L'esempio seguente mostra come verificare se una colonna è stata 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 è possibile utilizzare una colonna 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;
}

Aggiunto nella 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 funzione seguente per verificare che la colonna possa essere utilizzata nella API di reporting principale V3: 

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

ETag

Un ETag è incluso in ogni risposta dell'API Metadata. L'ETag è un identificatore che può essere utilizzato per memorizzare nella cache e aggiornare le risposte dell'API Metadata. Questo è importante perché i dati delle colonne (ovvero le dimensioni e le metriche) possono rimanere invariati per lunghi periodi di tempo ed è inefficiente effettuare richieste e aggiornamenti non obbligatori quando è possibile utilizzare i 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 includerla in una richiesta dell'API Metadata.

Controllare una risposta memorizzata nella cache

Se confronti il valore ETag restituito da una risposta dell'API Metadata ed è equivalente all'ETag di una risorsa memorizzata nella cache, la versione memorizzata nella cache sarà aggiornata. Se gli ETag non sono equivalenti, aggiorna l'applicazione e aggiorna la cache con l'ultima risposta.

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

Utilizzo di un ETag con una richiesta API

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