I canali Alpha e Beta dell'API continuano a essere supportati. Il canale beta contiene un sottoinsieme delle funzionalità disponibili in versione alpha che sono considerate stabili e non subiranno cambiamenti significativi in futuro. Una volta raggiunto il limite di maturità, verranno aggiunte nuove funzionalità alla versione beta.
Questo documento fornisce istruzioni su come eseguire la migrazione del codice esistente dall'API Google Analytics Management v3 all'API Google Analytics Admin v1 e fornisce una breve panoramica delle principali differenze tra le due API.
Perché devo eseguire la migrazione?
Se la tua applicazione deve creare o configurare una proprietà Google Analytics 4, deve utilizzare l'API Admin v1. L'API Management v3 funziona solo con le proprietà Universal Analytics, mentre l'API Admin v1 funziona solo con le proprietà Google Analytics 4.
Prerequisiti
Per acquisire familiarità con le nozioni di base dell'API Admin v1, leggi la guida rapida.
Inizia
Per iniziare, prepara una proprietà Google Analytics 4, abilita l'API Admin v1, poi configurerai una libreria client API adatta alla tua piattaforma.
Preparare una proprietà Google Analytics 4
Prima di eseguire la migrazione del codice per supportare l'API Admin v1, devi eseguire la migrazione del sito web per utilizzare una proprietà Google Analytics 4.
Abilita l'API
Fai clic su questo pulsante per abilitare automaticamente l'API Admin v1 nel progetto Google Cloud selezionato.
Attivare l'API Google Analytics AdminUtilizzare una libreria client
Installa una libreria client
Se utilizzi una libreria client, devi installare la libreria client dell'API Admin v1 per il tuo linguaggio di programmazione.
Java
Python
Node.js
.NET
PHP
Go
go get google.golang.org/genproto/googleapis/analytics/admin/v1alpha
Inizializzare una libreria client
Le librerie client dell'API Admin v1 sono state progettate per consentirti di iniziare rapidamente. Per impostazione predefinita, le librerie client provano a trovare automaticamente le credenziali dell'account di servizio.
Un modo semplice per fornire le credenziali dell'account di servizio consiste nell'impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS. Il client API utilizzerà il valore di questa variabile per trovare il file JSON della chiave dell'account di servizio.
Ad esempio, puoi impostare le credenziali dell'account di servizio eseguendo questo comando e utilizzando il percorso del file JSON dell'account di servizio:
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Di seguito sono riportati gli snippet di codice comunemente utilizzati per inizializzare le librerie client dell'API Admin v1.
Java
try (AnalyticsAdminServiceClient analyticsAdmin = AnalyticsAdminServiceClient.create()) {
Python
client = AlphaAnalyticsAdminClient()
.NET
AlphaAnalyticsAdminClient client = AlphaAnalyticsAdminClient.Create();
PHP
$client = new AlphaAnalyticsAdminClient();
Node.js
// Imports the Google Analytics Data API client library.
const {AlphaAnalyticsAdminClient} = require('@google-analytics/admin');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsAdminClient = new AlphaAnalyticsAdminClient();
Anziché utilizzare una variabile di ambiente, è anche possibile passare le informazioni sulle credenziali a un'istanza del client API in modo esplicito durante l'inizializzazione.
Se non utilizzi una libreria client
Se utilizzi l'API di gestione v3 senza una libreria client e vuoi continuare a farlo con l'API Admin v1, puoi comunque utilizzare le tue credenziali.
Devi utilizzare il nuovo endpoint HTTP e il documento di rilevamento forniti dall'API Admin:
Se il tuo codice sfrutta un documento di rilevamento, devi aggiornarlo al documento di rilevamento fornito dall'API Admin v1:
Dopo l'aggiornamento dell'endpoint, dovrai acquisire familiarità con la nuova struttura delle richieste e i nuovi concetti dell'API Admin per aggiornare la query JSON.
Attività comuni
Gestisci account
L'API Admin v1 fornisce un insieme di metodi di gestione di account e proprietà Google Analytics paragonabili alla versione 3 dell'API di gestione. Inoltre, l'API Admin v1 introduce funzionalità per provisioning, eliminazione e aggiornamento degli account Google Analytics.
I metodi di gestione delle proprietà v1 dell'API Admin supportano solo le proprietà Google Analytics 4.
La nozione di viste (profili) non è presente nella versione 1 dell'API Admin.
Da quando sono stati introdotti gli stream di dati in Google Analytics 4, alcune informazioni non sono più presenti a livello di proprietà. Ad esempio, il campo
websiteUrlora è presente nell'entitàDataStreamanziché far parte dell'oggetto proprietà.
Elenca riepiloghi account
Il metodo accountSummaries dell'API Admin restituisce riepiloghi leggeri di tutti gli account accessibili al chiamante, in modo simile al metodo accountSummaries dell'API di gestione v3.
Una distinzione importante è che l'API Admin v1 restituisce solo informazioni sulle proprietà Google Analytics 4, mentre le risposte dell'API di gestione v3 contengono dati sulle proprietà create con Universal Analytics. Non è possibile recuperare informazioni su entrambi i tipi di proprietà utilizzando una singola chiamata.
Poiché non esistono viste (profili) in Google Analytics 4, i riepiloghi degli account restituiti dall'API Admin non contengono informazioni sulle viste (profilo).
I dati di riepilogo dell'account Google Analytics 4 sono limitati alla risorsa e ai nomi visualizzati degli account o delle proprietà disponibili per l'utente corrente.
Utilizza i nomi delle risorse restituiti nei campi account e property della risposta dei riepiloghi per recuperare i dati di configurazione completi chiamando i metodi account.get e property.get.
Richiesta API Admin v1
GET https://analyticsadmin.googleapis.com/v1beta/accountSummaries?key=[YOUR_API_KEY]
Risposta dell'API Admin v1
{
"accountSummaries": [
{
"name": "accountSummaries/XXXXXX",
"account": "accounts/XXXXXX",
"displayName": "Test",
"propertySummaries": [
{
"property": "properties/XXXXXX",
"displayName": "Test App"
}
]
},
...
}
Richiesta API Management v3
GET https://analytics.googleapis.com/analytics/v3/management/accountSummaries?key=[YOUR_API_KEY]
Risposta dell'API Management v3
{
"kind": "analytics#accountSummaries",
"username": "XXXXXX",
"totalResults": 9,
"startIndex": 1,
"itemsPerPage": 1000,
"items": [
{
"id": "XXXXXX",
"kind": "analytics#accountSummary",
"name": "Test Account",
"webProperties": [
{
"kind": "analytics#webPropertySummary",
"id": "UA-XXXXXX",
"name": "Test Property",
"internalWebPropertyId": "XXXXXX",
"level": "STANDARD",
"websiteUrl": "XXXXXX",
"profiles": [
{
"kind": "analytics#profileSummary",
"id": "XXXXXX",
"name": "Test Profile",
"type": "WEB"
}
]
},
...
}
Codice campione per chiamare l'API Admin v1 utilizzando le librerie client:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
def list_account_summaries(transport: str = None) -> None:
"""
Prints summaries of all accounts accessible by the caller.
Args:
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
results = client.list_account_summaries()
print("Result:")
for account_summary in results:
print("-- Account --")
print(f"Resource name: {account_summary.name}")
print(f"Account name: {account_summary.account}")
print(f"Display name: {account_summary.display_name}")
print()
for property_summary in account_summary.property_summaries:
print("-- Property --")
print(f"Property resource name: {property_summary.property}")
print(f"Property display name: {property_summary.display_name}")
print()
Elenco account
Il metodo accounts.list dell'API Admin v1 restituisce tutti gli account accessibili al chiamante, in modo simile al metodo accounts.list dell'API di gestione v3.
Richiesta API Admin v1
GET https://analyticsadmin.googleapis.com/v1beta/accounts?key=[YOUR_API_KEY]
Risposta dell'API Admin v1
{
"accounts": [
{
"name": "accounts/XXXXXX",
"createTime": "2020-02-21T00:17:33.282Z",
"updateTime": "2021-01-07T02:47:57.386Z",
"displayName": "Test Account",
"regionCode": "US"
},
...
}
Richiesta API Management v3
GET https://analytics.googleapis.com/analytics/v3/management/accounts?key=[YOUR_API_KEY]
Risposta dell'API Management v3
{
"kind": "analytics#accounts",
"username": "XXXXXX",
"totalResults": 9,
"startIndex": 1,
"itemsPerPage": 1000,
"items": [
{
"id": "XXXXXX",
"kind": "analytics#account",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
"name": "Test Account",
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"READ_AND_ANALYZE"
]
},
"created": "2020-02-21T00:17:33.282Z",
"updated": "2021-01-07T02:47:57.386Z",
"childLink": {
"type": "analytics#webproperties",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties"
}
},
...
}
Tieni presente che la risposta dell'API Admin v1 non include informazioni sulle autorizzazioni utente effettive né sul campo childLink presente nell'API di gestione v3.
Codice campione per chiamare l'API Admin v1 utilizzando le librerie client:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from accounts_get import print_account
def list_accounts(transport: str = None):
"""
Lists the Google Analytics accounts available to the current user.
Args:
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
results = client.list_accounts()
print("Result:")
for account in results:
print_account(account)
Gestire le proprietà
Proprietà elenco
Il metodo properties.list dell'API Admin v1 restituisce tutte le proprietà Google Analytics 4 accessibili dal chiamante, in modo simile al metodo webproperties.list dell'API di gestione v3, che restituisce tutte le proprietà Universal Analytics accessibili.
Poiché il campo websiteUrl non è più presente a livello di proprietà in
Google Analytics 4, utilizza
properties.dataStreams/list
per elencare tutti gli stream di dati associati alla proprietà e cerca il campo
defaultUri
per recuperare l'URL del sito web associato a uno stream.
Prendi nota del parametro filter nell'URL della richiesta properties.list. Il valore del parametro contiene un'espressione per filtrare i risultati della richiesta e può essere utilizzato per elencare le proprietà associate all'ID account Google Analytics specificato o al progetto Firebase collegato.
Richiesta API Admin v1
GET https://analyticsadmin.googleapis.com/v1beta/properties?filter=parent:accounts/XXXXXX&key=[YOUR_API_KEY]
Risposta dell'API Admin v1
{
"properties": [
{
"name": "properties/XXXXXX",
"parent": "accounts/XXXXXX",
"createTime": "2020-10-29T04:02:49.124Z",
"updateTime": "2020-10-29T04:02:49.124Z",
"displayName": "Test Property",
"timeZone": "America/Los_Angeles",
"currencyCode": "USD"
},
...
}
Richiesta API Management v3
GET https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties?key=[YOUR_API_KEY]
Risposta dell'API Management v3
{
"kind": "analytics#webproperties",
"username": "XXXXXX",
"totalResults": 33,
"startIndex": 1,
"itemsPerPage": 1000,
"items": [
{
"id": "UA-XXXXXX-1",
"kind": "analytics#webproperty",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1",
"accountId": "XXXXXX",
"internalWebPropertyId": "XXXXXX",
"name": "Test Account",
"websiteUrl": "XXXXXX",
"level": "PREMIUM",
"profileCount": 4,
"industryVertical": "HEALTH",
"defaultProfileId": "XXXXXX",
"dataRetentionTtl": "INDEFINITE",
"dataRetentionResetOnNewActivity": true,
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"READ_AND_ANALYZE"
]
},
"created": "2020-02-21T00:28:47.287Z",
"updated": "2021-01-27T21:39:22.704Z",
"parentLink": {
"type": "analytics#account",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
},
"childLink": {
"type": "analytics#profiles",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/profiles"
}
},
...
}
Codice campione per chiamare l'API Admin v1 utilizzando le librerie client:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import ListPropertiesRequest
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
list_properties(account_id)
def list_properties(account_id: str, transport: str = None):
"""
Lists Google Analytics 4 properties under the specified parent account
that are available to the current user.
Args:
account_id(str): The Google Analytics account ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
results = client.list_properties(
ListPropertiesRequest(filter=f"parent:accounts/{account_id}", show_deleted=True)
)
print("Result:")
for property_ in results:
print(property_)
print()
Ottieni proprietà
Il metodo properties.get dell'API Admin v1 restituisce le informazioni su una proprietà Google Analytics 4, simili al metodo webproperties.get dell'API di gestione v3.
Tieni presente che il metodo properties.get dell'API Admin supporta solo le proprietà
Google Analytics 4.
Richiesta API Admin v1
GET https://analyticsadmin.googleapis.com/v1beta/properties/XXXXXX?key=[YOUR_API_KEY]
Risposta dell'API Admin v1
{
"name": "properties/XXXXXX",
"parent": "accounts/XXXXXX",
"createTime": "2021-04-30T21:32:49.804Z",
"updateTime": "2021-04-30T21:32:49.804Z",
"displayName": "Test Property",
"industryCategory": "FINANCE",
"timeZone": "America/Los_Angeles",
"currencyCode": "USD"
}
Richiesta API Management v3
GET https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3?key=[YOUR_API_KEY]
Risposta dell'API Management v3
{
"id": "UA-XXXXXX-3",
"kind": "analytics#webproperty",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3",
"accountId": "XXXXXX",
"internalWebPropertyId": "XXXXXX",
"name": "Test 2",
"websiteUrl": "YOUR-WEBSITE-URL",
"level": "STANDARD",
"profileCount": 0,
"industryVertical": "FINANCE",
"dataRetentionTtl": "MONTHS_26",
"dataRetentionResetOnNewActivity": true,
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
]
},
"created": "2021-05-20T05:35:51.985Z",
"updated": "2021-05-20T05:41:39.219Z",
"parentLink": {
"type": "analytics#account",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
},
"childLink": {
"type": "analytics#profiles",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3/profiles"
}
}
Codice campione per chiamare l'API Admin v1 utilizzando le librerie client:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import IndustryCategory
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID (e.g. "123456") before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
get_property(property_id)
def get_property(property_id: str, transport: str = None):
"""
Retrieves the Google Analytics 4 property details.
Args:
property_id(str): The Google Analytics Property ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
property_ = client.get_property(name=f"properties/{property_id}")
print("Result:")
print_property(property_)
def print_property(property):
"""Prints the Google Analytics 4 property details."""
print(f"Resource name: {property.name}")
print(f"Parent: {property.parent}")
print(f"Display name: {property.display_name}")
print(f"Create time: {property.create_time}")
print(f"Update time: {property.update_time}")
# print(f"Delete time: {property.delete_time}")
# print(f"Expire time: {property.expire_time}")
if property.industry_category:
print(f"Industry category: {IndustryCategory(property.industry_category).name}")
print(f"Time zone: {property.time_zone}")
print(f"Currency code: {property.currency_code}")
Crea proprietà
Il metodo properties.create dell'API Admin v1 crea una nuova proprietà Google Analytics 4, simile al metodo webproperties.insert dell'API di gestione v3.
Richiesta API Admin v1
POST https://analyticsadmin.googleapis.com/v1beta/properties?key=[YOUR_API_KEY]
{
"displayName": "Test Property",
"industryCategory": "AUTOMOTIVE",
"currencyCode": "USD",
"timeZone": "America/Los_Angeles",
"parent": "accounts/XXXXXX"
}
Risposta dell'API Admin v1
{
"name": "properties/XXXXXX",
"parent": "accounts/XXXXXX",
"createTime": "2021-05-20T09:16:08.458Z",
"updateTime": "2021-05-20T09:16:08.458Z",
"displayName": "Test Property",
"industryCategory": "AUTOMOTIVE",
"timeZone": "America/Los_Angeles",
"currencyCode": "USD"
}
Richiesta API Management v3
POST https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties?key=[YOUR_API_KEY]
{
"name": "Test",
"websiteUrl": "YOUR-WEBSITE-URL"
}
Risposta dell'API Management v3
{
"id": "UA-XXXXXX-3",
"kind": "analytics#webproperty",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3",
"accountId": "XXXXXX",
"internalWebPropertyId": "XXXXXX",
"name": "Test",
"websiteUrl": "YOUR-WEBSITE-URL",
"level": "STANDARD",
"profileCount": 0,
"dataRetentionTtl": "MONTHS_26",
"dataRetentionResetOnNewActivity": true,
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
]
},
"created": "2021-05-20T05:35:51.985Z",
"updated": "2021-05-20T05:35:51.985Z",
"parentLink": {
"type": "analytics#account",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
},
"childLink": {
"type": "analytics#profiles",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3/profiles"
}
}
Codice campione per chiamare l'API Admin v1 utilizzando le librerie client:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import Property
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics account ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
create_property(account_id)
def create_property(account_id: str, transport: str = None):
"""
Creates a Google Analytics 4 property.
Args:
account_id(str): The Google Analytics Account ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
property_ = client.create_property(
property=Property(
parent=f"accounts/{account_id}",
currency_code="USD",
display_name="Test property",
industry_category="OTHER",
time_zone="America/Los_Angeles",
)
)
print("Result:")
print(property_)
Aggiornamento/applicazione patch
Il metodo properties.patch dell'API Admin v1 aggiorna la configurazione di una proprietà Google Analytics 4, in modo simile al metodo webproperties.patch dell'API di gestione v3.
Prendi nota del parametro updateMask nell'URL della richiesta, che contiene l'elenco dei campi da aggiornare separati da virgole. I campi non presenti in questo elenco non verranno aggiornati. Se utilizzi una libreria client, il parametro update_mask sarà disponibile come parte della firma del metodo.
Richiesta API Admin v1
PATCH https://analyticsadmin.googleapis.com/v1beta/properties/XXXXXX?updateMask=displayName,industryCategory&key=[YOUR_API_KEY]
{
"displayName": "New Property Name",
"industryCategory": "FINANCE"
}
Risposta dell'API Admin v1
{
"name": "properties/XXXXXX",
"parent": "accounts/XXXXXX",
"createTime": "2021-04-30T21:32:49.804Z",
"updateTime": "2021-05-20T09:25:14.810Z",
"displayName": "New Property Name",
"industryCategory": "FINANCE",
"timeZone": "America/Los_Angeles",
"currencyCode": "USD"
}
Richiesta API Management v3
PATCH https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3?key=[YOUR_API_KEY]
{
"name": "New Property Name",
"industryVertical": "FINANCE"
}
Risposta dell'API Management v3
{
"id": "UA-XXXXXX-3",
"kind": "analytics#webproperty",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3",
"accountId": "XXXXXX",
"internalWebPropertyId": "XXXXXX",
"name": "New Property Name",
"websiteUrl": "XXXXXX",
"level": "STANDARD",
"profileCount": 0,
"industryVertical": "FINANCE",
"dataRetentionTtl": "MONTHS_26",
"dataRetentionResetOnNewActivity": true,
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
]
},
"created": "2021-05-20T05:35:51.985Z",
"updated": "2021-05-20T05:41:39.219Z",
"parentLink": {
"type": "analytics#account",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
},
"childLink": {
"type": "analytics#profiles",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3/profiles"
}
}
Codice campione per chiamare l'API Admin v1 utilizzando le librerie client:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import Property
from google.protobuf.field_mask_pb2 import FieldMask
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics property ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID (e.g. "123456") before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
update_property(property_id)
def update_property(property_id: str, transport: str = None):
"""
Updates the Google Analytics 4 property.
Args:
property_id(str): The Google Analytics Property ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
# This call updates the display name, industry category and time zone of the
# property, as indicated by the value of the `update_mask` field.
# The property to update is specified in the `name` field of the `Property`
# instance.
property_ = client.update_property(
property=Property(
name=f"properties/{property_id}",
display_name="This is an updated test property",
industry_category="GAMES",
time_zone="America/New_York",
),
update_mask=FieldMask(paths=["display_name", "time_zone", "industry_category"]),
)
print("Result:")
print(property_)
Gestisci utenti
L'API Google Analytics Admin attualmente implementa un modello di autorizzazioni utente simile all'API di gestione v3, ma con alcune differenze.
- Puoi gestire le autorizzazioni degli utenti con l'API Google Analytics Admin utilizzando le risorse dell'account
AccessBindinge della proprietàAccessBindinganziché le risorseAccountUserLink,WebPropertyUserLinkeProfileUserLinknell'API di gestione v3. - Le associazioni di accesso alla proprietà nell'API Google Analytics Admin non includono autorizzazioni o autorizzazioni implicite ereditate dalle associazioni di accesso all'account. Nell'API di gestione v3, ogni link utente conteneva una raccolta
permissions.effectiveche includeva autorizzazioni implicite ed ereditate.
Un'entità AccessBinding contiene un utente (indirizzo email) e un elenco di ruoli
concessi all'utente. Un'entità AccessBinding può essere creata, aggiornata o
eliminata.
La mappatura tra i nomi dei ruoli dell'API Admin v1 e i nomi delle autorizzazioni dell'API di gestione v3 è la seguente:
| Ruolo API Admin v1 | Nome autorizzazione API di gestione v3 |
|---|---|
| predefinitiRuoli/spettatore | READ_AND_ANALYZE |
| Ruoli/analisti predefiniti | COLLABORA |
| predefinitiRuoli/editor | MODIFICA |
| ruoli/amministratore predefiniti | MANAGE_USERS |
I ruoli predefinedRoles/no-cost-data e predefinedRoles/no-revenue-data sono stati introdotti nell'API Admin v1 e non hanno una mappatura corrispondente nell'API di gestione v3.
Questa guida illustra come gestire le associazioni di accesso a livello di account. Per gestire le associazioni di accesso a livello di proprietà, segui la stessa procedura, ma utilizza le risorse e i metodi della proprietà AccessBinding al posto di accountAccessBinding.
Elenca associazioni di accesso all'account
Il metodo accounts.accessBindings.list dell'API Admin v1 elenca tutte le associazioni di accesso in un account, in modo simile al metodo accountUserLinks.list dell'API di gestione v3.
Richiesta API Admin v1
GET https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/accessBindings/XXXXXXXX
Risposta dell'API Admin v1
{
"accessBindings": [
{
"name": "accounts/XXXXXX/accessBindings/XXXXXX",
"user": "XXXXXX",
"roles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
]
}
]
}
Richiesta API Management v3
GET https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks?key=[YOUR_API_KEY]
Risposta dell'API Management v3
{
"kind": "analytics#entityUserLinks",
"totalResults": 1,
"startIndex": 1,
"itemsPerPage": 1000,
"items": [
{
"id": "XXXXXX:XXXXXX",
"kind": "analytics#entityUserLink",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX:XXXXXX",
"entity": {
"accountRef": {
"id": "XXXXXX",
"kind": "analytics#accountRef",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
"name": "This is a test account"
}
},
"userRef": {
"kind": "analytics#userRef",
"id": "XXXXXX",
"email": "XXXXXX"
},
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
],
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
]
}
Codice campione per chiamare l'API Admin utilizzando le librerie client:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
list_account_access_bindings(account_id)
def list_account_access_bindings(account_id: str, transport: str = None):
"""
Lists access bindings under the specified parent account.
Args:
account_id(str): The id of the account.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
results = client.list_access_bindings(parent=f"accounts/{account_id}")
print("Result:")
for access_binding in results:
print(access_binding)
print()
Aggiorna associazioni di accesso all'account
Il metodo accounts.accessBindings.patch dell'API Admin v1 aggiorna un'associazione di accesso di un account, in modo simile al metodo accountUserLinks.update dell'API di gestione v3.
Richiesta API Admin v1
PATCH https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/accessBindings/XXXXXXXX
{
"roles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
]
}
Risposta dell'API Admin v1
{
"name": "accounts/XXXXXX/accessBindings/XXXXXXXX",
"user": "USER-EMAIL",
"directRoles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
]
}
Richiesta API Management v3
PUT https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX%3A104236685715552897132?key=[YOUR_API_KEY]
{
"entity": {
"accountRef": {
"id": "XXXXXX"
}
},
"userRef": {
"email": "XXXXXX"
},
"permissions": {
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
Risposta dell'API Management v3
{
"id": "XXXXXX:104236685715552897132",
"kind": "analytics#entityUserLink",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX:104236685715552897132",
"entity": {
"accountRef": {
"id": "XXXXXX",
"kind": "analytics#accountRef",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
"name": "This is a test account"
}
},
"userRef": {
"kind": "analytics#userRef",
"id": "104236685715552897132",
"email": "XXXXXX"
},
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
],
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
Codice campione per chiamare l'API Admin v1 utilizzando le librerie client:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import AccessBinding
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics property ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
# TODO(developer): Replace this variable with your Google Analytics
# account access binding ID (e.g. "123456") before running the sample.
account_access_binding_id = "YOUR-ACCOUNT-ACCESS-BINDING-ID"
update_account_access_binding(account_id, account_access_binding_id)
def update_account_access_binding(
account_id: str, account_access_binding_id: str, transport: str = None
):
"""
Updates the account access binding.
Args:
account_id(str): The Google Analytics Account ID.
account_access_binding_id(str): Google Analytics account access binding ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
# This call updates the roles of the access binding. The access binding to
# update is specified in the `name` field of the `AccessBinding` instance.
access_binding = client.update_access_binding(
access_binding=AccessBinding(
name=f"accounts/{account_id}/accessBindings/{account_access_binding_id}",
roles=["predefinedRoles/collaborate"],
),
)
print("Result:")
print(access_binding)
Creare associazioni di accesso all'account
Il metodo accounts.accessBindings.create dell'API Admin v1 crea un'associazione di accesso in un account, simile al metodo accountUserLinks.insert dell'API di gestione v3.
Richiesta API Admin v1
POST https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/accessBindings
{
"roles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
],
"user": "USER-EMAIL"
}
Risposta dell'API Admin v1
{
"name": "accounts/XXXXXX/accessBindings/XXXXXXXX",
"user": "USER-EMAIL",
"roles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
]
}
Richiesta API Management v3
POST https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks?key=[YOUR_API_KEY]
{
"entity": {
"accountRef": {
"id": "XXXXXX"
}
},
"userRef": {
"email": "XXXXXX"
},
"permissions": {
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
Risposta dell'API Management v3
{
"id": "XXXXXX:114236685715552897132",
"kind": "analytics#entityUserLink",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX:114236685715552897132",
"entity": {
"accountRef": {
"id": "XXXXXX",
"kind": "analytics#accountRef",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
"name": "This is a test account"
}
},
"userRef": {
"kind": "analytics#userRef",
"id": "114236685715552897132",
"email": "XXXXXX"
},
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
],
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
Codice campione per chiamare l'API Admin v1 utilizzando le librerie client:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import (
AccessBinding,
CreateAccessBindingRequest,
)
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics account ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
# TODO(developer): Replace this variable with an email address of the user to
# link. This user will be given access to your account after running the
# sample.
email_address = "TEST-EMAIL-ADDRESS"
create_account_access_binding(account_id, email_address)
def create_account_access_binding(
account_id: str, email_address: str, transport: str = None
):
"""
Creates a access binding for the account.
Args:
account_id(str): The Google Analytics Account ID.
email_address(str): Email address of the access binding user.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
access_binding = client.create_access_binding(
CreateAccessBindingRequest(
parent=f"accounts/{account_id}",
access_binding=AccessBinding(
user=email_address, roles=["predefinedRoles/read"]
),
)
)
print("Result:")
print(access_binding)
Batch
L'API Admin v1 non supporta il raggruppamento di più chiamate API di Google Analytics utilizzando il tipo di contenuto multiparte/misto, a differenza dell'API di gestione v3.
Il raggruppamento in batch è invece supportato esplicitamente a livello di API. I seguenti metodi dell'API Admin v1 supportano la funzionalità di raggruppamento in batch:
Codice campione per chiamare l'API Admin v1 utilizzando le librerie client:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import (
AccessBinding,
BatchCreateAccessBindingsRequest,
CreateAccessBindingRequest,
)
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics account ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
# TODO(developer): Replace this variable with an email address of the user to
# link. This user will be given access to your account after running the
# sample.
email_address = "TEST-EMAIL-ADDRESS"
batch_create_account_access_binding(account_id, email_address)
def batch_create_account_access_binding(
account_id: str, email_address: str, transport: str = None
):
"""
Creates a access binding for the account using a batch call.
Args:
account_id(str): The Google Analytics Account ID.
email_address(str): Email address of the access binding user.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
response = client.batch_create_access_bindings(
BatchCreateAccessBindingsRequest(
parent=f"accounts/{account_id}",
requests=[
CreateAccessBindingRequest(
access_binding=AccessBinding(
user=email_address,
roles=["predefinedRoles/read"],
)
)
],
)
)
print("Result:")
for access_binding in response.access_bindings:
print(access_binding)
print()
Modifiche alla quota API
L'API Admin v1 introduce quote meno restrittive rispetto all'API di gestione v3.
- Per impostazione predefinita, il numero di richieste all'API Admin v1 è limitato a 600 richieste al minuto per un progetto Google Cloud.
- Attualmente non è prevista una quota limite giornaliera per il numero di chiamate all'API Admin v1 per progetto Google Cloud. Tieni presente che il numero massimo teorico di richieste al giorno è ancora limitato dalla quota di richieste al minuto.
- È stato rimosso un limite separato al numero di operazioni di scrittura al giorno.