GCP Cloud Storage Source Connection | Documentación de Crestone

Requisitos Previos

Antes de configurar la conexión de origen GCP Cloud Storage en Crestone, asegúrese de contar con lo siguiente:

Requisito Principal: Un bucket de GCP Cloud Storage activo que contenga los archivos que desea extraer. Crestone se conecta mediante una clave JSON de cuenta de servicio (service account) — no se requieren cuentas de usuario ni flujos de navegador OAuth.

Nota: Crestone utiliza el SDK google-cloud-storage con Client.from_service_account_info(). No se requieren bibliotecas cliente adicionales ni una puerta de enlace (gateway) local.

Formatos de archivo admitidos:

Formato	Extensión	Notas
CSV	`.csv`	Delimitador y fila de encabezado configurables
TSV	`.tsv`	Delimitado por tabulaciones, mismas opciones que CSV
JSON	`.json`	Arreglo de objetos planos
Parquet	`.parquet`	El esquema se lee directamente del archivo
Excel (Open XML)	`.xlsx`	Lectura mediante `openpyxl`; nombre de hoja opcional
Excel (97-2003)	`.xls`	Lectura mediante `xlrd`; nombre de hoja opcional

Otros tipos de archivos (ej. .txt, .zip, .gz) no se listan al explorar el bucket.

Información Requerida:

Campo	Descripción
Service Account JSON	Archivo de clave JSON completo descargado de GCP — arrástrelo y suéltelo en el formulario de credenciales
Project ID	Extraído automáticamente de la clave JSON; identifica el proyecto de GCP

Consejo: Puede utilizar la misma cuenta de servicio tanto para el origen (extracción de archivos) como para el destino (carga de archivos) si la cuenta cuenta con los permisos necesarios en ambas operaciones. Crestone los trata como tipos de conexión independientes al crearlos.

Paso de Pre-Verificación

Antes de configurar la conexión en Crestone, verifique su cuenta de servicio y el acceso al bucket en la Consola de GCP:

Vaya a Cloud Storage en la Consola de GCP y confirme que el bucket de destino exista y contenga los archivos que desea extraer.
Vaya a IAM & Admin → Service Accounts y confirme que la cuenta de servicio exista y tenga una clave activa.
Verifique que la cuenta de servicio tenga los permisos requeridos (consulte Permisos Requeridos más abajo).

Cómo crear una clave de cuenta de servicio (si no dispone de una):

Vaya a IAM & Admin → Service Accounts.
Seleccione (o cree) la cuenta de servicio que utilizará Crestone.
Haga clic en Keys → Add key → Create new key → JSON.
Descargue el archivo .json — este es el archivo que subirá a Crestone.

Importante: Mantenga seguro el archivo de clave JSON. Concede acceso a su proyecto de GCP. Revóquelo desde IAM & Admin → Service Accounts → Keys si alguna vez se ve comprometido.

Pasos de Configuración

Siga estos pasos para crear una nueva conexión de origen GCP Cloud Storage en Crestone:

Navegue a Connections en la barra de navegación superior.
Seleccione la pestaña Source.
Haga clic en el botón + para crear una nueva conexión.
Complete el campo Connection Name con un nombre descriptivo (ej. GCP Storage - Data Lake).
En el menú desplegable Source Type, seleccione GCP Storage.
En el formulario de credenciales, arrastre y suelte (o haga clic para examinar) su archivo de clave JSON de cuenta de servicio. El Project ID se completa automáticamente.
Haga clic en Test Connection para validar que Crestone pueda comunicarse con el proyecto de GCP.
Una vez superada la prueba, haga clic en Create Source para guardar la conexión.

Edición de una Conexión Existente

Para actualizar las credenciales de una conexión de origen GCP Cloud Storage existente:

Navegue a Connections y localice su origen GCP Storage.
Haga clic en Edit.
Suelte el nuevo archivo de clave JSON de la cuenta de servicio en el área de credenciales.
Haga clic en Test Connection para verificar las nuevas credenciales.
Haga clic en Confirm para guardar los cambios.

Uso de GCP Cloud Storage como Fuente en un Nodo de Extracción

Una vez creada la conexión, puede utilizarla como origen de un Extraction Node. GCP Cloud Storage utiliza un modelo de bucket/blob — no hay esquemas ni tablas.

Abra o cree un Extraction Node y diríjase a la pestaña Source.
En Select Source, elija su conexión GCP Cloud Storage.
En Bucket, seleccione el bucket de GCS del que desea leer. Se listan todos los buckets accesibles para la cuenta de servicio.
(Opcional) Utilice el campo Folder / prefix filter para acotar la lista de archivos (ej. data/2026/) y haga clic en Filter.
En File, elija el blob (objeto) a extraer. Solo se listan los archivos con una extensión admitida.
El File format se detecta automáticamente a partir de la extensión del archivo, pero se puede anular:
- Para CSV/TSV: configure el Delimiter y active/desactive File has header row.
- Para Excel (.xlsx/.xls): opcionalmente configure el Sheet name (déjelo en blanco para usar la primera hoja).
- JSON y Parquet no requieren opciones adicionales.
La tarjeta de resumen muestra el bucket/archivo seleccionado, el formato detectado y las opciones elegidas.
El panel de Preview muestra una muestra de los datos que se extraerán.

Nota: Los archivos de Excel se leen con pandas (motor openpyxl para .xlsx, motor xlrd para .xls). Todos los valores de celda se leen como cadenas de texto para evitar problemas de análisis de números y fechas dependientes de la configuración regional; la inferencia de tipos se realiza posteriormente en el destino.

Manejo de Tipos de Datos

El manejo de tipos depende del formato del archivo de origen:

Formato	Comportamiento de tipos
CSV / TSV	Todas las columnas se leen como tipos inferidos por Polars; cadenas vacías, `NULL` y `null` se tratan como valores ausentes
JSON	Tipos inferidos a partir de los valores JSON (string, number, boolean)
Parquet	Los tipos de columna nativos se conservan tal como se almacenan en el archivo
Excel (`.xlsx` / `.xls`)	Todas las celdas se leen como strings (`dtype=str`); las celdas en blanco se convierten en `null`

Los nombres de columna se sanitizan automáticamente antes de la extracción: los caracteres especiales se reemplazan por _, los nombres no pueden comenzar con un dígito y los nombres duplicados se desambiguan (ej. name, name_1). Esto garantiza la compatibilidad con todos los destinos admitidos (SQL Server, Snowflake, Oracle, PostgreSQL, etc.).

Problemas Frecuentes

Problema	Causa Posible	Solución
Fallo en Test connection con error de autenticación	Clave de cuenta de servicio inválida o vencida	Genere una nueva clave en IAM & Admin → Service Accounts → Keys
El menú desplegable de Bucket está vacío	La cuenta de servicio carece de `storage.buckets.list` a nivel de proyecto	Asigne el rol Storage Object Viewer (o `roles/storage.admin`) a la cuenta de servicio a nivel de proyecto en IAM & Admin → IAM
El menú desplegable de File está vacío con un recuadro rojo de error	La cuenta de servicio carece de `storage.objects.list` sobre el bucket específico	Asigne el rol Storage Object Viewer a la cuenta de servicio sobre el bucket en Cloud Storage → Bucket → Permissions
No se listan archivos en el bucket	Todos los archivos tienen extensiones no admitidas, o el filtro de prefijo es demasiado restrictivo	Limpie el filtro de prefijo; confirme que el bucket contenga archivos `.csv`, `.tsv`, `.json`, `.parquet`, `.xlsx` o `.xls`
La lista de archivos es muy extensa y tarda en cargar	Bucket grande con muchos objetos	Utilice el filtro de prefijo para restringir el listado a una carpeta específica (ej. `reports/2026/`)
La vista previa muestra "No data found" para un archivo Excel	Nombre de hoja incorrecto o discrepancia de formato	Deje Sheet name en blanco para usar la primera hoja, o verifique la ortografía del nombre de la hoja
Falla la ejecución del job tras una previsualización exitosa	Problema transitorio de acceso a GCS o blob eliminado entre la vista previa y la ejecución	Vuelva a ejecutar el job; verifique que el blob aún exista en el bucket
`Invalid JSON` al cargar el archivo de clave	El archivo no es una clave JSON válida de cuenta de servicio de GCP	Descargue una clave JSON nueva desde IAM & Admin → Service Accounts → Keys

Permisos Requeridos

Crestone requiere dos niveles independientes de permisos en GCP al utilizar Cloud Storage como fuente:

Nivel de proyecto (para el selector de buckets)

Operación	Permiso GCP
Listar todos los buckets accesibles	`storage.buckets.list`

Otorgue esto a nivel de proyecto en IAM & Admin → IAM asignando uno de los siguientes roles:

roles/storage.objectViewer (mínimo recomendado)
roles/storage.admin

Nivel de bucket (para listar y descargar archivos)

Operación	Permiso GCP
Listar blobs en un bucket	`storage.objects.list`
Descargar un blob para preview/extracción	`storage.objects.get`

Otorgue esto a nivel de bucket en Cloud Storage → [nombre del bucket] → Permissions asignando:

roles/storage.objectViewer en el bucket específico

Importante: Contar con storage.buckets.list a nivel de proyecto no otorga automáticamente storage.objects.list en todos los buckets. Cada bucket debe otorgar permisos de listar+obtener por separado a menos que el rol se asigne a nivel de proyecto.

Consejo: Para mayor seguridad y conveniencia, otorgue a la cuenta de servicio el rol Storage Object Viewer a nivel de proyecto (cubre tanto el listado de buckets como el acceso a objetos en todos los buckets del proyecto) en lugar de gestionar listas de control de acceso por bucket de forma individual.

Conexión Fuente GCP Cloud Storage