Cómo importar un archivo CSV

En esta página, se describe cómo importar datos de un archivo CSV almacenado en un bucket de Cloud Storage a un clúster de AlloyDB para PostgreSQL.

Nota: Si migras una base de datos completa desde un servidor de base de datos compatible (local, en AWS o AlloyDB) a un clúster nuevo de AlloyDB, puedes usar Database Migration Service en lugar de exportar y, luego, importar los archivos. Si exportas porque quieres crear un clúster nuevo desde el archivo exportado, considera restablecer una copia de seguridad almacenada.

Puedes cancelar la importación de datos a clústeres de AlloyDB. Para obtener más información, consulta Cancela una operación de importación.

Antes de comenzar

Antes de comenzar una operación de importación, haz lo siguiente:

• Asegúrate de que tu base de datos tenga suficiente espacio libre.
• Las operaciones de importación usan recursos de bases de datos, pero no interfieren en las operaciones normales de la base de datos, a menos que el clúster no cuente con el aprovisionamiento suficiente.

Importante: Antes de iniciar una operación de importación grande, asegúrate de que al menos el 25 por ciento del disco esté disponible en el clúster. Esto ayuda a evitar problemas de crecimiento automático agresivo, lo que puede afectar de manera adversa la disponibilidad del clúster. Verifica que el archivo CSV tenga los datos esperados y que sea un archivo CSV válido.

Roles y permisos obligatorios para la importación a clústeres de AlloyDB

Para importar datos de Cloud Storage a AlloyDB, el usuario que inicia la importación debe tener uno de los siguientes roles:

• El rol de administrador de AlloyDB
• Un rol personalizado, que incluya los siguientes permisos:
  • alloydb.clusters.get
  • alloydb.clusters.import

Además, la cuenta de servicio para el clúster de AlloyDB debe tener uno de los siguientes roles:

• El rol de IAM storage.objectViewer
• Un rol personalizado que incluya los siguientes permisos:
  • storage.objects.get

Para obtener ayuda con los roles de IAM, consulta Identity and Access Management.

Nota: Los cambios que realices en los roles y permisos de IAM pueden tardar unos minutos en aplicarse. Para obtener más información, consulta Propagación de cambios de acceso.

Importa datos de un archivo CSV a clústeres de AlloyDB

• La base de datos y la tabla a las que importas deben existir en tu clúster de AlloyDB. Para obtener ayuda para crear una base de datos, consulta Crea una base de datos.
• Los archivos CSV deben tener una línea por cada fila de datos y usar campos separados por comas.

Nota: El comportamiento predeterminado para AlloyDB es importar las columnas de tu archivo CSV en el mismo orden que el esquema de la tabla. Si el orden es diferente en el archivo CSV o si se omiten algunas columnas, usa las opciones de importación de CSV para importar desde el archivo CSV a las columnas requeridas.

Para importar datos a un clúster de AlloyDB con un archivo CSV, sigue estos pasos:

Console

1. Ve a la página Clústeres.

   Ir a los clústeres

2. Haz clic en el nombre de un clúster para abrir la página Descripción general de ese clúster.

3. Haz clic en Importar.

4. En Formato del archivo, selecciona CSV.

5. En Seleccionar archivo fuente, elige si deseas subir archivos desde tu computadora o seleccionar un archivo de una ubicación de Cloud Storage.

   1. Para subir un archivo desde tu computadora, haz lo siguiente:

      1. Selecciona Subir archivos de tu computadora.
      2. Haz clic en Explorar junto a Seleccionar archivo local para seleccionar un archivo CSV de tu máquina local.
      3. Haz clic en Explorar junto a Seleccionar ubicación de Cloud Storage para seleccionar una ubicación de Cloud Storage en la que se almacenará el archivo local subido.
      4. Haz clic en Subir para subir el archivo.

   2. Para seleccionar un archivo CSV que existe en un bucket de Cloud Storage, haz lo siguiente:

      1. Selecciona Seleccionar archivo de Google Cloud Storage.
      2. Haz clic en Explorar junto a bucket-name/file-name para seleccionar un archivo CSV de un bucket de Cloud Storage.

6. Selecciona la base de datos a la que deseas importar los datos en el menú desplegable Base de datos.

7. Selecciona la tabla dentro de la base de datos en el menú desplegable Tabla.

8. Es opcional. Para especificar un usuario para la operación de importación, haz clic en Mostrar opciones de usuario y, luego, ingresa el nombre de usuario en el campo Usuario.

9. Para iniciar la operación de importación, haz clic en Importar.

Nota: Puedes importar un archivo .gz comprimido o .csv sin comprimir.

gcloud

1. Crea buckets de Cloud Storage.
2. Sube el archivo CSV al bucket. Para obtener ayuda con la carga de archivos en buckets, consulta Sube objetos.

3. Usa gcloud storage buckets add-iam-policy-binding para otorgar el storage.objectViewer rol de IAM a la cuenta de servicio de AlloyDB para el bucket.

    [e-mail]

   Para obtener ayuda con la configuración de permisos de IAM, consulta la sección sobre cómo usar permisos de IAM.

4. Importa el archivo:

   gcloud alloydb clusters import CLUSTER_NAME --region=REGION --gcs-uri=gs://BUCKET_NAME/FILE_NAME --database=DATABASE_NAME --user=USER --csv --table=TABLE_NAME

   Nota: Puedes importar un archivo comprimido (.gz) o sin comprimir (.csv).

   Realiza los siguientes reemplazos:

   • CLUSTER_NAME: el nombre del clúster
   • REGION: la región en la que se implementa el clúster de AlloyDB
   • BUCKET_NAME: el nombre del bucket de Cloud Storage
   • FILE_NAME: el nombre del archivo CSV
   • DATABASE_NAME: el nombre de una base de datos dentro del clúster
   • USER: el usuario para la operación de importación
   • TABLE_NAME: la tabla dentro de la base de datos

   Para obtener más información sobre el uso del importcomando, consulta la alloydb import página de referencia del comando.

5. Si no necesitas conservar los permisos de IAM que configuraste anteriormente, quítalos con gcloud storage buckets remove-iam-policy-binding.

REST v1

1. Crea buckets de Cloud Storage.
2. Sube el archivo CSV al bucket. Para obtener ayuda con la carga de archivos en buckets, consulta Sube objetos.

3. Otorga permisos a la cuenta de servicio al bucket de Cloud Storage para la operación de importación. Usa el formato de la cuenta de servicio para identificar la cuenta de servicio del proyecto al que importas. El formato de la cuenta de servicio es el siguiente:

   [e-mail]

4. Usa gcloud storage buckets add-iam-policy-binding para otorgar el storage.objectViewer rol de IAM a la cuenta de servicio del clúster de AlloyDB para el bucket. Para obtener ayuda con la configuración de permisos de IAM, consulta la sección sobre cómo usar permisos de IAM.

5. Importa el archivo.

   Nota: Puedes importar un archivo comprimido (.gz) o sin comprimir (.csv).

   Usa el siguiente método y URL HTTP:

   POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:import

   Antes de usar cualquiera de los datos de la solicitud, realiza los siguientes reemplazos:

   • PROJECT_ID: Es el ID del proyecto.
   • LOCATION_ID: la región en la que se implementa el clúster de AlloyDB
   • CLUSTER_ID: el ID del clúster
   • BUCKET_NAME: el nombre del bucket de Cloud Storage
   • PATH_TO_CSV_FILE: la ruta de acceso al archivo CSV
   • USER: el usuario para la operación de importación
   • DATABASE_NAME: el nombre de una base de datos dentro del clúster de AlloyDB
   • TABLE_NAME: la tabla dentro de la base de datos
   • COLUMNS (opcional): las columnas para importar
   • ESCAPE_CHARACTER (opcional): el carácter que debe aparecer antes de un carácter de datos que debe escaparse El valor de este argumento debe ser un carácter en el código ASCII de Hex. Por ejemplo, 22 representa una comilla doble.
   • QUOTE_CHARACTER (opcional): el carácter que encierra valores de columnas que tienen un tipo de datos de string El valor de este argumento debe ser un carácter en el código ASCII de Hex. Por ejemplo, 22 representa una comilla doble.
   • FIELD_DELIMITER (opcional): el carácter que divide los valores de las columnas El valor de este argumento debe ser un carácter en el código ASCII de Hex. Por ejemplo, 2C representa una coma.

   Cuerpo JSON de la solicitud:

   {
     "gcsUri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE",
     "database": "DATABASE_NAME",
     "user": "USER",
     "csvImportOptions": {
       "table": "TABLE_NAME",
       "columns": ["COLUMN1", "COLUMN2"],
       "fieldDelimiter": "FIELD_DELIMITER",
       "quoteCharacter": "QUOTE_CHARACTER",
       "escapeCharacter": "ESCAPE_CHARACTER"
     }
   }
   

   Para enviar tu solicitud, expande una de estas opciones:

   curl (Linux, macOS o Cloud Shell)

   Con el siguiente comando, se supone que accediste a Google Cloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI. Puedes verificar la cuenta activa ejecutando gcloud auth list.

   Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

      curl -X POST \
            -H "Authorization: Bearer $(gcloud auth print-access-token)" \
            -H "Content-Type: application/json; charset=utf-8" \
            -d @request.json \
            "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID:import"
   

   PowerShell (Windows)

   Con el siguiente comando, se supone que accediste a Google Cloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI. Puedes verificar la cuenta activa ejecutando gcloud auth list.

   Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method POST `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -InFile request.json `
     -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID:import"| Select-Object -Expand Content
   

   Recibirás una respuesta JSON similar a la siguiente:

   Respuesta

   {
    "name": "projects/PROJECT_ID/locations/LOCATION_ID/operations/OPERATION_ID",
    "metadata": {
     "@type": "type.googleapis.com/google.cloud.alloydb.v1.OperationMetadata",
     "createTime": "2024-09-17T06:05:31.244428646Z",
     "target": "projects/project-id/locations/location-id/clusters/target-cluster",
     "verb": "import",
     "requestedCancellation": false,
     "apiVersion": "v1"
    },
    "done": false
   }
   

6. Si no necesitas conservar los permisos de IAM que configuraste anteriormente, quítalos ahora.

   Para obtener la lista completa de parámetros de la solicitud, consulta clusters:import.

Personaliza el formato CSV y, luego, importa el archivo

Puedes personalizar el formato CSV y, luego, importar el archivo cuando el archivo CSV contiene un delimitador de campo, o comillas o caracteres de escape no predeterminados. Para importar un archivo CSV con un formato no predeterminado, debes proporcionar las mismas opciones de formato en la solicitud.

Usa los siguientes ejemplos de gcloud CLI y la API de REST para personalizar el formato de tu archivo CSV.

gcloud

gcloud alloydb clusters import CLUSTER_NAME --region=REGION --database=DATABASE_NAME --gcs-uri='gs://BUCKET_NAME/PATH_TO_CSV_FILE' --user=USERNAME --table=TABLE_NAME --columns=COLUMNS --field-delimiter='2C' --quote-character='22' --escape-character='5C' --csv

REST v1

El cuerpo de la solicitud a la API de REST equivalente es similar al siguiente:

{
 "gcsUri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE",
 "database": "DATABASE_NAME",
 "user": "USER",
 "csvImportOptions": {
     "table": "TABLE_NAME",
     "columns": ["COLUMN1", "COLUMN2"],
     "escapeCharacter": "5C",
     "quoteCharacter": "22",
     "fieldDelimiter": "2C",
 }
}

Si quieres ver cómo se crea la solicitud a la API de REST subyacente para esta tarea, consulta el Explorador de API en la página de underlying REST API request APIs Explorer on the clusters:import page.

Nota: Si usas opciones de formato personalizadas en tus comandos de importación, asegúrate de crear el archivo exportado con las mismas opciones.

Si recibes un error como INVALID_ARGUMENT, asegúrate de que la tabla exista. Si la tabla existe, confirma que tienes los permisos correctos en el bucket. Para obtener ayuda para configurar el control de acceso en Cloud Storage, consulta Crea y administra Listas de control de acceso.

Verifica el estado de una operación de importación

Para verificar el estado de una operación de importación, sigue estos pasos:

gcloud

Ejecuta lo siguiente con el gcloud alloydb operations describe comando:

gcloud alloydb operations describe OPERATION_ID --region=REGION

El estado de estas operaciones está en el campo STATUS.

También puedes enumerar detalles de una operación específica o cancelar una operación específica. Para obtener más información sobre este comando, consulta la gcloud alloydb operations página de referencia del comando.

REST v1

Usa el método GET y la siguiente URL:

GET https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID

Para obtener más información, consulta get.

Antes de usar cualquiera de los datos de la solicitud, realiza los siguientes reemplazos:

• REGION: la región en la que se implementa el clúster de AlloyDB
• PROJECT_ID: Es el ID del proyecto.
• OPERATION_ID: el ID de la operación de importación Para obtener más información, consulta Antes de comenzar.

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Con el siguiente comando, se supone que accediste a la gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI. Puedes verificar la cuenta activa por ejecutando gcloud auth list.

Ejecuta el siguiente comando:

  curl -X GET \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID
 

PowerShell (Windows)

Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login. Puedes verificar la cuenta activa ejecutando gcloud auth list.

Ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID | Select-Object -Expand Content

Recibirás una respuesta JSON similar a la siguiente:

Si se ejecuta correctamente, el cuerpo de la respuesta contiene una instancia de operación.

¿Qué sigue?

• Obtén información para importar un archivo SQL.
• Obtén información para cancelar una operación de importación.