Utilizzo programmatico di Ask Advisor in Google Analytics per eseguire query e analizzare i dati

Il metodo chat dell' API Data fornisce accesso programmatico a Ask Advisor in Google Analytics — un assistente analitico basato sull'AI che ti aiuta a eseguire query, analizzare e diagnosticare i dati di Google Analytics utilizzando il linguaggio naturale.

Sebbene Ask Advisor sia disponibile in modo interattivo all'interno dell'interfaccia utente di Google Analytics, l'API chat consente a sviluppatori, agenti AI autonomi e strumenti interni di interagire con Ask Advisor a livello di programmazione tramite HTTP.

Importante: questo prodotto utilizza l'AI e potrebbe mostrare informazioni imprecise. La tua attività di chat potrebbe essere usata per migliorare il prodotto e il suo utilizzo da parte tua è soggetto ai Termini, alle Norme sull'utilizzo dell'AI e alle Norme sulla privacy di Google.

Panoramica

Il metodo chat consente sia di porre domande sui dati ad hoc in un unico turno sia di avviare sessioni di conversazione multi-turno:

  1. Query in un unico turno: fai domande analitiche immediate (ad es. "Quali sono stati i nostri principali canali di traffico la scorsa settimana?") e ricevi risposte in linguaggio naturale insieme a tabelle di dati strutturati.
  2. Conversazioni multi-turno: passa un sessionId per mantenere la cronologia delle conversazioni e porre domande di follow-up diagnostiche (ad es. "Perché il traffico organico è diminuito in quel periodo?").
  3. Risposte con dati strutturati: oltre alle descrizioni testuali, le risposte contengono blocchi table strutturati con intestazioni di colonna e righe.
  4. Monitoraggio della quota di chat: controlla le quote di token di chat rimanenti per giorno e per ora impostando returnPropertyQuota su true.

Autenticazione

Le chiamate al metodo chat richiedono l'autorizzazione OAuth 2.0 con il seguente ambito:

Prima di iniziare

  1. Installa e inizializza gcloud CLI.

  2. Per generare le credenziali predefinite dell'applicazione e assegnare al tuo account gli ambiti necessari, esegui il comando seguente:

    gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"

  3. Nell'interfaccia utente di Google Analytics, concedi al tuo account utente l'accesso a una proprietà Google Analytics.

  4. Configura le variabili di ambiente inserendo quanto segue. Sostituisci PROJECT_ID con l'ID del tuo progetto e PROPERTY_ID con l'ID della tua proprietà Google Analytics. 

      export PROJECT_ID=PROJECT_ID
  export PROPERTY_ID=PROPERTY_ID

Esempio 1: query in un unico turno con monitoraggio della quota

Per avviare una nuova conversazione, crea un ChatRequest contenente la userQuery. Imposta returnPropertyQuota su true per controllare il saldo dei token rimanenti.

Scenario: entrate e tasso di conversione per dispositivo

Vuoi confrontare le entrate e il tasso di conversione delle sessioni tra i dispositivi negli ultimi 30 giorni.

Richiesta HTTP

curl -X POST \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "userQuery": "Compare our revenue and conversion rate across mobile vs desktop over the last 30 days.",
    "returnPropertyQuota": true
  }'

Risposta HTTP

La risposta contiene:

  • Un sessionId appena assegnato che puoi utilizzare per i turni successivi.
  • Un elenco di blocks contenenti sia un riepilogo in linguaggio naturale (text) sia una tabella strutturata (table). I blocchi di testo possono contenere la formattazione Markdown, ad esempio testo in grassetto, titoli e link.
  • I dettagli di propertyQuota della proprietà.
{
  "sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
  "blocks": [
    {
      "text": "Your report on revenue and conversion rates for mobile vs. desktop over the last 30 days (August 15 - September 13, 2026) is ready.\n\nHere is a summary of your revenue and conversion rate by device category:\n"
    },
   {
      "table": {
        "headers": [
          {
            "header": "Device Category",
            "dataType": "string"
          },
          {
            "header": "Total Revenue",
            "dataType": "string"
          },
          {
            "header": "User Conversion Rate",
            "dataType": "string"
          }
        ],
        "rows": [
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "$17,412.62"
              },
              {
                "value": "99.9%"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "$15,309.41"
              },
              {
                "value": "99.46%"
              }
            ]
          }
      }
    },
    {
      "text": "**Revenue and Conversion Rate Trends:**\n\nRevenue from desktop devices saw a peak on August 18th, while mobile revenue peaked on August 30th. Conversion rates remained high and relatively stable for both desktop and mobile throughout the period."
    },
    {
      "text": "This product uses AI and may display inaccurate info. Your chat activity may be used to improve the product and your use is subject to Google's [Terms](https://policies.google.com/terms), [AI Use Policy](https://policies.google.com/terms/generative-ai/use-policy), and [Privacy Policy](https://policies.google.com/privacy). [Learn more about Chat AI Privacy](https://support.google.com/helpguide/answer/14185196)."
    }
  ],
   "propertyQuota": {
    "tokensPerDay": {
      "consumed": 26849,
      "remaining": 3723151
    },
    "tokensPerHour": {
      "consumed": 26849,
      "remaining": 473151
    }
  }
}

Esempio 2: diagnostica conversazionale multi-turno

Per porre una domanda di follow-up mantenendo il contesto, includi il sessionId restituito dalla risposta precedente nella richiesta.

Scenario: confronta con il periodo precedente

Dopo il confronto precedente tra i dispositivi, chiedi al consulente di confrontare i risultati con il periodo precedente.

Richiesta HTTP

curl -X POST \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
    "userQuery": "Compare results with the same period in the previous mounth."
  }'

Risposta HTTP

Chiedi al consulente utilizza la memoria della sessione per correlare i risultati con il periodo precedente.

{
  "sessionId": "eb3284b2-49ce-4aed-b6d0-fdc15cb87b5f",
  "blocks": [
    {
      "text": "The following table provides a detailed comparison of total revenue and user conversion rate by device category for the two periods.\n"
    },
    {
      "table": {
        "headers": [
          {
            "header": "Device Category",
            "dataType": "string"
          },
          {
            "header": "Metric",
            "dataType": "string"
          },
          {
            "header": "Jul 16 - Aug 15, 2026",
            "dataType": "string"
          },
          {
            "header": "Aug 16 - Sep 14, 2026",
            "dataType": "string"
          }
        ],
        "rows": [
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "Total Revenue"
              },
              {
                "value": "$17,412.62"
              },
              {
                "value": "$19,565.46"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "User Conversion Rate"
              },
              {
                "value": "1.90%"
              },
              {
                "value": "1.95%"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "Total Revenue"
              },
              {
                "value": "$13,997.19"
              },
              {
                "value": "$15,309.41"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "User Conversion Rate"
              },
              {
                "value": "1.95%"
              },
              {
                "value": "1.99%"
              }
            ]
          }
      }
    }
  ]
}

Struttura della risposta e blocchi di dati

L'ChatResponse oggetto restituisce componenti strutturati nell'blocks array:

Tipo di blocco Campo Descrizione
Testo narrativo blocks[].text Spiegazione leggibile e risultati analitici di alto livello.
Tabella strutturata blocks[].table Suddivisione dei dati tabulari contenente headers (nomi e tipi di dati) e rows (valori delle celle).

Tipi di dati dell'intestazione della tabella

Le colonne in blocks[].table.headers descrivono il tipo di dati semantici:

  • string: valori di testo categorici (ad es. "desktop", "/shop/apparel").
  • float: numeri numerici in virgola mobile.

Gestione della quota di chat

Le richieste di Ask Advisor consumano token di chat in base alla complessità della query. Lo stato attuale della quota viene restituito in propertyQuota quando returnPropertyQuota è true:

  • tokensPerDay: limite di token giornaliero e saldo rimanente.
  • tokensPerHour: limite di frequenza della finestra scorrevole oraria e saldo rimanente.

Applicazioni di integrazione suggerite

Il metodo properties.chat sblocca diverse architetture di integrazione tra team e strumenti:

Bot di chat e collaborazione aziendale

Collega il tuo spazio di lavoro di chat del team direttamente a Google Analytics.

  • Sessioni in thread: archivia il sessionId rispetto all'ID del thread di chat per consentire ai membri del team di porre domande di follow-up in modo collaborativo.
  • Rendering di schede interattive: formatta i blocchi di risposta table in widget di schede interattive.

Strumenti Model Context Protocol (MCP) e agenti AI autonomi

Fornisci agli orchestratori LLM (come Gemini, LangChain o Claude) uno strumento di analisi di GA:

  • Anziché forzare un LLM a generare query runReport complesse, l'agente LLM può richiamare il metodo chat con l'intento in linguaggio naturale.
  • L'agente riceve riepiloghi di alta qualità e tabelle strutturate da sintetizzare in suggerimenti di marketing multicanale.

Briefing esecutivi e avvisi automatici

Crea servizi pianificati che analizzano in modo proattivo le anomalie:

  • Un cron job giornaliero esegue la query: "Riassumi le metriche sul rendimento chiave di ieri e identifica eventuali cali anomali delle conversioni."
  • Se viene rilevata un'anomalia, lo script attiva automaticamente una query di follow-up per diagnosticare le cause principali e pubblica un riepilogo sui dashboard interni o sui sistemi CRM.

Passaggi successivi