对云中的文件执行批量操作

PL/SQL 程序包 DBMS_CLOUD 为批量文件上载、下载、复制和传输活动提供了并行执行支持，这简化了用户体验，并为批量文件操作提供了最佳性能。

软件包 DBMS_CLOUD 支持将文件加载和卸载到以下云服务中：

• Oracle Cloud Infrastructure Object Storage

• Azure Blob 存储

• Amazon S3

• Google Cloud 存储

有关更多信息，请参见 DBMS_CLOUD Package File URI Formats 。

关于批量文件操作

DBMS_CLOUD 批量文件操作支持在自治 AI 数据库上下载和上载文件，包括支持在同一对象存储提供程序内或在对象存储提供程序之间跨云对象存储复制、移动和删除文件。

批量文件操作支持并行操作，并为上载、下载、复制和移动文件提供最佳性能。批量文件操作的并行性通过指定操作的优先级来处理。支持的优先级包括：

• HIGH：使用自治 AI 数据库实例 CPU 计算计数来确定处理的并行文件数。

• MEDIUM：使用中等服务的并发性限制来确定并行性。

• LOW：按序列顺序（无并发）处理文件。

以更高优先级运行批量操作时，当并行操作可以加快操作速度时，会更快地使用更多数据库资源和操作。当并行性可以加快操作速度时，较低优先级消耗的数据库资源较少，完成操作所需的时间较长。当批量操作涉及少量包含少量数据的文件时，指定较高的优先级可能不会更改性能。

要提高批量文件操作的并行度，请使用 HIGH 优先级并增加分配给自治 AI 数据库实例的 CPU 数。对于批量文件操作，支持的最大并发文件操作数限制为 64。

默认优先级为 MEDIUM，该优先级指定批量文件操作使用为 MEDIUM 使用者组定义的并发限制。

有关使用 format 参数指定具有批量文件操作的 priority 的详细信息，请参见 DBMS_CLOUD for Bulk File Management 。

在下面讨论的 DBMS_CLOUD 子程序中，对于公共存储桶 URI、预验证存储桶 URI 或预签名存储桶 URI，credential_name、source_credential_name 或 target_credential_name 可以是 NULL。

在云对象存储中批量复制文件

使用 DBMS_CLOUD.BULK_COPY 过程可将文件从一个对象存储存储桶或文件夹批量复制到另一个存储桶或文件夹。

1. 创建身份证明对象以访问源位置。

   缺省情况下，使用 source_credential_name 参数指定的源身份证明名称也用作目标位置的身份证明。

   有关更多信息，请参见 CREATE_CREDENTIAL 。

2. 当源和目标位于不同的对象存储中或具有具有相同云提供商的不同账户时，请创建身份证明以访问目标位置并包括 target_credential_name 参数。

3. 运行 DBMS_CLOUD.BULK_COPY 过程以并行方式将文件从一个对象存储存储桶或文件夹复制到另一个存储桶或文件夹（可以跨云提供商、账户和存储桶）。要运行该过程，您必须以 ADMIN 用户身份登录，或者对 DBMS_CLOUD 具有 EXECUTE 权限。

    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;
    /
   

此示例将文件从一个 Oracle Cloud Infrastructure Object Storage 存储桶批量复制到另一个存储桶。

有关更多信息，请参见 BULK_COPY Procedure 。

有关更多信息，请参见 DBMS_CLOUD Package File Cloud Object Storage URI Formats 。

例如，使用 DBMS_CLOUD.BULK_COPY 将文件从 Amazon S3 复制到 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;
/

跨云对象存储批量移动文件

使用 DBMS_CLOUD.BULK_MOVE 过程将文件从一个云对象存储位置批量移动到另一个云对象存储位置。

移动文件的第一步是将它们复制到目标位置。成功复制文件后，将从源位置删除这些文件。

如果对象存储允许在源位置和目标位置之间重命名操作，则会重命名而不是复制文件。

1. 创建身份证明对象以访问源位置。

   缺省情况下，使用 source_credential_name 参数指定的源身份证明名称也用作目标位置的身份证明。

   有关更多信息，请参见 CREATE_CREDENTIAL 。

2. 当源和目标位于不同的对象存储中或具有具有相同云提供商的不同账户时，请创建身份证明以访问目标位置并包括 target_credential_name 参数。

3. 运行 DBMS_CLOUD.BULK_MOVE 过程以将文件从一个云对象存储位置批量移动到另一个云对象存储位置。要运行该过程，您必须以 ADMIN 用户身份登录，或者对 DBMS_CLOUD 具有 EXECUTE 权限。

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;
/

此示例将文件从一个 Oracle Cloud Infrastructure Object Storage 位置成批移动到另一个位置。

有关更多信息，请参见 BULK_MOVE Procedure 。

有关更多信息，请参见 DBMS_CLOUD Package File Cloud Object Storage URI Formats 。

例如，使用 DBMS_CLOUD.BULK_MOVE 将文件从 Amazon S3 移动到 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;
/

从云对象存储批量下载文件

使用 DBMS_CLOUD.BULK_DOWNLOAD 过程可将文件从云对象存储位置批量下载到自治 AI 数据库中的目录对象。

1. 创建用于访问云对象存储的身份证明。

   凭证名称是使用 credential_name 参数指定的。

   有关更多信息，请参见 CREATE_CREDENTIAL 。

2. 运行 DBMS_CLOUD.BULK_DOWNLOAD 过程以将文件从云对象存储下载到自治 AI 数据库目录中。要运行该过程，您必须以 ADMIN 用户身份登录，或者对 DBMS_CLOUD 具有 EXECUTE 权限。

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;
/

此示例将文件从 Oracle Cloud Infrastructure 对象存储位置 URI 批量下载到自治 AI 数据库中的目录对象。

注：要在目标目录对象中写入文件，必须对目录对象具有 WRITE 权限。

有关更多信息，请参见 BULK_DOWNLOAD Procedure 。

有关更多信息，请参见 DBMS_CLOUD Package File Cloud Object Storage URI Formats 。

将文件批量上载到云对象存储

使用 DBMS_CLOUD.BULK_UPLOAD 过程可将文件从数据库中的目录对象批量上载到云对象存储位置。

1. 创建用于访问云对象存储的身份证明。

   凭证名称是使用 credential_name 参数指定的。

   有关更多信息，请参见 CREATE_CREDENTIAL 。

2. 运行 DBMS_CLOUD.BULK_UPLOAD 过程以将文件从自治 AI 数据库实例上的数据库目录复制到云对象存储。要运行该过程，您必须以 ADMIN 用户身份登录，或者对 DBMS_CLOUD 具有 EXECUTE 权限。

    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;
    /
   

   此示例将文件从目录对象批量上载（使用 directory_name 参数指定）到 Oracle Cloud Infrastructure 对象存储位置 URI。

   注：要读取目录对象中的源文件，必须对目录对象具有 READ 权限。

   有关更多信息，请参见 BULK_UPLOAD Procedure 。

从云对象存储批量删除文件

使用 DBMS_CLOUD.BULK_DELETE 过程从云对象存储中批量删除文件。

1. 创建用于访问云对象存储的身份证明。

   凭证名称是使用 credential_name 参数指定的。

   对于公共存储桶、预验证存储桶或预签名存储桶 URI，credential_name 可以是 NULL。

   有关更多信息，请参见 CREATE_CREDENTIAL 。

2. 运行 DBMS_CLOUD.BULK_DELETE 过程以从云对象存储中删除文件。要运行该过程，您必须以 ADMIN 用户身份登录，或者对 DBMS_CLOUD 具有 EXECUTE 权限。

    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;
    /
   

   此示例从 Oracle Cloud Infrastructure 对象存储中批量删除文件。

   有关更多信息，请参见 BULK_DELETE Procedure 。

   有关更多信息，请参见 DBMS_CLOUD Package File Cloud Object Storage URI Formats 。

监视成批文件加载并对其进行故障排除

所有 DBMS_CLOUD 数据加载操作都记录在 dba_load_operations 和 user_load_operations 视图中。

可以使用以下视图对批量文件加载进行监视和故障排除：

• dba_load_operations：显示所有装入操作。

• user_load_operations：显示方案中的加载操作。

查询这些视图可查看有关正在进行的和已完成的批量文件操作的信息。例如，在 TYPE 上具有 WHERE 子句谓词的以下 SELECT 语句显示 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

STATUS_TABLE 列显示您可以查询的表的名称，以便查看批量下载操作的详细日志记录信息。例如：

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

状态表显示批量操作的每个文件名及其状态。

如果对特定文件的操作失败，相关错误号和消息将记录在状态表中。

对于已完成的操作，可以使用报告的 START_TIME 和 END_TIME 时间计算每个操作所需的时间。

文件操作 STATUS 列可以具有以下值之一：

文件状态	说明
COMPLETED	文件操作已成功完成。
FAILED	文件操作失败，可以尝试重试两次。
PENDING	文件操作尚未启动。
RUNNING	文件操作当前正在进行中。
SKIPPED	已跳过文件操作。

如果任何文件操作在两次重试尝试后失败，则将批量操作标记为失败并引发错误。例如：

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

使用 DBMS_CLOUD 批量文件操作时，存在控制状态表的 format 参数选项：

• logretention：指定一个整数值，用于确定状态表保留的持续时间（天）。默认值为 2 天。

• logprefix：指定用于确定批量操作状态表的名称前缀的字符串值。

  每个批量操作都有其自己的 logprefix 选项默认值：

  过程	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

有关清除 user_load_operations 表的信息，请参见 DELETE_ALL_OPERATIONS Procedure 。

相关内容

用于批量文件管理的 DBMS_CLOUD