Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Contrôle des accès à l'API Conversational Analytics avec IAM

L'API Conversational Analytics utilise Identity and Access Management (IAM) pour le contrôle des accès, ce qui vous permet de partager des agents de données et de contrôler qui est autorisé à les créer, à les gérer et à interagir avec eux. Cette page décrit les rôles IAM prédéfinis que vous pouvez attribuer à des principaux (tels que des utilisateurs, des groupes et des comptes de service) pour accorder ces autorisations.

Avant de commencer

Pour obtenir les autorisations nécessaires à l'attribution de rôles IAM pour l'API Conversational Analytics, demandez à votre administrateur de vous attribuer le rôle IAM Administrateur de projet IAM (roles/resourcemanager.projectIamAdmin) sur le projet dans lequel l'API Conversational Analytics est activée. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Présentation des rôles IAM pour l'API Conversational Analytics

Les rôles IAM prédéfinis pour l'API Conversational Analytics offrent un contrôle précis sur les personnes autorisées à créer et à gérer des agents de données, ainsi qu'à interagir avec eux. Cette section explique comment partager des agents de données en attribuant des rôles IAM et décrit les rôles IAM requis pour d'autres tâches utilisateur courantes.

Vous pouvez attribuer des rôles au niveau du projet pour accorder des autorisations à tous les agents d'un projet. Pour contrôler l'accès à un agent spécifique, un propriétaire d'agent (un compte principal doté du rôle Propriétaire d'agent de données des analyses de données Gemini) peut modifier la stratégie IAM de cet agent par programmation.

Le schéma suivant montre comment un propriétaire d'agent peut gérer l'accès à un agent spécifique :

Un propriétaire d'agent attribue les rôles "Éditeur d'agent de données" et "Utilisateur d'agent de données" à d'autres utilisateurs.

Dans ce scénario, un analyste de données senior doté du rôle Créateur d'agent de données des analyses de données Gemini crée un agent. Lorsqu'un utilisateur crée un agent, il se voit automatiquement attribuer le rôle Propriétaire d'agent de données des analyses de données Gemini pour cet agent. En tant que propriétaire de l'agent, l'analyste de données senior gère l'accès à l'agent en définissant sa stratégie IAM et attribue les rôles suivants aux membres de l'équipe :

Éditeur d'agent de données des analyses de données Gemini : le propriétaire de l'agent attribue ce rôle aux analystes de données juniors. Ce rôle permet aux analystes juniors de modifier la configuration de l'agent et de discuter avec lui.
Utilisateur d'agent de données des analyses de données Gemini : le propriétaire de l'agent attribue ce rôle aux membres de l'équipe qui n'ont pas besoin de pouvoir modifier la configuration de l'agent. Ce rôle permet à ces membres de l'équipe de discuter avec l'agent.

Rôles requis pour les tâches utilisateur courantes

Pour vous aider à déterminer les rôles à attribuer, tenez compte des tâches utilisateur courantes suivantes :

Créer des agents de données: Attribuez le rôle Créateur d'agent des données des analyses de données Gemini aux utilisateurs chargés de créer des agents de données dans un projet.
Partager des agents: Attribuez le rôle Propriétaire d'agent de données des analyses de données Gemini aux utilisateurs qui doivent partager des agents avec d'autres comptes principaux en gérant les autorisations des agents.
Gérer les autorisations des agents: Attribuez le rôle Propriétaire d'agent de données des analyses de données Gemini aux utilisateurs qui doivent partager des agents avec d'autres utilisateurs en gérant les autorisations des agents, ou qui ont besoin d'avoir le plus haut niveau de contrôle sur un agent, y compris la possibilité de supprimer des agents. Lorsqu'un utilisateur crée un agent, le système lui attribue automatiquement ce rôle pour l'agent en question.
Modifier les configurations d'agent: Attribuez le rôle Éditeur d'agent des données des analyses de données Gemini aux utilisateurs qui modifient la configuration d'un agent, comme ses mappages de source de données ou de contexte. Ces utilisateurs ne sont pas autorisés à partager ni à supprimer l'agent.
Discuter avec les agents: Attribuez le rôle Utilisateur d'agent des données des analyses de données Gemini aux utilisateurs ou aux applications qui interagissent principalement avec les agents en posant des questions et en recevant des réponses.
Afficher les configurations d'agent: Attribuez le rôle Lecteur d'agent des données des analyses de données Gemini aux utilisateurs qui ont besoin d'un accès en lecture seule pour afficher les configurations d'agent.
Discuter en utilisant le contexte intégré: Attribuez le rôle Utilisateur sans état du chat des analyses de données Gemini aux applications ou aux utilisateurs qui interagissent avec l'API en mode sans état (l'utilisateur fournit alors tout le contexte de la conversation dans chaque requête).
Interroger des données en langage naturel: Attribuez le rôle Utilisateur de données de requête des analyses de données Gemini aux utilisateurs ou aux applications qui doivent utiliser le langage naturel pour interroger des données et créer des applications de données. Ce rôle ne s'applique qu'aux bases de données cloud, à savoir AlloyDB, GoogleSQL pour Spanner, Cloud SQL et Cloud SQL pour PostgreSQL.

Rôles prédéfinis pour l'API Conversational Analytics

Le tableau suivant décrit les rôles prédéfinis pour l'API Conversational Analytics. Si les rôles prédéfinis ne fournissent pas l'ensemble d'autorisations souhaité, vous pouvez également créer vos propres rôles personnalisés.

Rôle	Autorisations
Créateur d'agent de données des analyses de données Gemini (`roles/geminidataanalytics.dataAgentCreator`) Permet à un compte principal de créer des ressources d'agent de données dans un projet spécifique. Lorsqu'un compte principal crée un agent, le système lui attribue automatiquement le rôle `dataAgentOwner` pour cet agent spécifique.	`geminidataanalytics.dataAgents.create`
Propriétaire d'agent de données des analyses de données Gemini (`roles/geminidataanalytics.dataAgentOwner`) Permet à un compte principal de contrôler entièrement le cycle de vie de tout agent du projet, y compris de partager et de supprimer des agents. Ce rôle est destiné aux comptes principaux approuvés qui peuvent gérer le partage d'agents. Ce rôle hérite de toutes les autorisations des rôles `dataAgentEditor`, `dataAgentUser` et `dataAgentViewer`. Un compte principal doté de ce rôle peut partager et supprimer des agents.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update` `geminidataanalytics.dataAgents.delete` `geminidataanalytics.dataAgents.getIamPolicy` `geminidataanalytics.dataAgents.setIamPolicy`
Éditeur d'agent de données des analyses de données Gemini (`roles/geminidataanalytics.dataAgentEditor`) Permet de modifier et de gérer les configurations d'agent existantes. Ce rôle hérite de toutes les autorisations des rôles `dataAgentUser` et `dataAgentViewer`.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update`
Utilisateur d'agent de données des analyses de données Gemini (`roles/geminidataanalytics.dataAgentUser`) Permet à un compte principal de discuter avec les agents spécifiques auxquels il a accès. Ce rôle hérite de toutes les autorisations du rôle `dataAgentViewer`.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat`
Lecteur d'agent de données des analyses de données Gemini (`roles/geminidataanalytics.dataAgentViewer`) Accorde à un compte principal un accès en lecture seule pour lister et afficher les configurations d'agent. Ce rôle ne permet pas de discuter avec des agents.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get`
Utilisateur sans état du chat des analyses de données Gemini (`roles/geminidataanalytics.dataAgentStatelessUser`) Permet à un compte principal d'appeler l'API Chat en mode sans état. Avec le chat sans état, le contexte est fourni directement dans la requête au lieu d'être enregistré de manière explicite dans la configuration d'agent lors de la création.	`geminidataanalytics.chat`
Utilisateur de données de requête des analyses de données Gemini (`roles/geminidataanalytics.queryDataUser`) Permet à un compte principal d'utiliser le langage naturel pour interroger des données et créer des applications de données à l'aide de l'API QueryData. Ce rôle ne s'applique qu'aux bases de données cloud, à savoir AlloyDB, GoogleSQL pour Spanner, Cloud SQL et Cloud SQL pour PostgreSQL.	`geminidataanalytics.locations.queryData`

Accorder des rôles IAM

Vous pouvez attribuer des rôles IAM pour l'API Conversational Analytics au niveau du projet ou pour un agent spécifique. L'attribution d'un rôle au niveau du projet donne à un compte principal les mêmes autorisations pour tous les agents de ce projet, tandis que la définition de la stratégie sur un agent spécifique offre un contrôle plus précis.

Les rôles IAM prédéfinis pour l'API Conversational Analytics font partie du service geminidataanalytics. Les noms techniques de ces rôles respectent le format roles/geminidataanalytics.ROLE_NAME. Dans la Google Cloud console, vous pouvez trouver ces rôles en filtrant sur le service Analyses de données Gemini.

Attribuer des rôles à tous les agents d'un projet

Utilisez la Google Cloud console ou Google Cloud CLI pour attribuer des rôles à l'ensemble d'un projet.

Console

Pour attribuer un rôle à un compte principal dans la console Google Cloud , procédez comme suit :

Dans la console Google Cloud , accédez à la page IAM.

Accéder à IAM
Cliquez sur Accorder l'accès.
Dans le champ Nouveaux comptes principaux, saisissez l'adresse e-mail de l'utilisateur, du groupe ou du compte de service.
Dans le menu Sélectionner un rôle, filtrez sur Analyses de données Gemini afin d'afficher les rôles IAM disponibles pour l'API Conversational Analytics.
Sélectionnez le rôle approprié, par exemple Utilisateur d'agent de données des analyses de données Gemini.
Cliquez sur Enregistrer.

gcloud

Pour attribuer des rôles à l'aide de la gcloud CLI, procédez comme suit :

Connectez-vous à Google Cloud et définissez votre projet :

gcloud auth login
gcloud config set project project_id

Vous pouvez également exécuter la commande gcloud iam list-grantable-roles pour lister les rôles IAM que vous pouvez attribuer à votre projet pour l'API Conversational Analytics :

gcloud iam list-grantable-roles //cloudresourcemanager.googleapis.com/projects/project_id --filter "geminidataanalytics"

Attribuez un rôle à un compte principal à l'aide de la commande gcloud projects add-iam-policy-binding.

Pour attribuer un rôle à un utilisateur, exécutez la commande suivante :

gcloud projects add-iam-policy-binding project_id --member='user:user_email' --role='roles/gda_grantable_role'

Pour attribuer un rôle à un compte de service, exécutez la commande suivante :

gcloud projects add-iam-policy-binding project_id --member='serviceAccount:service_account_email' --role='roles/gda_grantable_role'

Dans les instructions précédentes, remplacez les exemples de valeurs comme suit :

project_id : ID de votre projet Google Cloud .
user_email : adresse e-mail de l'utilisateur, par exemple test-user@example.com.
service_account_email : adresse e-mail du compte de service, par exemple test-sa@example.com.
gda_grantable_role : rôle IAM pour l'API Conversational Analytics que vous souhaitez attribuer, tel que geminidataanalytics.dataAgentCreator.

Attribuer des rôles à un agent spécifique

Pour gérer l'accès à un agent de données spécifique, vous devez modifier sa stratégie d'autorisation par programmation. Ce processus suit un modèle standard de lecture-modification-écriture dans lequel vous lisez la stratégie actuelle, la modifiez, puis la réécrivez.

Les exemples suivants montrent les corps de requête pour obtenir et définir des stratégies IAM pour un agent de données.

HTTP

Pour obtenir la stratégie existante d'un agent, envoyez une requête POST au point de terminaison :getIamPolicy avec le corps de requête suivant :

{
  "resource": "projects/project_id/locations/global/dataAgents/agent_id"
}

Pour définir la stratégie d'un agent, envoyez une requête POST au point de terminaison :setIamPolicy avec le corps de requête suivant :

{
  "policy": {
    "bindings": [
      {
        "role": "role",
        "members": [
          "user:email"
        ]
      }
    ]
  }
}

Remplacez les éléments suivants :

project_id: ID de votre Google Cloud projet.
agent_id : ID de l'agent de données pour lequel obtenir ou définir la stratégie.
role : rôle à accorder, tel que roles/geminidataanalytics.dataAgentUser.
email : adresse e-mail de l'utilisateur, par exemple test-user@example.com.

Pour obtenir des exemples complets, consultez Obtenir la stratégie IAM d'un agent de données et Définir la stratégie IAM pour un agent de données.

SDK Python

Pour obtenir la stratégie existante d'un agent, utilisez la méthode get_iam_policy, comme dans l'exemple de requête suivant :

resource = "projects/project_id/locations/global/dataAgents/agent_id"
request = iam_policy_pb2.GetIamPolicyRequest(
            resource=resource,
        )

Pour définir la stratégie d'un agent, utilisez la méthode set_iam_policy, comme dans l'exemple de requête suivant :

resource = "projects/project_id/locations/global/dataAgents/agent_id"
policy = policy_pb2.Policy(
    bindings=[
        policy_pb2.Binding(
            role="role",
            members=["user:email"]
        )
    ]
)
request = iam_policy_pb2.SetIamPolicyRequest(
    resource=resource,
    policy=policy
)