Administra conjuntos de contexto en Cloud SQL Studio

Vista previa

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio y las Condiciones Adicionales para Productos de IA Generativa en Versión Preliminar. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Cuando usas el agente de ingeniería de contexto, puede crear y subir conjuntos de información contextual automáticamente desde tu CLI. En este documento, se describe cómo crear, editar y borrar conjuntos de contexto en Cloud SQL para MySQL Studio cuando quieres una interfaz visual en la consola de Google Cloud para administrar archivos de conjuntos de contexto. Cuando creas un conjunto de contexto en Cloud SQL Studio, este lo almacena en el grupo de conjuntos de contexto default del proyecto para la región seleccionada y lo vincula a la base de datos actual. Los nombres de los conjuntos de contextos (y sus IDs de conjuntos de contextos derivados) deben ser únicos dentro del grupo de conjuntos de contextos default del proyecto para una región determinada, en todas las bases de datos y las instancias. En Cloud SQL Studio, la creación de un conjunto de contexto con un nombre cuyo ID derivado ya existe no pasa la validación. Para reemplazar su contenido y mantener sus asociaciones de base de datos, edita el conjunto de contexto existente. Si subes contenido directamente a través del agente de ingeniería de contexto o la API de Dataplex con un ID de conjunto de contexto existente, se reemplazará su contenido y, si se especifican, sus asociaciones de bases de datos.

La lista Conjuntos de contexto de Cloud SQL Studio solo muestra los conjuntos de contexto del grupo de conjuntos de contexto default en todas las regiones admitidas que están vinculadas a la base de datos actual. Los conjuntos de contexto creados para otra base de datos o a través de la API sin vincular el recurso de la base de datos en databases (o en un grupo de conjuntos de contexto personalizado) no aparecen en la lista de Cloud SQL Studio.

Para obtener más información sobre los conjuntos de contexto, consulta Descripción general de los conjuntos de contexto.

Antes de comenzar

Completa los siguientes requisitos previos antes de crear o subir un conjunto de contexto.

Los conjuntos de contexto se pueden crear en las regiones us-central1, us-east1, europe-west4 y asia-southeast1.

Habilita los servicios obligatorios

Habilita los siguientes servicios para tu proyecto:

• API de Data Analytics with Gemini
• API de Gemini para Google Cloud
• API de Knowledge Catalog

Prepara una instancia de Cloud SQL

• Asegúrate de tener acceso a una instancia de Cloud SQL existente o crea una nueva. Para obtener más información, consulta Crea instancias para Cloud SQL.
• Asegúrate de crear una base de datos en tu instancia en la que crearás las tablas. Para obtener más información, consulta Crea una base de datos en la instancia de Cloud SQL.

Roles y permisos requeridos

• Habilita la autenticación de la base de datos de IAM en la instancia configurando la marca de base de datos cloudsql_iam_authentication como on (cloudsql_iam_authentication=on). Para obtener más información, consulta Configura instancias existentes para la autenticación de la base de datos de IAM.
• Agrega un usuario o una cuenta de servicio de IAM a nivel de la instancia. Para obtener más información, consulta Agrega una vinculación de política de IAM a un usuario, una cuenta de servicio o un grupo.
• Otorga los roles roles/cloudsql.studioUser, roles/cloudsql.instanceUser, roles/serviceusage.serviceUsageConsumer y roles/geminidataanalytics.queryDataUser al usuario o a la cuenta de servicio de IAM a nivel del proyecto. Para obtener más información, consulta Agrega una vinculación de política de IAM para un proyecto.
• Para crear, subir y administrar conjuntos de contexto, otorga el rol de editor de Dataplex Catalog (roles/dataplex.catalogEditor) o de administrador de Dataplex Catalog (roles/dataplex.catalogAdmin) al usuario de IAM o a la cuenta de servicio a nivel del proyecto. Para obtener más información, consulta Permisos de conjuntos de contextos.
• Debes tener un usuario con privilegios que otorgue privilegios de base de datos al usuario o a la cuenta de servicio de IAM.
  
  GRANT SELECT ON DATABASE_NAME.* TO 'IAM_USERNAME'@'%';
  
  Reemplaza DATABASE_NAME por el nombre de tu base de datos y IAM_USERNAME por el nombre de usuario de IAM sin el sufijo de dominio ni @ (por ejemplo, [e-mail] se convierte en user, lo que da como resultado 'user'@'%').
  
  Para obtener más información, consulta Otorga privilegios de base de datos a un usuario o una cuenta de servicio de IAM individuales.

Otorga el permiso executesql a la instancia de Cloud SQL

Para otorgar el permiso executesql a la instancia de Cloud SQL y habilitar las APIs de datos de Cloud SQL, ejecuta el siguiente comando:

gcloud sql instances patch INSTANCE_ID --project=PROJECT_ID --data-api-access=ALLOW_DATA_API

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto de Google Cloud .
• INSTANCE_ID: Es el ID de tu instancia de Cloud SQL.

Para realizar los pasos de este instructivo, accede a Google Cloud y, luego, autentícate en la base de datos con la autenticación de IAM.

Crear un conjunto de contextos

Para crear un conjunto de contexto, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página de Cloud SQL.

   Ir a Cloud SQL

2. Elige una instancia de la lista.

3. En el menú de navegación, haz clic en Cloud SQL Studio.

4. Accede a Cloud SQL Studio con la autenticación de IAM.

5. En el panel Explorador, junto a Conjuntos de contexto, haz clic en Ver acciones.

6. Haz clic en Crear conjunto de contextos.

7. En Nombre del conjunto de contextos, proporciona un nombre único para el conjunto de contextos. En Cloud SQL Studio, el nombre debe tener entre 4 y 30 caracteres, y no puede comenzar con un espacio en blanco. Studio deriva el ID del conjunto de contexto convirtiendo el nombre a minúsculas y reemplazando los caracteres no alfanuméricos por guiones (-). El ID del conjunto de contexto derivado debe ser único dentro del grupo de conjuntos de contexto default del proyecto para la región seleccionada. Por ejemplo, el nombre del conjunto de contextos querydata_e2e_test tiene el ID de conjunto de contextos querydata-e2e-test. Cuando subes un conjunto de contexto directamente con el agente de ingeniería de contexto o la API de Dataplex, el ID del conjunto de contexto distingue mayúsculas de minúsculas, no puede contener barras diagonales (/) y no está restringido a entre 4 y 30 caracteres, ni a caracteres alfanuméricos, guiones y guiones bajos.

8. Es opcional. En Descripción del conjunto de contextos, agrega una descripción para tu conjunto de contextos.

9. Es opcional. Para subir un archivo de conjunto de contexto, haz clic en Explorar en la sección Subir archivo de conjunto de contexto y selecciona el archivo de conjunto de contexto.

10. Es opcional. Para elegir una región para el conjunto de contexto, haz clic en Mostrar opciones avanzadas y selecciona una región en Seleccionar una ubicación (el valor predeterminado es us-east1 en cada creación). Si eliges una región que no sea us-east1, selecciónala antes de ingresar el nombre del conjunto de contexto para que Cloud SQL Studio valide la unicidad del nombre en esa región.

11. Haz clic en Crear.

Nota: Crear un conjunto de contexto desde Cloud SQL Studio puede tardar unos minutos mientras Cloud SQL Studio procesa el conjunto de contexto. La creación o carga de un conjunto de información contextual a través del agente de ingeniería de contexto o la API de Dataplex suele completarse en unos segundos.

Crea conjuntos de información contextual

Si creaste un conjunto de contexto vacío en Studio o quieres actualizar uno existente, sigue los pasos que se indican en Crea y optimiza conjuntos de contexto con el agente de ingeniería de contexto para generar y optimizar un archivo de conjunto de contexto. El agente de ingeniería de contexto puede crear y subir tu conjunto de contexto directamente desde la CLI, o puedes editarlo en Studio para subir el archivo del conjunto de contexto de forma manual.

Cómo editar un conjunto de contextos

Para editar un conjunto de contextos, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página de Cloud SQL.

   Ir a Cloud SQL

2. Elige una instancia de la lista.

3. En el menú de navegación, haz clic en Cloud SQL Studio.

4. Accede a Cloud SQL Studio con la autenticación de IAM.

5. Haz clic en Ver acciones junto al conjunto de contextos que deseas editar.

6. Haz clic en Editar conjunto de contextos.

7. Es opcional. Edita la descripción del conjunto de información contextual.

8. Haz clic en Explorar en la sección Subir archivo de conjunto de contextos y selecciona el archivo de conjunto de contextos.

9. Haz clic en Guardar.

Borra un conjunto de información contextual

Para borrar un conjunto de contextos, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página de Cloud SQL.

   Ir a Cloud SQL

2. Elige una instancia de la lista.

3. En el menú de navegación, haz clic en Cloud SQL Studio.

4. Accede a Cloud SQL Studio con la autenticación de IAM.

5. Haz clic en Ver acciones junto al conjunto de contextos que quieres borrar.

6. Haz clic en Borrar conjunto de contextos.

7. En el cuadro de diálogo de confirmación Borrar conjunto de contextos, ingresa el ID del conjunto de contextos.

8. Haz clic en Confirmar para borrar el conjunto de contextos.

Nota: Borrar una base de datos no borra sus conjuntos de contexto. Para evitar conjuntos de contextos huérfanos que aún expongan detalles del esquema, bórralos antes de borrar la base de datos.

¿Qué sigue?

• Obtén más información sobre los conjuntos de contexto.
• Aprende a probar QueryData en Cloud SQL Studio.
• Obtén información para crear y optimizar conjuntos de contexto con el agente de ingeniería de contexto.
• Obtén información para integrar QueryData en una aplicación.