Utiliser le conseiller Analytics pour interroger et analyser vos données

La méthode chat de l'API Data fournit un accès programmatique à Analytics Advisor, un assistant analytique optimisé par l'IA qui vous aide à interroger, analyser et diagnostiquer vos données Google Analytics en langage naturel.

Alors que le Conseiller Analytics est disponible de manière interactive dans l'interface utilisateur Google Analytics, l'API chat permet aux développeurs, aux agents d'IA autonomes et aux outils internes d'interagir avec le Conseiller Analytics de manière programmatique via HTTP.

Important : Ce produit utilise l'IA et peut afficher des informations inexactes. Votre activité de chat peut être utilisée pour améliorer le produit, et votre utilisation est soumise aux Conditions d'utilisation, au Règlement sur l'utilisation de l'IA et aux Règles de confidentialité de Google.

Présentation

La méthode chat permet à la fois de poser des questions ponctuelles sur les données en un seul tour et de mener des sessions de conversation multitours :

  1. Requêtes en un tour : posez des questions analytiques immédiates (par exemple, "Quels ont été nos principaux canaux de trafic la semaine dernière ?") et recevez des réponses en langage naturel ainsi que des tableaux de données structurées.
  2. Conversations multitours : transmettez un sessionId pour conserver l'historique des conversations et poser des questions de diagnostic complémentaires (par exemple, "Pourquoi le trafic généré par les résultats naturels a-t-il diminué au cours de cette période ?").
  3. Réponses de données structurées : en plus des récits textuels, les réponses contiennent des blocs table structurés avec des en-têtes de colonne et des lignes.
  4. Surveillance des quotas de chat : inspectez les quotas de jetons de chat restants par jour et par heure en définissant returnPropertyQuota sur true.

Authentification

Les appels à la méthode chat nécessitent une autorisation OAuth 2.0 avec le champ d'application suivant :

Avant de commencer

  1. Installez et initialisez gcloud CLI.

  2. Pour générer les identifiants par défaut de l'application et accorder à votre compte les niveaux d'accès nécessaires, exécutez la commande suivante :

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

  3. Dans l'interface utilisateur Google Analytics, accordez à votre compte utilisateur l'accès à une propriété Google Analytics.

  4. Configurez vos variables d'environnement en saisissant les informations suivantes. Remplacez PROJECT_ID par l'ID de votre projet et PROPERTY_ID par l'ID de votre propriété Google Analytics. 

      export PROJECT_ID=PROJECT_ID
  export PROPERTY_ID=PROPERTY_ID

Exemple 1 : Requête à un seul tour avec suivi du quota

Pour démarrer une nouvelle conversation, créez un ChatRequest contenant votre userQuery. Définissez returnPropertyQuota sur true pour inspecter votre solde de jetons restant.

Scénario : Revenus et taux de conversion par appareil

Vous souhaitez comparer les revenus et le taux de conversion des sessions sur différents appareils au cours des 30 derniers jours.

Requête 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
  }'

Réponse HTTP

La réponse contient les éléments suivants :

  • Un sessionId nouvellement attribué que vous pouvez utiliser pour les tours de suivi.
  • Liste blocks contenant à la fois un résumé en langage naturel (text) et un tableau structuré (table). Les blocs de texte peuvent contenir une mise en forme Markdown, comme du texte en gras, des titres et des liens.
  • Informations propertyQuota sur l'établissement.
{
  "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
    }
  }
}

Exemple 2 : Diagnostic conversationnel multitour

Pour poser une question complémentaire tout en conservant le contexte, incluez le sessionId renvoyé par la réponse précédente dans votre requête.

Scénario : comparer avec la période précédente

Suite à la comparaison des appareils précédente, vous demandez à l'assistant de comparer les résultats avec la période précédente.

Requête 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."
  }'

Réponse HTTP

Le conseiller Analytics utilise la mémoire de session pour corréler les résultats avec la période précédente.

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

Structure de la réponse et blocs de données

L'objet ChatResponse renvoie des composants structurés dans le tableau blocks :

Type de bloc Champ Description
Texte narratif blocks[].text Explication lisible par l'humain et conclusions analytiques générales.
Table structurée blocks[].table Répartition des données tabulaires contenant headers (noms et types de données) et rows (valeurs des cellules).

Types de données des en-têtes de tableau

Les colonnes de blocks[].table.headers décrivent le type de données sémantiques :

  • string : valeurs de texte catégorielles (par exemple, "desktop", "/shop/apparel").
  • float : nombres à virgule flottante.

Gestion des quotas de chat

Les requêtes de l'assistant Analytics consomment des jetons de chat en fonction de la complexité de la requête. L'état actuel du quota est renvoyé dans propertyQuota lorsque returnPropertyQuota est défini sur true :

  • tokensPerDay : limite quotidienne de jetons et solde restant.
  • tokensPerHour : limite de débit de la fenêtre glissante horaire et solde restant.

Applications d'intégration suggérées

La méthode properties.chat permet de débloquer plusieurs architectures d'intégration entre les équipes et les outils :

Bots de chat et de collaboration pour les entreprises

Associez directement votre espace de travail de chat en équipe à Google Analytics.

  • Sessions avec fils de discussion : stockez sessionId par rapport à l'ID du fil de discussion pour permettre aux membres de l'équipe de poser des questions complémentaires de manière collaborative.
  • Affichage des cartes enrichies : met en forme les blocs de réponse table en widgets de cartes interactifs.

Agents d'IA autonomes et outils MCP (Model Context Protocol)

Équipez les orchestrateurs LLM (tels que Gemini, LangChain ou Claude) d'un outil d'analyse GA :

  • Au lieu de forcer un LLM à générer des requêtes runReport complexes, l'agent LLM peut appeler la méthode chat avec une intention en langage naturel.
  • L'agent reçoit des résumés très factuels et des tableaux structurés qu'il synthétise pour formuler des recommandations marketing multicanaux.

Briefings et alertes automatisés pour les dirigeants

Créez des services planifiés qui examinent de manière proactive les anomalies :

  • Un job Cron quotidien interroge : "Résume les principaux indicateurs de performances d'hier et identifie toute baisse anormale des conversions."
  • Si une anomalie est détectée, le script déclenche automatiquement une requête de suivi pour diagnostiquer les causes premières et publie un récapitulatif dans les tableaux de bord internes ou les systèmes CRM.