Questions fréquentes sur l'API Conversational Analytics

L'API Conversational Analytics peut-elle modifier ou supprimer mes données ?

L'API Conversational Analytics est conçue avec des mesures de protection pour empêcher la modification ou la suppression de vos données.

Voici comment la sécurité des données est gérée pour différentes sources de données :

  • BigQuery : l'API bloque les instructions LDD (langage de définition de données) et LMD (langage de manipulation de données). Plus précisément, le système effectue un test sur le code SQL généré et n'autorise que les requêtes de type SELECT.
  • Looker : l'API interagit avec Looker à l'aide de méthodes comme run_inline_query, qui sont limitées aux opérations de lecture telles que les sélections, les filtres et les limites. Ces méthodes ne sont compatibles ni avec les opérations LDD, ni avec les opérations LMD, et elles n'incluent pas les opérations de suppression.
  • Looker Studio (pour les fichiers CSV et les feuilles de calcul Google Sheets) : Looker Studio utilise un format structuré pour définir et extraire les données destinées aux visualisations et aux rapports. Toutes les requêtes exécutées avec cette méthode sont en lecture seule et n'acceptent pas les mutations de données.

L'API Conversational Analytics est conçue pour être en lecture seule sur ces sources de données.

Comment gérer les erreurs d'authentification et d'autorisation ?

Voici quelques erreurs d'authentification et d'autorisation courantes que vous pouvez rencontrer lorsque vous utilisez l'API Conversational Analytics :

  1. Erreur : PERMISSION_DENIED ou 403 Write access to project ... was denied

    • Cause probable : ce message indique souvent des problèmes liés aux rôles IAM Google Cloud . L'utilisateur ou le compte de service qui tente d'utiliser l'API ne dispose pas des autorisations nécessaires sur le projet Google Cloud .
    • Dépannage :
      • Le propriétaire du projet Google Cloud doit s'assurer que les rôles IAM appropriés sont attribués à l'utilisateur ou au compte de service dans le projet Google Cloud . Des rôles tels que Project Editor peuvent être nécessaires pour certaines opérations, comme l'activation de l'API ou le test de ses fonctions.
      • Si vous rencontrez une erreur 403 telle que Write access to project 'us-gcp-project-name' was denied lorsque vous changez de région, vérifiez la configuration IAM de votre projet.

  2. Erreur : 500 Internal Server Error lorsqu'un utilisateur Looker doté du rôle Utilisateur tente de discuter avec un agent de données.

Quelles sont les exigences de Looker concernant l'utilisation de l'API Conversational Analytics ?

Pour utiliser l'API Conversational Analytics, vous devez disposer des autorisations appropriées dans Google Cloud IAM et dans Looker, en fonction de la source de données et des actions que vous souhaitez effectuer :

  1. Rôles IAMGoogle Cloud  :

    • Vous devez disposer de rôles IAM suffisants sur votre projet Google Cloud pour interagir avec l'API geminidataanalytics.googleapis.com. Des rôles IAM mal configurés entraînent souvent des erreurs PERMISSION_DENIED.
    • Les rôles spécifiques requis peuvent dépendre des actions, mais des rôles généraux tels que Éditeur de projet peuvent être nécessaires pour certaines opérations.

  2. Autorisations et rôles Looker :

    • Autorisations au niveau du modèle : pour utiliser Conversational Analytics et l'API Conversational Analytics, un utilisateur Looker doit disposer d'un rôle contenant l'autorisation gemini_in_looker pour les modèles avec lesquels il interagit.

Pour en savoir plus sur les autorisations et les rôles requis pour utiliser l'API Conversational Analytics, consultez la page de documentation Attribuer des rôles IAM et des autorisations pour l'API Conversational Analytics.

De plus, votre instance Looker doit répondre à des exigences spécifiques :

Pour utiliser l'API Conversational Analytics avec Looker Studio Pro, votre abonnement Pro doit se trouver en dehors d'un périmètre VPC-SC.

Comment migrer de l'API Data QnA vers l'API Conversational Analytics ?

Si vous avez utilisé l'ancienne version expérimentale de l'API Data QnA (dataqna.googleapis.com), consultez le guide de migration pour savoir comment migrer vers le nouveau point de terminaison officiel de l'API Conversational Analytics (geminidataanalytics.googleapis.com).

Quelle est la différence entre le nom et l'ID d'un agent de données ?

L'ID de l'agent de données, défini comme la valeur de data_agent_id, est l'identifiant unique de l'agent de données. Le nom de l'agent de données, data_agent.name, est dérivé automatiquement de data_agent_id en tant que nom complet (FQN), sous la forme projects/<project>/locations/<location>/dataAgents/<data_agent_id>.

Lorsque vous créez un agent de données, toute valeur que vous avez pu saisir pour data_agent.name est ignorée. Lorsque vous effectuez des opérations get, update ou delete, le data_agent.name complet est traité comme l'identifiant unique de l'agent de données.

Lorsque vous utilisez l'API Conversational Analytics pour créer des agents de données, les scénarios suivants s'appliquent :

  • Si vous ne définissez pas data_agent_id, un ID unique est généré automatiquement.
  • Si vous définissez data_agent_id sur TestID, par exemple, toute valeur que vous avez pu saisir pour data_agent.name est remplacée par projects/<project>/locations/<location>/dataAgents/TestID.
  • Si vous définissez data_agent_id avec un FQN, vous recevez une erreur "Nom incorrect".

Quelles sont les capacités de mémoire de l'agent de données de l'API Conversational Analytics ?

  • Au cours d'une même session : l'API Conversational Analytics est compatible avec les conversations multitours, ce qui signifie qu'elle peut faire référence à des parties antérieures de la conversation actuelle.
  • Sur plusieurs sessions : l'API Conversational Analytics inclut des fonctionnalités pour gérer l'historique des conversations, ce qui permet aux utilisateurs de discuter sur plusieurs sessions. Elle accepte également les agents avec état et les conversations multitours gérées par Google.
  • Mémoire à long terme : les agents de données de l'API Conversational Analytics ne sont pas compatibles avec les fonctionnalités de mémoire à long terme explicites.

Un agent de données de l'API Conversational Analytics me donnera-t-il la même réponse chaque fois que je poserai la même question ?

  • Les réponses en langage naturel de l'agent de données de l'API Conversational Analytics ne sont pas déterministes. La réponse en langage naturel fournie par l'agent peut donc varier, même pour une question formulée de manière identique.
  • Réponses aux requêtes de données : toutefois, pour une question spécifique de recherche de données, la requête sous-jacente générée (requête SQL ou Looker) doit être déterministe. Les données récupérées devraient être les mêmes, en supposant que les données sous-jacentes n'ont pas changé.

Comment améliorer la justesse des réponses d'un agent de données de l'API Conversational Analytics ?

Pour améliorer la justesse des réponses des agents de données, vous pouvez leur fournir des informations contextuelles pertinentes. Vous pouvez ajouter du contexte de différentes manières :

  • Dans la couche sémantique de Looker, vous pouvez fournir du contexte dans les définitions LookML. Pour en savoir plus et obtenir des exemples, consultez la page de documentation Guider le comportement de l'agent avec un contexte créé pour les sources de données Looker.
  • Lorsque vous créez un agent de données, vous pouvez fournir des instructions système. Il s'agit de consignes définies par l'utilisateur qui peuvent façonner le comportement d'un agent de données. Ces consignes incluent la logique spécifique à l'entreprise, le format de réponse ou la présentation des données. Vous pouvez également fournir des "requêtes de référence", qui sont des exemples de questions en langage naturel associées à leurs requêtes SQL ou Looker correctes. Pour en savoir plus sur les instructions système, consultez la page de documentation Guider le comportement de l'agent avec un contexte créé.

Puis-je intégrer l'API Conversational Analytics à des applications tierces ?

L'intégration de l'API Conversational Analytics à des applications tierces permet aux utilisateurs d'interagir avec leurs données directement dans les outils qu'ils utilisent au quotidien.

Toute application tierce qui interagit avec les points de terminaison de l'API geminidataanalytics.googleapis.com doit pouvoir envoyer des messages utilisateur de l'application à l'agent et afficher les réponses.

Pour créer une intégration, consultez le dépôt de guides de démarrage rapide Conversational Analytics pour obtenir des exemples ou des bibliothèques. Vous pouvez également consulter les forums Google Developers pour rechercher des exemples d'autres utilisateurs.

Combien coûte l'API Conversational Analytics ?

L'API Conversational Analytics est en phase preview. Google ne facture pas les produits en preview. Nous vous informerons à l'avance de tout changement de prix.

Quelles sources de données sont compatibles avec l'API Conversational Analytics ?

L'API Conversational Analytics est compatible avec les sources de données suivantes :

  • BigQuery
  • Explorations Looker
  • Looker Studio

Vous pouvez également vous connecter à des sources telles que SAP et Salesforce par le biais de BigQuery, et à des fichiers CSV et des feuilles de calcul Google Sheets par le biais de Looker Studio.

Quelles sont les limites connues de l'API Conversational Analytics ?

Pour en savoir plus sur les limites connues de l'API Conversational Analytics, consultez la page de documentation Limites connues de l'API Conversational Analytics.

Quels sont les quotas à connaître pour les projets Google Cloud  ?

Aucune restriction n'est appliquée concernant l'emplacement ou la sélection du projet Google Cloud . Vous pouvez créer des agents de données pour interroger les sources de données compatibles appartenant à n'importe quel projet ou n'importe quelle région.

L'API Conversational Analytics est-elle compatible avec la régionalisation des données ?

Étant donné que l'API Conversational Analytics n'est pas encore compatible avec la résidence des données (DRZ) ni avec les périmètres VPC Service Controls (VPC-SC), vous ne pouvez pas encore héberger d'agents dans des régions géographiques spécifiques. La régionalisation des données n'est pas compatible.

L'API Conversational Analytics prend-elle en charge d'autres langues que l'anglais ?

La seule langue officiellement acceptée pour l'API Conversational Analytics est l'anglais. Bien que les modèles Gemini sous-jacents soient compatibles avec de nombreuses langues et que certains utilisateurs aient signalé des résultats positifs avec des requêtes qui ne sont pas en anglais, l'API Conversational Analytics ne prend officiellement en charge que l'anglais.