Utiliser Ask Advisor dans Google Analytics de manière programmatique pour interroger et analyser vos données

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

Bien que Demander à l'assistant soit disponible de manière interactive dans l'interface utilisateur de Google Analytics , l'API chat permet aux développeurs, aux agents d'IA autonomes et aux outils internes d'interagir avec Demander à l'assistant de manière programmatique via HTTP.

Important : Ce produit est basé sur l'IA et peut afficher des informations inexactes. Votre activité de chat peut servir à 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 et d'avoir des sessions de conversation multitour :

  1. Requêtes à un seul 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 multitour : transmettez un sessionId pour conserver l'historique des conversations et poser des questions de diagnostic de suivi (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 l'autorisation suivante :

Avant de commencer

  1. Installez et initialisez la gcloud CLI.

  2. Pour générer des identifiants par défaut de l'application et accorder à votre compte les autorisations 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 de 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 des quotas

Pour démarrer une conversation, créez un ChatRequest contenant votre userQuery. Définissez returnPropertyQuota sur true pour vérifier 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 suivants.
  • Une liste de 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.
  • Les détails propertyQuota de la propriété.
{
  "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 de suivi tout en conservant le contexte, incluez le sessionId renvoyé par la réponse précédente dans votre requête.

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

Suite à la comparaison précédente des appareils, 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

Demander à l'assistant utilise la mémoire de la 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'ChatResponse objet renvoie des composants structurés dans le blocks tableau :

Type de bloc Champ Description
Texte narratif blocks[].text Explication lisible par l'humain et conclusions analytiques de haut niveau.
Tableau structuré 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 d'en-tête de tableau

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

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

Gestion des quotas de chat

Les requêtes Demander à l'assistant 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 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 débloque plusieurs architectures d'intégration entre les équipes et les outils :

Bots de chat et de collaboration pour les entreprises

Connectez directement votre espace de travail de chat d'équipe à Google Analytics.

  • Sessions groupées par fil de discussion : stockez le sessionId par rapport à l’ID du fil de discussion pour permettre aux membres de l’équipe de poser des questions de suivi de manière collaborative.
  • Rendu de cartes enrichies : mettez en forme les blocs de réponse table en widgets de carte 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 :

  • Plutôt que de forcer un LLM à générer des runReport requêtes complexes, l'agent LLM peut appeler la chat méthode avec une intention en langage naturel.
  • L'agent reçoit des résumés très factuels et des tableaux structurés à synthétiser en recommandations marketing multicanal.

Briefings et alertes automatisés pour les dirigeants

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

  • Une tâche cron quotidienne interroge : "Résumez les métriques clés de performance d'hier et identifiez 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 profondes et publie un résumé dans les tableaux de bord internes ou les systèmes CRM.

Étapes suivantes