Gestione utenti

L'API di gestione di Google Analytics consente la gestione programmatica delle autorizzazioni utente. Ciò è particolarmente utile per le grandi aziende con aggiornamenti frequenti ai propri elenchi di controllo dell'accesso (ACL).

Introduzione

Esistono tre risorse principali utilizzate per controllare chi può accedere a un account, a una proprietà o a una vista (profilo):

• Link degli utenti con account
• Link utente delle proprietà web
• Link degli utenti del profilo

È inoltre disponibile un supporto speciale in batch per le operazioni di scrittura con autorizzazioni utente.

Autorizzazioni utente

A un utente, rappresentato da un Account Google, possono essere concessi i seguenti livelli di accesso a un account, una proprietà o una vista (profilo Google Analytics):

• MANAGE_USERS - È necessaria per effettuare richieste di scrittura alle API User autorizzazioni.
• EDIT - Necessaria per modificare le risorse di gestione dei dati.
• COLLABORATE
• READ_AND_ANALYZE

Per ulteriori dettagli su ciascun livello di accesso, consulta l'articolo del Centro assistenza Autorizzazioni dell'utente.

Assegnazione delle autorizzazioni

L'API espone due tipi di autorizzazioni: local e effective. Le autorizzazioni locali si applicano all'account, alla proprietà o alla vista (profilo) specificati. Quando assegni le autorizzazioni con l'API, devi utilizzare la proprietà permissions.local. Le autorizzazioni Effective rappresentano le autorizzazioni ereditate dalle risorse padre.

Autorizzazioni ereditate

Se a un utente viene concessa l'autorizzazione EDIT per un account, tutti i profili e le proprietà all'interno dell'account erediteranno tale autorizzazione, che sarà rappresentata dalla proprietàpermissions.effective.

Se gli account, le proprietà o le viste di Google Analytics appartengono a un'organizzazione, i relativi proprietari possono modificare gli utenti in questi account. Tuttavia, l'API di gestione elenca solo i membri espliciti degli Account, delle Proprietà o delle Viste, non dell'organizzazione o dei relativi proprietari.

casi d'uso

Le autorizzazioni utente nell'API di gestione possono essere utilizzate per risolvere i seguenti casi d'uso:

• Elenca tutti gli utenti di un account
• Aggiornare un numero elevato di utenti
• Eliminare un utente dalla gerarchia degli account
• Aggiornare un singolo utente
• Aggiungere un singolo utente

Elenca tutti gli utenti di un account

Per elencare tutti gli utenti di un account, inclusi tutti gli utenti che dispongono delle autorizzazioni per qualsiasi proprietà o vista (profilo) nell'account, esegui il metodo list della risorsa accountUserLinks.

Nota: la proprietà Autorizzazioni local potrebbe essere vuota per alcuni utenti se hanno ricevuto l'accesso a un livello più interno della gerarchia dell'account e non direttamente nell'account.

Aggiorna un numero elevato di utenti

Per aggiornare le autorizzazioni per un numero elevato di utenti, ti consigliamo vivamente di utilizzare l'organizzazione in batch. In questo modo, non solo risparmierai la quota, ma avrai anche prestazioni molto più elevate. Per informazioni dettagliate complete, consulta la sezione relativa al batch di seguito. Per eseguire questa operazione per un account, procedi nel seguente modo:

1. Ottieni tutti i link degli utenti per l'account:
   • list tutti i accountUserLinks.
2. Crea richieste di aggiornamento per ciascun utente con le autorizzazioni appropriate:
   • update ogni accountUserLink.
3. Crea una singola richiesta batch per ogni 300 utenti contenente le richieste di aggiornamento precedenti:
   • chiamare batch ogni 300 utenti.

Eliminare un utente dalla gerarchia degli account

Per rimuovere tutte le occorrenze di un utente dalla gerarchia dell'account (ad es. account, proprietà e viste (profili). Per eseguire questa operazione, procedi nel seguente modo:

1. Ottieni tutti i link degli utenti per ogni livello di entità. Esegui 3 richieste list per l'account:
   • list tutti i accountUserLinks.
   • list tutti i webpropertyUserLinks impostando il parametro webpropertyId su ~all.
   • list tutti i profileUserLinks impostando i parametri webpropertyId e profileId su ~all.
2. Trova ed elimina gli utenti con autorizzazioni locali. Per ogni risposta ricevuta dalle tre operazioni di elenco nel passaggio 1, ripeti ciascuna entityUserLink:
   • se le proprietà userRef corrispondono all'utente e se sono impostate le autorizzazioni local, quindi esegui un delete sulla risorsa

Per ulteriori dettagli sul metodo delete delle risorse Link utente account, Link utente proprietà web e Visualizzazione link utente (profilo), consulta la sezione Riferimento API.

Aggiornare un singolo utente

Le autorizzazioni degli utenti possono essere aggiornate anche utilizzando l'API di gestione. Ad esempio, per modificare il livello di autorizzazione di un utente da READ_AND_ANALYZE a EDIT, supponendo che non si conosca il nome o l'ID della vista (profilo) sono:

1. Ottieni tutti i link degli utenti per ogni livello di entità Esegui 3 richieste list per l'account:

   • list tutti i accountUserLinks.
   • list tutti i webpropertyUserLinks impostando il parametro webpropertyId su ~all.
   • list tutti i profileUserLinks impostando i parametri webpropertyId e profileId su ~all.

2. Trova e aggiorna gli utenti con autorizzazioni locali. Per ogni risposta ricevuta dalle tre operazioni di elenco nel passaggio 1, ripeti ciascuna entityUserLink:

   • Se le proprietà userRef corrispondono all'utente e se l'utente dispone delle autorizzazioni local con accesso READ_AND_ANALYZE, quindi esegui un update sulla risorsa.

Per ulteriori dettagli sul metodo update delle risorse Link utente account, Link utente proprietà web e Visualizzazione link utente (profilo), consulta la sezione Riferimento API.

Aggiungi un singolo utente

Per aggiungere un utente alla gerarchia degli account, ad esempio a una vista (profilo), sono necessari i seguenti passaggi:

1. Utilizza l'API di gestione o l'interfaccia web per recuperare gli ID dell'account, della proprietà e della vista (profilo).
2. Aggiungi l'utente eseguendo il metodo insert della risorsa profileUserLinks.

Batch

Ci sono miglioramenti delle prestazioni e incentivi in termini di quota durante il batch delle richieste di scrittura (eliminazione, inserimento, aggiornamento) dell'API di autorizzazione.

• Le richieste di autorizzazioni utente in batch possono sfruttare le ottimizzazioni back-end e registrare miglioramenti significativi delle prestazioni.
• Ogni 30 richieste API di autorizzazione utente in batch viene conteggiata come una sola operazione di scrittura singola.
• In una singola richiesta batch è possibile effettuare fino a 300 richieste API per le autorizzazioni utente, consentendo un QPS più elevato per limite utente.

Per ottenere il massimo da questi aumenti del rendimento, devi intraprendere alcune azioni.

• Raggruppa la richiesta API per utente.
• Solo richieste batch per un account. Le richieste di autorizzazioni utente raggruppate con più di un account Google Analytics generano un errore con il seguente messaggio: All batched requests must be under the same account.

Gestione degli errori

Tutte le chiamate di autorizzazioni in una richiesta batch vengono trattate come una singola transazione. Ciò significa che se una delle mutazioni è errata, non viene apportata alcuna modifica. I motivi per cui li trattiamo come un'unica chiamata sono:

• Potrebbero essere necessarie più modifiche per cambiare le autorizzazioni di un singolo utente. Se una delle modifiche non è corretta, il commit di una parte del batch potrebbe causare uno stato indesiderato delle autorizzazioni dell'utente.
• Poiché le modifiche vengono considerate come una singola transazione, ottimizziamo il traffico e possiamo ridurre la quota richiesta per la chiamata.

Esempio di batch - Python

Di seguito è riportato un semplice esempio in Python di come raggruppare le richieste per aggiungere un elenco di utenti a un insieme di viste (profili). L'esempio viene eseguito in loop tra gli account dell'utente autorizzato e viene creata una singola richiesta batch per ogni account. All'interno di ogni richiesta batch, raggruppa tutte le modifiche per un determinato utente.

"""A simple example of Google Analytics batched user permissions."""
import json
from googleapiclient.errors import HttpError
from googleapiclient.http import BatchHttpRequest

def call_back(request_id, response, exception):
  """Handle batched request responses."""
  print request_id
  if exception is not None:
    if isinstance(exception, HttpError):
      message = json.loads(exception.content)['error']['message']
      print ('Request %s returned API error : %s : %s ' %
             (request_id, exception.resp.status, message))
  else:
    print response


def add_users(users, permissions):
  """Adds users to every view (profile) with the given permissions.

  Args:
    users: A list of user email addresses.
    permissions: A list of user permissions.
  Note: this code assumes you have MANAGE_USERS level permissions
  to each profile and an authorized Google Analytics service object.
  """

  # Get the a full set of account summaries.
  account_summaries = analytics.management().accountSummaries().list().execute()

  # Loop through each account.
  for account in account_summaries.get('items', []):
    account_id = account.get('id')

    # Loop through each user.
    for user in users:
      # Create the BatchHttpRequest object.
      batch = BatchHttpRequest(callback=call_back)

      # Loop through each property.
      for property_summary in account.get('webProperties', []):
        property_id = property_summary.get('id')

        # Loop through each view (profile).
        for view in property_summary.get('profiles', []):
          view_id = view.get('id')

          # Construct the Profile User Link.
          link = analytics.management().profileUserLinks().insert(
              accountId=account_id,
              webPropertyId=property_id,
              profileId=view_id,
              body={
                  'permissions': {
                      'local': permissions
                  },
                  'userRef': {
                      'email': user
                  }
              }
          )
          batch.add(link)

      # Execute the batch request for each user.
      batch.execute()

if __name__ == '__main__':

  # Construct a list of users.
  emails = ['[e-mail]', '[e-mail]', '[e-mail]', '[e-mail]']

  # call the add_users function with the list of desired permissions.
  add_users(emails, ['READ_AND_ANALYZE'])

Passaggi successivi

Quindi vedremo come utilizzare l'API di gestione di Google Analytics per configurare varie risorse di dati.