Cette page a été traduite par l'API Cloud Translation.

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

L'API Conversational Analytics utilise Identity and Access Management (IAM) pour contrôle des accès. Vous pouvez ainsi partager des agents de données et 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 aux comptes principaux (tels que des utilisateurs, des groupes et des comptes de service) pour leur 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 la page 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 permettent de contrôler précisément qui peut créer et gérer des agents de données, et 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 disposant du rôle Propriétaire d'agent des données Gemini Data Analytics) peut modifier la stratégie IAM de cet agent de manière programmatique.

Le diagramme 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 disposant du rôle Créateur d'agent des données des analyses de données Gemini crée un agent. Lorsqu'un utilisateur crée un agent, le rôle Propriétaire d'agent des données Gemini Data Analytics lui est automatiquement attribué 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 en accordant les rôles suivants aux membres de l'équipe :

Éditeur d'agent des 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 des 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 aux membres de l'équipe de discuter avec l'agent.

Rôles requis pour les tâches utilisateur courantes

Pour vous aider à choisir 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 des données des analyses de données Gemini aux utilisateurs qui ont besoin de 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 des données des analyses de données Gemini aux utilisateurs qui ont besoin de partager des agents avec d'autres utilisateurs en gérant les autorisations d'agent, 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).

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`

Attribuer 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. Si vous attribuez un rôle au niveau du projet, un compte principal bénéficie des mêmes autorisations pour tous les agents de ce projet. En revanche, si vous définissez la stratégie sur un agent spécifique, vous bénéficiez d'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 console Google Cloud , vous pouvez trouver ces rôles en filtrant sur le service d'analyses de données Gemini.

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

Utilisez la console Google Cloud 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@gmail.com.
service_account_email : adresse e-mail du compte de service, par exemple test-proj@example.domain.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 de manière programmatique. Ce processus suit un modèle de lecture-modification-écriture standard, 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 règle 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 règle pour 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 projet Google Cloud .
AGENT_ID : ID de l'agent de données pour lequel obtenir ou définir la stratégie.
ROLE : rôle à accorder, par exemple roles/geminidataanalytics.dataAgentUser.
EMAIL : adresse e-mail de l'utilisateur, par exemple test-user@gmail.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 règle 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 règle 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
)