データのロードやクラウド内の外部データの問合せを行う場合、または他のケースで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 Key Vault
    • 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署名キー認証では、Oracle Cloud Infrastructure署名キー関連のパラメータ(user_ocid、tenancy_ocid、private_key、fingerprintなど)を使用します。

次に例を示します。

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をコールする場合、usernameはAzureストレージ・アカウント名で、passwordはAzureストレージ・アカウント・アクセス・キーです。Azureストレージ・アカウントについてを参照してください。

Amazon S3互換の資格証明

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

ソース・ファイルがAmazon S3にある場合、またはAWS APIをコールしている場合、paramsを使用してAmazonリソース名(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 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;
/

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

構文

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には、通常のCREATE TABLEのDEFAULT句のように機能する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 Storage、Wasabi Hot Cloud Storageなど。

  • 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);

パラメータ

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'

使用上のノート

• プロシージャ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 Storage、Wasabi Hot Cloud Storageなど。

  • 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

サポートされている構成の詳細は、「Apache Iceberg表の問合せについて」を参照してください。

構文

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')

構文

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の例

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

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

パラメータ

例

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 Storage、Wasabi Hot Cloud Storageなど。

  • 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パラメータ値は、必要に応じて、結合や副問合せを含む問合せなどの拡張問合せにすることができます。

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

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

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

  • ORACLE_DATAPUMPアクセス・ドライバを使用したダンプ・ファイルへのデータの書込み。

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

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

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

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

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

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

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

• formatパラメータのtypeオプションにdatapumpを持つDBMS_CLOUD.EXPORT_DATAを使用したAutonomous Databaseエクスポートでは、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 Database OCPUの数、サービス・レベル、データのサイズによって異なります。

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

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

  • Autonomous 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

サンプル

次の例は、formatのtypeパラメータに値datapumpが指定された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 warehouse_id, quantity FROM inventories'
     );
   END;
/  

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

次の例は、formatのtypeパラメータに値jsonが指定された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;
/  

次の例は、formatのtypeパラメータに値xmlが指定された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;
/

次の例は、formatのtypeパラメータに値csvが指定された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;
/  

次の例は、typeパラメータに値datapumpを使用して、ディレクトリの場所にデータをエクスポートする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;

パラメータ

使用上のノート

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

  GRANT READ ON DIRECTORY data_pump_dir TO adb_user;

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

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

例

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

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_OBJECTS (
       credential_name      IN VARCHAR2,
       location_uri         IN VARCHAR2)
   RETURN TABLE;

パラメータ

使用上のノート

• オブジェクト・ストアの機能によって、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リポジトリ

• チェックサム値は、MD5チェックサムです。これは、オブジェクトの内容に基づいて計算されます。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はバケット名です。詳細は、オブジェクト・ストレージ・ネームスペースの理解を参照してください。

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

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

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

構文

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

パラメータ

使用上のノート

• ソースとターゲットの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
);

パラメータ

例

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

パラメータ

例

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

パラメータ

例

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です。

バケットの削除の例

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

この例の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です。

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

HTTP GETメソッドでDBMS_CLOUD.SEND_REQUESTを使用して、テナント(ルート・コンパートメント)内のすべてのコンパートメントをリストする例を示します。この例では、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です。

非同期リクエストの例

HTTP POSTメソッドでDBMS_CLOUD.SEND_REQUESTを使用して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リソース識別子です。詳細は、リソース識別子を参照してください。