Imposta le autorizzazioni per le funzioni AI generative che chiamano gli LLM di Gemini Enterprise Agent Platform

Console

1. Nella console Cloud de Confiance vai alla pagina IAM.

   Vai a IAM

2. Seleziona il progetto.

3. Per concedere i ruoli a un'entità, segui questi passaggi:

   1. Vai alla pagina IAM e amministrazione.

      Vai a IAM e amministrazione

   2. Fai clic su person_add Concedi l'accesso.

      Viene visualizzata la finestra di dialogo Aggiungi entità.

   3. Nel campo Nuove entità, inserisci l'identificatore dell'entità, ad esempio //iam.googleapis.com/locations/global/workforcePools/my-pool/subject/my-user@example.com o //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.

   4. Nella sezione Assegna i ruoli, fai clic sulla freccia menu a discesa in Seleziona un ruolo.

   5. Cerca il ruolo Agent Platform User e selezionalo.

   6. Fai clic su Aggiungi un altro ruolo.

   7. Nella sezione Assegna i ruoli, fai clic sulla freccia menu a discesa in Seleziona un ruolo.

   8. Cerca o vai al ruolo Utente job BigQuery e selezionalo.

   9. Fai clic su Salva.

SQL

Utilizza l'istruzione GRANT:

1. Nella console Cloud de Confiance , vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor di query, inserisci la seguente istruzione:

   GRANT `roles/aiplatform.user`, `roles/bigquery.jobUser`
   ON PROJECT `PROJECT_ID`
   TO "USER_OR_GROUP";

   Sostituisci quanto segue:

   • PROJECT_ID: il progetto in cui prevedi di utilizzare le funzioni AI.*.
   • USER_OR_GROUP: l'utente o il gruppo a cui concedere l'accesso, nel formato user:USER@DOMAIN o group:GROUP@DOMAIN.

3. Fai clic su play_circle Esegui.

Per saperne di più su come eseguire le query, consulta Esegui una query interattiva.

Console

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su explore Explorer:

   

   Se non vedi il riquadro a sinistra, fai clic su last_page Espandi riquadro sinistro per aprirlo.

3. Nel riquadro Explorer, espandi il nome del progetto, quindi fai clic su Connessioni.

4. Nella pagina Connessioni, fai clic su Crea connessione.

5. In Tipo di connessione, scegli Modelli remoti di Vertex AI, funzioni remote, BigLake e Spanner (risorsa Cloud).

6. Nel campo ID connessione, inserisci un nome per la connessione.

7. In Tipo di località, seleziona una località per la connessione. La connessione deve essere collocata insieme alle altre risorse, ad esempio i set di dati.

8. Fai clic su Crea connessione.

9. Fai clic su Vai alla connessione.

10. Nel riquadro Informazioni sulla connessione, copia l'ID account di servizio da utilizzare in un passaggio successivo.

SQL

Utilizza l'istruzione CREATE CONNECTION:

1. Nella console Cloud de Confiance , vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor di query, inserisci la seguente istruzione:

   CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME`
   OPTIONS (
     connection_type = "CLOUD_RESOURCE",
     friendly_name = "FRIENDLY_NAME",
     description = "DESCRIPTION"
     );

   Sostituisci quanto segue:

   • CONNECTION_NAME: il nome della connessione nel formato PROJECT_ID.LOCATION.CONNECTION_ID, LOCATION.CONNECTION_ID o CONNECTION_ID. Se il progetto o la località vengono omessi, vengono dedotti dal progetto e dalla località in cui viene eseguita l'istruzione.
   • FRIENDLY_NAME (facoltativo): un nome descrittivo per la connessione.
   • DESCRIPTION (facoltativo): una descrizione della connessione.

3. Fai clic su play_circle Esegui.

Per saperne di più su come eseguire le query, consulta Esegui una query interattiva.

bq

1. In un ambiente a riga di comando, crea una connessione:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   Il parametro --project_id sostituisce il progetto predefinito.

   Sostituisci quanto segue:

   • REGION: la tua regione di connessione
   • PROJECT_ID: il tuo ID progetto Cloud de Confiance
   • CONNECTION_ID: un ID per la tua connessione

   Quando crei una risorsa di connessione, BigQuery crea un account di servizio di sistema univoco e lo associa alla connessione.

   Risoluzione dei problemi: se ricevi il seguente errore di connessione, aggiorna Google Cloud SDK:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Recupera e copia l'ID del account di servizio da utilizzare in un passaggio successivo:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   L'output è simile al seguente:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.s3ns-system.iam.gserviceaccount.com"}
   

Python

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

Node.js

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

Java

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.connection.v1.CloudResourceProperties;
import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.CreateConnectionRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

public class CreateConnection {

  /**
   * Creates a BigQuery connection to a Cloud Resource. A Cloud Resource connection provisions a
   * service account that can be granted access to other Google Cloud resources for federated
   * queries.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the connection (for example, "us-central1").
   * @param connectionId The ID of the connection to create (for example, "example-connection-id").
   */
  public static void createConnection(String projectId, String location, String connectionId) {
    LocationName parent = LocationName.of(projectId, location);

    // CloudResourceProperties provisions a managed Google Cloud service account on creation.
    CloudResourceProperties cloudResourceProperties = CloudResourceProperties.newBuilder().build();
    Connection connection =
        Connection.newBuilder()
            .setFriendlyName("Example Connection")
            .setDescription("Cloud Resource connection for federated queries.")
            .setCloudResource(cloudResourceProperties)
            .build();

    CreateConnectionRequest request =
        CreateConnectionRequest.newBuilder()
            .setParent(parent.toString())
            .setConnectionId(connectionId)
            .setConnection(connection)
            .build();

    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      Connection response = client.createConnection(request);

      System.out.printf("Successfully created connection: %s%n", response.getName());
      System.out.printf("Friendly name: %s%n", response.getFriendlyName());
      System.out.printf(
          "Service Account: %s%n", response.getCloudResource().getServiceAccountId());
    } catch (AlreadyExistsException err) {
      System.err.printf(
          "error: connection '%s' already exists in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to create connection '%s' in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    }
  }

Terraform

Utilizza la risorsa google_bigquery_connection.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

L'esempio seguente crea una connessione alle risorse Cloud denominata my_cloud_resource_connection nella regione US:

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Per applicare la configurazione Terraform in un progetto Cloud de Confiance , completa i passaggi descritti nelle sezioni seguenti.

Prepara Cloud Shell

1. Avvia Cloud Shell.

2. Imposta il progetto Cloud de Confiance predefinito in cui vuoi applicare le configurazioni Terraform.

   Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo in qualsiasi directory.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione Terraform deve avere la propria directory (chiamata anche modulo principale).

1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

   Copia il codice campione nel file main.tf appena creato.

   Facoltativamente, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
4. Salva le modifiche.
5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.

   terraform init

   Facoltativamente, per utilizzare l'ultima versione del provider Google, includi l'opzione -upgrade:

   terraform init -upgrade

Applica le modifiche

1. Esamina la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative:

   terraform plan

   Apporta le correzioni necessarie alla configurazione.

2. Applica la configurazione Terraform eseguendo il comando seguente e inserendo yes al prompt:

   terraform apply

   Attendi che Terraform visualizzi il messaggio "Apply complete!".

3. Apri il tuo progetto Cloud de Confiance per visualizzare i risultati. Nella console Cloud de Confiance , vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

Console

1. Vai alla pagina IAM e amministrazione.

   Vai a IAM e amministrazione

2. Fai clic su person_add Concedi l'accesso.

   Viene visualizzata la finestra di dialogo Aggiungi entità.

3. Nel campo Nuove entità, inserisci l'ID del account di servizio che hai copiato in precedenza.

4. Nella sezione Assegna ruoli, fai clic su Aggiungi ruoli.

5. Cerca il ruolo Agent Platform User, selezionalo e poi fai clic su Applica.

6. Fai clic su Salva.

SQL

Utilizza l'istruzione GRANT:

1. Nella console Cloud de Confiance , vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor di query, inserisci la seguente istruzione:

   GRANT `roles/aiplatform.user`
   ON PROJECT `PROJECT_ID`
   TO "connection:CONNECTION_NAME";

   Sostituisci quanto segue:

   • PROJECT_ID: il progetto in cui prevedi di utilizzare Agent Platform.
   • CONNECTION_NAME: il nome della connessione nel formato PROJECT_ID.LOCATION.CONNECTION_ID o LOCATION.CONNECTION_ID. Se il progetto viene omesso, viene dedotto dal progetto in cui viene eseguita l'istruzione.

3. Fai clic su play_circle Esegui.

Per saperne di più su come eseguire le query, consulta Esegui una query interattiva.

gcloud

Utilizza il comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:$(bq show --format=prettyjson --connection $PROJECT_ID.$REGION.$CONNECTION_ID | jq -r .cloudResource.serviceAccountId)"
--role=roles/aiplatform.user

Sostituisci quanto segue:

• PROJECT_ID: il nome del progetto.
• REGION: la località in cui è stata creata la connessione.
• CONNECTION_ID: il nome della connessione che hai creato.

Terraform

Utilizza la risorsa google_bigquery_connection.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

L'esempio seguente concede l'accesso al ruolo IAM al service account della connessione alle risorse Cloud:

## This grants IAM role access to the service account of the connection created in the previous step.
resource "google_project_iam_member" "aiplatformpermission" {
  project = data.google_project.default.project_id
  role    = "roles/aiplatform.user"
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

Per applicare la configurazione Terraform in un progetto Cloud de Confiance , completa i passaggi descritti nelle sezioni seguenti.

Prepara Cloud Shell

1. Avvia Cloud Shell.

2. Imposta il progetto Cloud de Confiance predefinito in cui vuoi applicare le configurazioni Terraform.

   Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo in qualsiasi directory.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione Terraform deve avere la propria directory (chiamata anche modulo principale).

1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

   Copia il codice campione nel file main.tf appena creato.

   Facoltativamente, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
4. Salva le modifiche.
5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.

   terraform init

   Facoltativamente, per utilizzare l'ultima versione del provider Google, includi l'opzione -upgrade:

   terraform init -upgrade

Applica le modifiche

1. Esamina la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative:

   terraform plan

   Apporta le correzioni necessarie alla configurazione.

2. Applica la configurazione Terraform eseguendo il comando seguente e inserendo yes al prompt:

   terraform apply

   Attendi che Terraform visualizzi il messaggio "Apply complete!".

3. Apri il tuo progetto Cloud de Confiance per visualizzare i risultati. Nella console Cloud de Confiance , vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.