Usar o Consultor do Analytics para consultar e analisar seus dados

O método chat da API Data oferece acesso programático ao Analytics Advisor — 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 Consultor do Analytics esteja disponível de forma interativa na interface do usuário do Google Analytics, a API chat permite que desenvolvedores, agentes autônomos de IA e ferramentas internas interajam com o Consultor do Analytics 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 únicas sobre dados ad hoc e sessões de conversa 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 com tabelas de dados estruturados.
  2. Conversas multiturno:transmita um sessionId para manter o histórico de conversas e fazer perguntas de acompanhamento de diagnóstico (por exemplo, "Por que o tráfego orgânico diminuiu nesse período?").
  3. Respostas com dados estruturados:além de narrativas de texto, as respostas contêm blocos estruturados table com cabeçalhos de coluna e linhas.
  4. Monitoramento da cota do Chat:inspecione as cotas restantes de tokens de chat por dia e por hora definindo returnPropertyQuota como true.

Autenticação

As chamadas ao método chat 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 Application Default Credentials 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 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 acompanhamento de cota

Para iniciar uma conversa, crie um ChatRequest que contenha seu userQuery. Defina returnPropertyQuota como true para inspecionar seu 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 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 novo sessionId que você pode usar em conversas 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, cabeçalhos 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 complementar e preservar o contexto, inclua o sessionId retornado pela resposta anterior na sua solicitação.

Cenário: comparar com o período anterior

Seguindo a comparação de dispositivos anterior, peça 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 Analytics Advisor usa a memória da sessão para correlacionar 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
Texto narrativo blocks[].text Explicação legível e principais conclusões analíticas.
Tabela estruturada blocks[].table Detalhamento de dados tabulares que contêm headers (nomes e tipos de dados) e rows (valores das células).

Tipos de dados de 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 Consultor de análises 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 de janela deslizante por hora e saldo restante.

Sugestões de aplicativos de integração

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

Bots de chat e colaboração para empresas

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

  • Sessões em conversas:armazene o sessionId em relação ao ID da conversa para permitir que os membros da equipe façam perguntas de acompanhamento de forma colaborativa.
  • Renderização de Rich Card:formata blocos de resposta table em widgets de card interativos.

Agentes autônomos de IA 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 consultas complexas de runReport, o agente de LLM pode invocar o método chat com uma 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 as anomalias:

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