云中文件的批量操作

关于批量文件操作

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

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

HIGH：使用 Autonomous Database 实例 CPU 计算计数确定处理的并行文件数。
MEDIUM：使用中等服务的并发限制来确定并行度。
LOW：按序列顺序处理文件（无并发）。

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

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

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

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

在下面讨论的 DBMS_CLOUD 子程序中，对于 public、Pre-authenticated 或 Pre-signed 存储桶 URI，credential_name、source_credential_name 或 target_credential_name 可以为 NULL。

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

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

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

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

有关更多信息，请参见 CREATE_CREDENTIAL 。
当源和目标位于不同的对象存储中或者具有具有相同云提供商的不同账户时，请创建身份证明以访问目标位置并包括 target_credential_name 参数。
运行 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 对象存储桶批量复制到另一个存储桶。

有关更多信息，请参见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 过程可以将文件从一个云对象存储位置批量移动到另一个云对象存储位置。

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

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

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

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

有关更多信息，请参见 CREATE_CREDENTIAL 。
当源和目标位于不同的对象存储中或者具有具有相同云提供商的不同账户时，请创建身份证明以访问目标位置并包括 target_credential_name 参数。
运行 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 对象存储位置移动到另一个位置。

有关更多信息，请参见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 过程将文件从 Cloud Object Store 位置批量下载到 Autonomous Database 中的目录对象。

创建身份证明以访问云对象存储。

使用 credential_name 参数指定身份证明名称。

有关更多信息，请参见 CREATE_CREDENTIAL 。
运行 DBMS_CLOUD.BULK_DOWNLOAD 过程，将文件从 Cloud Object Storage 下载到 Autonomous Database 目录中。要运行该过程，您必须以 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 批量下载到 Autonomous Database 中的目录对象。

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

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

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

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

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

创建身份证明以访问云对象存储。

使用 credential_name 参数指定身份证明名称。

有关更多信息，请参见 CREATE_CREDENTIAL 。
运行 DBMS_CLOUD.BULK_UPLOAD 过程，将文件从 Autonomous Database 实例上的数据库目录复制到 Cloud Object Storage 中。要运行该过程，您必须以 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 过程从云对象存储中批量删除文件。

创建身份证明以访问云对象存储。

使用 credential_name 参数指定身份证明名称。

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

有关更多信息，请参见 CREATE_CREDENTIAL 。
运行 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 。