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 aprimorar 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 tanto perguntas de dados ad hoc de turno único e sessões de conversação multiturno:

  1. Consultas de turno único:faça perguntas analíticas imediatas (por exemplo, "Quais foram nossos principais canais de tráfego na semana passada?") e receba respostas em linguagem natural, além de tabelas de dados estruturados.
  2. Conversas multiturno: transmita um sessionId para manter o histórico da conversa e faça perguntas de acompanhamento de diagnóstico (por exemplo, "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 table estruturados com cabeçalhos de coluna e linhas.
  4. Monitoramento de cota de chat: inspecione as cotas de token de chat restantes por dia e por hora definindo returnPropertyQuota como true.

Autenticação

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

Antes de começar

  1. Instale e inicialize a CLI gcloud.

  2. Para gerar Credenciais Padrão do Aplicativo e conceder à 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 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 acompanhamento de cota

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

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 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 turnos de acompanhamento.
  • 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 conversacional multiturno

Para fazer uma pergunta de acompanhamento, mantendo o contexto, inclua o sessionId retornado pela resposta anterior na sua solicitação.

Cenário: comparação com o período anterior

Após a comparação de dispositivos anterior, você pede ao Consultor 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 ChatResponse objeto retorna componentes estruturados na blocks matriz:

Tipo de bloco Campo Descrição
Texto narrativo blocks[].text Explicação legível por humanos e principais conclusões analíticas.
Tabela estruturada blocks[].table Detalhes de dados tabulares que contêm headers (nomes e tipos de dados) e rows (valores de célula).

Tipos de dados de cabeçalho de tabela

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

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

Gerenciamento de cotas de 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 de tokens diário e saldo restante.
  • tokensPerHour: limite de taxa de janela deslizante por hora e saldo restante.

Aplicativos de integração sugeridos

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

Bots de chat e colaboração corporativos

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

  • Sessões encadeadas: armazene o sessionId no ID do encadeamento de chat para permitir que os membros da equipe façam perguntas de acompanhamento de forma colaborativa.
  • Renderização de Rich Card:formate table blocos de resposta em widgets de card interativos.

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

Equipe orquestradores de LLM (como Gemini, LangChain ou Claude) com uma ferramenta analítica do GA:

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

Resumos executivos e alertas automatizados

Crie serviços programados que investiguem proativamente anomalias:

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

Próximas etapas