Oracle Cloud Infrastructureドキュメント

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

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

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

  • Oracle Cloud Infrastructure Object Storage

  • Azure Blob StorageまたはAzure Data Lake Storage

  • Amazon S3

  • Amazon S3対応(Wasabi Hot Cloud Storageを含む)

  • Google Cloud Storage

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

バルク・ファイル操作について

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

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

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

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

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

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

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

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

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

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

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;
/

Cloud Object Storageからのファイル一括ダウンロード

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

バルク・ファイル操作のノート

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

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

    • Oracle Cloud Infrastructureのリソース・プリンシパル

    • AWS Amazon Resource Name (ARN)

    • Azureサービス・プリンシパル

    • Googleサービス・アカウント

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

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