DBMS_CLOUDサブプログラムおよびREST API

データのロードやクラウド内の外部データの問合せを行う場合は、または他のケースでDBMS_CLOUDプロシージャをcredential_nameパラメータとともに使用する場合、格納されているクラウド・サービス資格証明を使用して、クラウド・サービスにアクセスします。このプロシージャはオーバーロードされています。

• Oracle Cloud Infrastructure関連のパラメータ(user_ocid、tenancy_ocid、private_key、fingerprintなど)は、Oracle Cloud Infrastructure署名キー認証を使用している場合にのみ使用します。

• paramsパラメータは、次のいずれかに使用します。

  • Amazonリソース名(ARN)資格証明

  • Google AnalyticsまたはGoogle BigQuery資格証明

  • サポートされているボールトで使用するVaultシークレット資格証明:

    • Oracle Cloud Infrastructure Vault
    • Azureキー・ボールト
    • AWSシークレット・マネージャ
    • GCPシークレット・マネージャ

構文

DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name   IN VARCHAR2,
      username          IN VARCHAR2,
      password          IN VARCHAR2 DEFAULT NULL,
      comments          IN VARCHAR2 DEFAULT NULL);


DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name   IN VARCHAR2,
      user_ocid         IN VARCHAR2,
      tenancy_ocid      IN VARCHAR2,
      private_key       IN VARCHAR2,
      fingerprint       IN VARCHAR2,
      comments          IN VARCHAR2 DEFAULT NULL);


DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name  IN VARCHAR2,
      params           IN CLOB DEFAULT);

パラメータ

使用上のノート

• この操作によって、資格証明が暗号化された形式でデータベースに格納されます。

• ユーザーは、user_credentials表を問い合せることにより、自分のスキーマ内の資格証明を確認できます。

• user_credentials表を問い合せると、スキーマ内のクレデンシャル・コメントを確認できます。たとえば:

  SELECT comments FROM user_credentials
          WHERE credential_name = 'MY_CRED';

• ADMINユーザーは、dba_credentials表を問い合せることにより、すべての資格証明を表示できます。

• クラウド・サービス資格証明が変更されないかぎり、資格証明を作成する必要があるのは1回のみです。資格証明をいったん格納したら、credential_nameパラメータを必要とするDBMS_CLOUDプロシージャに対して同じ資格証明名を使用できます。

• このプロシージャはオーバーロードされています。キー・ベースの認証属性user_ocid、tenancy_ocid、private_keyまたはfingerprintのいずれかを指定すると、コールはOracle Cloud Infrastructure署名キー・ベースの資格証明であるとみなされます。

• ALL_CREDENTIALSビューから資格証明をリストできます。たとえば、次のコマンドを実行して資格証明をリストします。

  SELECT credential_name, username, comments FROM all_credentials;

Oracle Cloud Infrastructure資格証明(認証トークン)

Oracle Cloud Infrastructureの場合、usernameはOracle Cloud Infrastructureのユーザー名です。passwordはOracle Cloud Infrastructureの認証トークンです。認証トークンの作業を参照してください。

たとえば:

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'DEF_CRED_NAME',
    username => 'adb_user@example.com',
    password => 'password' );
END;
/

OCIオブジェクト・ストレージへのコールを認証する場合は、認証トークン・ベースの資格証明を使用します。他のタイプのOracle Cloud Infrastructureクラウド・サービスへのコールには、Oracle Cloud Infrastructure署名キー・ベースの資格証明を使用します。

OCIオブジェクト・ストレージの場合、usernameパラメータ値には、アイデンティティ・ドメインとプロファイルのユーザー名を含める必要があります。ユーザーに関連付けられたアイデンティティ・ドメインは、Oracle Cloud Infrastructure Consoleにあります。

たとえば:

oracleidentitycloudservice/adb_user@example.com

デフォルトのアイデンティティ・ドメインでは、ドメイン名Defaultを含める必要はありません。たとえば:

adb_user@example.com

Oracle Cloud Infrastructure署名キー・ベースの資格証明

Oracle Cloud Infrastructure署名キー認証では、user_ocid、tenancy_ocid、private_keyおよびfingerprintなど、Oracle Cloud Infrastructure署名キー関連のパラメータを使用します。

たとえば:

BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL (
       credential_name => ‘OCI_KEY_CRED’,
       user_ocid       => ‘ocid1.user.oc1..aaaaaaaauq54mi7zdyfhw33ozkwuontjceel7fok5nq3bf2vwetkpqsoa’,
       tenancy_ocid    => ‘ocid1.tenancy.oc1..aabbbbbbaafcue47pqmrf4vigneebgbcmmoy5r7xvoypicjqqge32ewnrcyx2a’,
       private_key     => ‘MIIEogIBAAKCAQEAtUnxbmrekwgVac6FdWeRzoXvIpA9+0r1.....wtnNpESQQQ0QLGPD8NM//JEBg=’,
       fingerprint     => ‘f2:db:f9:18:a4:aa:fc:94:f4:f6:6c:39:96:16:aa:27’);
END;
/

パスフレーズを設定して生成された秘密キーはサポートされていません。パスフレーズなしで秘密キーを生成する必要があります。詳細は、API署名キーの生成方法を参照してください。

Oracle Cloud Infrastructure Object Storage Classicの資格証明

ソース・ファイルがOracle Cloud Infrastructure Object Storage Classicに存在する場合、usernameはOracle Cloud Infrastructure Classicのユーザー名で、passwordはOracle Cloud Infrastructure Classicのパスワードです。

Amazon Web Services (AWS)の資格証明

ソース・ファイルがAmazon S3に存在する場合、またはAWS APIをコールしている場合、usernameはAWSのアクセス・キーIDで、passwordはAWSのシークレット・アクセス・キーです。AWS Identity and Access Managementを参照してください。

Microsoft Azureの資格証明

ソース・ファイルがAzure Blob StorageまたはAzure Data Lake Storageにある場合、またはAzure APIをコールしている場合、passwordはAzureストレージ・アカウント名になり、usernameはAzureストレージ・アカウント・アクセス・キーとなります。Azureストレージ・アカウントについてを参照してください。

Amazon S3互換の資格証明

AWS Amazon Resource Name (ARN)の資格証明

ソース・ファイルがAmazon S3にあるか、AWS APIをコールする場合、paramsを使用してAmazon Resource Names (ARN)についてのパラメータを指定してください。

たとえば:

BEGIN DBMS_CLOUD.CREATE_CREDENTIAL(
        credential_name      => 'MY_CRED',
        params               => JSON_OBJECT(
               'aws_role_arn'      value 'arn:aws:iam::123456:role/AWS_ROLE_ARN',
               'external_id_type'  value 'database_ocid'));
END;
/

GitHubの個人アクセス・トークン

ソース・ファイルがGitHubリポジトリにある場合、またはGitHub APIをコールする場合、usernameはGitHubの電子メールで、passwordはGitHubの個人アクセス・トークンです。詳細は、「個人用アクセス トークンの作成」を参照してください。

たとえば:

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'MY_GITHUB_CRED',
    username => 'user@example.com',
    password => 'your_personal_access_token' );
END;
/

Google AnalyticsまたはGoogle BigQuery資格証明

Google AnalyticsまたはGoogle BigQueryにアクセスする場合は、paramsパラメータを使用して、Google OAuth 2.0資格証明パラメータを指定します。

たとえば:

BEGIN DBMS_CLOUD.CREATE_CREDENTIAL(
      credential_name => 'GOOGLE_BIGQUERY_CRED',
      params => JSON_OBJECT('gcp_oauth2' value 
                                  JSON_OBJECT(
                                       'client_id'     value 'client_id',
                                       'client_secret' value 'client_secret',
                                       'refresh_token' value 'refresh_token' )));
END;
/

Oracle Cloud Infrastructure VaultでのVaultシークレット資格証明

Oracle Cloud Infrastructure Vaultでボールト・シークレット資格証明を作成するには、paramsパラメータを使用して必須パラメータを指定します:

• username: OCI Swiftパスワードのユーザー名など、任意のタイプのユーザー名/パスワード資格証明のユーザー名を指定します。たとえば、ユーザー名がscott、パスワードがpasswordのSwift資格証明がある場合は、usernameパラメータとしてscottを指定します。

• secret_id: ボールト・シークレットIDです。ボールト・シークレットOCIDとしてsecret_id値を指定します。詳細は、Vaultの概要を参照してください。

• region: oracleクラウド・リージョン識別子を指定するオプションのパラメータです。リージョンが指定されている場合は、Oracle Cloud Infrastructure Vaultシークレットが存在する場所を示します。

  デフォルトでは、CREATE_CREDENTIALは、secret_idのリージョン・キーからマップされたregionを使用します。リージョンの例として、us-ashburn-1があります。

  リージョンの完全なリストは、「リージョンおよび可用性ドメイン」を参照してください。

たとえば:

BEGIN DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'OCI_SECRET_CRED',
    params => JSON_OBJECT( 
                'username'   value 'scott',
                'region'     value 'us-ashburn-1',
                'secret_id'  value 'ocid1.vaultsecret.co1.ap-mumbai-1.example..aaaaaaaauq5ok5nq3bf2vwetkpqsoa'));
END;
/

Oracle Cloud Infrastructure Vaultシークレットを使用してボールト・シークレットを格納するためのノート:

• Oracle Cloud Infrastructure Vaultを使用する場合、Autonomous AI Databaseインスタンスで、DBMS_CLOUD_ADMIN.ENABLE_RESOURCE_PRINCIPALを使用してプリンシパル認証を有効にする必要があります。

• Oracle Cloud Infrastructureでは、シークレットにアクセスするためのリソース・プリンシパルのポリシーを指定する必要があります。

ボールト・シークレット資格証明を作成するには、DBMS_CLOUDパッケージに対するEXECUTE権限が必要です。

Azure Key Vaultを使用したVaultシークレット資格証明

Azure Key Vault資格証明を作成するには、paramsパラメータを使用して必須パラメータを指定します:

• username: キーに関連付けられたユーザー名を指定します。

• secret_id: シークレット名を指定します。

• azure_vault_name: シークレットがあるボールトの名前を指定します。

詳細は、キー・ボールトの作成を参照してください。

ボールト・シークレット資格証明を作成するには、DBMS_CLOUDパッケージに対するEXECUTE権限が必要です。

AWSシークレット・マネージャを使用したVaultシークレット資格証明

AWSシークレット・マネージャを使用してボールト・シークレット資格証明を作成するには、paramsパラメータを使用して必須パラメータを指定します:

• username: AWSシークレット・マネージャのアクセス・キーを指定します。

• secret_id: AWSシークレット・マネージャAWS ARNです。

• region: (オプション)ボールトおよびシークレットがあるAWSサービス・リージョンを指定します。AWSリージョンの例は「us-east-2」です。デフォルトのregionは、secret_idパラメータのARNで指定されたリージョンです。

  詳細は、AWSリージョンの管理を参照してください。

  ボールト・シークレット資格証明を作成するには、DBMS_CLOUDパッケージに対するEXECUTE権限が必要です。

GCPシークレット・マネージャを使用したVaultシークレット資格証明

GCPシークレット・マネージャ資格証明を作成するには、paramsパラメータを使用して必須パラメータを指定します:

• username: シークレットに関連付けられたユーザー名を指定します。

• secret_id: シークレット名です。

• gcp_project_id: シークレットがあるプロジェクトのIDを指定します。

詳細は、シークレット・マネージャを参照してください。

ボールト・シークレット資格証明を作成するには、DBMS_CLOUDパッケージに対するEXECUTE権限が必要です。

構文

DBMS_CLOUD.DROP_CREDENTIAL (
   credential_name     IN VARCHAR2);

パラメータ

このプロシージャを使用すると、ボールト・シークレット資格証明のボールト・シークレットをすぐにリフレッシュして、指定したcredential_nameのボールト・シークレットの最新バージョンを取得できます。

構文

DBMS_CLOUD.REFRESH_VAULT_CREDENTIAL (
    credential_name   IN VARCHAR2);

パラメータ

使用上のノート

• ADMINユーザーは、dba_credentials表を問い合せることにより、すべての資格証明を表示できます。

• ALL_CREDENTIALSビューから資格証明をリストできます。たとえば、次のコマンドを実行して資格証明をリストします。

  SELECT credential_name, username, comments FROM all_credentials;

例

BEGIN
  DBMS_CLOUD.REFRESH_VAULT_CREDENTIAL(
     credential_name => 'AZURE_SECRET_CRED'); 
END;
/

データのロード、クラウド内の外部データの問合せ、またはDBMS_CLOUDプロシージャのcredential_nameパラメータとともに使用する場合は、格納されている資格証明を使用します。

構文

DBMS_CLOUD.UPDATE_CREDENTIAL (
    credential_name   IN VARCHAR2,
    attribute         IN VARCHAR2,
    value             IN VARCHAR2);

パラメータ

使用上のノート

• ユーザー名の値では大文字と小文字が区別されます。二重引用符や空白を含めることはできません。

• ADMINユーザーは、dba_credentialsを問い合せることにより、すべての資格証明を参照できます。

• クラウド・サービス資格証明が変更されないかぎり、資格証明を作成する必要があるのは1回のみです。資格証明をいったん格納したら、credential_nameパラメータを必要とするDBMS_CLOUDプロシージャに対して同じ資格証明名を使用できます。

• ALL_CREDENTIALSビューから資格証明をリストできます。たとえば、次のコマンドを実行して資格証明をリストします。

  SELECT credential_name, username, comments FROM all_credentials;

例

BEGIN
  DBMS_CLOUD.UPDATE_CREDENTIAL(
     credential_name => 'OBJ_STORE_CRED',
     attribute => 'PASSWORD',
     value => 'password'); 
END;
/

BEGIN
  DBMS_CLOUD.UPDATE_CREDENTIAL(
     credential_name => 'ARN_CRED',
     attribute => 'aws_role_arn',
     value => 'NEW_AWS_ARN'); 
END;
/

構文

DBMS_CLOUD.COPY_COLLECTION (
    collection_name   IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    format            IN CLOB     DEFAULT NULL
);

DBMS_CLOUD.COPY_COLLECTION (
    collection_name   IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    format            IN CLOB     DEFAULT NULL,
    operation_id      OUT NOCOPY NUMBER
);

パラメータ

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

例

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'OBJ_STORE_CRED',
            username        => 'user_name@oracle.com',
            password        => 'password'
            );

    DBMS_CLOUD.COPY_COLLECTION(
            collection_name => 'myCollection',
            credential_name => 'OBJ_STORE_CRED',
            file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/adbexample/b/json/o/myCollection.json'  
            );
END;
/

構文

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    schema_name       IN VARCHAR2,
    field_list        IN CLOB,
    format            IN CLOB);

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB DEFAULT NULL,
    schema_name       IN VARCHAR2 DEFAULT NULL,
    field_list        IN CLOB DEFAULT NULL,
    format            IN CLOB DEFAULT NULL
    operation_id      OUT NOCOPY NUMBER);

パラメータ

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

使用上のノート

デフォルトのレコード・デリミタはdetected newlineです。detected newlineを指定すると、DBMS_CLOUDは、レコード・デリミタとして使用する適切な改行文字を自動的に見つけようとします。DBMS_CLOUDは、最初にWindowsの改行文字\r\nを検索します。Windowsの改行文字が見つかると、それがプロシージャのすべてのファイルのレコード・デリミタとして使用されます。Windowsの改行文字が見つからない場合、DBMS_CLOUDは、UNIX/Linuxの改行文字\nを検索し、見つかった場合は\nがプロシージャのすべてのファイルのレコード・デリミタとして使用されます。ソース・ファイルで異なるレコード・デリミタの組合せが使用されている場合は、KUP-04020: found record longer than buffer size supportedなどのエラーが発生する可能性があります。この場合、同じレコード・デリミタを使用するようにソース・ファイルを変更するか、同じレコード・デリミタを使用するソース・ファイルのみを指定する必要があります。

recorddelmiterフォーマット・オプションの詳細は、「DBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。

例

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'DEF_CRED_NAME',
            username        => 'user_name@oracle.com',
            password        => 'password'
            );
END;
/

BEGIN
 DBMS_CLOUD.COPY_DATA(
    table_name =>'CHANNELS',
    credential_name =>'DEF_CRED_NAME',
    file_uri_list =>'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/channels.txt',
    format => json_object('delimiter' value ',')
 );
END;
/

BEGIN
    DBMS_CLOUD.COPY_DATA(
            table_name      => 'ORDERS',
            schema_name     => 'TEST_SCHEMA',
            credential_name => 'DEF_CRED_NAME',
	     file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/adbexample/b/json/o/orde[r]s.tbl.1'
            format          =>  json_object('ignoreblanklines' value TRUE,
                                            'rejectlimit' value '0',
                                            'dateformat' value 'yyyy-mm-dd',
                                            'regexuri' value TRUE)
            );
END;
/

構文

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    schema_name       IN VARCHAR2 DEFAULT,
    field_list        IN CLOB DEFAULT,
    format            IN CLOB DEFAULT);

パラメータ

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

使用上のノート

• 他のデータ・ファイルと同様に、Avro、ORCおよびParquetデータ・ロードにより、表dba_load_operationsとuser_load_operationsで表示可能なログが生成されます。各ロード操作により、ログを含む表を示すdba[user]_load_operationsにレコードが追加されます。

  ログ表には、ロードに関するサマリー情報が表示されます。

• Avro、ORCまたはParquetの場合、formatのパラメータtypeが値avro、orcまたはparquetに設定されていると、BADFILE_TABLE表は常に空です。

  • Parquetファイルの場合、PRIMARY KEY制約のエラーによりORAエラーがスローされます。

  • 列のデータで変換エラーが発生した場合(たとえば、ターゲット列の大きさが変換済の値を保持するのに十分な大きさでない場合など)、その列の値はNULLに設定されます。これにより、拒否されたレコードは生成されません。

ソースとターゲットのバケットまたはフォルダは、同じまたは異なるクラウド・オブジェクト・ストア・プロバイダに配置できます。

ソースとターゲットが個別のオブジェクト・ストアにある場合、または同じクラウド・プロバイダを持つ異なるアカウントがある場合は、ソースとターゲットの場所に個別の資格証明名を指定できます。

ソース資格証明名は、ターゲット資格証明名が指定されていない場合、ターゲットの場所でもデフォルトで使用されます。

構文

DBMS_CLOUD.COPY_OBJECT (
    source_credential_name  IN  VARCHAR2 DEFAULT NULL,
    source_object_uri       IN  VARCHAR2,
    target_object_uri       IN  VARCHAR2,
    target_credential_name  IN  VARCHAR2 DEFAULT NULL
);

パラメータ

例

BEGIN 
DBMS_CLOUD.COPY_OBJECT (
    source_credential_name => 'OCI_CRED',
    source_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/bgfile.csv',
    target_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/myfile.csv'
);
END;
/

構文

DBMS_CLOUD.CREATE_CLOUD_TABLE (
    table_name       IN VARCHAR2,
    column_list      IN CLOB,
    params           IN CLOB);

パラメータ

使用上のノート

• DEFAULT属性: column_listにはDEFAULT句を含めることができます。この句は、通常のCREATE TABLEのDEFAULT句のように機能します。DEFAULT句の動作の詳細は、「CREATE TABLE」を参照してください。

• クラウド表を削除するには、DROP TABLEを使用します。クラウド表はごみ箱をサポートしていません。

  たとえば:

  DROP TABLE CLOUD_TAB1; 

• SELECT、INSERTおよびUPDATE権限をクラウド表に付与できます。他の権限はクラウド表に付与できません。

  詳細は、「権限とロール認可の構成」を参照してください。

例

EXEC DBMS_CLOUD.CREATE_CLOUD_TABLE( 'CLOUD_TAB1', 'I INTEGER, J INTEGER' );

BEGIN
  DBMS_CLOUD.CREATE_CLOUD_TABLE(
   table_name  => 'CLOUD_TABLE_WITH_DEFAULT',
   column_list => 'I INTEGER,
                   A VARCHAR2(32) DEFAULT ''ABC''' );
END;
/

構文

DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    partitioning_clause  IN CLOB,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);


DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    file_uri_list        IN VARCHAR2,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);

パラメータ

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

使用上のノート

• partitioning_clauseパラメータとfile_uri_listパラメータの両方を使用してこのプロシージャをコールすることはできません。

• Avro、ParquetまたはORCデータ・ファイルを含む構造化データ・ファイルでは、column_listパラメータの指定はオプションです。column_listを指定しない場合、formatパラメータのpartition_columnsオプションには、nameとtypeの両方を含める必要があります。

• CSVテキスト・ファイルなどの非構造化データ・ファイルでは、column_listパラメータは必須です。

• プロシージャDBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEは、次のようなサポートされているクラウド・オブジェクト・ストレージ・サービスの外部パーティション・ファイルをサポートします。

  • Oracle Cloud Infrastructure Object Storage

  • Azure Blob StorageまたはAzure Data Lake Storage

  • Amazon S3

  • Amazon S3互換: Oracle Cloud Infrastructure Object Storage、Google Cloudストレージ、Wasabi Hot Cloudストレージなど。

  • GitHubリポジトリ

  詳細は、DBMS_CLOUD URIフォーマットを参照してください。

• プロシージャDBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEは、ローカル・ファイル・システムまたはネットワーク・ファイル・システムのディレクトリ内の外部パーティション・ファイルをサポートします。

• file_uri_listパラメータを指定してDBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEをコールする場合、クラウド・オブジェクト・ストアのファイル名で指定する列の型は次のいずれかの型である必要があります。

  VARCHAR2(n)
  NUMBER(n)
  NUMBER(p,s)
  NUMBER
  DATE
  TIMESTAMP(9)

• デフォルトのレコード・デリミタはdetected newlineです。detected newlineを指定すると、DBMS_CLOUDは、レコード・デリミタとして使用する適切な改行文字を自動的に見つけようとします。DBMS_CLOUDは、最初にWindowsの改行文字\r\nを検索します。Windowsの改行文字が見つかると、それがプロシージャのすべてのファイルのレコード・デリミタとして使用されます。Windowsの改行文字が見つからない場合、DBMS_CLOUDは、UNIX/Linuxの改行文字\nを検索し、見つかった場合は\nがプロシージャのすべてのファイルのレコード・デリミタとして使用されます。ソース・ファイルで異なるレコード・デリミタの組合せが使用されている場合は、KUP-04020: found record longer than buffer size supportedなどのエラーが発生する可能性があります。この場合、同じレコード・デリミタを使用するようにソース・ファイルを変更するか、同じレコード・デリミタを使用するソース・ファイルのみを指定する必要があります。

  recorddelmiterフォーマット・オプションの詳細は、「DBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。

• DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEを使用して作成する外部パーティション表には、2つの非表示列file$pathとfile$nameが含まれます。これらの列は、レコードの取得元ファイルの識別に役立ちます。

  • file$path: オブジェクト名の先頭までのファイル・パス・テキストを指定します。

  • file$name: バケット名に続くすべてのテキストを含め、オブジェクト名を指定します。

例

partitioning_clauseパラメータを使用した例:

BEGIN  
   DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
      table_name =>'PET1',  
      credential_name =>'OBJ_STORE_CRED',
      format => json_object('delimiter' value ',', 'recorddelimiter' value 'newline', 'characterset' value 'us7ascii'),
      column_list => 'col1 number, col2 number, col3 number',
      partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) location
                                    ( ''&base_URL//file_11.txt'')
                                 ,
                                 partition p2 values less than (2000) location
                                    ( ''&base_URL/file_21.txt'')
                                 ,
                                 partition p3 values less than (3000) location 
                                    ( ''&base_URL/file_31.txt'')
                                 )'
     );
   END;
/  


BEGIN
    DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
       table_name          => 'PET',
       format              => json_object('delimiter'value ','),
       column_list         => 'name varchar2(20), gender varchar2(10), salary number',
       partitioning_clause => 'partition by range (salary)
              (   -- Use test1.csv in the DEFAULT DIRECTORY DATA_PUMP_DIR 
                  partition p1 values less than (100) LOCATION (''test1.csv''),
                   -- Use test2.csv in a specified directory MY_DIR
                  partition p2 values less than (300) DEFAULT DIRECTORY MY_DIR LOCATION (''test2.csv'')        )'   );                       
END;                     
/

非構造化データ・ファイルでfile_uri_listおよびcolumn_listパラメータを使用した例:

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
   table_name => 'MYSALES',
   credential_name => 'DEF_CRED_NAME',
   file_uri_list     => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/*.csv', 
   column_list       => 'product varchar2(100), units number, country varchar2(100), year number, month varchar2(2)', 
   field_list        => 'product, units', --[Because country, year and month are not in the file, they are not listed in the field list]
   format            => '{"type":"csv", "partition_columns":["country","year","month"]}');
END;
/ 

構造化データ・ファイルでcolumn_listパラメータを指定せずにfile_uri_listを使用した例:

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
  table_name => 'MYSALES',
  credential_name => 'DEF_CRED_NAME',
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
    table_name      => 'MYSALES',
    credential_name => 'DEF_CRED_NAME',
    file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/*.parquet',
    format          => 
        json_object('type' value 'parquet', 'schema' value 'first',
                    'partition_columns' value 
                          json_array(
                                json_object('name' value 'country', 'type' value 'varchar2(100)'),
                                json_object('name' value 'year', 'type' value 'number'),
                                json_object('name' value 'month', 'type' value 'varchar2(2)')
                          )
         )
    );
END;
/

構文

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    file_uri_list    IN CLOB,
    column_list      IN CLOB,
    field_list       IN CLOB DEFAULT,
    format           IN CLOB DEFAULT);

パラメータ

使用上のノート

• プロシージャDBMS_CLOUD.CREATE_EXTERNAL_TABLEでは、次を含むサポート対象クラウド・オブジェクト・ストレージ・ソースでパーティション化された外部ファイルをサポートしています:

  • Oracle Cloud Infrastructure Object Storage

  • Azure Blob StorageまたはAzure Data Lake Storage

  • Amazon S3

  • Amazon S3互換: Oracle Cloud Infrastructure Object Storage、Google Cloudストレージ、Wasabi Hot Cloudストレージなど。

  • GitHubリポジトリ

  • 表ハイパーリンクURLを使用したOracle Cloud Infrastructure Object Storage

  資格証明は表レベルのプロパティであるため、外部ファイルは同じオブジェクト・ストアに存在する必要があります。

  詳細は、DBMS_CLOUD URIフォーマットを参照してください。

• デフォルトのレコード・デリミタはdetected newlineです。detected newlineを指定すると、DBMS_CLOUDは、レコード・デリミタとして使用する適切な改行文字を自動的に見つけようとします。DBMS_CLOUDは、最初にWindowsの改行文字\r\nを検索します。Windowsの改行文字が見つかると、それがプロシージャのすべてのファイルのレコード・デリミタとして使用されます。Windowsの改行文字が見つからない場合、DBMS_CLOUDは、UNIX/Linuxの改行文字\nを検索し、見つかった場合は\nがプロシージャのすべてのファイルのレコード・デリミタとして使用されます。ソース・ファイルで異なるレコード・デリミタの組合せが使用されている場合は、KUP-04020: found record longer than buffer size supportedなどのエラーが発生する可能性があります。この場合、同じレコード・デリミタを使用するようにソース・ファイルを変更するか、同じレコード・デリミタを使用するソース・ファイルのみを指定する必要があります。

  recorddelimiterフォーマット・オプションの詳細は、「DBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。

例

BEGIN  
   DBMS_CLOUD.CREATE_EXTERNAL_TABLE(   
      table_name =>'WEATHER_REPORT_DOUBLE_DATE',   
      credential_name =>'OBJ_STORE_CRED',   
      file_uri_list =>'&base_URL/Charlotte_NC_Weather_History_Double_Dates.csv',
      format => json_object('type' value 'csv', 'skipheaders' value '1'),   
      field_list => 'REPORT_DATE DATE''mm/dd/yy'',                   
                     REPORT_DATE_COPY DATE ''yyyy-mm-dd'',
                     ACTUAL_MEAN_TEMP,                 
                     ACTUAL_MIN_TEMP,                 
                     ACTUAL_MAX_TEMP,                 
                     AVERAGE_MIN_TEMP,                    
                     AVERAGE_MAX_TEMP,     
                     AVERAGE_PRECIPITATION',   
      column_list => 'REPORT_DATE DATE,   
                     REPORT_DATE_COPY DATE,
                     ACTUAL_MEAN_TEMP NUMBER,  
                     ACTUAL_MIN_TEMP NUMBER,  
                     ACTUAL_MAX_TEMP NUMBER,  
                     AVERAGE_MIN_TEMP NUMBER,   
                     AVERAGE_MAX_TEMP NUMBER,                  
                     AVERAGE_PRECIPITATION NUMBER');
   END;
/ 

SELECT * FROM WEATHER_REPORT_DOUBLE_DATE where         
   actual_mean_temp > 69 and actual_mean_temp < 74

構文

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    file_uri_list    IN CLOB,
    column_list      IN CLOB DEFAULT NULL,
    field_list       IN CLOB DEFAULT NULL,
    format           IN CLOB DEFAULT NULL
);

パラメータ

AWS Glue Catalogを使用したAWS Iceberg表のフォーマット・パラメータの例

AWS Glue Catalogを使用してAWS Iceberg表に表を作成する場合のformatパラメータの例を次に示します。

format => json_object('access_protocol' value
       json_object('protocol_type' value 'iceberg',
                   'protocol_config' value
                    json_object('iceberg_catalog_type' value 'aws_glue',
                                'iceberg_glue_region'  value 'glue region',
                                'iceberg_table_path'   value 'database_name.table_name'))); 

メタデータ・ファイルURIを使用したAWS Iceberg表のフォーマット・パラメータの例

format => json_object('access_protocol' value
       json_object('protocol_type' value 'iceberg')

HadoopCatalogカタログを使用したOCI Iceberg表のフォーマット・パラメータの例

format => json_object('access_protocol' value
       json_object('protocol_type'   value 'iceberg',
                   'protocol_config' value
                   json_object('iceberg_catalog_type'  value 'hadoop',
                               'iceberg_warehouse'     value '<OCI folder URI>',
                               'iceberg_table_path'    value 'database_name.table_name')));

メタデータ・ファイルのURIを使用したOCI Iceberg表のフォーマット・パラメータの例

format => json_object('access_protocol' value
       json_object('protocol_type' value 'iceberg')

Unityカタログに基づくIceberg表の書式パラメータの例

Unityカタログ上に表を作成する場合のformatパラメータの例を次に示します。

{
  "access_protocol": {
    "protocol_type": "iceberg",
    "protocol_config": {
      "iceberg_catalog_type": "unity",
      "rest_catalog_endpoint": "https://adb-...azuredatabricks.net/api/2.1/unity-catalog/iceberg",
      "rest_authentication": {
        "rest_auth_cred": "PDB_ADMIN_UNITY_PRINC_CRED",
        "rest_auth_endpoint": "https://adb-...azuredatabricks.net/oidc/v1/token"
      },
      "table_path": [
        "spapadom-catalog",
        "default",
        "people_10m"
      ]
    }
  }
}

formatパラメータには次のコンポーネントがあります。

• table_path: Unityで使用される3レベルのネームスペース階層を指定するJSON配列オブジェクト: <catalog>.<schema>.<table>。配列には3つのアイテムのみを含める必要があります。
• rest_catalog_endpoint: scheme=httpまたはhttpsの{scheme}://{host}:{port}/{basePath}または{scheme}://{host}/{basePath}の形式のエンドポイントURL。
• rest_auth_endpoint: トークン・リフレッシュのエンドポイント。
• rest_auth_cred: Unity Personal Access TokenのOracle資格証明、またはOAuthのClientID/ClientSecretの組合せ。セキュリティを考慮すると、資格証明はdbms_cloudの外部表資格証明と同じ方法で処理されます。

BearerトークンまたはPersonal Accessトークンを使用したUntityカタログのコール例

BearerトークンまたはPersonal Access Tokenを使用したUnityカタログのサンプル・コールは次のとおりです。

begin    dbms_cloud.create_external_table (
        table_name       => 'people_10m',
        credential_name  => 'AZURE_CRED',
        file_uri_list    => '',
        format           =>'{
  "access_protocol": {
    "protocol_type": "iceberg",
    "protocol_config": {
      "iceberg_catalog_type": "unity",
      "rest_catalog_endpoint": "https://adb-...azuredatabricks.net/api/2.1/unity-catalog/iceberg",
      "rest_authentication":{
        "rest_auth_cred":"UNITY_CRED"
      },
      "table_path":["spapadom-catalog", "default","people_10m"]
    }
  }
}'    );
end;

サービス・プリンシパルを使用したUnityカタログのコール例

サービス・プリンシパルを使用してUnityカタログを呼び出すサンプル外部表は、次のとおりです。

BEGIN
    dbms_cloud.create_external_table (
        table_name       => 'dbu_table_complex_type',
        credential_name  => 'AWS_CRED',
        file_uri_list    => '',
        format           =>'{
  "access_protocol": {
    "protocol_type": "iceberg",
    "protocol_config": {
      "iceberg_catalog_type": "polaris",
      "rest_catalog_prefix":"spapadom-catalog",
      "rest_catalog_endpoint": "https://...snowflakecomputing.com/polaris/api/catalog",
      "rest_authentication":{
        "rest_auth_cred":"PDB_ADMIN_OPEN_CRED"
      },
      "table_path":["SPAPADOM_ICEBERG", "PUBLIC","DBU_TABLE_COMPLEX_TYPE"]
    }
  }
}'
    );
END;
/

Bearerトークンを使用したOpen Catalogのコール例

Bearerトークンを使用してOpen Catalogを呼び出すサンプル外部表は、次のとおりです。

BEGIN
    dbms_cloud.create_external_table (
        table_name       => 'dbu_table_complex_type',
        credential_name  => 'AWS_CRED',
        file_uri_list    => '',
        format           =>'{
  "access_protocol": {
    "protocol_type": "iceberg",
    "protocol_config": {
      "iceberg_catalog_type": "polaris",
      "rest_catalog_prefix":"spapadom-catalog",
      "rest_catalog_endpoint": "https://...snowflakecomputing.com/polaris/api/catalog",
      "rest_authentication":{
        "rest_auth_cred":"PDB_ADMIN_OPEN_CRED"
      },
      "table_path":["SPAPADOM_ICEBERG", "PUBLIC","DBU_TABLE_COMPLEX_TYPE"]
    }
  }
}'
    );
END;
/

サービス・プリンシパルを使用したオープン・カタログのコール例

サービス・プリンシパルを使用してオープン・カタログをコールするサンプル外部表は、次のとおりです。

BEGIN
    dbms_cloud.create_external_table (
        table_name       => 'dbu_table_complex_type',
        credential_name  => 'AWS_CRED',
        file_uri_list    => '',
        format           =>'{
  "access_protocol": {
    "protocol_type": "iceberg",
    "protocol_config": { 
     "iceberg_catalog_type": "polaris",
      "rest_catalog_prefix":"spapadom-catalog",
      "rest_catalog_endpoint": "https://...snowflakecomputing.com/polaris/api/catalog",
      "rest_authentication":{
        "rest_auth_cred":"PDB_ADMIN_OPEN_PRINC_CRED",
        "rest_auth_endpoint":"https://...snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens"
      },
      "table_path":["SPAPADOM_ICEBERG", "PUBLIC", "DBU_TABLE_COMPLEX_TYPE"]
    }
  }
}'
    );
END;
/

構文

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    file_uri_list    IN CLOB,
    column_list      IN CLOB,
    field_list       IN CLOB DEFAULT,
    format           IN CLOB DEFAULT);

パラメータ

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.parquet'

ORCの例

Avroの例

Parquetの例

Avro、ORCまたはParquet列名のOracle列名へのマッピング

Oracle SQLでの列名マッピングおよび列名変換の使用方法の詳細は、「DBMS_CLOUDパッケージAvro、ORCおよびParquetからOracle列名へのマッピング」を参照してください。

CREATE_EXTERNAL_TEXT_INDEXプロシージャは、location_uriの場所で指定されたオブジェクト・ストレージ・ファイルにテキスト索引を作成します。場所URI上のファイルを使用して行われた新しい追加または削除については、索引が定期的にリフレッシュされます。

構文

DBMS_CLOUD.CREATE_EXTERNAL_TEXT_INDEX (
      credential_name  IN  VARCHAR2 DEFAULT NULL,
      location_uri     IN  VARCHAR2,
      index_name       IN  VARCHAR2,
      format           IN  CLOB     DEFAULT NULL
);

パラメータ

location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv

例

BEGIN 
DBMS_CLOUD.CREATE_EXTERNAL_TEXT_INDEX (
        credential_name => 'DEFAULT_CREDENTIAL',
        location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/ts_data/'
        index_name      => 'EMP',
        format          => JSON_OBJECT ('refresh_rate' value 10)
);
END;
/

構文

DBMS_CLOUD.CREATE_HYBRID_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    partitioning_clause  IN CLOB,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);

パラメータ

partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) external location
				    ( ''https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.txt''),….

使用上のノート

• プロシージャDBMS_CLOUD.CREATE_HYBRID_PART_TABLEでは、サポートされているクラウド・オブジェクト・ストレージ・サービスで、次のような外部パーティション・ファイルをサポートしています:

  • Oracle Cloud Infrastructure Object Storage

  • Azure Blob StorageまたはAzure Data Lake Storage

  • Amazon S3

  • Amazon S3互換: Oracle Cloud Infrastructure Object Storage、Google Cloudストレージ、Wasabi Hot Cloudストレージなど。

  • GitHubリポジトリ

  資格証明は表レベルのプロパティであるため、外部ファイルは同じオブジェクト・ストアに存在する必要があります。

  詳細は、DBMS_CLOUD URIフォーマットを参照してください。

• DBMS_CLOUD.CREATE_HYBRID_PART_TABLEプロシージャは、ローカル・ファイル・システムまたはネットワーク・ファイル・システムのディレクトリ内のハイブリッド・パーティション・ファイルをサポートします。

• DBMS_CLOUD.CREATE_HYBRID_PART_TABLEを使用して作成する外部パーティション表には、2つの非表示列file$pathとfile$nameが含まれます。これらの列は、レコードの取得元ファイルの識別に役立ちます。

  • file$path: オブジェクト名の先頭までのファイル・パス・テキストを指定します。

  • file$name: バケット名に続くすべてのテキストを含め、オブジェクト名を指定します。

例

BEGIN  
   DBMS_CLOUD.CREATE_HYBRID_PART_TABLE(
      table_name =>'HPT1',  
      credential_name =>'OBJ_STORE_CRED',  
      format => json_object('delimiter' value ',', 'recorddelimiter' value 'newline', 'characterset' value 'us7ascii'),  
      column_list => 'col1 number, col2 number, col3 number',
      partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) external location
                                    ( ''&base_URL/file_11.txt'')
                                 ,
                                 partition p2 values less than (2000) external location
                                    ( ''&base_URL/file_21.txt'')
                                 ,
                                 partition p3 values less than (3000)
                                 )'
     );
   END;
/ 


BEGIN
   DBMS_CLOUD.CREATE_HYBRID_PART_TABLE(
    table_name  => 'HPT1',
    format      => json_object('delimiter'value ',', 'recorddelimiter'value 'newline'),
    column_list => 'NAME VARCHAR2(30), GENDER VARCHAR2(10), BALANCE number',
    partitioning_clause => 'partition by range (B  2  ALANCE)
               (partition p1 values less than (1000) external DEFAULT DIRECTORY DATA_PUMP_DIR LOCATION (''Scott_male_1000.csv''),
                partition p2 values less than (2000) external DEFAULT DIRECTORY DATA_PUMP_DIR LOCATION (''Mary_female_3000.csv''),
                partition p3 values less than (3000))' );
END;
/

構文

DBMS_CLOUD.DELETE_ALL_OPERATIONS (
	type      IN VARCHAR DEFAULT NULL);

パラメータ

使用上のノート

• このプロシージャは、現在実行中の操作(「実行中」ステータスの操作)は削除しません。

• このプロシージャは、操作に関連付けられたロギング表およびログ・ファイルを削除します。

構文

 DBMS_CLOUD.DELETE_FILE ( 
       directory_name     IN VARCHAR2,
       file_name          IN VARCHAR2,
       force              IN BOOLEAN DEFAULT FALSE); 

パラメータ

GRANT WRITE ON DIRECTORY data_pump_dir TO adb_user;

例

BEGIN
   DBMS_CLOUD.DELETE_FILE(
      directory_name =>  'DATA_PUMP_DIR',
      file_name => 'exp1.dmp' );
   END;
/ 

構文

DBMS_CLOUD.DELETE_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       force                IN BOOLEAN DEFAULT FALSE);

パラメータ

例

BEGIN
   DBMS_CLOUD.DELETE_OBJECT(
       credential_name => 'DEF_CRED_NAME',
       object_uri => 'https://objectstorage.us-ashburn-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.dmp' );
   END;
/ 

構文

DBMS_CLOUD.DELETE_OPERATION (
	id      IN NUMBER);

パラメータ

使用上のノート

• このプロシージャは、入力で指定された操作IDに関連付けられたロギング表およびログ・ファイルを削除します。

例

SELECT id FROM user_load_operations WHERE type LIKE '%BAD%';
EXEC DBMS_CLOUD.DELETE_OPERATION(id);

DROP_EXTERNAL_TEXT_INDEXプロシージャは、CREATE_EXTERNAL_TEXT_INDEXプロシージャで作成された指定された索引を削除します。

構文

DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
      index_name       IN  VARCHAR2,
);

パラメータ

例

BEGIN 
DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
        index_name => 'EMP',
);
END;
/

構文

DBMS_CLOUD.EXPORT_DATA (
      credential_name   IN VARCHAR2 DEFAULT NULL,
      file_uri_list     IN CLOB,
      format            IN CLOB,
      query             IN CLOB);

DBMS_CLOUD.EXPORT_DATA (
      credential_name   IN VARCHAR2 DEFAULT NULL,
      file_uri_list     IN CLOB DEFAULT NULL,
      format            IN CLOB DEFAULT NULL,
      query             IN CLOB DEFAULT NULL,
      operation_id      OUT NOCOPY NUMBER);

パラメータ

使用上の注意:

• 指定するqueryパラメータ値は、必要に応じて、結合や副問合せを含む問合せなどの拡張問合せにすることができます。

• 指定されたフォーマット・パラメータに応じて、DBMS_CLOUD.EXPORT_DATAは、指定された問合せの結果をクラウド・オブジェクト・ストアまたはディレクトリの場所に次のいずれかの形式で出力します。

  • CSV、JSON、ParquetまたはXMLファイル。

    CSV、JSON、ParquetまたはXML出力ファイルでDBMS_CLOUD.EXPORT_DATAを使用する方法の詳細は、「テキストとしてのオブジェクト・ストアへのデータのエクスポート」および「ディレクトリへのデータのエクスポート」を参照してください。

  • ORACLE_DATAPUMPアクセス・ドライバを使用して、ダンプ・ファイルにデータを書き込みます。

• CSV、JSONまたはXML出力の場合、生成されたファイルに10MBのデータが含まれていると、デフォルトで新しい出力ファイルが作成されます。ただし、結果データの10MB未満の場合は、Autonomous AI Databaseインスタンスのデータベース・サービスおよびECPU数(データベースがOCPUを使用する場合はOCPU)に応じて、複数の出力ファイルがある場合があります。

  詳細は、テキスト出力(CSV、JSON、ParquetまたはXML)のファイル・ネーミングを参照してください。

  デフォルトの出力ファイルのチャンク・サイズは、CSV、JSONまたはXMLの場合は10MBです。formatパラメータのmaxfilesizeオプションを使用して、この値を変更できます。詳細は、EXPORT_DATAのDBMS_CLOUDパッケージ・フォーマット・オプションを参照してください。

• Parquet出力の場合、生成される各ファイルは128MB未満で、複数の出力ファイルが生成される可能性があります。ただし、結果データが128MB未満の場合、Autonomous AI Databaseインスタンスのデータベース・サービスおよびECPU数(データベースでOCPUが使用されている場合はOCPU)に応じて、複数の出力ファイルがある場合があります。

  詳細は、テキスト出力(CSV、JSON、ParquetまたはXML)のファイル・ネーミングを参照してください。

ORACLE_DATAPUMP出力の使用上のノート(formatパラメータtypeオプションdatapumpのDBMS_CLOUD.EXPORT_DATA):

• EXPORT_DATAは、デフォルトのロギング・ディレクトリとしてDATA_PUMP_DIRを使用します。そのため、ORACLE_DATAPUMP出力を使用する場合は、DATA_PUMP_DIRに対する書込み権限が必要です。

• DBMS_CLOUD.EXPORT_DATAとformatパラメータtypeオプションdatapumpを使用した自律型AIデータベース・エクスポートでは、Oracle Cloud Infrastructure Object Storage、Oracle Cloud Infrastructure Object Storage Classicオブジェクト・ストアまたはディレクトリ出力のみがサポートされます。

• formatパラメータのtypeオプションdatapumpでDBMS_CLOUD.EXPORT_DATAを指定すると、credential_nameパラメータ値をOCIリソース・プリンシパルにすることはできません。

• Oracle Data Pumpでは、各ダンプ・ファイルの部分を小さなチャンクに分割してアップロードを高速化します。Oracle Cloud Infrastructure Object Storageコンソールには、エクスポートするダンプ・ファイル・パートごとに複数のファイルが表示されます。実際のダンプファイルのサイズはゼロ(0)、関連するファイル・チャンクは10mb以下と表示されます。たとえば:

  exp01.dmp
  exp01.dmp_aaaaaa
  exp02.dmp
  exp02.dmp_aaaaaa

  Oracle Cloud InfrastructureコンソールまたはOracle Cloud Infrastructure CLIを使用してゼロ・バイト・ダンプ・ファイルをダウンロードしても、完全なダンプ・ファイルは得られません。オブジェクト・ストアから完全なダンプ・ファイルをダウンロードするには、curlなどのSwiftをサポートするツールを使用して、ユーザー・ログインおよびSwift認証トークンを指定します。

  curl -O -v -X GET -u 'user1@example.com:auth_token' \
     https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/namespace-string/bucketname/exp01.dmp

  値datapumpを持つformatパラメータtypeをサポートするDBMS_CLOUDプロシージャを使用してファイルをインポートする場合は、プライマリ・ファイル名のみを指定する必要があります。datapump形式タイプをサポートするプロシージャでは、チャンクが自動的に検出およびダウンロードされます。

  DBMS_CLOUD.DELETE_OBJECTを使用する場合、プロシージャは、プライマリ・ファイルを削除したときにチャンクを自動的に検出して削除します。

• DBMS_CLOUD.EXPORT_DATAプロシージャは、次のように、指定したfile_uri_list値からダンプ・ファイルを作成します:

  • さらにファイルが必要な場合は、file_uri_listから追加のファイルを作成します。

  • ファイルは上書きしません。file_uri_listにダンプ・ファイルが存在する場合、DBMS_CLOUD.EXPORT_DATAはエラーを報告します。

  • DBMS_CLOUD.EXPORT_DATAはバケットを作成しません。

• DBMS_CLOUD.EXPORT_DATAによって生成されるダンプ・ファイルの数は、プロシージャの実行時に決まります。生成されるダンプ・ファイルの数は、file_uri_listパラメータで指定するファイル名の数、およびインスタンスで使用可能なAutonomous AI Database OCPUの数、サービス・レベル、データのサイズによって異なります。

  たとえば、1個のOCPU Autonomous AI Databaseインスタンスまたはlowサービスを使用すると、複数のファイル名を指定した場合でも、単一のダンプ・ファイルが並列度なしでエクスポートされます。4 OCPUのAutonomous AI Databaseインスタンスをmediumまたはhighサービスとともに使用すると、 複数のファイル名を指定した場合、ジョブをパラレルに実行でき、 複数のダンプ・ファイルがエクスポートされます。

• DBMS_CLOUD.EXPORT_DATAを使用して作成したダンプ・ファイルは、Oracle Data Pump impdpを使用してインポートすることはできません。データベースに応じて、次のようにファイルを使用できます:

  • Autonomous AI Databaseでは、値datapumpを持つformatパラメータtypeをサポートするDBMS_CLOUDプロシージャでダンプ・ファイルを使用できます。DBMS_CLOUD.COPY_DATAを使用してダンプ・ファイルをインポートすることも、DBMS_CLOUD.CREATE_EXTERNAL_TABLEをコールして外部表を作成することも可能です。

  • Oracle Database 19cオンプレミスなどの他のOracle Databaseでは、ORACLE_DATAPUMPアクセス・ドライバを使用すると、プロシージャDBMS_CLOUD.EXPORT_DATAで作成されたダンプ・ファイルをインポートできます。詳細は、「ORACLE_DATAPUMPアクセス・ドライバを使用したデータのアンロードおよびロード」を参照してください。

• 指定するqueryパラメータ値は、必要に応じて、結合や副問合せを含む問合せなどの拡張問合せにすることができます。

ディレクトリへの出力を含むDBMS_CLOUD.EXPORT_DATAの使用上のノート

• 指定されたディレクトリが存在し、ADMINユーザーとしてログインするか、ディレクトリへのWRITEアクセス権を持っている必要があります。

• DBMS_CLOUD.EXPORT_DATAはディレクトリを作成しません。

• ファイルは上書きしません。たとえば、file_uri_listにダンプ・ファイルが存在する場合、DBMS_CLOUD.EXPORT_DATAは次のようなエラーを報告します。

  ORA-31641: unable to create dump file  "/u02/exports/123.dmp"
  ORA-27038: created file already exists

例

次の例は、datapumpという値を持つtypeパラメータの書式を持つDBMS_CLOUD.EXPORT_DATAを示しています。

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name =>'OBJ_STORE_CRED',
      file_uri_list =>'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.dmp',
      format => json_object('type' value 'datapump', 'compression' value 'basic', 'version' value 'latest'),
      query => 'SELECT lakehouse_id, quantity FROM inventories'
     );
   END;
/  

この例では、namespace-stringはOracle Cloud Infrastructureオブジェクト・ストレージ・ネームスペースで、bucketnameはバケット名です。詳細は、オブジェクト・ストレージ・ネームスペースの理解を参照してください。

次の例は、jsonという値を持つtypeパラメータの書式を持つDBMS_CLOUD.EXPORT_DATAを示しています。

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.json', 
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'json', 'compression' value 'gzip'));
     );
   END;
/  

次の例は、xmlという値を持つtypeパラメータの書式を持つDBMS_CLOUD.EXPORT_DATAを示しています。

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.xml', 
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'xml', 'compression' value 'gzip'));
     );
   END;
/

次の例は、csvという値を持つtypeパラメータの書式を持つDBMS_CLOUD.EXPORT_DATAを示しています。

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp.csv', 
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'csv', 'delimiter' value '|', 'compression' value 'gzip', 'header' value true, 'encryption' value ('user_defined_function' value 'ADMIN.decryption_callback')));
     );
   END;
/  

次の例は、値がdatapumpのtypeパラメータを使用して、ディレクトリの場所にデータをエクスポートするDBMS_CLOUD.EXPORT_DATAを示しています。

BEGIN
 DBMS_CLOUD.EXPORT_DATA(
    file_uri_list => 'export_dir:sales.dmp',
    format        => json_object('type' value 'datapump'),
    query         => 'SELECT * FROM sales'
 );
END;
/

構文

DBMS_CLOUD.GET_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       directory_name       IN VARCHAR2,
       file_name            IN VARCHAR2 DEFAULT  NULL,
       startoffset          IN NUMBER DEFAULT  0,
       endoffset            IN NUMBER DEFAULT  0,
       compression          IN VARCHAR2 DEFAULT  NULL);


DBMS_CLOUD.GET_OBJECT(
       credential_name      IN VARCHAR2 DEFAULT NULL,
       object_uri           IN VARCHAR2,
       startoffset          IN NUMBER DEFAULT  0,
       endoffset            IN NUMBER DEFAULT  0,
       compression          IN VARCHAR2 DEFAULT  NULL)
RETURN BLOB;

パラメータ

^脚注1

GRANT WRITE ON DIRECTORY data_pump_dir TO adb_user;

戻り値

ファンクション・フォームはオブジェクト・ストアから読み取り、DBMS_CLOUD.GET_OBJECTはBLOBを戻します。

例

BEGIN 
   DBMS_CLOUD.GET_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/file.txt',
     directory_name => 'DATA_PUMP_DIR'); 
END;
/

オブジェクト・ストア内のファイルから文字データを読み取るには:

SELECT to_clob(
     DBMS_CLOUD.GET_OBJECT(
       credential_name => 'OBJ_STORE_CRED',
       object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/file.txt'))
FROM DUAL;

データベースのBLOBのオブジェクト・ストアに格納されているイメージを追加するには:

DECLARE
   l_blob BLOB := NULL;
BEGIN
   l_blob := DBMS_CLOUD.GET_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/MyImage.gif' );
END;
/

この例では、namespace-stringはOracle Cloud Infrastructureオブジェクト・ストレージ・ネームスペースで、bucketnameはバケット名です。詳細は、オブジェクト・ストレージ・ネームスペースの理解を参照してください。

構文

DBMS_CLOUD.LIST_FILES (
	directory_name      IN VARCHAR2)
       RETURN TABLE;

パラメータ

使用上のノート

• ADMIN以外のユーザーでDBMS_CLOUD.LIST_FILESを実行するには、そのユーザーにそのディレクトリに対する読取り権限を付与する必要があります。たとえば、ADMINとして次のコマンドを実行して、adb_userに読取り権限を付与します。

  GRANT READ ON DIRECTORY data_pump_dir TO adb_user;

• これは、戻り値のタイプがDBMS_CLOUD_TYPES.list_object_ret_tのパイプライン・テーブル・ファンクションである。

• DBMS_CLOUD.LIST_FILESはチェックサム値を取得せず、このフィールドに対してNULLを返します。

• DBMS_CLOUD.LIST_FILESでは、directory:filename構文を使用してファイルのフィルタリングを選択的にサポートします。ファイル名ではワイルドカードがサポートされています。

例:

これは、各ファイルの行を戻すパイプライン・ファンクション。たとえば、次の問合せを使用してこのファンクションを使用します:

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR');

OBJECT_NAME       BYTES   CHECKSUM      CREATED              LAST_MODIFIED
------------ ---------- ----------    ---------------------  ---------------------
cwallet.sso        2965               2018-12-12T18:10:47Z   2019-11-23T06:36:54Z

ワイルドカードを使用した問合せの例:

DBMS_CLOUD.LIST_FILESをDIRECTORY:FILE構文とともに使用するには、ファイルを指定するか、ワイルドカードを使用します。*および?がサポートされるワイルドカード文字です。

例1:ワイルドカードを使用して、ディレクトリDATA_PUMP_DIRの"f"で始まるすべてのCSVファイルをリストします。

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR:f*.csv');

例2:ファイル名を指定するディレクトリDATA_PUMP_DIR内のファイルf1.csvをリストします。

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR:f1.csv');

構文

DBMS_CLOUD.LIST_OBJECTS (
       credential_name      IN VARCHAR2,
       location_uri         IN VARCHAR2)
   RETURN TABLE;

パラメータ

location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv'

使用上のノート

• オブジェクト・ストアの機能に応じて、DBMS_CLOUD.LIST_OBJECTSは特定の属性の値を返さず、この場合、フィールドの戻り値はNULLになります。

  サポートされているすべてのオブジェクト・ストアが、OBJECT_NAME、BYTESおよびCHECKSUMフィールドの戻り値を返します。

  次の表に、オブジェクト・ストアごとのフィールドCREATEDおよびLAST_MODIFIEDのサポートを示します。

  オブジェクト・ストア	CREATED	LAST_MODIFIED
  Oracle Cloud Infrastructureネイティブ	タイムスタンプを返します	タイムスタンプを返します
  Oracle Cloud Infrastructure Swift	NULLを戻します	タイムスタンプを返します
  Oracle Cloud Infrastructure Classic	NULLを戻します	タイムスタンプを返します
  Amazon S3	NULLを戻します	タイムスタンプを返します
  Amazon S3互換	NULLを戻します	タイムスタンプを返します
  Azure	タイムスタンプを返します	タイムスタンプを返します
  GitHubリポジトリ
  SharePoint	タイムスタンプを返します	タイムスタンプを返します

• チェックサム値は、MD5チェックサムです。これは、オブジェクトの内容に基づいて計算される32文字の10進数です。OCI$RESOURCE_PRINCIPAL資格証明を使用する場合、チェックサム値は異なる必要があります。

• これは、戻り値のタイプがDBMS_CLOUD_TYPES.list_object_ret_tのパイプライン・テーブル・ファンクションである。

例

これは、オブジェクトごとの行を戻すパイプライン・ファンクション。たとえば、次の問合せを使用してこのファンクションを使用します:

SELECT * FROM DBMS_CLOUD.LIST_OBJECTS('OBJ_STORE_CRED', 
    'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/');


OBJECT_NAME   BYTES              CHECKSUM                       CREATED         LAST_MODIFIED
------------ ---------- -------------------------------- --------------------- --------------------
cwallet.sso   2965      2339a2731ba24a837b26d344d643dc07 2019-11-23T06:36:54Z          

この例では、namespace-stringはOracle Cloud Infrastructureオブジェクト・ストレージ・ネームスペースで、bucketnameはバケット名です。詳細は、オブジェクト・ストレージ・ネームスペースの理解を参照してください。

この関数は、OCI、S3、Azure Blob、SharePointなどのオブジェクト・ストアへの読取り専用アクセスをサポートします。

構文

DBMS_CLOUD.LIST_OBJECTS_EXTENDED(
   credential_name IN VARCHAR2,
   location_uri    IN VARCHAR2
) RETURN TABLE (
   object_name    VARCHAR2(2000),
   bytes          NUMBER,
   checksum       VARCHAR2(512),
   created        TIMESTAMP,
   last_modified  TIMESTAMP,
   metadata       CLOB
);

パラメータ

使用上のノート

この関数を使用して、サポートされている記憶域の場所のファイルをリストします。特に、DBMS_CLOUD.GET_OBJECTやパイプラインなどの操作にSharePointメタデータが必要な場合です。

ソースとターゲットのバケットまたはフォルダは、同じまたは異なるクラウド・オブジェクト・ストア・プロバイダに配置できます。

ソースとターゲットが個別のオブジェクト・ストアにある場合、または同じクラウド・プロバイダを持つ異なるアカウントがある場合は、ソースとターゲットの場所に個別の資格証明名を指定できます。

ソース資格証明名は、ターゲット資格証明名が指定されていない場合、ターゲットの場所でもデフォルトで使用されます。

構文

DBMS_CLOUD.MOVE_OBJECT (
    source_credential_name  IN  VARCHAR2 DEFAULT NULL,
    source_object_uri       IN  VARCHAR2,
    target_object_uri       IN  VARCHAR2,
    target_credential_name  IN  VARCHAR2 DEFAULT NULL
);

パラメータ

例

BEGIN 
DBMS_CLOUD.MOVE_OBJECT (
    source_credential_name => 'OCI_CRED',
    source_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/bgfile.csv',
    target_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/myfile.csv'
);
END;
/

構文

DBMS_CLOUD.PUT_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       directory_name       IN VARCHAR2,
       file_name            IN VARCHAR2
       compression          IN VARCHAR2 DEFAULT  NULL);


DBMS_CLOUD.PUT_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       contents             IN BLOB
       compression          IN VARCHAR2 DEFAULT  NULL);

パラメータ

^脚注2

GRANT READ ON DIRECTORY data_pump_dir TO adb_user;

例

データベース内処理後にBLOBデータを処理し、そのデータをオブジェクト・ストアのファイルに直接格納するには:

DECLARE
      my_blob_data BLOB;
BEGIN 
 /* Some processing producing BLOB data and populating my_blob_data */
DBMS_CLOUD.PUT_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/my_new_file',
     contents => my_blob_data)); 
END;
/

使用上のノート

Cloud Object Storageに応じて、転送するオブジェクトのサイズは次のように制限されます:

Oracle Cloud Infrastructureオブジェクト・ストアでは、資格証明を指定せずにファイルをパブリック・バケットに書き込むことはできません(Oracle Cloud Infrastructureでは、ユーザーはパブリック・バケットからオブジェクトをダウンロードできます)。したがって、PUT_OBJECTを使用してオブジェクトをOracle Cloud Infrastructureパブリック・バケットに格納するには、有効な資格証明を含む資格証明名を指定する必要があります。

詳細は、DBMS_CLOUD URIフォーマットを参照してください。

構文

DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLE (
	table_name        IN VARCHAR2,
	schema_name       IN VARCHAR2 DEFAULT,
	update_columns    IN BOOLEAN DEFAULT);

パラメータ

構文

DBMS_CLOUD.VALIDATE_EXTERNAL_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);


DBMS_CLOUD.VALIDATE_EXTERNAL_PART_TABLE (
       table_name                 IN VARCHAR2,
       operation_id               OUT NUMBER,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

パラメータ

構文

DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE (
	table_name      IN VARCHAR2,
	schema_name     IN VARCHAR2 DEFAULT,		
	rowcount        IN NUMBER DEFAULT,
	stop_on_error   IN BOOLEAN DEFAULT);


DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE(
	table_name      IN VARCHAR2,
	operation_id    OUT NOCOPY NUMBER,
	schema_name     IN VARCHAR2 DEFAULT NULL,		
	rowcount        IN NUMBER DEFAULT 0,
	stop_on_error   IN BOOLEAN DEFAULT TRUE);

パラメータ

使用上のノート

• DBMS_CLOUD.VALIDATE_EXTERNAL_TABLEは、パーティション化された外部表とハイブリッド・パーティション表の両方で機能します。これは、rowcountに達するか、stop_on_errorが適用されるまで、場合によってはすべての外部パーティションからデータを読み取る可能性があります。読み取るパーティションまたはパーティションの一部をどの順序で読み取るかは制御できません。

構文

DBMS_CLOUD.VALIDATE_HYBRID_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);


DBMS_CLOUD.VALIDATE_HYBRID_PART_TABLE (
       table_name                 IN VARCHAR2,
       operation_id               OUT NUMBER,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

パラメータ

REGEXP_LIKE演算子と互換性のある正規表現パターンを使用して、削除するファイルのリストをフィルタできます。

ソースとターゲットのバケットまたはフォルダは、同じまたは異なるクラウド・オブジェクト・ストア・プロバイダに配置できます。

ソースとターゲットが個別のオブジェクト・ストアにある場合、または同じクラウド・プロバイダを持つ異なるアカウントがある場合は、ソースとターゲットの場所に個別の資格証明名を指定できます。

デフォルトでは、ソース資格証明名はターゲットの場所でも使用されます。

構文

DBMS_CLOUD.BULK_COPY (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_COPY (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL,
      operation_id            OUT NUMBER
);

パラメータ

source_location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

source_location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv

使用上のノート

• ソースURIとターゲットURIが同じオブジェクト・ストレージ・バケットまたはフォルダを指している場合、エラーが返されます。

例

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

構文

 DBMS_CLOUD.BULK_DELETE(
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_DELETE (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL,
     operation_id     OUT NUMBER
);

パラメータ

location_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

例

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

構文

DBMS_CLOUD.BULK_DOWNLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_DOWNLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL,
     operation_id     OUT NUMBER
);

パラメータ

location_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

例

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

REGEXP_LIKE演算子と互換性のある正規表現パターンを使用して、削除するファイルのリストをフィルタできます。

ソースとターゲットのバケットまたはフォルダは、同じまたは異なるクラウド・オブジェクト・ストア・プロバイダに配置できます。

ソースとターゲットが個別のオブジェクト・ストアにある場合、または同じクラウド・プロバイダを持つ異なるアカウントがある場合は、ソースとターゲットの場所に個別の資格証明名を指定できます。

ソース資格証明名は、ターゲット資格証明名が指定されていない場合、ターゲットの場所でもデフォルトで使用されます。

ファイルを移動する最初のステップは、ターゲットの場所にコピーしてから、正常にコピーされたソース・ファイルを削除することです。

オブジェクト・ストアでソースの場所とターゲットの場所の間の操作の名前変更が許可されている場合、オブジェクトは移動ではなく名前変更されます。

構文

DBMS_CLOUD.BULK_MOVE (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_MOVE (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL,
      operation_id            OUT NUMBER
);

パラメータ

source_location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

source_location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv

例

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

構文

DBMS_CLOUD.BULK_UPLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_UPLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL,
     operation_id     OUT NUMBER
);

パラメータ

例

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

DBMS_CLOUDは、GET、PUT、POST、HEADおよびDELETE HTTPメソッドをサポートしています。HTTPリクエストに使用されるREST APIメソッドは通常、クラウドREST APIドキュメントに記載されています。

デフォルトでは、DBMS_CLOUD REST APIコールはセッションの結果を保存しません。この場合、DBMS_CLOUD.SEND_REQUEST関数を使用して結果を返します。

DBMS_CLOUD.SEND_REQUESTを使用してcacheパラメータをTRUEに設定すると、結果が保存され、過去の結果をSESSION_CLOUD_API_RESULTSビューで表示できます。DBMS_CLOUD REST APIリクエストの履歴結果を保存および問合せすると、アプリケーションで以前の結果を処理する必要がある場合に役立ちます。

たとえば、最近のDBMS_CLOUD REST APIの結果を問い合せるには、ビューSESSION_CLOUD_API_RESULTSを使用します。

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

DBMS_CLOUD REST APIの結果をDBMS_CLOUD.SEND_REQUESTで保存すると、保存されたデータは同じセッション(接続)内でのみ使用できます。セッションが終了すると、保存されたデータは使用できなくなります。

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZEおよびDBMS_CLOUD.SET_API_RESULT_CACHE_SIZEを使用して、DBMS_CLOUD REST APIキャッシュ・サイズを表示および設定し、キャッシュを無効にします。

構文

DBMS_CLOUD.GET_RESPONSE_HEADERS(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN JSON_OBJECT_T;

パラメータ

例外

構文

DBMS_CLOUD.GET_RESPONSE_RAW(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN BLOB;

パラメータ

例外

構文

DBMS_CLOUD.GET_RESPONSE_STATUS_CODE(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN PLS_INTEGER;

パラメータ

例外

構文

DBMS_CLOUD.GET_RESPONSE_TEXT(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN CLOB;

パラメータ

例外

構文

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE()
   RETURN NUMBER;

構文

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL)
   RETURN DBMS_CLOUD_TYPES.resp;

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL);

パラメータ

例外

使用上のノート

• Oracle Cloud Infrastructureを使用している場合は、credential_nameに署名キー・ベースの資格証明値を使用する必要があります。詳細は「CREATE_CREDENTIALプロシージャ」を参照してください。

• オプションのパラメータasync_request_url、wait_for_statesおよびtimeoutを使用すると、長時間実行リクエストを処理できます。この非同期形式のsend_requestを使用すると、ファンクションはwait_for_statesで指定された完了ステータスを待機してから戻ります。送信リクエストでこれらのパラメータを使用して、予期される戻り状態をwait_for_statesパラメータで渡し、async_request_urlパラメータを使用して関連する作業リクエストを指定しても、リクエストはすぐには戻されません。かわりに、リクエストは、戻り状態が予想される状態のいずれかになるか、timeoutを超える(timeoutはオプション)まで、async_request_urlをプローブします。timeoutが指定されていない場合、リクエストは、wait_for_statesで検出された状態が発生するまで待機します。

構文

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

パラメータ

例外

例

EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(101);

バケットの作成の例

DBMS_CLOUD.SEND_REQUESTをHTTP POSTメソッドとともに使用して、bucketnameという名前のオブジェクト・ストア・バケットを作成する例を示します。

この例のOracle Cloud Infrastructure Object Storage Service APIの詳細は、CreateBucketを参照してください。

SET SERVEROUTPUT ON
DECLARE
  resp DBMS_CLOUD_TYPES.resp;
BEGIN
  -- Send request
  resp := DBMS_CLOUD.send_request(
            credential_name => 'OCI_KEY_CRED',
            uri => 'https://objectstorage.region.oraclecloud.com/n/namespace-string/b/',
            method => DBMS_CLOUD.METHOD_POST,
            body => UTL_RAW.cast_to_raw(
                        JSON_OBJECT('name' value 'bucketname',
                                    'compartmentId' value 'compartment_OCID'))
          );
 
  -- Response Body in TEXT format
  dbms_output.put_line('Body: ' || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_text(resp) || CHR(10));
  
  -- Response Headers in JSON format
  dbms_output.put_line('Headers: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_headers(resp).to_clob || CHR(10));
 
  -- Response Status Code
  dbms_output.put_line('Status Code: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_status_code(resp));
 
END;
/

ノート:

• この例では、namespace-stringはOracle Cloud Infrastructureオブジェクト・ストレージ・ネームスペースで、bucketnameはバケット名です。詳細は、オブジェクト・ストレージ・ネームスペースの理解を参照してください。

• この場合、regionはエンドポイント・リージョンです。詳細は、「APIリファレンスおよびエンドポイント」のオブジェクト・ストレージAPIリファレンスを参照してください。たとえば、regionはus-phoenix-1です。

バケットの削除の例

DBMS_CLOUD.SEND_REQUESTをHTTP DELETEメソッドとともに使用して、bucketnameという名前のオブジェクト・ストア・バケットを削除する例を示します。

この例のOracle Cloud Infrastructure Object Storage Service APIの詳細は、DeleteBucketを参照してください。

SET SERVEROUTPUT ON
DECLARE
  resp DBMS_CLOUD_TYPES.resp;
BEGIN
  -- Send request
  resp := DBMS_CLOUD.send_request(
            credential_name => 'OCI_KEY_CRED',
            uri => 'https://objectstorage.region.oraclecloud.com/n/namespace-string/b/bucketname',
            method => DBMS_CLOUD.METHOD_DELETE
          );
 
  -- Response Body in TEXT format
  dbms_output.put_line('Body: ' || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_text(resp) || CHR(10));
  
  -- Response Headers in JSON format
  dbms_output.put_line('Headers: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_headers(resp).to_clob || CHR(10));
 
  -- Response Status Code
  dbms_output.put_line('Status Code: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_status_code(resp));
 
END;
/

ノート:

• この例では、namespace-stringはOracle Cloud Infrastructureオブジェクト・ストレージ・ネームスペースで、bucketnameはバケット名です。詳細は、オブジェクト・ストレージ・ネームスペースの理解を参照してください。

• この場合、regionはエンドポイント・リージョンです。詳細は、「APIリファレンスおよびエンドポイント」のオブジェクト・ストレージAPIリファレンスを参照してください。たとえば、regionはus-phoenix-1です。

コンパートメントのリストの例

DBMS_CLOUD.SEND_REQUESTをHTTP GETメソッドとともに使用して、テナンシ(ルート・コンパートメント)内のすべてのコンパートメントをリストする例を示します。この例は、DBMS_CLOUD.SEND_REQUESTでリクエスト・ヘッダーを渡す方法を示しています。

この例のOracle Cloud Infrastructure Identity and Access Management Service APIの詳細は、ListCompartmentsを参照してください。

--
-- List compartments
--
DECLARE
  resp DBMS_CLOUD_TYPES.resp;
  root_compartment_ocid VARCHAR2(512) := '&1';
BEGIN
  -- Send request
  dbms_output.put_line('Send Request');
  resp := DBMS_CLOUD.send_request(
            credential_name => 'OCI_KEY_CRED',
            uri => 'https://identity.region.oraclecloud.com/20160918/compartments?compartmentId=' || root_compartment_ocid,
            method => DBMS_CLOUD.METHOD_GET,
            headers => JSON_OBJECT('opc-request-id' value 'list-compartments')
          );
  dbms_output.put_line('Body: ' || '------------' || CHR(10) || DBMS_CLOUD.get_response_text(resp) || CHR(10));
  dbms_output.put_line('Headers: ' || CHR(10) || '------------' || CHR(10) || DBMS_CLOUD.get_response_headers(resp).to_clob || CHR(10));
  dbms_output.put_line('Status Code: ' || CHR(10) || '------------' || CHR(10) || DBMS_CLOUD.get_response_status_code(resp));
  dbms_output.put_line(CHR(10));
END;
/

この場合、regionはエンドポイント・リージョンです。詳細は、「APIリファレンスおよびエンドポイント」のIdentity and Access Management (IAM) APIリファレンスを参照してください。たとえば、regionはuk-london-1です。

非同期リクエストの例

DBMS_CLOUD.SEND_REQUESTをHTTP POSTメソッドとともに使用してAutonomous Databaseの停止操作を実行し、ステータス待ちする例を示します。この例は、DBMS_CLOUD.SEND_REQUESTをasync_request_url、wait_for_statesおよびtimeoutパラメータとともに使用する方法を示しています。

--
-- Sent Work Request Autonomous Database Stop Request with Wait for Status
DECLARE
    l_resp DBMS_CLOUD_TYPES.resp;
    l_resp_json JSON_OBJECT_T;
    l_key_shape JSON_OBJECT_T;
    l_body JSON_OBJECT_T;
    status_array DBMS_CLOUD_TYPES.wait_for_states_t;
BEGIN
  status_array := DBMS_CLOUD_TYPES.wait_for_states_t('SUCCEEDED');
  l_body := JSON_OBJECT_T('{}');
  l_body.put('autonomousDatabaseId', 'ocid');
-- Send request
  dbms_output.put_line(l_body.to_clob);
  dbms_output.put_line('Send Request');
  l_resp := DBMS_CLOUD.send_request(
                       credential_name    => 'NATIVE_CRED_OCI',
                       uri                => 'https://database.region.oraclecloud.com/20160918/autonomousDatabases/ocid/actions/stop',
                       method             => DBMS_CLOUD.METHOD_POST,
                       body               => UTL_RAW.cast_to_raw(l_body.to_clob),
                       async_request_url  => 'https://iaas.region.oraclecloud.com/20160918/workRequests',
                       wait_for_states    => status_array,
                       timeout            => 600
                  );
   dbms_output.put_line('resp body: '||DBMS_CLOUD.get_response_text(l_resp));
   dbms_output.put_line('resp headers: '||DBMS_CLOUD.get_response_headers(l_resp).to_clob);
END;
/

この場合、regionはエンドポイント・リージョンです。詳細は、「APIリファレンスおよびエンドポイント」のIdentity and Access Management (IAM) APIリファレンスを参照してください。たとえば、regionはuk-london-1です。

ocidは、Oracle Cloud Infrastructureリソース識別子である。詳細は、「リソース識別子」を参照してください。