De forma programática usando o Ask Advisor no Google Analytics para consultar e analisar seus dados

O método chat da API Data oferece acesso programático ao Ask Advisor no Google Analytics, um assistente analítico com tecnologia de IA que ajuda você a consultar, analisar e diagnosticar seus dados do Google Analytics usando linguagem natural.

Embora o Ask Advisor esteja disponível de forma interativa na interface do usuário do Google Analytics, a API chat permite que desenvolvedores, agentes de IA autônomos e ferramentas internas interajam com o Ask Advisor de forma programática por HTTP.

Importante: este produto usa IA e pode apresentar informações imprecisas. Sua atividade no chat pode ser usada para melhorar o produto e está sujeita aos Termos, à Política de Uso de IA e à Política de Privacidade do Google.

Visão geral

O método chat permite perguntas de dados ad hoc de turno único e sessões de conversa multiturno:

  1. Consultas de turno único: faça perguntas analíticas imediatas (como "Quais foram nossos principais canais de tráfego na semana passada?") e receba respostas em linguagem natural com tabelas de dados estruturados.
  2. Conversas multiturno: transmita um sessionId para manter o histórico de conversas e fazer perguntas de diagnóstico complementares (como "Por que o tráfego orgânico diminuiu nesse período?").
  3. Respostas de dados estruturados: além de narrativas de texto, as respostas contêm blocos estruturados do table com cabeçalhos de coluna e linhas.
  4. Monitoramento de cotas do Chat: inspecione as cotas restantes de tokens de chat por dia e por hora definindo returnPropertyQuota como true.

Autenticação

As chamadas para o método chat exigem autorização do OAuth 2.0 com o seguinte escopo:

Antes de começar

  1. Instale e inicialize a gcloud CLI.

  2. Para gerar o Application Default Credentials e dar à sua conta os escopos necessários, execute o seguinte:

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

  3. Na interface do Google Analytics, conceda à sua conta de usuário acesso a uma propriedade do Google Analytics.

  4. Insira o comando abaixo para configurar as variáveis de ambiente. Substitua PROJECT_ID pelo ID do seu projeto do e PROPERTY_ID pelo ID da sua propriedade do Google Analytics. 

      export PROJECT_ID=PROJECT_ID
  export PROPERTY_ID=PROPERTY_ID

Exemplo 1: consulta de turno único com rastreamento de cota

Para iniciar uma nova conversa, crie um ChatRequest que contenha seu userQuery. Defina returnPropertyQuota como true para inspecionar o saldo restante de tokens.

Cenário: receita e taxa de conversão por dispositivo

Você quer comparar a receita e a taxa de conversão em sessões em vários dispositivos nos últimos 30 dias.

Solicitação 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
  }'

Resposta HTTP

A resposta contém:

  • Um sessionId recém-atribuído que pode ser usado para as próximas interações.
  • Uma lista de blocks que contém um resumo em linguagem natural (text) e uma tabela estruturada (table). Os blocos de texto podem conter formatação Markdown, como texto em negrito, títulos e links.
  • Os detalhes de propertyQuota da propriedade.
{
  "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
    }
  }
}

Exemplo 2: diagnóstico de conversação multiturno

Para fazer uma pergunta complementar sem perder o contexto, inclua o sessionId retornado pela resposta anterior na sua solicitação.

Cenário: comparar com o período anterior

continuidade à comparação de dispositivos anterior, você pede ao Advisor para comparar os resultados com o período anterior.

Solicitação 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."
  }'

Resposta HTTP

O Ask Advisor usa a memória da sessão para correlacionar os resultados com o período anterior.

{
  "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%"
              }
            ]
          }
      }
    }
  ]
}

Estrutura de resposta e blocos de dados

O objeto ChatResponse retorna componentes estruturados na matriz blocks:

Tipo de bloqueio Campo Descrição
Narrative Text blocks[].text Explicação legível por humanos e conclusões analíticas de alto nível.
Tabela estruturada blocks[].table Detalhamento de dados tabulares contendo headers (nomes e tipos de dados) e rows (valores de células).

Tipos de dados do cabeçalho da tabela

As colunas em blocks[].table.headers descrevem o tipo de dados semânticos:

  • string: valores de texto categóricos (por exemplo, "desktop", "/shop/apparel").
  • float: números de ponto flutuante numéricos.

Gerenciamento de cotas do Chat

As solicitações do Ask Advisor consomem tokens de chat com base na complexidade da consulta. O estado atual da cota é retornado em propertyQuota quando returnPropertyQuota é true:

  • tokensPerDay: limite diário de tokens e saldo restante.
  • tokensPerHour: limite de taxa da janela deslizante por hora e saldo restante.

Aplicativos de integração sugeridos

O método properties.chat desbloqueia várias arquiteturas de integração entre equipes e ferramentas:

Bots de chat e colaboração corporativos

Conecte seu espaço de trabalho de chat em equipe diretamente ao Google Analytics.

  • Sessões em conversas: armazene o sessionId no ID da conversa para que os membros da equipe possam fazer perguntas complementares de forma colaborativa.
  • Renderização de Rich Card: formate os blocos de resposta table em widgets de card interativos.

Agentes de IA autônomos e ferramentas do Protocolo de Contexto de Modelo (MCP)

Equipe os orquestradores de LLM (como Gemini, LangChain ou Claude) com uma ferramenta de análise do GA:

  • Em vez de forçar um LLM a gerar consultas runReport complexas, o agente de LLM pode invocar o método chat com intenção de linguagem natural.
  • O agente recebe resumos de alta precisão e tabelas estruturadas para sintetizar em recomendações de marketing multicanal.

Resumos executivos e alertas automatizados

Crie serviços programados que investiguem anomalias de forma proativa:

  • Um cron job diário consulta: "Resuma as principais métricas de performance de ontem e identifique qualquer queda anormal nas conversões".
  • Se uma anomalia for encontrada, o script aciona automaticamente uma consulta de acompanhamento para diagnosticar as causas raiz e publica um resumo em painéis internos ou sistemas de CRM.

Próximas etapas