Documentación de Oracle Cloud Infrastructure

Operaciones masivas para archivos en la nube

El paquete PL/SQL DBMS_CLOUD ofrece soporte de ejecución en paralelo para las actividades de carga, descarga, copia y transferencia de archivos en bloque, lo que optimiza la experiencia del usuario y ofrece un rendimiento óptimo para las operaciones de archivos en bloque.

El paquete DBMS_CLOUD soporta la carga y descarga de archivos en los siguientes servicios en la nube:

  • Oracle Cloud Infrastructure Object Storage

  • Almacenamiento de bloques de Azure

  • Amazon S3

  • Compatibilidad con Amazon S3, incluido Wasabi Hot Cloud Storage

  • Google Cloud Storage

Consulte DBMS_CLOUD Package File URI Formats para obtener más información.

Tema principal: Mover archivos

Acerca de las operaciones de archivos masivos

Las operaciones de archivos en bloque de DBMS_CLOUD soportan la descarga y carga de archivos en Autonomous Database, incluido el soporte para copiar, mover y suprimir archivos en almacenes de objetos en la nube, ya sea dentro del mismo proveedor de almacén de objetos o entre proveedores de almacén de objetos.

Las operaciones de archivos en bloque soportan el paralelismo y proporcionan un rendimiento óptimo para cargar, descargar, copiar y mover archivos. El paralelismo para operaciones de archivos en bloque se maneja especificando una prioridad para una operación. Las prioridades apoyadas son:

  • HIGH: utilice el recuento de recursos informáticos de CPU de la instancia de Autonomous Database para determinar el número de archivos paralelos procesados.
  • MEDIUM: utilice el límite de simultaneidad para el servicio Medium para determinar el paralelismo.
  • LOW: procesa los archivos en orden de serie (sin simultaneidad).

La ejecución de operaciones en bloque con mayor prioridad utiliza más recursos de base de datos y las operaciones se completan más rápido cuando el paralelismo puede acelerar la operación. Una prioridad más baja consume menos recursos de base de datos y las operaciones tardan más en completarse cuando el paralelismo puede acelerar la operación. Cuando las operaciones en bloque implican un número reducido de archivos que contienen pocos datos, la especificación de una prioridad más alta puede no cambiar el rendimiento.

Para aumentar el paralelismo de las operaciones de archivos en bloque, utilice la prioridad HIGH y aumente el número de CPU asignadas a la instancia de Autonomous Database. El máximo de operaciones de archivos simultáneos admitidas está limitado a 64 para operaciones de archivos masivos.

La prioridad por defecto es MEDIUM, que especifica que las operaciones de archivos en bloque utilizan el límite de simultaneidad definido para el grupo de consumidores MEDIUM. Consulte Gestión de la simultaneidad y las prioridades en Autonomous Database para obtener más información.

Consulte DBMS_CLOUD para la gestión de archivos en bloque para obtener más información sobre el uso del parámetro format para especificar priority con operaciones de archivos en bloque.

Copia masiva de archivos en el almacenamiento de objetos en la nube

Utilice el procedimiento DBMS_CLOUD.BULK_COPY para copiar archivos de forma masiva de un cubo o carpeta del almacén de objetos a otro cubo o carpeta.

  1. Cree un objeto de credencial para acceder a la ubicación de origen.

    El nombre de credencial de origen, tal y como se especifica con el parámetro source_credential_name, también se utiliza por defecto como credencial para la ubicación de destino.

    Consulte Procedimiento CREATE_CREDENTIAL para obtener más información.

  2. Cuando el origen y el destino están en almacenes de objetos distintos o tienen cuentas diferentes con el mismo proveedor de nube, cree una credencial para acceder a la ubicación de destino e incluya el parámetro target_credential_name.
  3. Ejecute el procedimiento DBMS_CLOUD.BULK_COPY para copiar archivos en paralelo de un cubo o carpeta del almacén de objetos a otro cubo o carpeta que pueda estar en el proveedor de nube, las cuentas y los cubos. Para ejecutar el procedimiento, debe estar conectado como usuario ADMIN o tener el privilegio EXECUTE en DBMS_CLOUD.
    BEGIN 
DBMS_CLOUD.BULK_COPY (
      source_credential_name => 'OCI_CRED',
      source_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/o',
      target_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
      format                 => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
);
END;
/

    En este ejemplo, se copian archivos en bloque de un cubo de Oracle Cloud Infrastructure Object Storage a otro.

    Consulte el procedimiento BULK_COPY para obtener más información.

    Consulte DBMS_CLOUD URI Formats para obtener más información.

Por ejemplo, utilice DBMS_CLOUD.BULK_COPY para copiar archivos de Amazon S3 en Oracle Cloud Infrastructure Object Storage. 

BEGIN
DBMS_CLOUD.BULK_COPY(      
      source_credential_name  => 'AWS_CRED',
      source_location_uri     => 'https://bucketname.s3-us-west-2.amazonaws.com/',
      target_credential_name  => 'OCI_CRED',
      target_location_uri     => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
      format                  =>  JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
);
END;
/

Movimiento masivo de archivos en Cloud Object Storage

Utilice el procedimiento DBMS_CLOUD.BULK_MOVE para mover archivos de forma masiva de una ubicación de Cloud Object Storage a otra.

El primer paso para mover archivos es copiarlos en la ubicación de destino. Después de que los archivos se copian correctamente, se suprimen de la ubicación de origen.

Se cambia el nombre de los archivos en lugar de copiarlos si el almacén de objetos permite cambiar el nombre de las operaciones entre las ubicaciones de origen y destino.

  1. Cree un objeto de credencial para acceder a la ubicación de origen.

    El nombre de credencial de origen, tal y como se especifica con el parámetro source_credential_name, también se utiliza por defecto como credencial para la ubicación de destino.

    Consulte Procedimiento CREATE_CREDENTIAL para obtener más información.

  2. Cuando el origen y el destino están en almacenes de objetos distintos o tienen cuentas diferentes con el mismo proveedor de nube, cree una credencial para acceder a la ubicación de destino e incluya el parámetro target_credential_name.
  3. Ejecute el procedimiento DBMS_CLOUD.BULK_MOVE para mover archivos de forma masiva de una ubicación de Cloud Object Storage a otra. Para ejecutar el procedimiento, debe estar conectado como usuario ADMIN o tener el privilegio EXECUTE en DBMS_CLOUD.
    BEGIN 
DBMS_CLOUD.BULK_MOVE (    
     source_credential_name => 'OCI_CRED',
     source_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/o',
     target_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
     format                 => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKMOVE')
);
END;
/

    En este ejemplo, los archivos se mueven en bloque de una ubicación de Oracle Cloud Infrastructure Object Storage a otra.

    Consulte el procedimiento BULK_MOVE para obtener más información.

    Consulte DBMS_CLOUD URI Formats para obtener más información.

Por ejemplo, utilice DBMS_CLOUD.BULK_MOVE para mover archivos de Amazon S3 a Oracle Cloud Infrastructure Object Storage. 

BEGIN
DBMS_CLOUD.BULK_MOVE(      
      source_credential_name  => 'AWS_CRED',
      source_location_uri     => 'https://bucketname.s3-us-west-2.amazonaws.com/',
      target_credential_name  => 'OCI_CRED',
      target_location_uri     => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
      format                  =>  JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
);
END;
/

Descarga masiva de archivos de Cloud Object Storage

Utilice el procedimiento DBMS_CLOUD.BULK_DOWNLOAD para descargar archivos de forma masiva desde la ubicación del almacén de objetos en la nube al objeto de directorio de una instancia de Autonomous Database.

  1. Cree una credencial para acceder al almacenamiento de objetos en la nube.

    El nombre de credencial se especifica con el parámetro credential_name.

    Consulte Procedimiento CREATE_CREDENTIAL para obtener más información.

  2. Ejecute el procedimiento DBMS_CLOUD.BULK_DOWNLOAD para descargar archivos en un directorio de Autonomous Database desde Cloud Object Storage. Para ejecutar el procedimiento, debe estar conectado como usuario ADMIN o tener el privilegio EXECUTE en DBMS_CLOUD.
    BEGIN
DBMS_CLOUD.BULK_DOWNLOAD (
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     directory_name  => 'BULK_TEST',
     format          => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
 );
END;
/

    En este ejemplo, se descargan archivos en bloque del URI de ubicación del almacén de objetos de Oracle Cloud Infrastructure en el objeto de directorio de una instancia de Autonomous Database.

    Nota

    Para escribir los archivos en el objeto de directorio de destino, debe tener el privilegio WRITE en el objeto de directorio.

    Consulte el procedimiento BULK_DOWNLOAD para obtener más información.

    Consulte DBMS_CLOUD URI Formats para obtener más información.

Carga masiva de archivos en Cloud Object Storage

Utilice el procedimiento DBMS_CLOUD.BULK_UPLOAD para cargar archivos de forma masiva desde un objeto de directorio de la base de datos a una ubicación del almacén de objetos en la nube.

  1. Cree una credencial para acceder al almacenamiento de objetos en la nube.

    El nombre de credencial se especifica con el parámetro credential_name.

    Consulte Procedimiento CREATE_CREDENTIAL para obtener más información.

  2. Ejecute el procedimiento DBMS_CLOUD.BULK_UPLOAD para copiar archivos en Cloud Object Storage desde un directorio de base de datos en la instancia de Autonomous Database. Para ejecutar el procedimiento, debe estar conectado como usuario ADMIN o tener el privilegio EXECUTE en DBMS_CLOUD.
    BEGIN
DBMS_CLOUD.BULK_UPLOAD (    
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     directory_name  => 'BULK_TEST',
     format          => JSON_OBJECT ('logretention' value 5, 'logprefix' value 'BULKUPLOAD')
 );
END;
/

    En este ejemplo, se cargan archivos en bloque desde un objeto de directorio, como se especifica con el parámetro directory_name en el URI de ubicación del almacén de objetos de Oracle Cloud Infrastructure.

    Nota

    Para leer los archivos de origen en el objeto de directorio, debe tener el privilegio READ en el objeto de directorio.

    Consulte el procedimiento BULK_UPLOAD para obtener más información.

Supresión masiva de archivos de Cloud Object Storage

Utilice el procedimiento DBMS_CLOUD.BULK_DELETE para suprimir archivos de Cloud Object Storage de forma masiva.

  1. Cree una credencial para acceder al almacenamiento de objetos en la nube.

    El nombre de credencial se especifica con el parámetro credential_name.

    credential_name puede ser NULL para el URI de cubo público, autenticado previamente o firmado previamente.

    Consulte Procedimiento CREATE_CREDENTIAL para obtener más información.

  2. Ejecute el procedimiento DBMS_CLOUD.BULK_DELETE para suprimir archivos del almacén de objetos en la nube. Para ejecutar el procedimiento, debe estar conectado como usuario ADMIN o tener el privilegio EXECUTE en DBMS_CLOUD.
    BEGIN
DBMS_CLOUD.BULK_DELETE (    
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     format          => JSON_OBJECT ('logretention' value 5, 'logprefix' value 'BULKDEL')
);
END;
/

    En este ejemplo, se suprimen archivos en bloque del almacén de objetos de Oracle Cloud Infrastructure.

    Consulte el procedimiento BULK_DELETE para obtener más información.

    Consulte DBMS_CLOUD URI Formats para obtener más información.

Supervisión y solución de problemas de cargas de archivos masivas

Todas las operaciones de carga de datos DBMS_CLOUD se registran en las vistas dba_load_operations y user_load_operations.

Puede utilizar las siguientes vistas para supervisar y solucionar problemas de cargas de archivos masivos:

  • dba_load_operations: muestra todas las operaciones de carga.

  • user_load_operations: muestra las operaciones de carga del esquema.

Consulte estas vistas para ver información sobre las operaciones de archivos masivos en curso y finalizadas. Por ejemplo, la siguiente sentencia SELECT con un predicado de cláusula WHERE en TYPE, se muestran las operaciones DOWNLOAD: 


SELECT owner_name, type, status, start_time, update_time, status_table, rows_loaded 
   FROM user_load_operations WHERE type = 'DOWNLOAD';

OWNER_NAME TYPE     STATUS    START_TIME               UPDATE_TIME              STATUS_TABLE ROWS_LOADED 
---------- -------- --------- ------------------------ ------------------------ ------------ ----------- 
"ADMIN"    DOWNLOAD COMPLETED 2022-10-17T20:42:19.498Z 2022-10-17T20:42:21.054Z DWN$2_STATUS           4 
"ADMIN"    DOWNLOAD FAILED    2022-10-17T20:40:54.348Z 2022-10-17T20:40:55.679Z DWN$1_STATUS

La columna STATUS_TABLE muestra el nombre de la tabla que puede consultar para consultar información de registro detallada para la operación de descarga masiva. Por ejemplo: 

DESCRIBE DWN$2_STATUS
Name          Null?    Type                        
------------- -------- --------------------------- 
ID            NOT NULL NUMBER                      
NAME                   VARCHAR2(4000)              
BYTES                  NUMBER                      
CHECKSUM               VARCHAR2(128)               
LAST_MODIFIED          TIMESTAMP(6) WITH TIME ZONE 
STATUS                 VARCHAR2(30)                
ERROR_CODE             NUMBER                      
ERROR_MESSAGE          VARCHAR2(4000)              
START_TIME             TIMESTAMP(6) WITH TIME ZONE 
END_TIME               TIMESTAMP(6) WITH TIME ZONE 
SID                    NUMBER                      
SERIAL#                NUMBER                      
ROWS_LOADED            NUMBER                      

SELECT id, name, bytes, status, error_message, start_time, end_time FROM DWN$2_STATUS;
ID NAME       BYTES STATUS    ERROR_MESSAGE START_TIME               END_TIME                 
-- ---------- ----- --------- ------------- ------------------------ ------------------------ 
 1 trees.txt     58 COMPLETED               2022-10-17T20:42:19.998Z 2022-10-17T20:42:20.421Z 
 2 trees1.txt    58 COMPLETED               2022-10-17T20:42:20.425Z 2022-10-17T20:42:20.533Z 
 3 trees2.txt    58 COMPLETED               2022-10-17T20:42:20.535Z 2022-10-17T20:42:20.894Z 
 4 trees3.txt    58 COMPLETED               2022-10-17T20:42:20.896Z 2022-10-17T20:42:21.043Z

La tabla de estado muestra cada nombre de archivo y su estado para la operación en bloque.

El mensaje y el número de error relevantes se registran en la tabla de estado si falla una operación en un archivo específico.

Para las operaciones finalizadas, el tiempo necesario para cada operación se puede calcular mediante el tiempo START_TIME y END_TIME informado.

La columna STATUS de la operación de archivo puede tener uno de los siguientes valores:

Estado del Archivo Descripción

COMPLETED

La operación de archivo se ha realizado correctamente.

FAILED

Fallo en la operación de archivo. Puede que se intente un reintento dos veces.

PENDING

La operación de archivo aún no se ha iniciado.

RUNNING

La operación de archivo está en curso actualmente.

SKIPPED

Se ha saltado la operación de archivo.

Si alguna operación de archivo falla después de dos reintentos, la operación masiva se marca como fallida y se emite un error. Por ejemplo:

ORA-20003: Operation failed, please query table DOWNLOAD$2_STATUS for error details

Al utilizar una operación de archivo masivo DBMS_CLOUD, hay opciones de parámetros format que controlan las tablas de estado:

  • logretention: especifica un valor entero que determina la duración en días que se retiene la tabla de estado. El valor por defecto es 2 días.

  • logprefix: especifica un valor de cadena que determina el prefijo de nombre de la tabla de estado de operación en bloque.

    Cada operación en bloque tiene su propio valor por defecto para la opción logprefix:

    Procedimiento Valor por defecto para logprefix
    DBMS_CLOUD.BULK_COPY COPYOBJ
    DBMS_CLOUD.BULK_DELETE DELETE
    DBMS_CLOUD.BULK_DOWNLOAD DOWNLOAD
    DBMS_CLOUD.BULK_MOVE MOVE
    DBMS_CLOUD.BULK_UPLOAD UPLOAD

Consulte Procedimiento DELETE_ALL_OPERATIONS para obtener información sobre cómo borrar la tabla user_load_operations.

Notas para operaciones de archivos masivos

Proporciona notas para las credenciales que utiliza con operaciones de archivos masivos.

  • Puede especificar principales como el parámetro credential_name, source_credential_name o target_credential_name para acceder a los recursos en la nube de forma segura sin almacenar credenciales de usuario. Los principales admitidos son:

    • Entidades de recurso de Oracle Cloud Infrastructure
    • Nombres de recursos de Amazon (ARN) de AWS
    • Entidad de servicio de Azure
    • Cuenta de servicio de Google

    Consulte Configuración de políticas y roles para acceder a recursos para obtener más información.

  • credential_name, source_credential_name o target_credential_name pueden ser NULL para el URI de cubo público, autenticado previamente o firmado previamente.