雲端檔案的大量作業

PL/SQL 套裝程式 DBMS_CLOUD 提供大量檔案上傳、下載、複製及傳輸活動的平行執行支援,可簡化使用者體驗,並為大量檔案作業提供最佳效能。

套裝軟體 DBMS_CLOUD 支援將檔案載入及卸載至下列雲端服務:

  • Oracle Cloud Infrastructure Object Storage

  • Azure Blob 儲存體

  • Amazon S3

  • Google Cloud Storage

如需詳細資訊,請參閱 DBMS_CLOUD Package File URI Format

關於大量檔案作業

DBMS_CLOUD 大量檔案作業支援在 Autonomous Database 上下載和上傳檔案,包括支援在相同物件存放區提供者內或在物件存放區提供者之間,跨雲端物件存放區複製、移動及刪除檔案。

大量檔案作業支援平行程度,並提供上傳、下載、複製及移動檔案的最佳效能。大量檔案作業的平行程度,是藉由指定作業的優先順序來處理。支援的優先順序為:

  • HIGH:使用 Autonomous Database 執行處理 CPU 運算計數來判斷處理的平行檔案數目。
  • MEDIUM:使用「中」服務的並行限制來判斷平行程度。
  • LOW:依序處理檔案 (無並行)。

以更高的優先順序執行大量作業時,當平行程度可加速作業時,會使用更多的資料庫資源與作業更快完成。較低的優先順序耗用較少的資料庫資源,而當平行程度可加速作業時,作業需要較長的時間完成。當大量作業涉及少量資料的檔案時,指定較高的優先順序可能不會變更效能。

若要增加大量檔案作業的平行程度,請使用 HIGH 優先順序並增加指派給 Autonomous Database 執行處理的 CPU 數目。大量檔案作業支援的並行檔案作業上限為 64。

預設優先順序為 MEDIUM,指定大量檔案作業使用為 MEDIUM 用戶群組定義的並行限制。

請參閱 DBMS_CLOUD for Bulk File Management ,瞭解使用 format 參數指定 priority 與大量檔案作業的詳細資訊。

在下面討論的 DBMS_CLOUD 子程式中,credential_namesource_credential_nametarget_credential_name 可以是 NULL,適用於公用、預先認證或預先簽署的儲存桶 URI。

大量複製雲端物件儲存中的檔案

使用 DBMS_CLOUD.BULK_COPY 程序,將檔案從一個物件存放區儲存桶或資料夾大量複製到另一個儲存桶或資料夾。

  1. 建立證明資料物件以存取來源位置。

    依照預設,使用 source_credential_name 參數指定的來源證明資料名稱也會作為目標位置的證明資料。

    如需詳細資訊,請參閱 CREATE_CREDENTIAL

  2. 當來源和目標位於不同的物件存放區,或具有相同雲端提供者的不同帳戶時,請建立證明資料以存取目標位置並包含 target_credential_name 參數。
  3. 執行 DBMS_CLOUD.BULK_COPY 程序,將檔案從一個物件存放區儲存桶或資料夾平行複製到另一個儲存桶或資料夾,這些儲存桶或資料夾可跨雲端提供者、帳戶和儲存桶。若要執行此程序,您必須以 ADMIN 使用者身分登入,或具備 DBMS_CLOUDEXECUTE 權限。
    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 程序

    如需詳細資訊,請參閱 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_CLOUDEXECUTE 權限。
    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 程序

    如需詳細資訊,請參閱 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 程序,將檔案從雲端物件存放區位置大量下載至 Autonomous Database 中的目錄物件。

  1. 建立證明資料以存取您的雲端物件儲存。

    使用 credential_name 參數指定證明資料名稱。

    如需詳細資訊,請參閱 CREATE_CREDENTIAL

  2. 執行 DBMS_CLOUD.BULK_DOWNLOAD 程序,從雲端物件儲存將檔案下載至 Autonomous Database 目錄。若要執行此程序,您必須以 ADMIN 使用者身分登入,或具備 DBMS_CLOUDEXECUTE 權限。
    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 Object Store 位置 URI 中的檔案大量下載至 Autonomous Database 中的目錄物件。

    附註:

    若要在目標目錄物件中寫入檔案,您必須要有目錄物件的 WRITE 權限。

    如需詳細資訊,請參閱BULK_DOWNLOAD 程序

    如需詳細資訊,請參閱 DBMS_CLOUD Package File Cloud Object Storage URI Formats

大量上傳檔案至雲端物件儲存

您可以使用 DBMS_CLOUD.BULK_UPLOAD 程序,將檔案從資料庫中的目錄物件大量上傳至「雲端物件存放區」位置。

  1. 建立證明資料以存取您的雲端物件儲存。

    使用 credential_name 參數指定證明資料名稱。

    如需詳細資訊,請參閱 CREATE_CREDENTIAL

  2. 執行 DBMS_CLOUD.BULK_UPLOAD 程序,從 Autonomous Database 執行處理的資料庫目錄將檔案複製到雲端物件儲存。若要執行此程序,您必須以 ADMIN 使用者身分登入,或具備 DBMS_CLOUDEXECUTE 權限。
    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 程序

大量刪除雲端物件儲存中的檔案

您可以使用 DBMS_CLOUD.BULK_DELETE 程序大量刪除雲端物件儲存中的檔案。

  1. 建立證明資料以存取您的雲端物件儲存。

    使用 credential_name 參數指定證明資料名稱。

    對於公用、預先認證或預先簽署的儲存桶 URI,credential_name 可以是 NULL

    如需詳細資訊,請參閱 CREATE_CREDENTIAL

  2. 執行 DBMS_CLOUD.BULK_DELETE 程序,從「雲端物件存放區」刪除檔案。若要執行此程序,您必須以 ADMIN 使用者身分登入,或具備 DBMS_CLOUDEXECUTE 權限。
    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 程序

    如需詳細資訊,請參閱 DBMS_CLOUD Package File Cloud Object Storage URI Formats

監督及疑難排解大量檔案載入

所有 DBMS_CLOUD 資料載入作業都會記錄在 dba_load_operationsuser_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_TIMEEND_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

請參閱 DELETE_ALL_OPERATIONS 程序,瞭解清除 user_load_operations 表格的資訊。