雲端檔案大量作業

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

套裝軟體 DBMS_CLOUD 支援將檔案載入及取消載入下列雲端服務：

• Oracle Cloud Infrastructure Object Storage

• Azure Blob 儲存

• Amazon S3

• Google 雲端儲存

請參閱 DBMS_CLOUD 套裝程式檔案 URI 格式以瞭解詳細資訊。

關於大量檔案作業

DBMS_CLOUD 大量檔案作業支援在自治式 AI 資料庫上下載和上傳檔案，包括支援在相同物件存放區提供者內或物件存放區提供者之間，跨雲端物件存放區複製、移動及刪除檔案。

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

• HIGH：使用自治式 AI 資料庫執行處理 CPU 運算數目來判斷處理的平行檔案數目。

• MEDIUM：使用「中」服務的並行限制來判斷平行程度。

• LOW：以序列順序處理檔案 (無並行)。

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

若要提高大量檔案作業的平行程度，請使用 HIGH 優先順序並增加指定給自治式 AI 資料庫執行處理的 CPU 數目。大量檔案作業支援的並行檔案作業上限為 64。

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

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

在下面討論的 DBMS_CLOUD 子程式中，credential_name、source_credential_name 或 target_credential_name 可以是公用、預先認證或預先簽署儲存桶 URI 的 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 程序以瞭解詳細資訊。

請參閱 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 程序，從 Cloud Object Storage 將檔案下載至 Autonomous AI 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 大量下載至自治式 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 程序以瞭解詳細資訊。

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

請使用 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 程序以瞭解詳細資訊。

   請參閱 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

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

相關內容

大量檔案管理的 DBMS_CLOUD