Oracle Cloud Infrastructureドキュメント

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

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

パッケージDBMS_CLOUDは、次のクラウド・サービスへのファイルのロードおよびアンロードをサポートしています:

  • Oracle Cloud Infrastructure Object Storage

  • Azure Blob Storage

  • Amazon S3

  • Amazon S3互換(Wasabi Hot Cloud Storageを含む)

  • Google Cloud Storage

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

親トピック: ファイルの移動

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

DBMS_CLOUDの一括ファイル操作では、同じオブジェクト・ストア・プロバイダ内またはオブジェクト・ストア・プロバイダ間でのクラウド・オブジェクト・ストア間でのファイルのコピー、移動および削除のサポートなど、Autonomous Databaseでのファイルのダウンロードおよびアップロードがサポートされます。

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

  • HIGH: Autonomous DatabaseインスタンスのCPUコンピュート数を使用して、処理されるパラレル・ファイルの数を決定します。
  • MEDIUM: Mediumサービスの同時実行性の制限を使用して、並列性を判断します。
  • LOW: ファイルを順番に処理します(同時実行性なし)。

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

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

デフォルトの優先度はMEDIUMで、バルク・ファイル操作でMEDIUMコンシューマ・グループに定義された同時実行性の制限が使用されるように指定します。詳細は、Autonomous Databaseでの同時実行性および優先度の管理を参照してください。

See DBMS_CLOUD for Bulk File Management for details on using the format parameter to specify the priority with bulk file operations.

クラウド・オブジェクト・ストレージのファイルの一括コピー

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

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

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

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

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

    ノート

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

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

    詳細は、DBMS_CLOUD URI形式を参照してください。

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

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

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

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

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

  2. DBMS_CLOUD.BULK_UPLOADプロシージャを実行して、Autonomous 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 Object Storeの場所URIに一括アップロードします。

    ノート

    ディレクトリ・オブジェクト内のソース・ファイルを読み取るには、ディレクトリ・オブジェクトに対するREAD権限が必要です。

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

クラウド・オブジェクト・ストレージからのファイルの一括削除

DBMS_CLOUD.BULK_DELETEプロシージャを使用して、クラウド・オブジェクト・ストレージからファイルを一括削除します。

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

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

    credential_nameは、パブリックまたは事前認証済または事前署名済バケット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 Object Storeからファイルを一括削除します。

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

    詳細は、DBMS_CLOUD URI形式を参照してください。

一括ファイル・ロードのモニターおよびトラブルシューティング

すべてのDBMS_CLOUDデータ・ロード操作は、dba_load_operationsビューおよびuser_load_operationsビューに記録されます。

次のビューを使用して、バルク・ファイル・ロードを監視およびトラブルシューティングできます。

  • dba_load_operations: すべてのロード操作が表示されます。

  • user_load_operations: 自分のスキーマのロード操作が表示されます。

これらのビューを問い合せて、進行中および完了したバルク・ファイル操作に関する情報を確認します。たとえば、WHERE句述語でTYPEを指定した次の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プロシージャを参照してください。

一括ファイル操作のノート

バルク・ファイル操作で使用する資格証明に関するノートを提供します。

  • credential_name、source_credential_nameまたはtarget_credential_nameパラメータとしてプリンシパルを指定すると、ユーザー資格証明を格納せずにクラウド・リソースに安全にアクセスできます。サポートされているプリンシパルは次のとおりです。

    • Oracle Cloud Infrastructureリソース・プリンシパル
    • AWS Amazon Resource Name (ARN)s
    • Azureサービス・プリンシパル
    • Googleサービス・アカウント

    詳細は、リソースにアクセスするためのポリシーとロールの構成を参照してください。

  • credential_name、source_credential_nameまたはtarget_credential_nameは、パブリック、事前認証済または事前署名済バケットURIに対してNULLにできます。