DBMS_CLOUDサブプログラムおよびREST API
このページのスクリプト・コンテンツはナビゲーションのみを目的としており、いかなる方法においても内容を変更するものではありません。
この項では、Autonomous AI Databaseで提供されるDBMS_CLOUDサブプログラムおよびREST APIについて説明します
注意:
ユーザー以外のユーザーでサブプログラムを実行するには、そのユーザーに権限を付与する必要があります。たとえば、次のコマンドを実行して、次の権限を付与します:
GRANT EXECUTE ON DBMS_CLOUD TO adb_user;アクセス管理用のDBMS_CLOUD
資格証明の作成、削除および更新など、DBMS_CLOUDパッケージ内の資格証明管理のためのサブプログラム。
| サブプログラム | 摘要 |
|---|---|
| CREATE_CREDENTIALプロシージャ | このプロシージャでは、クラウド・サービス資格証明がAutonomous AI Databaseに格納されます。 |
| DROP_CREDENTIALプロシージャ | このプロシージャは、Autonomous AI Databaseから既存の資格証明を削除します。 |
| REFRESH_VAULT_CREDENTIALプロシージャ | このプロシージャは、ボールト・シークレット資格証明のボールト・シークレットを即時にリフレッシュして、Autonomous AI Database内の指定されたcredential_nameのボールト・シークレットの最新バージョンを取得します。 |
| UPDATE_CREDENTIALプロシージャ | このプロシージャは、Autonomous AI Database内のクラウド・サービス資格証明属性を更新します。 |
CREATE_CREDENTIALプロシージャ
このプロシージャでは、クラウド・サービス資格証明がAutonomous AI Databaseに格納されます。
データのロード、クラウド内の外部データの問合せ、または他のケースで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);パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
格納する資格証明の名前。credential_nameパラメータは、Oracleオブジェクトのネーミング規則に準拠している必要があります。credential_nameパラメータは、引用符なしの識別子または引用符付き識別子として定義できます。詳細は、「データベース・オブジェクトのネーミング規則」を参照してください。 |
username |
username引数とpassword引数の両方で、クラウド・サービス資格証明を指定します。様々なクラウド・サービスに関してusernameとpasswordに指定する内容については、使用時のノートを参照してください。 |
password |
username引数とpassword引数の両方で、クラウド・サービス資格証明を指定します。 |
comments |
資格証明のコメント・テキストを指定します。このフィールドは、資格証明の説明および識別に役立ちます。 コメントの最大長は3800文字です。 |
user_ocid |
ユーザーのOCIDを指定します。ユーザーのOCIDの取得の詳細は、テナンシのOCIDおよびユーザーのOCIDの取得場所を参照してください。 |
tenancy_ocid |
テナンシのOCIDを指定します。テナンシのOCIDの取得の詳細は、テナンシのOCIDおよびユーザーのOCIDの取得場所を参照してください。 |
private_key |
生成された秘密キーを指定します。パスフレーズを設定して生成された秘密キーはサポートされていません。パスフレーズなしで秘密キーを生成する必要があります。PEMフォーマットのキー・ペアの生成の詳細は、API署名キーの生成方法を参照してください。 |
fingerprint |
フィンガープリントを指定します。生成された公開キーがユーザーのアカウントにアップロードされると、コンソールにフィンガープリントが表示されます。表示されたフィンガープリントをこの引数に使用します。詳細は、キーのフィンガープリントの取得方法およびAPI署名キーの生成方法を参照してください。 |
params |
次のいずれかの資格証明パラメータを指定します。
|
使用上のノート
-
この操作によって、資格証明が暗号化された形式でデータベースに格納されます。
-
ユーザーは、
user_credentials表を問い合せることにより、自分のスキーマ内の資格証明を確認できます。 user_credentials表を問い合せると、自分のスキーマの資格コメントを確認できます。次に例を示します。SELECT comments FROM user_credentials WHERE credential_name = 'MY_CRED';-
ADMINユーザーは、dba_credentials表を問い合せることにより、すべての資格証明を表示できます。 -
クラウド・サービス資格証明が変更されないかぎり、資格証明を作成する必要があるのは1回のみです。資格証明を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.comOracle 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 => 'ocid
1.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互換の資格証明
| サービス | 資格証明情報 |
|---|---|
| Oracle Cloud Infrastructure (顧客秘密キー) | ソース・ファイルがOracle Cloud Infrastructureに存在する場合は、顧客秘密キーをS3互換URLとともに使用する必要があります。詳細は、顧客秘密キーの作業を参照してください。 |
| Google Cloud Storage | ソース・ファイルがGoogle Cloud Storageに存在する場合、またはGoogle Cloud Storage APIをコールしている場合は、デフォルトのGoogleプロジェクトを設定し、HMACキーを取得して、Google Cloud Storage S3互換URLを提供する資格証明を作成する必要があります。ユーザー名としてHMACキーIDを使用し、パスワードとしてHMACシークレットを使用します。 |
| Wasabi Hot Cloud Storage | ソース・ファイルがWasabi Hot Cloud Storageに存在する場合、またはWasabi Hot Cloud Storage APIをコールしている場合は、S3互換URLを提供する資格証明を作成するためにアクセス・キーが必要です。ユーザー名としてWasabi Hot Cloud Storageアクセス・キーを使用し、パスワードとしてWasabi Hot Cloud Storage秘密キーを使用します。 詳細は、Wasabi APIアクセス・キー・セットの作成を参照してください。 |
AWS Amazon Resource Name (ARN)の資格証明
ソース・ファイルがAmazon S3にあるか、AWS APIをコールする場合は、paramsを使用してAmazon Resource Names (ARN)についてのパラメータを指定してください。
| パラメータ | 値 |
|---|---|
aws_role_arn |
AWSロールを特定するAmazon Resource Name (ARN)を指定します。 資格証明の作成時にこのパラメータを指定しなかった場合は、 |
external_id_type |
オプションで、 資格証明の作成時にこのパラメータを指定しない場合、デフォルト値は |
たとえば:
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資格証明パラメータを指定します。
| パラメータ | 値 |
|---|---|
gcp_oauth2 |
次のパラメータとその値を含むJSONオブジェクトを使用して、Google AnalyticsまたはGoogle BigQueryに対するOAuth 2.0アクセスを指定します。
Google OAuth資格証明の詳細は、OAuth 2.0を使用したGoogle APIへのアクセスを参照してください。 |
たとえば:
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です。secret_id値をボールト・シークレットOCIDとして指定します。詳細は、「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権限が必要です。
DROP_CREDENTIALプロシージャ
このプロシージャは、Autonomous AI Databaseから既存の資格証明を削除します。
構文
DBMS_CLOUD.DROP_CREDENTIAL (
credential_name IN VARCHAR2);パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
削除する資格証明の名前。 |
REFRESH_VAULT_CREDENTIALプロシージャ
このプロシージャは、ボールト・シークレット資格証明のボールト・シークレットをリフレッシュします。
このプロシージャを使用すると、ボールト・シークレット資格証明のボールト・シークレットをすぐにリフレッシュして、指定したcredential_nameの最新バージョンのボールト・シークレットを取得できます。
構文
DBMS_CLOUD.REFRESH_VAULT_CREDENTIAL (
credential_name IN VARCHAR2);パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
リフレッシュする資格証明の名前。 |
使用上のノート
-
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; /
UPDATE_CREDENTIALプロシージャ
このプロシージャにより、指定したcredential_nameの新しい値で属性が更新されます。
データのロード、クラウド内の外部データの問合せ、またはcredential_nameパラメータでDBMS_CLOUDプロシージャを使用する場合には、格納されている資格証明を使用します。
構文
DBMS_CLOUD.UPDATE_CREDENTIAL (
credential_name IN VARCHAR2,
attribute IN VARCHAR2,
value IN VARCHAR2);パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
更新する資格証明の名前。 |
attribute |
更新する属性の名前。 ユーザー名/パスワード・タイプの資格証明の場合、有効な Amazon ARNの資格証明の場合、有効な Google BigQueryまたはGoogle Analyticsの資格証明の場合、有効な 使用しているボールトに応じて、Vaultシークレット資格証明の場合、有効な
詳細は、「CREATE_CREDENTIALプロシージャ」を参照してください。 |
value |
指定された属性の新しい値。 |
使用上のノート
-
ユーザー名の値では大文字と小文字が区別されます。二重引用符や空白を含めることはできません。
-
ADMINユーザーは、dba_credentialsを問い合せることで、すべての資格証明を参照できます。 -
クラウド・サービス資格証明が変更されないかぎり、資格証明を作成する必要があるのは1回のみです。資格証明を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
DBMS_CLOUDパッケージ内のオブジェクトおよびファイル管理用のサブプログラム。
| サブプログラム | 摘要 |
|---|---|
| COPY_COLLECTIONプロシージャ | このプロシージャは、クラウド・オブジェクト・ストレージまたはディレクトリ内のファイルから、既存のSODAコレクションにデータをロードします。 |
| COPY_DATAプロシージャ | このプロシージャは、クラウド・オブジェクト・ストレージから、またはディレクトリ内のファイルから、既存のAutonomous AI Database表にデータをロードします。 |
| Avro、ORCまたはParquetファイル用のCOPY_DATAプロシージャ | このプロシージャは、formatパラメータのtypeを値orc、parquetまたはavroに設定して、クラウド内のORC、ParquetまたはAvroファイルから、またはディレクトリ内のORC、ParquetまたはAvroファイルから既存のAutonomous AI Database表にデータをロードします。テキスト・ファイルと同様に、データはソースのAvro、ORCまたはParquetファイルから既存の内部表にコピーされます。 |
| COPY_OBJECTプロシージャ | このプロシージャは、クラウド・オブジェクト・ストレージ・バケット間でファイルをコピーします。 |
| CREATE_CLOUD_TABLEプロシージャ | このプロシージャは、すべての永続データがOracle管理オブジェクト・ストレージに格納されるクラウド表を作成します。 |
| CREATE_EXTERNAL_TABLEプロシージャ | このプロシージャでは、クラウド内のファイルに基づいて、またはディレクトリ内のファイルから外部表を作成します。これにより、Autonomous AI Databaseから外部データに対する問合せを実行できます。 |
| Apache IcebergのCREATE_EXTERNAL_TABLEプロシージャ | このプロシージャは、サポートされている構成でApache Iceberg表の外部表を作成します。 |
| Avro、ORCまたはParquetファイル用のCREATE_EXTERNAL_TABLEプロシージャ | このプロシージャは、formatパラメータのtypeを値parquet、orcまたはavroに設定することによって、クラウドまたはディレクトリにParquet、ORCまたはAvroフォーマット・ファイルを使用して外部表を作成します。これにより、Autonomous AI Databaseから外部データに対する問合せを実行できます。 |
| CREATE_EXTERNAL_PART_TABLEプロシージャ | このプロシージャでは、クラウド内のファイルに外部パーティション表を作成します。これにより、Autonomous AI Databaseから外部データに対する問合せを実行できます。 |
| CREATE_EXTERNAL_TEXT_INDEXプロシージャ | このプロシージャは、オブジェクト・ストア・ファイルにテキスト索引を作成します。 |
| CREATE_HYBRID_PART_TABLEプロシージャ | このプロシージャでは、ハイブリッド・パーティション表を作成します。これにより、Autonomous AI Databaseからハイブリッド・パーティション・データに対する問合せを実行できます。 |
| DELETE_ALL_OPERATIONSプロシージャ | このプロシージャでは、スキーマ内のuser_load_operations表に記録されたすべてのデータ・ロード操作を消去するか、typeパラメータで示されている、指定されたタイプのすべてのデータ・ロード操作を消去します。 |
| DELETE_FILEプロシージャ | このプロシージャは、Autonomous AI Database上の指定されたディレクトリから指定したファイルを削除します |
| DELETE_OBJECTプロシージャ | このプロシージャは、オブジェクト・ストアの指定されたオブジェクトを削除します。 |
| DELETE_OPERATIONプロシージャ | このプロシージャは、入力としてoperation_idを受け入れ、指定されたoperation_idに関連付けられたログを削除します。 |
| DROP_EXTERNAL_TEXT_INDEXプロシージャ | このプロシージャは、オブジェクト・ストア・ファイルのテキスト索引を削除します。 |
| EXPORT_DATAプロシージャ | このプロシージャは、問合せの結果に基づいてAutonomous AI Databaseからクラウド内のファイルにデータをエクスポートします。オーバーロード・フォームでは、operation_idパラメータを使用できます。指定されたformatパラメータのtypeオプションに応じて、CSV、JSON、ParquetまたはXMLのオプションを含むテキストとしてクラウド・オブジェクト・ストアに行をエクスポートするか、ORACLE_DATAPUMPアクセス・ドライバを使用してデータをダンプ・ファイルに書き込みます。 |
| GET_OBJECTプロシージャ/ファンクション | このプロシージャはオーバーロードされています。プロシージャ・フォームは、Cloud Object Storageからオブジェクトを読み取り、そのオブジェクトをAutonomous AI Databaseにコピーします。このファンクション・フォームは、Cloud Object Storageからオブジェクトを読み取り、BLOBをAutonomous AI Databaseに返します。 |
| LIST_FILESファンクション | このファンクションは、指定されたディレクトリ内のファイルを一覧表示します。結果には、ファイル名と、ファイルに関する追加のメタデータ(ファイル・サイズ(バイト)、作成タイムスタンプ、最終変更タイムスタンプなど)が含まれます。 |
| LIST_OBJECTSファンクション | このファンクションは、オブジェクト・ストアの指定された場所にあるオブジェクトを一覧表示します。結果には、オブジェクト名と、オブジェクトに関する追加のメタデータ(サイズ、チェックサム、作成タイムスタンプ、最終変更タイムスタンプなど)が含まれます。 |
| MOVE_OBJECTプロシージャ | このプロシージャは、あるクラウド・オブジェクト・ストレージ・バケットから別のバケットにオブジェクトを移動します。 |
| PUT_OBJECTプロシージャ | このプロシージャはオーバーロードされています。このプロシージャは、1つの形式でAutonomous AI DatabaseからCloud Object Storageファイルにファイルをコピーします。別の形式では、このプロシージャには、Autonomous AI DatabaseからCloud Object StorageにBLOBがコピーされます。 |
| SYNC_EXTERNAL_PART_TABLEプロシージャ | この手順により、クラウド内のファイルから外部パーティション表を更新することが簡略化されます。新しいパーティションが追加されたとき、または外部パーティション表のオブジェクト・ストア・ソースからパーティションが削除されたときに、このプロシージャを実行します。 |
| VALIDATE_EXTERNAL_TABLEプロシージャ | このプロシージャでは、外部表のソース・ファイルを検証し、ログ情報を生成して、外部表に指定されたフォーマット・オプションと一致しない行をAutonomous AIデータベースのbadfile表に格納されます。 |
| VALIDATE_EXTERNAL_PART_TABLEプロシージャ | このプロシージャにより、外部パーティション表のソース・ファイルが検証され、ログ情報が生成され、外部表に指定したフォーマット・オプションと一致しない行がAutonomous AI DatabaseのbadFile表に格納されます。 |
| VALIDATE_HYBRID_PART_TABLEプロシージャ | このプロシージャによって、ハイブリッド・パーティション表のソース・ファイルが検証され、ログ情報が生成され、ハイブリッド表に指定されたフォーマット・オプションと一致しない行がAutonomous AI DatabaseのbadFile表に格納されます。 |
COPY_COLLECTIONプロシージャ
このプロシージャでは、クラウド・オブジェクト・ストレージからまたはディレクトリからSODAコレクションにデータがロードされます。指定したSODAコレクションが存在しない場合は、プロシージャによって作成されます。オーバーロード・フォームでは、operation_idパラメータを使用できます。
構文
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
);パラメータ
| パラメータ | 摘要 |
|---|---|
collection_name |
データのロード先のSODAコレクションの名前。この名前のコレクションがすでに存在する場合は、指定したデータがロードされ、そうでない場合は新しいコレクションが作成されます。 |
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、
|
file_uri_list |
このパラメータでは、ソース・ファイルURIのカンマ区切りリスト、または1つ以上のディレクトリとソース・ファイルを指定します。 クラウドのソース・ファイルURI クラウド・ソース・ファイルURIのファイル名には、ワイルドカードと正規表現を使用できます。 正規表現を使用できるのは、
正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされ、パターン一致は たとえば: `sql 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'` URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」をご覧ください。
ディレクトリ 1つのディレクトリと1つ以上のファイル名を指定することも、ディレクトリとファイル名のカンマ区切りリストを使用することもできます。ディレクトリを指定する形式は、 ディレクトリにファイル名を指定する場合、正規表現はサポートされません。ワイルドカードを使用して、ディレクトリ内のファイル名を指定できます。文字「*」は複数の文字のワイルドカードとして使用でき、文字「?」は1文字のワイルドカードとして使用できます。例: 複数のディレクトリを指定するには、ディレクトリのカンマ区切りリストを使用します。例: 大/小文字を区別するディレクトリ名を指定するには、二重引用符を使用します。例: 引用符文字を含めるには、2つの引用符を使用します。例: |
format |
ソース・ファイルのフォーマットを説明するオプション。これらのオプションはJSON文字列として指定されます。 サポートされている形式は、 前述したJSONデータのフォーマットとは別に、Autonomous AI Databaseでは他のフォーマットもサポートされています。Autonomous AI Databaseでサポートされているフォーマット引数のリストは、「DBMS_CLOUDパッケージ・フォーマット・オプション」を参照してください。 |
operation_id |
このパラメータを使用して、USER_LOAD_OPERATIONSビューで、ロード操作の進行状況および最終ステータスを対応するIDとして追跡します。 |
例
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;
/COPY_DATAプロシージャ
このプロシージャにより、クラウドのファイルまたはディレクトリ内のファイルから既存のAutonomous AI Database表にデータがロードされます。オーバーロード・フォームでは、operation_idパラメータを使用できます。
構文
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);パラメータ
| パラメータ | 摘要 |
|---|---|
table_name |
データベースのターゲット表の名前。ターゲット表はCOPY_DATAを実行する前に作成しておく必要があります。 |
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、 このパラメータは、 |
file_uri_list |
このパラメータでは、次のいずれかを指定します。
クラウド・ソース・ファイルURIのファイル名には、ワイルドカードと正規表現を使用できます。 クラウドのソース・ファイルURI このパラメータでは、ソース・ファイルURIのカンマ区切りリスト、または1つ以上のディレクトリとソース・ファイルを指定します。 正規表現を使用できるのは、
正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされ、パターン一致は たとえば: `sql 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'` URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」をご覧ください。
表ハイパーリンクURL 表のハイパーリンクは次の方法で使用できます。
ディレクトリ 1つのディレクトリと1つ以上のファイル名を指定することも、ディレクトリとファイル名のカンマ区切りリストを使用することもできます。ディレクトリを指定する形式は、 ディレクトリにファイル名を指定する場合、正規表現はサポートされません。ワイルドカードを使用して、ディレクトリ内のファイル名を指定できます。文字「*」は複数文字のワイルドカードとして使用でき、文字「?」は1文字のワイルドカードとして使用することができます。例: 複数のディレクトリを指定するには、ディレクトリのカンマ区切りリストを使用します。例: 大/小文字を区別するディレクトリ名を指定するには、二重引用符を使用します。例: 引用符文字を含めるには、2つの引用符を使用します。例: |
schema_name |
ターゲット表が存在するスキーマの名前。デフォルト値はNULLで、ターゲット表がプロシージャを実行しているユーザーと同じスキーマ内に存在することを意味します。 |
field_list |
ソース・ファイル内のフィールドとそのデータ型を識別します。デフォルト値はNULLで、フィールドとそのデータ型がターゲット表の定義によって決定されることを意味します。この引数の構文は、通常のOracle外部表の
|
format |
ソース・ファイル、ログ・ファイルおよび不良ファイルの形式を示すオプション。オプションのリストと値の指定方法については、「DBMS_CLOUDパッケージ・フォーマット・オプション」を参照。 Avro、ORCまたはParquetファイル形式オプションについては、「Avro、ORCまたはParquet用のDBMS_CLOUDパッケージの形式オプション」を参照してください。 |
operation_id |
このパラメータを使用して、USER_LOAD_OPERATIONSビューで、ロード操作の進行状況および最終ステータスを対応するIDとして追跡します。 |
使用上のノート
デフォルトのレコード・デリミタは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;
/Avro、ORCまたはParquetファイル用のCOPY_DATAプロシージャ
このプロシージャは、formatパラメータのtypeを値avro、orcまたはparquetに設定することで、「クラウド」のAvro、ORCまたはParquetファイルあるいはディレクトリ内のファイルから既存のAutonomous AI Database表にデータをロードします。
テキスト・ファイルと同様に、データはソースのAvro、ORCまたはParquetファイルから既存の内部表にコピーされます。
構文
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);パラメータ
| パラメータ | 摘要 |
|---|---|
table_name |
データベースのターゲット表の名前。ターゲット表はCOPY_DATAを実行する前に作成しておく必要があります。 |
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、
|
file_uri_list |
このパラメータでは、ソース・ファイルURIのカンマ区切りリスト、または1つ以上のディレクトリとソース・ファイルを指定します。 クラウドのソース・ファイルURI クラウド・ソース・ファイルURIのファイル名には、ワイルドカードと正規表現を使用できます。 正規表現を使用できるのは、
正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされ、パターン一致は たとえば: `sql 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'` URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」をご覧ください。
ディレクトリ 1つのディレクトリと1つ以上のファイル名を指定することも、ディレクトリとファイル名のカンマ区切りリストを使用することもできます。ディレクトリを指定する形式は、 ディレクトリにファイル名を指定する場合、正規表現はサポートされません。ワイルドカードを使用して、ディレクトリ内のファイル名を指定できます。文字「*」は複数の文字のワイルドカードとして使用でき、文字「?」は1文字のワイルドカードとして使用できます。例: 複数のディレクトリを指定するには、ディレクトリのカンマ区切りリストを使用します。例: 大/小文字を区別するディレクトリ名を指定するには、二重引用符を使用します。例: 引用符文字を含めるには、2つの引用符を使用します。例: |
schema_name |
ターゲット表が存在するスキーマの名前。デフォルト値はNULLで、ターゲット表がプロシージャを実行しているユーザーと同じスキーマ内に存在することを意味します。 |
field_list |
Avro、ORCまたはParquetファイルの場合は無視されます。 ソースのフィールドは、名前によって外部表の列と一致します。ソースのデータ型は、外部表の列のデータ型に変換されます。 ORCファイルの場合、詳細は、「DBMS_CLOUDパッケージのORCからOracleデータ型へのマッピング」に関する項を参照してください。 Parquetファイルの詳細は、「DBMS_CLOUDパッケージParquetからOracleデータ型へのマッピング」を参照してください。 Avroファイルについては、「DBMS_CLOUDパッケージAvroからOracleデータ型へのマッピング」を参照してください。 |
format |
ソース・ファイルのフォーマットを説明するオプション。Avro、ORCまたはParquetファイルについては、2つのオプションのみがサポートされています。「Avro、ORCまたはParquet用のDBMS_CLOUDパッケージの形式オプション」を参照してください。 |
使用上のノート
- 他のデータ・ファイルと同様に、Avro、ORCおよびParquetデータのロードにより、表
dba_load_operationsとuser_load_operationsで参照できるログが生成されます。各ロード操作により、ログを含む表を示すdba[user]_load_operationsにレコードが追加されます。
ログ表には、ロードに関するサマリー情報が表示されます。
-
Avro、ORCまたはParquetの場合、
formatパラメータのtypeが値1avro、orcまたはparquetに設定されていると、BADFILE_TABLE表は常に空になります。-
Parquetファイルの場合、
PRIMARY KEY制約エラーによりORAエラーがスローされます。 -
列のデータで変換エラーが発生した場合(たとえば、ターゲット列の大きさが変換後の値を格納できるほど大きくない場合など)、その列の値は
NULLに設定されます。これにより、拒否されたレコードは生成されません。
-
COPY_OBJECTプロシージャ
このプロシージャは、あるクラウド・オブジェクト・ストレージのバケットまたはフォルダから別のバケットにオブジェクトをコピーします。
ソースとターゲットのバケットまたはフォルダは、同じまたは異なるクラウド・オブジェクト・ストア・プロバイダに配置できます。
ソースとターゲットが個別のオブジェクト・ストアにある場合、または同じクラウド・プロバイダを持つ異なるアカウントがある場合は、ソースとターゲットの場所に個別の資格証明名を指定できます。
ソース資格証明名は、ターゲット資格証明名が指定されていない場合、ターゲットの場所でもデフォルトで使用されます。
構文
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
);パラメータ
| パラメータ | 摘要 |
|---|---|
source_credential_name |
ソースのクラウド・オブジェクト・ストレージにアクセスするための資格証明の名前です。 リソース・プリンシパルが有効になっている場合は、
|
source_object_uri |
ソース・オブジェクト・ストレージ・バケットまたはフォルダの場所を指すURIを指定します。 このパラメータは必須です。 URIのフォーマットは、クラウド・オブジェクト・ストレージ・サービスによって異なります。詳細は、「DBMS_CLOUD URIフォーマット」を参照してください。 |
target_object_uri |
ターゲット・オブジェクト・ストアのURIを指定します。 このパラメータは必須です。 URIのフォーマットは、クラウド・オブジェクト・ストレージ・サービスによって異なります。詳細は、「DBMS_CLOUD URIフォーマット」を参照してください。 |
target_credential_name |
ターゲットのクラウド・オブジェクト・ストレージの場所にアクセスするための資格証明の名前です。 リソース・プリンシパルが有効になっている場合は、
|
例
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;
/CREATE_CLOUD_TABLEプロシージャ
このプロシージャは、クラウド表を作成します。すべてのクラウド表データは、Oracle Managed Object Storageに格納されます(クラウド表には、メタデータのみがデータベースに格納されます)。
構文
DBMS_CLOUD.CREATE_CLOUD_TABLE (
table_name IN VARCHAR2,
column_list IN CLOB,
params IN CLOB);パラメータ
| パラメータ | 摘要 |
|---|---|
table_name |
クラウド表の名前。 |
column_list |
クラウド表の列名およびデータ型のカンマ区切りリスト。 |
使用上のノート
-
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;
/CREATE_EXTERNAL_PART_TABLEプロシージャ
このプロシージャでは、クラウド内のファイルに基づいて、またはディレクトリ内のファイルから外部パーティション表を作成します。これにより、Autonomous AI Databaseから外部データに対する問合せを実行できます。
構文
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);パラメータ
| パラメータ | 摘要 |
|---|---|
table_name |
外部表の名前。 |
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、 |
partitioning_clause |
個々のパーティションの場所情報を含む、完全なパーティション化句を指定します。
|
file_uri_list |
このパラメータでは、ソース・ファイルURIのカンマ区切りリスト、または1つ以上のディレクトリとソース・ファイルを指定します。 クラウドのソース・ファイルURI クラウド・ソース・ファイルURIのファイル名には、ワイルドカードと正規表現を使用できます。 正規表現を使用できるのは、
正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされ、パターン一致は このオプションは、オブジェクト・ストレージのファイルに作成される外部表でのみサポートされます。 たとえば:
`sql 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'` パラメータ URIのフォーマットは、クラウド・オブジェクト・ストレージ・サービスによって異なります。詳細は、「DBMS_CLOUD URIフォーマット」を参照してください。
|
column_list |
外部表の列名およびデータ型のカンマ区切りリスト。このパラメータには、
|
field_list |
ソース・ファイル内のフィールドとそのデータ型を識別します。デフォルト値はNULLで、フィールドおよびそのデータ型がcolumn_listパラメータによって決定されることを示します。この引数の構文は、通常のOracle外部表のfield_list句と同じです。field_listの詳細は、『Oracle® Databaseユーティリティ』をご覧ください。 |
format |
フォーマット・オプション
データ・ファイルが構造化されておらず、 Hive形式に基づかないオブジェクト名の場合、 ソース・ファイルの形式を説明するすべての |
使用上のノート
-
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;
/CREATE_EXTERNAL_TABLEプロシージャ
このプロシージャでは、クラウド内のファイルに基づいて、またはディレクトリ内のファイルから外部表を作成します。これにより、Autonomous AI Databaseから外部データに対する問合せを実行できます。
構文
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);パラメータ
| パラメータ | 摘要 |
|---|---|
table_name |
外部表の名前。 |
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、
|
file_uri_list |
このパラメータでは、次のいずれかを指定します。
クラウドのソース・ファイルURI クラウドのソース・ファイルURIのファイル名に正規表現を使用できます。 正規表現は、 正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされ、パターン一致は このオプションは、オブジェクト・ストレージのファイルに作成される外部表でのみサポートされます。 ノート クラウド・ソース・ファイルのURIは、ワイルドカードをサポートしていません。 URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」をご覧ください。
表ハイパーリンクURL 表のハイパーリンクURLを使用して、次の方法で外部表を作成できます。
ノート 詳細は、Autonomous AI Databaseの表のハイパーリンクについておよびCREATE_URLプロシージャを参照してください。ディレクトリ表のハイパーリンクURLでは、ワイルドカードはサポートされていません。 1つのディレクトリと1つ以上のファイル名を指定することも、ディレクトリとファイル名のカンマ区切りリストを使用することもできます。ディレクトリを指定する形式は、 ディレクトリにファイル名を指定する場合、正規表現はサポートされません。ワイルドカードを使用して、ディレクトリ内のファイル名を指定できます。文字「*」は複数の文字のワイルドカードとして使用でき、文字「?」は1文字のワイルドカードとして使用できます。例: 複数のディレクトリを指定するには、ディレクトリのカンマ区切りリストを使用します。例: 大/小文字を区別するディレクトリ名を指定するには、二重引用符を使用します。例: 引用符文字を含めるには、2つの引用符を使用します。例: |
column_list |
外部表の列名およびデータ型のカンマ区切りリスト。 |
field_list |
ソース・ファイル内のフィールドとそのデータ型を識別します。デフォルト値はNULLで、フィールドおよびそのデータ型がcolumn_listパラメータによって決定されることを示します。この引数の構文は、通常のOracle AI Database外部表のfield_list句と同じです。field_listの詳細は、「Oracle AI Databaseユーティリティのfield_definitions句の下のORACLE_LOADERアクセス・ドライバfield_list」を参照してください。 |
format |
ソース・ファイルのフォーマットを説明するオプション。オプションのリストと値の指定方法については、「DBMS_CLOUDパッケージ・フォーマット・オプション」を参照。 Avro、ORCまたはParquet形式のファイルについては、「Avro、ORCまたはParquetファイル用のCREATE_EXTERNAL_TABLE手順」を参照してください。 |
使用上のノート
-
プロシージャ
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 < 74CREATE_EXTERNAL_TABLE Apache Icebergの手順
このプロシージャは、サポートされている構成でApache Iceberg表の外部表を作成します。
次の特定の構成がサポートされています。
-
AWSのIcebergテーブル:
-
SparkまたはAthenaで作成されたAWS Glue Data Catalogに登録されているIcebergテーブル。
詳細は、AWS Glueコネクタを使用したACIDトランザクションを含むApache Iceberg表の読取りおよび書込みおよびタイム・トラベルの実行およびIceberg表の使用を参照してください。
-
ルート・メタデータ・ファイルのURLを直接指定することで、AWS S3に格納されているIceberg表。
-
-
OCIのIceberg表:
-
Hadoopカタログを使用してOCIデータ・フローで生成されたIceberg表。
詳細は、Oracle Data Flowの例およびHadoopカタログの使用を参照してください。
-
ルート・メタデータ・ファイルのURLを直接指定することで、OCIオブジェクト・ストレージに格納されているIceberg表。
-
-
Iceberg RESTカタログで定義されたIcebergテーブル
- location句がIceberg RESTカタログで定義されたIceberg表を指す外部表。
ノート
ノート: Apache Iceberg RESTカタログは、Oracle Database 19cでのみサポートされます。
構文
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
);パラメータ
| パラメータ | 摘要 |
|---|---|
table_name |
外部表の名前。 |
credential_name |
データ・ファイル、メタデータ・ファイルおよびIcebergカタログ(使用する場合)へのアクセスに使用される資格証明の名前。 AWSおよびOCI構成の場合は、CREATE_CREDENTIALプロシージャの説明に従って資格証明を作成する必要があります。 AWS Amazonリソース名(ARN)資格証明は現在サポートされていません。 |
file_uri_list |
Icebergカタログを指定する場合は、NULLである必要があります(後述のformatパラメータを参照)。氷山カタログを使用しない場合、file_uri_listには氷山メタデータ・ファイルへのURIが含まれている必要があります。 |
column_list |
列名および型はIcebergメタデータから自動的に導出されるため、NULLである必要があります。 列名は、基礎となるデータ・ファイル(Parquet、Avro、ORC)にある名前と一致します。Oracleデータ型は、Icebergデータ型とParquetデータ型、Avroデータ型およびORCデータ型の間のParquet/Avro/ORCマッピングを使用して導出されます。したがって、ユーザーは |
field_list |
列名およびデータ型はIcebergメタデータから自動的に導出されるため、NULLである必要があります。 |
format |
詳細は、OCIデータ・フロー・サンプルでのIcebergサポートおよびDBMS_CLOUD URIフォーマットを参照してください。 |
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')));ここで、access_protocolパラメータには、次の2つの要素を持つJSONオブジェクトが含まれます。
-
protocol_type: 'iceberg'である必要があります -
protocol_config: icebergカタログの詳細を指定するネストされたJSONオブジェクト。-
iceberg_catalog_type:'aws_glue'である必要があります -
iceberg_glue_region: カタログ・リージョン('us-west-1'など) -
iceberg_table_path:glue database.glue table nameパス。ノート
注意:
table_pathまたはiceberg_table_pathの選択:- RESTカタログ(
"protocol_type": "iceberg-rest")では、table_path (識別子の配列)を使用します。この例では、["<catalog>","<schema>","<table>"]のようにtable_pathを使用します。 - 非RESTカタログ(
"protocol_type": "iceberg")では、iceberg_table_path(database.table形式の文字列)を使用します。- AWS Glueの例:"iceberg_table_path": "database_name.table_name"。- Hadoopカタログの例:"iceberg_table_path": "database_name.table_name"。 - 直接メタデータ(metadata.json): どちらのキーも使用しないでください。かわりに、Icebergの
metadata.jsonファイルを指すfile_uri_listを指定し、"protocol_type": "iceberg"を設定します。カタログが構成されていない場合、file_uri_listにはメタデータ・ファイルのURIを含める必要があります。
- RESTカタログ(
-
メタデータ・ファイルURIを使用したAWS Iceberg表のフォーマット・パラメータの例
メタデータ・ファイルURIを使用してAWS Iceberg表に表を作成する場合のformatパラメータの例を次に示します。
format => json_object('access_protocol' value
json_object('protocol_type' value 'iceberg')HadoopCatalogカタログを使用したOCI Iceberg表のフォーマット・パラメータの例
HadoopCatalogカタログを使用してOCIデータ・フローによって作成されたOCI Iceberg表に表を作成する場合のformatパラメータの例を次に示します。
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')));ここで、access_protocolパラメータには、次の2つの要素を持つJSONオブジェクトが含まれます。
-
protocol_type:'iceberg'である必要があります -
protocol_config: icebergカタログの詳細を指定するネストされたJSONオブジェクト。-
iceberg_catalog_type:'hadoop'である必要があります -
iceberg_warehouse: ネイティブURI形式で表の生成時に使用されるウェアハウス・ディレクトリ・パス。 -
iceberg_table_path: 表の作成時に使用されるdatabase_name.table nameパス。
-
メタデータ・ファイルのURIを使用したOCI Iceberg表のフォーマット・パラメータの例
メタデータ・ファイルのURIを使用してOCI Iceberg表に表を作成する場合のformatパラメータの例を次に示します。
format => json_object('access_protocol' value
json_object('protocol_type' value 'iceberg')access_protocolパラメータには、次のように1つの要素を持つJSONオブジェクトが含まれます。
protocol_type:'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個人アクセス・トークンの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;
/Avro、ORCまたはParquetファイル用のCREATE_EXTERNAL_TABLEプロシージャ
このプロシージャは、formatパラメータのtypeを値avro、orcまたはparquetに設定することによって、クラウド内のAvro、ORCまたはParquet形式のファイルを使用して、あるいはディレクトリ内の外部表を作成します。
これにより、Autonomous AI Databaseから外部データに対する問合せを実行できます。
構文
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);パラメータ
| パラメータ | 摘要 |
|---|---|
table_name |
外部表の名前。 |
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、
|
file_uri_list |
このパラメータでは、ソース・ファイルURIのカンマ区切りリスト、または1つ以上のディレクトリとソース・ファイルを指定します。 クラウドのソース・ファイルURI クラウド・ソース・ファイルURIのファイル名には、ワイルドカードと正規表現を使用できます。 正規表現を使用できるのは、
正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされ、パターン一致は このオプションは、オブジェクト・ストレージのファイルに作成される外部表でのみサポートされます。 たとえば: `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'` URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」をご覧ください。
ディレクトリ 1つのディレクトリと1つ以上のファイル名を指定することも、ディレクトリとファイル名のカンマ区切りリストを使用することもできます。ディレクトリを指定する形式は、 ディレクトリにファイル名を指定する場合、正規表現はサポートされません。ワイルドカードを使用して、ディレクトリ内のファイル名を指定できます。文字「*」は複数の文字のワイルドカードとして使用でき、文字「?」は1文字のワイルドカードとして使用できます。例: 複数のディレクトリを指定するには、ディレクトリのカンマ区切りリストを使用します。例: 大/小文字を区別するディレクトリ名を指定するには、二重引用符を使用します。例: 引用符文字を含めるには、2つの引用符を使用します。例: |
column_list |
(オプション)このフィールドは、指定されると、スキーマ、列およびデータ型を自動的に導出するように指定する Avro、ORCまたはParquetソースに対して Parquetファイルの場合、詳細は、DBMS_CLOUDパッケージParquetからOracleデータ型へのマッピングを参照してください。 ORCファイルの場合、詳細は、「DBMS_CLOUDパッケージORCからOracleデータ型へのマッピング」を参照してください。 Avroファイルの場合、詳細は、DBMS_CLOUDパッケージAvroからOracleデータ型へのマッピングを参照してください。 |
field_list |
Avro、ORCまたはParquetファイルの場合、無視されます。 ソースのフィールドは、名前によって外部表の列と一致します。ソースのデータ型は、外部表の列のデータ型に変換されます。 ORCファイルについては、「DBMS_CLOUDパッケージORCからOracleデータ型へのマッピング」を参照してください Parquetファイルの場合、詳細は、DBMS_CLOUDパッケージParquetからOracleデータ型へのマッピングを参照してください。 Avroファイルの場合、詳細は、DBMS_CLOUDパッケージAvroからOracleデータ型へのマッピングを参照してください。 |
format |
Avro、ORCまたはParquetのtypeソース・ファイルについては、「Avro、ORC、またはParquet用のDBMS_CLOUDパッケージの形式オプション」を参照してください。 |
ORCの例
format => '{"type":"orc", "schema": "all"}'format => json_object('type' value 'orc', 'schema' value 'first')Avroの例
format => '{"type":"avro", "schema": "all"}'format => json_object('type' value 'avro', 'schema' value 'first')Parquetの例
format => '{"type":"parquet", "schema": "all"}'format => json_object('type' value 'parquet', 'schema' value 'first')Avro、ORCまたはParquet列名のOracle列名へのマッピング
Oracle SQLでの列名マッピングおよび列名変換の使用方法の詳細は、「DBMS_CLOUDパッケージAvro、ORCおよびParquetからOracle列名へのマッピング」を参照してください。
CREATE_EXTERNAL_TEXT_INDEXプロシージャ
このプロシージャは、オブジェクト・ストレージ・ファイルにテキスト索引を作成します。
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
);パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
Cloud Object Storageの場所にアクセスするための資格証明の名前です。パブリック、事前認証済または事前署名済のバケットURIの場合、NULLを指定できます。 詳細は、リソースにアクセスするためのポリシーとロールの構成を参照してください。
|
location_uri |
このパラメータは、ソース・ファイルURIのカンマ区切りリストを指定します。 クラウド・ソース・ファイルURIのファイル名には、ワイルドカードと正規表現を使用できます。 このパラメータは必須です。 クラウドのソース・ファイルURI このパラメータでは、ソース・ファイルURIのカンマ区切りリスト、または1つ以上のディレクトリとソース・ファイルを指定します。 正規表現を使用できるのは、
正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされ、パターン一致は 正規表現を使用する例:
`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'` ワイルドカードの使用例:
URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」をご覧ください。
|
index_name |
location_uriの場所にあるファイル上に構築する索引の名前を指定します。このパラメータは必須です。 |
format |
追加の構成オプションを指定します。オプションはJSON文字列として指定されます。 サポートされているフォーマット・オプションは次のとおりです。
次の方法を使用してストップ・ワードを指定できます。
|
例
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;
/CREATE_HYBRID_PART_TABLEプロシージャ
このプロシージャでは、ハイブリッド・パーティション表を作成します。これにより、クラウド内のデータベース・オブジェクトとファイル、またはディレクトリ内のデータベース・オブジェクトとファイルを使用して、Autonomous AI Databaseのハイブリッド・パーティション・データに対して問合せを実行できます。
構文
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);パラメータ
| パラメータ | 摘要 |
|---|---|
table_name |
外部表の名前。 |
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、 |
partitioning_clause |
個々のパーティションの場所情報を含む、完全なパーティション化句を指定します。 ディレクトリを使用するには、パーティション化句で クラウド・ソース・ファイルURIのファイル名には、ワイルドカードと正規表現を使用できます。 正規表現を使用できるのは、
正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされ、パターン一致は たとえば: `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''),....`
|
column_list |
外部表の列名およびデータ型のカンマ区切りリスト。 |
field_list |
ソース・ファイル内のフィールドとそのデータ型を識別します。デフォルト値はNULLで、フィールドおよびそのデータ型がcolumn_listパラメータによって決定されることを示します。この引数の構文は、通常のOracle外部表のfield_list句と同じです。field_listの詳細は、『Oracle® Databaseユーティリティ』をご覧ください。 |
format |
ソース・ファイルのフォーマットを説明するオプション。オプションのリストと値の指定方法については、「DBMS_CLOUDパッケージ・フォーマット・オプション」を参照。 |
使用上のノート
-
プロシージャ
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;
/DELETE_ALL_OPERATIONSプロシージャ
このプロシージャでは、スキーマ内のuser_load_operations表に記録されたすべてのデータ・ロード操作を消去するか、typeパラメータで示されている、指定されたタイプのすべてのデータ・ロード操作を消去します。
構文
DBMS_CLOUD.DELETE_ALL_OPERATIONS (
type IN VARCHAR DEFAULT NULL);パラメータ
| パラメータ | 摘要 |
|---|---|
type |
削除する操作のタイプを指定します。タイプの値は、
|
使用上のノート
-
このプロシージャは、現在実行中の操作(ステータスが「実行中」の操作)は削除しません。
-
このプロシージャは、操作に関連付けられたロギング表およびログ・ファイルを削除します。
DELETE_FILEプロシージャ
このプロシージャは、Autonomous AI Database上の指定されたディレクトリから、指定されたファイルを削除します。
構文
DBMS_CLOUD.DELETE_FILE (
directory_name IN VARCHAR2,
file_name IN VARCHAR2,
force IN BOOLEAN DEFAULT FALSE);パラメータ
| パラメータ | 摘要 |
|---|---|
directory_name |
Autonomous AI Databaseインスタンスのディレクトリの名前。 |
file_name |
削除するファイルの名前。 |
force |
ファイルが存在しない場合、エラーを無視して報告しません。有効な値は、TRUEおよびFALSEです。デフォルト値はFALSEです。 |
ノート: ADMIN以外のユーザーで実行するには、そのファイルを含むディレクトリに対する書込み権限をそのユーザーに付与する必要があります。たとえば、ADMINとして次のコマンドを実行して、adb_userに書込み権限を付与します:
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;
/DELETE_OBJECTプロシージャ
このプロシージャは、オブジェクト・ストアの指定されたオブジェクトを削除します。
構文
DBMS_CLOUD.DELETE_OBJECT (
credential_name IN VARCHAR2,
object_uri IN VARCHAR2,
force IN BOOLEAN DEFAULT FALSE);パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、 |
object_uri |
削除するオブジェクトのオブジェクトまたはファイルURI。URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。 |
force |
オブジェクトが存在しない場合、エラーを無視して報告しません。有効な値は、TRUEおよびFALSEです。デフォルト値は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;
/DELETE_OPERATIONプロシージャ
このプロシージャは、スキーマのuser_load_operations表またはdba_load_operations表に記録された、指定された操作IDのデータ・ロード・エントリをクリアします。
構文
DBMS_CLOUD.DELETE_OPERATION (
id IN NUMBER);パラメータ
| パラメータ | 摘要 |
|---|---|
id |
削除するログ・ファイル・エントリに関連付けられた操作IDを指定します。 |
使用上のノート
- このプロシージャは、入力で指定された操作IDに関連付けられたロギング表およびログ・ファイルを削除します。
例
SELECT id FROM user_load_operations WHERE type LIKE '%BAD%';
EXEC DBMS_CLOUD.DELETE_OPERATION(id);DROP_EXTERNAL_TEXT_INDEXプロシージャ
このプロシージャは、オブジェクト・ストレージ・ファイルのテキスト索引を削除します。
DROP_EXTERNAL_TEXT_INDEXプロシージャは、CREATE_EXTERNAL_TEXT_INDEXプロシージャで作成された指定された索引を削除します。
構文
DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
index_name IN VARCHAR2,
);パラメータ
| パラメータ | 摘要 |
|---|---|
index_name |
削除する索引の名前を指定します。 索引名は、索引の作成時に指定された名前と一致する必要があります。 このパラメータは必須です。 |
例
BEGIN
DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
index_name => 'EMP',
);
END;
/EXPORT_DATAプロシージャ
このプロシージャは、問合せの結果に基づいてAutonomous AI Databaseからデータをエクスポートします。この手順はオーバーロードされ、クラウドまたはディレクトリへのファイルの書込みをサポートします。
format typeパラメータに基づいて、CSV、JSON、ParquetまたはXML形式のテキスト・ファイルとしてクラウドまたはディレクトリの場所にファイルをエクスポートするか、ORACLE_DATAPUMPアクセス・ドライバを使用してOracle Datapumpダンプ・ファイルにデータを書き込みます。
構文
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);パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、 資格証明パラメータが含まれていない場合は、ディレクトリへの出力を指定します。 |
file_uri_list |
formatパラメータの値および資格証明パラメータを含めるかどうかに応じて、様々なフォームがあります。
URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUD URIの形式」を参照してください。 |
format |
エクスポート形式オプションを提供するJSON文字列。 サポートされるオプションは次のとおりです。
EXPORT_DATAのDBMS_CLOUDパッケージ形式オプションを参照してください。 |
query |
このパラメータを使用して、必要なデータのみがエクスポートされるように SELECT lakehouse_id, quantity FROM inventories
たとえば: SELECT JSON_OBJECT(* RETURNING CLOB) from(SELECT lakehouse_id, quantity FROM inventories) |
operation_id |
このパラメータを使用して、エクスポート操作の進行状況および最終ステータスをUSER_LOAD_OPERATIONSビューの対応するIDとして追跡します。 |
全般的な使用上のノート
-
指定する
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出力の使用上のノート(DBMS_CLOUD.EXPORT_DATA with format parameter type option datapump)
-
EXPORT_DATAは、DATA_PUMP_DIRをデフォルトのロギング・ディレクトリとして使用します。したがって、ORACLE_DATAPUMP出力を使用する場合は、DATA_PUMP_DIRに対する書込み権限が必要です。 -
DBMS_CLOUD.EXPORT_DATAをformatパラメータtypeオプションdatapumpとともに使用したAutonomous AI 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_aaaaaaOracle 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.dmpdatapump値を持つ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 Pumpimpdpを使用してインポートすることはできません。データベースに応じて、次のようにファイルを使用できます:-
Autonomous AI Databaseでは、値
datapumpを持つformatパラメータtypeをサポートするDBMS_CLOUDプロシージャでダンプ・ファイルを使用できます。DBMS_CLOUD.COPY_DATAを使用してダンプ・ファイルをインポートすることも、DBMS_CLOUD.CREATE_EXTERNAL_TABLEをコールして外部表を作成することも可能です。 -
Oracle Database 19cオンプレミスなどの他のOracle AI 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;
/GET_OBJECTプロシージャおよびファンクション
このプロシージャはオーバーロードされています。プロシージャ・フォームは、Cloud Object Storageからオブジェクトを読み取り、そのオブジェクトをAutonomous AI Databaseにコピーします。このファンクション・フォームは、Cloud Object Storageからオブジェクトを読み取り、BLOBをAutonomous AI Databaseに返します。
構文
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;パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、 |
object_uri |
オブジェクトまたはファイルURI。URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」をご覧ください。 |
directory_name |
データベース上のディレクトリの名前。 足1表ハイパーリンクURLは、次の方法で使用できます。
|
file_name |
作成するファイルの名前を指定します。ファイル名を指定しない場合、ファイル名はobject_uriパラメータの最後のスラッシュの後から取得されます。たとえば、ファイル名にスラッシュが含まれるような特殊なケースでは、file_nameパラメータを使用してください。 |
startoffset |
プロシージャが読取りを開始するオフセット(バイト)。 |
endoffset |
プロシージャが読取りを停止するオフセット(バイト)。 |
compression |
オブジェクトの格納に使用する圧縮を指定します。compressionが'AUTO'に設定されている場合、ファイルは圧縮解除されます(値'AUTO'は、object_uriで指定されたオブジェクトがGzipで圧縮されることを意味します)。 |
脚注1 :
ノート: ADMIN以外のユーザーでDBMS_CLOUD.GET_OBJECTを実行するには、そのユーザーにディレクトリに対するWRITE権限を付与する必要があります。たとえば、ADMINとして次のコマンドを実行して、adb_userに書込み権限を付与します。
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はバケット名です。詳細は、オブジェクト・ストレージ・ネームスペースの理解を参照してください。
LIST_FILESファンクション
このファンクションは、指定されたディレクトリ内のファイルを一覧表示します。結果には、ファイル名と、ファイルに関する追加のメタデータ(ファイル・サイズ(バイト)、作成タイムスタンプ、最終変更タイムスタンプなど)が含まれます。
構文
DBMS_CLOUD.LIST_FILES (
directory_name IN VARCHAR2)
RETURN TABLE;パラメータ
| パラメータ | 摘要 |
|---|---|
directory_name |
データベース上のディレクトリの名前。このパラメータはワイルドカードをサポートしています。 |
使用上のノート
-
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');LIST_OBJECTSファンクション
このファンクションは、オブジェクト・ストアの指定された場所にあるオブジェクトを一覧表示します。結果には、オブジェクト名と、オブジェクトに関する追加のメタデータ(サイズ、チェックサム、作成タイムスタンプ、最終変更タイムスタンプなど)が含まれます。
構文
DBMS_CLOUD.LIST_OBJECTS (
credential_name IN VARCHAR2,
location_uri IN VARCHAR2)
RETURN TABLE;パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、 |
location_uri |
オブジェクト・ストレージ・バケットまたはフォルダURI。URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照。 ワイルド・カードは、URI内のファイルまたはサブフォルダを選択的にリストするためにサポートされています。文字" ワイルドカードの使用例: `sql 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のサポートを示します。オブジェクト・ストア CREATEDLAST_MODIFIEDOracle Cloud Infrastructureネイティブ タイムスタンプを返します タイムスタンプを返します Oracle Cloud Infrastructure Swift NULLを戻します。タイムスタンプを返します Oracle Cloud Infrastructure Classic NULLを戻します。タイムスタンプを返します Amazon S3 NULLを戻します。タイムスタンプを返します Amazon S3互換 NULLを戻します。タイムスタンプを返します Azure タイムスタンプを返します タイムスタンプを返します GitHubリポジトリ -
チェックサム値は、MD5チェックサムです。これは、オブジェクトの内容に基づいて計算される32文字の18進数です。
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はバケット名です。詳細は、オブジェクト・ストレージ・ネームスペースの理解を参照してください。
MOVE_OBJECTプロシージャ
このプロシージャは、クラウド・オブジェクト・ストレージのバケットまたはフォルダ間でオブジェクトを移動します。
ソースとターゲットのバケットまたはフォルダは、同じまたは異なるクラウド・オブジェクト・ストア・プロバイダに配置できます。
ソースとターゲットが個別のオブジェクト・ストアにある場合、または同じクラウド・プロバイダを持つ異なるアカウントがある場合は、ソースとターゲットの場所に個別の資格証明名を指定できます。
ソース資格証明名は、ターゲット資格証明名が指定されていない場合、ターゲットの場所でもデフォルトで使用されます。
構文
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
);パラメータ
| パラメータ | 摘要 |
|---|---|
source_credential_name |
ソースのクラウド・オブジェクト・ストレージにアクセスするための資格証明の名前です。 リソース・プリンシパルが有効になっている場合は、
|
source_object_uri |
ソース・オブジェクト・ストレージ・バケットまたはフォルダの場所を指すURIを指定します。 このパラメータは必須です。 URIのフォーマットは、クラウド・オブジェクト・ストレージ・サービスによって異なります。詳細は、「DBMS_CLOUD URIフォーマット」を参照してください。 |
target_object_uri |
ファイルを移動する必要があるターゲット・オブジェクト・ストレージ・バケットまたはフォルダのURIを指定します。 このパラメータは必須です。 URIのフォーマットは、クラウド・オブジェクト・ストレージ・サービスによって異なります。詳細は、「DBMS_CLOUD URIフォーマット」を参照してください。 |
target_credential_name |
ターゲットのクラウド・オブジェクト・ストレージの場所にアクセスするための資格証明の名前です。 リソース・プリンシパルが有効になっている場合は、
|
例
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;
/PUT_OBJECTプロシージャ
このプロシージャはオーバーロードされています。このプロシージャは、1つの形式でAutonomous AI DatabaseからCloud Object Storageファイルにファイルをコピーします。別の形式では、このプロシージャには、Autonomous AI DatabaseからCloud Object StorageへのBLOBのコピーがあります。
構文
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);パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、 |
object_uri |
オブジェクトまたはファイルURI。URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」をご覧ください。 |
directory_name |
Autonomous AI Database上のディレクトリの名前。 [脚注2](#fn_2) |
contents |
Autonomous AI Databaseからクラウド・オブジェクト・ストレージにコピーするBLOBを指定します。 |
file_name |
指定されたディレクトリ内のファイルの名前。 |
compression |
オブジェクトの格納に使用する圧縮を指定します。 デフォルト値: |
脚注2
ノート: ADMIN以外のユーザーでDBMS_CLOUD.PUT_OBJECTを実行するには、そのユーザーに対してディレクトリの読取り権限を付与する必要があります。たとえば、ADMINとして次のコマンドを実行して、adb_userに読取り権限を付与します。
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に応じて、転送するオブジェクトのサイズは次のように制限されます:
| Cloud Object Storageサービス | オブジェクト転送サイズの制限 |
|---|---|
| Oracle Cloud Infrastructure Object Storage | 50 GB |
| Amazon S3 | 5 GB |
| Azure Blob StorageまたはAzure Data Lake Storage | 5 GB |
| Amazon S3互換 | オブジェクト・ストア・プロバイダによって設定されます。詳細は、プロバイダのドキュメンテーションを参照してください。 |
Oracle Cloud Infrastructureオブジェクト・ストアでは、資格証明を指定せずにファイルをパブリック・バケットに書き込むことはできません(Oracle Cloud Infrastructureでは、ユーザーはパブリック・バケットからオブジェクトをダウンロードできます)。したがって、PUT_OBJECTを使用してオブジェクトをOracle Cloud Infrastructureパブリック・バケットに格納するには、有効な資格証明を含む資格証明名を指定する必要があります。
詳細は、「DBMS_CLOUD URIフォーマット」を参照してください。
SYNC_EXTERNAL_PART_TABLEプロシージャ
この手順により、クラウド内のファイルから外部パーティション表を更新することが簡略化されます。新しいパーティションが追加されたとき、または外部パーティション表のオブジェクト・ストア・ソースからパーティションが削除されたときに、このプロシージャを実行します。
構文
DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLE (
table_name IN VARCHAR2,
schema_name IN VARCHAR2 DEFAULT,
update_columns IN BOOLEAN DEFAULT);パラメータ
| パラメータ | 摘要 |
|---|---|
table_name |
ターゲット表の名前。ターゲット表は、DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLEを実行する前に作成しておく必要があります。 |
schema_name |
ターゲット表が存在するスキーマの名前。デフォルト値はNULLで、ターゲット表がプロシージャを実行しているユーザーと同じスキーマ内に存在することを意味します。 |
update_columns |
新しいファイルによって、スキーマが変更される場合があります。サポートされる更新には、新しい列、削除された列が含まれます。既存の列の更新。たとえば、データ型の変更はエラーをスローします。 デフォルト値はFalseです。 |
VALIDATE_EXTERNAL_PART_TABLEプロシージャ
このプロシージャにより、外部パーティション表のソース・ファイルが検証され、ログ情報が生成され、外部表に指定されたフォーマット・オプションと一致しない行がAutonomous AI Databaseのbadfile表に格納されます。オーバーロード・フォームでは、operation_idパラメータを使用できます。
構文
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);パラメータ
| パラメータ | 摘要 |
|---|---|
table_name |
外部表の名前。 |
operation_id |
このパラメータを使用して、USER_LOAD_OPERATIONSビューで、ロード操作の進行状況および最終ステータスを対応するIDとして追跡します。 |
partition_name |
定義すると、特定のパーティションのみが検証されます。指定しない場合は、rowcountに達するまで、すべてのパーティションを順次読み取ります。 |
subpartition_name |
定義した場合、特定のサブパーティションのみが検証されます。指定しない場合は、rowcountに達するまで、すべての外部パーティションまたはサブパーティションから順次読み取ります。 |
schema_name |
外部表が存在するスキーマの名前。デフォルト値はNULLで、外部表がプロシージャを実行しているユーザーと同じスキーマ内に存在することを意味します。 |
rowcount |
スキャンされる行数。デフォルト値はNULLで、ソース・ファイル内のすべての行がスキャンされることを意味します。 |
partition_key_validation |
内部使用のみこのパラメータを使用しないでください。 |
stop_on_error |
行が拒否されたときに検証を停止するかどうかを決定します。デフォルト値はTRUEで、最初に拒否された行で検証を停止することを意味します。値をFALSEに設定すると、最初に拒否された行で検証を停止せず、rowcountパラメータに指定された値までのすべての行を検証することを指定します。 |
VALIDATE_EXTERNAL_TABLEプロシージャ
このプロシージャでは、外部表のソース・ファイルを検証し、ログ情報を生成して、Autonomous AI Databaseのbadfile表に外部表に指定されたフォーマット・オプションと一致しない行を格納します。オーバーロード・フォームでは、operation_idパラメータを使用できます。
構文
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);パラメータ
| パラメータ | 摘要 |
|---|---|
table_name |
外部表の名前。 |
operation_id |
このパラメータを使用して、USER_LOAD_OPERATIONSビューで、ロード操作の進行状況および最終ステータスを対応するIDとして追跡します。 |
schema_name |
外部表が存在するスキーマの名前。デフォルト値はNULLで、外部表がプロシージャを実行しているユーザーと同じスキーマ内に存在することを意味します。 |
rowcount |
スキャンされる行数。デフォルト値はNULLで、ソース・ファイル内のすべての行がスキャンされることを意味します。 |
stop_on_error |
行が拒否されたときに検証を停止するかどうかを決定します。デフォルト値は 外部表がAvro、ORCまたはParquetファイルの場合は、最初に拒否された行で検証が停止します。 外部表で |
使用上のノート
DBMS_CLOUD.VALIDATE_EXTERNAL_TABLEは、パーティション化された外部表とハイブリッド・パーティション表の両方で機能します。これは、rowcountに達するか、stop_on_errorが適用されるまで、場合によってはすべての外部パーティションからデータを読み取ります。読み取るパーティションまたはパーティションの部分の順序は制御できません。
VALIDATE_HYBRID_PART_TABLEプロシージャ
このプロシージャによって、ハイブリッド・パーティション表のソース・ファイルが検証され、ログ情報が生成され、ハイブリッド表に指定したフォーマット・オプションと一致しない行がAutonomous AI Databaseのbadfile表に格納されます。オーバーロード・フォームでは、operation_idパラメータを使用できます。
構文
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);パラメータ
| パラメータ | 摘要 |
|---|---|
table_name |
外部表の名前。 |
operation_id |
このパラメータを使用して、USER_LOAD_OPERATIONSビューで、ロード操作の進行状況および最終ステータスを対応するIDとして追跡します。 |
partition_name |
定義すると、特定のパーティションのみが検証されます。指定しない場合は、rowcountに達するまで、すべての外部パーティションから順次読み取ります。 |
subpartition_name |
定義した場合、特定のサブパーティションのみが検証されます。指定しない場合は、rowcountに達するまで、すべての外部パーティションまたはサブパーティションから順次読み取ります。 |
schema_name |
外部表が存在するスキーマの名前。デフォルト値はNULLで、外部表がプロシージャを実行しているユーザーと同じスキーマ内に存在することを意味します。 |
rowcount |
スキャンされる行数。デフォルト値はNULLで、ソース・ファイル内のすべての行がスキャンされることを意味します。 |
partition_key_validation |
内部使用のみこのパラメータを使用しないでください。 |
stop_on_error |
行が拒否されたときに検証を停止するかどうかを決定します。デフォルト値はTRUEで、最初に拒否された行で検証を停止することを意味します。値をFALSEに設定すると、最初に拒否された行で検証を停止せず、rowcountパラメータに指定された値までのすべての行を検証することを指定します。 |
バルク・ファイル管理のためのDBMS_CLOUD
DBMS_CLOUDパッケージ内のバルク・ファイル操作のサブプログラム。
| サブプログラム | 摘要 |
|---|---|
| BULK_COPYプロシージャ | このプロシージャは、クラウド・オブジェクト・ストレージ・バケット間でファイルをコピーします。 |
| BULK_DELETEプロシージャ | このプロシージャは、クラウド・オブジェクト・ストレージのバケットまたはフォルダからファイルを削除します。 |
| BULK_DOWNLOADプロシージャ | このプロシージャは、クラウド・オブジェクト・ストア・バケットからAutonomous AI Databaseのディレクトリにファイルをダウンロードします。 |
| BULK_MOVEプロシージャ | この手順では、クラウド・オブジェクト・ストレージ・バケット間でファイルを移動します。 |
| BULK_UPLOADプロシージャ | このプロシージャは、Autonomous AI Databaseのディレクトリからクラウド・オブジェクト・ストレージにファイルをアップロードします。 |
BULK_COPYプロシージャ
このプロシージャは、あるクラウド・オブジェクト・ストレージ・バケットから別のクラウド・オブジェクト・ストレージ・バケットにファイルを一括コピーします。オーバーロード・フォームでは、operation_idパラメータを使用できます。
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_credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、
|
source_location_uri |
ソース・オブジェクト・ストレージ・バケットまたはフォルダの場所を指すURIを指定します。 このパラメータは必須です。 クラウドのソース・ファイルURI クラウド・ソース・ファイルURIのファイル名には、ワイルドカードと正規表現を使用できます。 正規表現を使用できるのは、
正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされ、パターン一致は 正規表現を使用する例:
`sql 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'` ワイルドカードの使用例:
URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」をご覧ください。
|
target_location_uri |
ファイルをコピーする必要があるターゲット・オブジェクト・ストレージ・バケットまたはフォルダのURIを指定します。 このパラメータは必須です。 ソース・オブジェクト・ストレージ・バケットまたはフォルダの場所を指すURIを指定します。 このパラメータは必須です。 URIのフォーマットは、クラウド・オブジェクト・ストレージ・サービスによって異なります。詳細は、「DBMS_CLOUD URIフォーマット」を参照してください。 |
target_credential_name |
ターゲットのクラウド・オブジェクト・ストレージの場所にアクセスするための資格証明の名前です。 リソース・プリンシパルが有効になっている場合は、
|
regex_filter |
ファイルをフィルタするREGEX式を指定します。REGEX式パターンは、
詳細は、REGEXP_LIKE条件を参照してください。 |
format |
ファイル操作の追加の構成オプションを指定します。これらのオプションはJSON文字列として指定されます。 サポートされているフォーマット・オプションは次のとおりです。
|
operation_id |
このパラメータを使用して、USER_LOAD_OPERATIONSビューで、ロード操作の進行状況および最終ステータスを対応するIDとして追跡します。 |
使用上のノート
- ソース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;
/BULK_DELETEプロシージャ
このプロシージャは、クラウド・オブジェクト・ストレージからファイルを一括削除します。オーバーロード・フォームでは、operation_idパラメータを使用できます。REGEXP_LIKE演算子と互換性のある正規表現パターンを使用して、削除するファイルのリストをフィルタできます。
構文
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
);パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、
|
location_uri |
Autonomous AI Databaseのオブジェクト・ストレージの場所を指すURIを指定します。 このパラメータは必須です。 クラウドのソース・ファイルURI クラウド・ソース・ファイルURIのファイル名には、ワイルドカードと正規表現を使用できます。 正規表現を使用できるのは、
正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされ、パターン一致は たとえば:
`sql 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'` URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照。
URIのフォーマットは、クラウド・オブジェクト・ストレージ・サービスによって異なります。詳細は、「DBMS_CLOUD URIフォーマット」を参照してください。 |
regex_filter |
ファイルをフィルタするREGEX式を指定します。REGEX式パターンは、
詳細は、REGEXP_LIKE条件を参照してください。 |
format |
ファイル操作の追加の構成オプションを指定します。これらのオプションはJSON文字列として指定されます。 サポートされているフォーマット・オプションは次のとおりです。
|
operation_id |
このパラメータを使用して、USER_LOAD_OPERATIONSビューで、ロード操作の進行状況および最終ステータスを対応するIDとして追跡します。 |
例
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;
/BULK_DOWNLOADプロシージャ
このプロシージャは、クラウド・オブジェクト・ストレージからAutonomous AI Databaseディレクトリにファイルをダウンロードします。オーバーロード・フォームでは、operation_idパラメータを使用できます。REGEXP_LIKE演算子と互換性のある正規表現パターンを使用して、ダウンロードするファイルのリストをフィルタできます。
構文
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
);パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、
|
location_uri |
Autonomous AI Databaseのオブジェクト・ストレージの場所を指すURIを指定します。 このパラメータは必須です。 クラウドのソース・ファイルURI クラウド・ソース・ファイルURIのファイル名には、ワイルドカードと正規表現を使用できます。 正規表現を使用できるのは、
正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされ、パターン一致は たとえば:
`sql 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'` URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照。
URIのフォーマットは、クラウド・オブジェクト・ストレージ・サービスによって異なります。詳細は、「DBMS_CLOUD URIフォーマット」を参照してください。 |
directory_name |
ファイルをダウンロードするAutonomous AI Database上のディレクトリの名前。 このパラメータは必須です。 |
regex_filter |
ファイルをフィルタするREGEX式を指定します。REGEX式パターンは、
詳細は、REGEXP_LIKE条件を参照してください。 |
format |
ファイル操作の追加の構成オプションを指定します。これらのオプションはJSON文字列として指定されます。 サポートされているフォーマット・オプションは次のとおりです。
|
operation_id |
このパラメータを使用して、USER_LOAD_OPERATIONSビューで、ロード操作の進行状況および最終ステータスを対応するIDとして追跡します。 |
例
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;
/BULK_MOVEプロシージャ
このプロシージャは、ファイルをクラウド・オブジェクト・ストレージのバケットまたはフォルダ間で一括移動します。オーバーロード・フォームでは、operation_idパラメータを使用できます。
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_credential_name |
ソースのクラウド・オブジェクト・ストレージにアクセスするための資格証明の名前です。 リソース・プリンシパルが有効になっている場合は、
|
source_location_uri |
ソース・オブジェクト・ストレージ・バケットまたはフォルダの場所を指すURIを指定します。 このパラメータは必須です。 クラウドのソース・ファイルURI クラウド・ソース・ファイルURIのファイル名には、ワイルドカードと正規表現を使用できます。 正規表現を使用できるのは、
正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされ、パターン一致は 正規表現を使用する例:
`sql 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'` ワイルドカードの使用例:
URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」をご覧ください。
|
target_location_uri |
ファイルを移動する必要があるターゲット・オブジェクト・ストレージ・バケットまたはフォルダのURIを指定します。 このパラメータは必須です。 URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照。 |
target_credential_name |
ターゲットのクラウド・オブジェクト・ストレージの場所にアクセスするための資格証明の名前です。 リソース・プリンシパルが有効になっている場合は、
|
regex_filter |
ファイルをフィルタするREGEX式を指定します。REGEX式パターンは、
詳細は、REGEXP_LIKE条件を参照してください。 |
format |
ファイル操作の追加の構成オプションを指定します。これらのオプションはJSON文字列として指定されます。 サポートされているフォーマット・オプションは次のとおりです。
|
operation_id |
このパラメータを使用して、USER_LOAD_OPERATIONSビューで、ロード操作の進行状況および最終ステータスを対応するIDとして追跡します。 |
例
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;
/ノート
ノート:ソースとターゲットのURIが同じオブジェクト・ストレージ・バケットまたはフォルダを指している場合、エラーが返されます。
BULK_UPLOADプロシージャ
このプロシージャは、Autonomous AI Databaseディレクトリからクラウド・オブジェクト・ストレージにファイルをコピーします。オーバーロード・フォームでは、operation_idパラメータを使用できます。
構文
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
);パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
クラウド・オブジェクト・ストレージにアクセスするための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、
|
location_uri |
ファイルをアップロードするオブジェクト・ストレージの場所を指すURIを指定します。 このパラメータは必須です。 URIのフォーマットは、クラウド・オブジェクト・ストレージ・サービスによって異なります。詳細は、「DBMS_CLOUD URIフォーマット」を参照してください。 |
directory_name |
ファイルをアップロードするAutonomous AI Database上のディレクトリの名前。 このパラメータは必須です。 ディレクトリ 1つのディレクトリと1つ以上のファイル名を指定することも、ディレクトリとファイル名のカンマ区切りリストを使用することもできます。ディレクトリを指定する形式は、 ディレクトリにファイル名を指定する場合、正規表現はサポートされません。ワイルドカードを使用して、ディレクトリ内のファイル名を指定できます。文字"*"は複数文字のワイルドカードとして、文字"?"は1つの文字のワイルドカードとして使用することができます。例: 複数のディレクトリを指定するには、ディレクトリのカンマ区切りリストを使用します。例: 大/小文字を区別するディレクトリ名を指定するには、二重引用符を使用します。例: 引用符文字を含めるには、2つの引用符を使用します。例: |
regex_filter |
ファイルをフィルタするREGEX式を指定します。REGEX式パターンは、
詳細は、REGEXP_LIKE条件を参照してください。 |
format |
ファイル操作の追加の構成オプションを指定します。これらのオプションはJSON文字列として指定されます。 サポートされているフォーマット・オプションは次のとおりです。
|
operation_id |
このパラメータを使用して、USER_LOAD_OPERATIONSビューで、ロード操作の進行状況および最終ステータスを対応するIDとして追跡します。 |
例
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 REST API
この項では、Autonomous AI Databaseで提供されるDBMS_CLOUD REST APIについて説明します.
| REST API | 摘要 |
|---|---|
| GET_RESPONSE_HEADERSファンクション | このファンクションは、Autonomous AI DatabaseのJSONオブジェクトのJSONデータとしてHTTPレスポンス・ヘッダーを返します。 |
| GET_RESPONSE_RAWファンクション | このファンクションは、RAW形式でHTTPレスポンスを戻します。Autonomous AI Database これは、HTTPレスポンスがバイナリ形式である必要がある場合に便利です。 |
| GET_RESPONSE_STATUS_CODEファンクション | このファンクションは、Autonomous AI DatabaseでHTTPレスポンス・ステータス・コードを整数として返します。ステータス・コードは、リクエストが成功したかどうかを識別するのに役立ちます。 |
| GET_RESPONSE_TEXTファンクション | このファンクションは、Autonomous AI DatabaseでHTTPレスポンスをテキスト形式(VARCHAR2またはCLOB)で返します。通常、ほとんどのクラウドREST APIはJSONレスポンスをテキスト形式で戻します。この関数は、HTTPレスポンスがテキスト形式であることを想定している場合に役立ちます。 |
| GET_API_RESULT_CACHE_SIZEファンクション | このファンクションは、構成された結果キャッシュ・サイズを返します。 |
| SEND_REQUESTファンクションおよびプロシージャ | このファンクションは、HTTPリクエストを開始し、レスポンスを取得して、Autonomous AI Databaseでレスポンスを終了しますこのファンクションは、引数、戻りレスポンス・コードおよびペイロードを使用してクラウドREST APIリクエストを送信するためのワークフローを提供します。 |
| SET_API_RESULT_CACHE_SIZEプロシージャ | このプロシージャは、現在のセッションの最大キャッシュ・サイズを設定します。 |
DBMS_CLOUD REST APIの概要
アプリケーションでPL/SQLを使用しているときに、クラウドREST APIをコールする必要がある場合は、DBMS_CLOUD.SEND_REQUESTを使用してREST APIリクエストを送信できます。
DBMS_CLOUD REST APIファンクションを使用すると、DBMS_CLOUD.SEND_REQUESTを使用してHTTPリクエストを作成し、結果を取得して保存できます。これらのファンクションは、サポートされている次のクラウド・サービスで任意のREST APIをコールできる汎用APIを提供します:
-
Oracle Cloud Infrastructure
Oracle Cloud Infrastructure REST APIsの詳細は、「APIリファレンスおよびエンドポイント」を参照してください。
-
Amazon Web Services (AWS)
Amazon Web Services REST APIの詳細は、「Guides and API References」を参照してください。
-
Azure Cloud脚注3
Azure REST APIの詳細は、「Azure REST API Reference」を参照してください。
-
Oracle Cloud Infrastructure Classic
Oracle Cloud Infrastructure Classic REST APIsの詳細は、すべてのRESTエンドポイントを参照してください。
-
GitHubリポジトリ
詳細は、GitHub REST APIを参照してください。
DBMS_CLOUD REST APIの定数
DBMS_CLOUD.SEND_REQUESTを使用してHTTPリクエストを行うためのDBMS_CLOUD定数について説明します。
DBMS_CLOUDは、GET、PUT、POST、HEADおよびDELETE HTTPメソッドをサポートしています。HTTPリクエストに使用されるREST APIメソッドは通常、クラウドREST APIドキュメントに記載されています。
| 名前 | タイプ | 値 |
|---|---|---|
METHOD_DELETE |
VARCHAR2(6) |
'DELETE' |
METHOD_GET |
VARCHAR2(3) |
'GET' |
METHOD_HEAD |
VARCHAR2(4) |
'HEAD' |
METHOD_POST |
VARCHAR2(4) |
'POST' |
METHOD_PUT |
VARCHAR2(3) |
'PUT' |
DBMS_CLOUD REST API結果キャッシュ
DBMS_CLOUD.SEND_REQUESTでcacheパラメータをtrueに設定した場合、DBMS_CLOUD REST APIの結果を保存できます。SESSION_CLOUD_API_RESULTSビューは、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 REST API結果cache_scopeパラメータ
DBMS_CLOUD REST APIの結果をDBMS_CLOUD.SEND_REQUESTで保存すると、cache_scopeの値に基づいて、SESSION_CLOUD_API_RESULTSの結果へのアクセスが提供されます。
デフォルトでは、cache_scopeは'PRIVATE'で、セッションの現在のユーザーのみが結果にアクセスできます。cache_scopeを'PUBLIC'に設定すると、すべてのセッション・ユーザーが結果にアクセスできます。cache_scopeのデフォルト値は、各ユーザーが実行者権限で起動するプロシージャによって生成されたDBMS_CLOUD.SEND_REQUEST REST API結果のみを表示できるように指定しています。セッションでDBMS_CLOUD.SEND_REQUESTを起動すると、cache_scope値に基づいて、現在のユーザーがキャッシュに結果を表示できるかどうかを決定する3つの可能性があります。
-
DBMS_CLOUD.SEND_REQUESTを最上位の文として直接実行し、DBMS_CLOUD.SEND_REQUESTをコールすると、REST APIの結果は同じユーザー名で保存されます。この場合、デフォルト値が'PRIVATE'で、cache_scopeに設定されているすべての結果にアクセスできます。 -
ラッパー実行者権限プロシージャを記述し、現行ユーザーとして
DBMS_CLOUD.SEND_REQUESTを使用してコールするとプロシージャがコールされ、REST APIの結果は同じユーザー名で保存されます。この場合、cache_scopeに設定されたデフォルト値'PRIVATE''を持つすべての結果にアクセスできます。 -
ラッパー定義者権限プロシージャを記述し、そのプロシージャは別のユーザーが所有します。プロシージャ内で
DBMS_CLOUD.SEND_REQUESTをコールすると、プロシージャ所有者のユーザー名を使用して結果が保存されます。この場合、別の定義者権限ユーザーが
DBMS_CLOUD.SEND_REQUESTを起動しており、REST APIの結果はその定義者プロシージャの所有者とともに保存されます。この場合、デフォルトでは、cache_scopeがPRIVATE'の場合、実行者のセッションでは結果を表示できません。定義者のプロシージャ所有者が、起動中のセッション・ユーザーが結果を使用できるようにする場合は、
DBMS_CLOUD.SEND_REQUESTでcache_scopeを'PUBLIC'に設定する必要があります。
DBMS_CLOUD REST API SESSION_CLOUD_API_RESULTSビュー
DBMS_CLOUD.SEND_REQUESTでcacheパラメータをtrueに設定した場合、DBMS_CLOUD REST APIの結果を保存できます。SESSION_CLOUD_API_RESULTSビューは、REST APIの結果が保存されるときに使用できる列を示します。
ビューSESSION_CLOUD_API_RESULTSは、DBMS_CLOUD.SEND_REQUESTを使用して結果をキャッシュした場合に作成されるビューです。ユーザー・セッションに属する履歴結果を問い合せることができます。セッションが終了すると、SESSION_CLOUD_API_RESULTS内のデータがパージされます。
| 列 | 摘要 |
|---|---|
URI |
DBMS_CLOUD REST APIリクエストURL |
TIMESTAMP |
DBMS_CLOUD REST APIレスポンス・タイムスタンプ |
CLOUD_TYPE |
Oracle Cloud Infrastructure、AMAZON_S3、AZURE_BLOBなどのDBMS_CLOUD REST APIクラウド・タイプ |
REQUEST_METHOD |
DBMS_CLOUD REST APIリクエスト・メソッド(GET、PUT、HEADなど) |
REQUEST_HEADERS |
DBMS_CLOUD REST APIのリクエスト・ヘッダー |
REQUEST_BODY_TEXT |
CLOBのDBMS_CLOUD REST APIリクエスト本文 |
RESPONSE_STATUS_CODE |
DBMS_CLOUD REST APIレスポンス・ステータス・コード(200(OK)、404(Not Found)など) |
RESPONSE_HEADERS |
DBMS_CLOUD REST APIレスポンス・ヘッダー |
RESPONSE_BODY_TEXT |
CLOBのDBMS_CLOUD REST APIレスポンス本文 |
SCOPE |
DBMS_CLOUD.SEND_REQUESTによって設定されたcache_scope。有効な値は、PUBLICまたはPRIVATEです。 |
GET_RESPONSE_HEADERSファンクション
このファンクションは、HTTPレスポンス・ヘッダーをJSONオブジェクト内のJSONデータとして戻します。
構文
DBMS_CLOUD.GET_RESPONSE_HEADERS(
resp IN DBMS_CLOUD_TYPES.resp)
RETURN JSON_OBJECT_T;パラメータ
| パラメータ | 摘要 |
|---|---|
resp |
DBMS_CLOUD.SEND_REQUESTから戻されるHTTPレスポンス・タイプ。 |
例外
| 例外 | エラー | 摘要 |
|---|---|---|
invalid_response |
ORA-20025 |
DBMS_CLOUD.GET_RESPONSE_HEADERSに無効なレスポンス・タイプ・オブジェクトが渡されました。 |
GET_RESPONSE_RAWファンクション
このファンクションは、HTTPレスポンスをRAW形式で戻します。これは、HTTPレスポンスがバイナリ形式である必要がある場合に便利です。
構文
DBMS_CLOUD.GET_RESPONSE_RAW(
resp IN DBMS_CLOUD_TYPES.resp)
RETURN BLOB;パラメータ
| パラメータ | 摘要 |
|---|---|
resp |
DBMS_CLOUD.SEND_REQUESTから戻されるHTTPレスポンス・タイプ。 |
例外
| 例外 | エラー | 摘要 |
|---|---|---|
invalid_response |
ORA-20025 |
DBMS_CLOUD.GET_RESPONSE_RAWに無効なレスポンス・タイプ・オブジェクトが渡されました。 |
GET_RESPONSE_STATUS_CODEファンクション
このファンクションは、HTTPレスポンス・ステータス・コードを整数として戻します。ステータス・コードは、リクエストが成功したかどうかを識別するのに役立ちます。
構文
DBMS_CLOUD.GET_RESPONSE_STATUS_CODE(
resp IN DBMS_CLOUD_TYPES.resp)
RETURN PLS_INTEGER;パラメータ
| パラメータ | 摘要 |
|---|---|
resp |
DBMS_CLOUD.SEND_REQUESTから戻されるHTTPレスポンス・タイプ。 |
例外
| 例外 | エラー | 摘要 |
|---|---|---|
invalid_response |
ORA-20025 |
DBMS_CLOUD.GET_RESPONSE_STATUS_CODEに無効なレスポンス・タイプ・オブジェクトが渡されました。 |
GET_RESPONSE_TEXTファンクション
このファンクションは、HTTPレスポンスをTEXT形式(VARCHAR2またはCLOB)で戻します。通常、ほとんどのクラウドREST APIはJSONレスポンスをテキスト形式で戻します。この関数は、HTTPレスポンスがテキスト形式であることを想定している場合に役立ちます。
構文
DBMS_CLOUD.GET_RESPONSE_TEXT(
resp IN DBMS_CLOUD_TYPES.resp)
RETURN CLOB;パラメータ
| パラメータ | 摘要 |
|---|---|
resp |
DBMS_CLOUD.SEND_REQUESTから戻されるHTTPレスポンス・タイプ。 |
例外
| 例外 | エラー | 摘要 |
|---|---|---|
invalid_response |
ORA-20025 |
DBMS_CLOUD.GET_RESPONSE_TEXTに無効なレスポンス・タイプ・オブジェクトが渡されました。 |
GET_API_RESULT_CACHE_SIZEファンクション
このファンクションは、構成された結果キャッシュ・サイズを返します。キャッシュ・サイズの値は、現在のセッションにのみ適用されます。
構文
DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE()
RETURN NUMBER;SEND_REQUESTファンクションおよびプロシージャ
このファンクションおよびプロシージャは、HTTPリクエストを開始し、レスポンスを取得して、レスポンスを終了しますこのファンクションは、引数、クラウドREST APIリクエストを送信するためのワークフローを提供し、ファンクションはレスポンス・コードおよびペイロードを返します。このプロシージャを使用すると、SESSION_CLOUD_API_RESULTSビューを使用して、保存された結果から結果およびレスポンスの詳細を表示できます。
構文
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);パラメータ
| パラメータ | 摘要 |
|---|---|
credential_name |
対応するクラウド・ネイティブAPIで認証するための資格証明の名前。 リソース・プリンシパルが有効になっている場合は、 |
uri |
リクエストを作成するためのHTTP URI。 |
method |
HTTPリクエスト・メソッド: 詳細は、「DBMS_CLOUD REST APIの定数」を参照してください。 |
headers |
JSON形式の対応するクラウド・ネイティブAPIのHTTPリクエスト・ヘッダー。認証ヘッダーは自動的に設定され、カスタム・ヘッダーのみを渡します。 |
async_request_url |
非同期リクエストURL。 URLを取得するには、APIのリストからリクエストAPIを選択します(https://docs.cloud.oracle.com/en-us/iaas/api/を参照)。次に、左ペインでリクエストのAPIに移動して検索します。たとえば、「Database Services API」→「Autonomous AI Database」→「StopAutonomousDatabase」です。このページには、APIホームが表示されます(ベース・エンドポイントも表示されます)。次に、作業リクエストのWorkRequestリンク用に取得した相対パスをベース・エンドポイントに追加します。 |
wait_for_states |
待機状態は次のタイプのステータスです:
|
timeout |
パラメータ デフォルト値は |
cache |
デフォルト値は |
cache_scope |
すべてのユーザーがこのリクエスト結果キャッシュにアクセスできるかどうかを指定します。有効な値は"PRIVATE"および"PUBLIC"です。デフォルト値は"PRIVATE"です。 |
body |
PUTおよびPOSTリクエストのHTTPリクエスト本文。 |
例外
| 例外 | エラー | 摘要 |
|---|---|---|
invalid_req_method |
ORA-20023 |
DBMS_CLOUD.SEND_REQUESTに渡されたリクエスト・メソッドが無効です。 |
invalid_req_header |
ORA-20024 |
DBMS_CLOUD.SEND_REQUESTに渡されたリクエスト・ヘッダーが有効なJSON形式ではありません。 |
使用上のノート
-
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で検出された状態が発生するまで待機します。
SET_API_RESULT_CACHE_SIZEプロシージャ
このプロシージャは、現在のセッションの最大キャッシュ・サイズを設定します。キャッシュ・サイズの値は、現在のセッションにのみ適用されます。
構文
DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
cache_size IN NUMBER);パラメータ
| パラメータ | 摘要 |
|---|---|
cache_size |
最大キャッシュ・サイズを指定された値 キャッシュ・サイズが デフォルトのキャッシュ・サイズは |
例外
| 例外 | エラー | 摘要 |
|---|---|---|
invalid API result cache size |
ORA-20032 |
最小値は0で、最大値は10000です。この例外は、入力値が0未満または10000より大きい場合に表示されます。 |
例
EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(101);DBMS_CLOUD REST APIの例
DBMS_CLOUD.SEND_REQUESTを使用してOracle Cloud Infrastructure Object Storageバケットを作成および削除する例と、テナンシ内のすべてのコンパートメントをリストする例を示します。
注意:
次の例では、Oracle Cloud InfrastructureリクエストAPIを示しており、credential_nameに対して署名キー・ベースの資格証明を使用する必要があります。Oracle Cloud Infrastructureの署名キー・ベースの資格証明には、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',
=> 'MIIEogIBAAKCAQEAtUnxbmrekwgVac6FdWeRzoXvIpA9+0r1.....wtnNpESQQQ0QLGPD8NM//JEBg=',
fingerprint => 'f2:db:f9:18:a4:aa:fc:94:f4:f6:6c:39:96:16:aa:27');
END;
/バケットの作成の例
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です。
非同期リクエストの例
0DBMS_CLOUD.SEND_REQUESTをHTTP POSTメソッドとともに使用してAutonomous AI Databaseの停止操作を実行し、ステータス待ちにする例を示します。この例は、DBMS_CLOUD.SEND_REQUESTをasync_request_url、wait_for_statesおよびtimeoutパラメータとともに使用する方法を示します。
--
-- Sent Work Request Autonomous AI 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リソース識別子である。詳細は、「リソース識別子」を参照してください。
脚注の説明
脚注3: Azure Cloud REST APIコールのサポートは、ドメインblob.windows.netに限定されます。