Importar un archivo CSV

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

Nota: Si vas a migrar una base de datos completa desde un servidor de bases de datos compatible (local, en AWS o en AlloyDB) a un nuevo clúster de AlloyDB, puedes usar Database Migration Service en lugar de exportar y, después, importar archivos. Si vas a exportar datos porque quieres crear un clúster a partir del archivo exportado, te recomendamos que restaures una copia de seguridad almacenada.

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

Antes de empezar

Antes de iniciar una operación de importación:

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

Importante: Antes de iniciar una operación de importación de gran tamaño, asegúrate de que al menos el 25 % del disco esté libre en el clúster. De esta forma, se evitan problemas con el crecimiento automático agresivo, que puede afectar negativamente a la disponibilidad del clúster. Comprueba que el archivo CSV tenga los datos esperados y que sea un archivo CSV válido.

Roles y permisos necesarios para importar datos a clústeres de AlloyDB

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

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

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

• Rol de gestión de identidades y accesos storage.objectViewer
• Un rol personalizado que incluya los siguientes permisos:
  • storage.objects.get

Para obtener ayuda con los roles de Gestión de Identidades y Accesos, consulta Gestión de Identidades y Accesos.

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

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

• La base de datos y la tabla en las que vas a importar los datos deben existir en tu clúster de AlloyDB. Para obtener ayuda sobre cómo crear una base de datos, consulta el artículo Crear 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 de 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 tu archivo CSV o si se omiten algunas columnas, usa las opciones de importación de CSV para importar del archivo CSV a las columnas obligatorias.

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

gcloud

1. Crea un segmento de Cloud Storage.
2. Sube el archivo CSV a tu segmento. Para obtener ayuda sobre cómo subir archivos a los contenedores, consulta Subir objetos.

3. Usa gcloud storage buckets add-iam-policy-binding para asignar el storage.objectViewer rol de gestión de identidades y accesos a la cuenta de servicio de AlloyDB para el segmento.

    [e-mail]

   Para obtener ayuda sobre cómo definir permisos de gestión de identidades y accesos, consulta Usar permisos de gestión de identidades y accesos.

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).

   Haz las siguientes sustituciones:

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

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

5. Si no necesitas conservar los permisos de gestión de identidades y accesos que has definido anteriormente, quítalos con gcloud storage buckets remove-iam-policy-binding.

REST v1

1. Crea un segmento de Cloud Storage.
2. Sube el archivo CSV a tu segmento. Para obtener ayuda sobre cómo subir archivos a los contenedores, consulta Subir objetos.

3. Concede permisos a la cuenta de servicio para acceder al segmento de Cloud Storage de la operación de importación. Usa el formato de cuenta de servicio para identificar la cuenta de servicio del proyecto al que vas a importar. El formato de la cuenta de servicio es el siguiente:

   [e-mail]

4. Usa gcloud storage buckets add-iam-policy-binding para asignar el storage.objectViewer rol de gestión de identidades y accesos a la cuenta de servicio del clúster de AlloyDB para el segmento. Para obtener ayuda sobre cómo configurar permisos de gestión de identidades y accesos, consulta Usar permisos de gestión de identidades y accesos.

5. Importa el archivo.

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

   Usa el siguiente método HTTP y la siguiente URL:

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

   Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

   • PROJECT_ID: el ID del proyecto.
   • LOCATION_ID: la región en la que se despliega el clúster de AlloyDB.
   • CLUSTER_ID: el ID del clúster.
   • BUCKET_NAME: el nombre del segmento de Cloud Storage.
   • PATH_TO_CSV_FILE: la ruta al archivo CSV.
   • USER: el usuario de la operación de importación.
   • DATABASE_NAME: nombre de una base de datos del clúster de AlloyDB.
   • TABLE_NAME: la tabla de la base de datos.
   • COLUMNS (Opcional): las columnas que se van a importar.
   • ESCAPE_CHARACTER (opcional): el carácter que debe aparecer antes de un carácter de datos que deba escaparse. El valor de este argumento debe ser un carácter en código ASCII hexadecimal. Por ejemplo, 22 representa una comilla doble.
   • QUOTE_CHARACTER (Opcional): el carácter que encierra los valores de las columnas que tienen un tipo de datos de cadena. El valor de este argumento debe ser un carácter en código ASCII hexadecimal. Por ejemplo, 22 representa comillas dobles.
   • FIELD_DELIMITER (opcional): el carácter que separa los valores de las columnas. El valor de este argumento debe ser un carácter en código ASCII hexadecimal. 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, despliega una de estas opciones:

   curl (Linux, macOS o Cloud Shell)

   Con el siguiente comando se da por hecho que has iniciado sesión en la CLI de Google Cloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login, o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud. Puedes comprobar 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 da por hecho que has iniciado sesión en la CLI de Google Cloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login, o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud. Puedes comprobar 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 gestión de identidades y accesos que has definido anteriormente, quítalos ahora.

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

Personalizar el formato CSV e importar el archivo

Puede personalizar el formato CSV e importar el archivo cuando este contenga delimitadores de campo, comillas o caracteres de escape no predeterminados. Para importar un archivo CSV con un formato no predeterminado, debe proporcionar las mismas opciones de formato en la solicitud.

Usa los siguientes ejemplos de la CLI de gcloud y de la API 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 de la API REST equivalente tiene un aspecto 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",
 }
}

Para ver cómo se construye la solicitud de la API REST subyacente para esta tarea, consulta el Explorador de APIs en la página clusters:import.

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 aparece un error como INVALID_ARGUMENT, comprueba que la tabla exista. Si la tabla existe, confirma que tienes los permisos correctos en el contenedor. Para obtener ayuda sobre cómo configurar el control de acceso en Cloud Storage, consulta Crear y gestionar listas de control de acceso.

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

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

gcloud

Ejecuta lo siguiente con el comando gcloud alloydb operations describe:

gcloud alloydb operations describe OPERATION_ID --region=REGION

El estado de estas operaciones se encuentra en el campo STATUS.

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

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 los datos de la solicitud, haz las siguientes sustituciones:

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

Para enviar tu solicitud, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

En el siguiente comando se da por hecho que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login, o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud. Puedes comprobar la cuenta activa ejecutando gcloud auth list.

Ejecuta el comando siguiente:

  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)

El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login. Puedes comprobar la cuenta activa ejecutando gcloud auth list.

Ejecuta el comando siguiente:

$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 la solicitud se completa correctamente, en el cuerpo de la respuesta se incluye una instancia de Operation.

Siguientes pasos

• Consulta cómo importar un archivo SQL.
• Consulta cómo cancelar una operación de importación.