クラウド内のファイルの一括操作

PL/SQLパッケージDBMS_CLOUDは、バルク・ファイルのアップロード、ダウンロード、コピーおよび転送アクティビティに対するパラレル実行サポートを提供します。これにより、ユーザー・エクスペリエンスが合理化され、バルク・ファイル操作に最適なパフォーマンスが得られます。

パッケージDBMS_CLOUDでは、次のクラウド・サービスへのファイルのロードおよびアンロードがサポートされます。

• Oracle Cloud Infrastructure Object Storage

• Azure Blobストレージ

• Amazon S3

• Google Cloudストレージ

詳細は、DBMS_CLOUDパッケージ・ファイルのURI形式を参照してください。

一括ファイル操作について

DBMS_CLOUDバルク・ファイル操作は、Autonomous AI Databaseでのファイルのダウンロードとアップロードをサポートします。これには、同じオブジェクト・ストア・プロバイダ内またはオブジェクト・ストア・プロバイダ間のクラウド・オブジェクト・ストア間でファイルをコピー、移動および削除するためのサポートが含まれます。

バルク・ファイル操作は並列性をサポートし、ファイルのアップロード、ダウンロード、コピーおよび移動に最適なパフォーマンスを提供します。一括ファイル操作の並列性は、操作の優先度を指定することによって処理されます。サポートされる優先順位は次のとおりです。

• HIGH: Autonomous AI DatabaseインスタンスのCPUコンピュート数を使用して、処理されたパラレル・ファイルの数を決定します。

• MEDIUM: 中型サービスの同時実行性制限を使用して、並列性を判断します。

• LOW: ファイルを順番に処理します(同時実行性なし)。

優先度の高いバルク操作の実行では、より多くのデータベース・リソースが使用され、パラレル化によって操作が高速化される場合は、より高速に操作が完了します。優先度が低いほどデータベース・リソースが消費され、パラレル化によって操作を高速化できる場合、操作の完了に時間がかかります。バルク操作に少数のデータを含むファイルが含まれる場合、優先度を高く指定してもパフォーマンスは変わりません。

バルク・ファイル操作の並列性を高めるには、HIGH優先度を使用し、Autonomous AI Databaseインスタンスに割り当てられているCPUの数を増やします。バルク・ファイル操作では、サポートされる同時ファイル操作の最大数は64に制限されます。

デフォルトの優先度はMEDIUMで、バルク・ファイル操作でMEDIUMコンシューマ・グループに対して定義された同時実行性制限を使用することを指定します。

formatパラメータを使用してバルク・ファイル操作でpriorityを指定する方法の詳細は、「バルク・ファイル管理用のDBMS_CLOUD」を参照してください。

次に示す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パッケージ・ファイル・クラウド・オブジェクト・ストレージのURI形式を参照してください。

たとえば、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プロシージャを参照してください。

詳細は、DBMS_CLOUDパッケージ・ファイル・クラウド・オブジェクト・ストレージのURI形式を参照してください。

たとえば、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 AI Databaseのディレクトリ・オブジェクトにファイルを一括ダウンロードします。

1. クラウド・オブジェクト・ストレージにアクセスするための資格証明を作成します。

   資格証明名は、credential_nameパラメータで指定します。

   詳細は、CREATE_CREDENTIALを参照してください。

2. DBMS_CLOUD.BULK_DOWNLOADプロシージャを実行して、クラウド・オブジェクト・ストレージから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からAutonomous AI Databaseのディレクトリ・オブジェクトにファイルを一括ダウンロードします。

ノート:ターゲット・ディレクトリ・オブジェクトにファイルを書き込むには、ディレクトリ・オブジェクトに対するWRITE権限が必要です。

詳細は、BULK_DOWNLOADプロシージャを参照してください。

詳細は、DBMS_CLOUDパッケージ・ファイル・クラウド・オブジェクト・ストレージのURI形式を参照してください。

ファイルをクラウド・オブジェクト・ストレージに一括アップロード

DBMS_CLOUD.BULK_UPLOADプロシージャを使用して、データベースのディレクトリ・オブジェクトからクラウド・オブジェクト・ストアの場所にファイルを一括アップロードします。

1. クラウド・オブジェクト・ストレージにアクセスするための資格証明を作成します。

   資格証明名は、credential_nameパラメータで指定します。

   詳細は、CREATE_CREDENTIALを参照してください。

2. DBMS_CLOUD.BULK_UPLOADプロシージャを実行して、Autonomous AI Databaseインスタンスのデータベース・ディレクトリからクラウド・オブジェクト・ストレージにファイルをコピーします。プロシージャを実行するには、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パラメータで指定します。

   credential_nameは、パブリック・バケットURI、事前認証済バケットURIまたは事前署名済バケットURIに対して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パッケージ・ファイル・クラウド・オブジェクト・ストレージのURI形式を参照してください。

バルク・ファイル・ロードの監視およびトラブルシューティング

すべての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	ファイル操作に失敗しました。再試行を2回試行できます。
PENDING	ファイル操作はまだ開始されていません。
RUNNING	ファイル操作は現在進行中です。
SKIPPED	ファイル操作がスキップされました。

2回の再試行後にファイル操作が失敗した場合、バルク操作は失敗としてマークされ、エラーが発生します。たとえば:

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プロシージャを参照してください。

関連コンテンツ

バルク・ファイル管理のためのDBMS_CLOUD