Oracle Cloud Infrastructureドキュメント

DBMS_DATA_ACCESSパッケージ

DBMS_DATA_ACCESSパッケージは、データ・セットの表ハイパーリンクを生成および管理するためのルーチンを提供します。

親トピック: Autonomous Databaseで提供されるパッケージのリファレンス

DBMS_DATA_ACCESS概要

DBMS_DATA_ACCESSパッケージの使用について説明します。

DBMS_DATA_ACCESSでは、次の操作がサポートされます。

  • 表ハイパーリンクの生成
  • 表ハイパーリンクの手動無効化
  • アクティブな表ハイパーリンクのリスト

DBMS_DATA_ACCESSセキュリティ・モデル

このパッケージのセキュリティは、選択したユーザーまたはロールにこのパッケージのEXECUTE権限を付与することで制御できます。

DBMS_DATA_ACCESSでEXECUTEが付与されると、ユーザーが作成した表ハイパーリンクを作成、リストまたは無効化できます。また、デフォルトでADMINユーザーには次の権限があります。
  • PDB_DBAロールを持つADMINユーザーは、DBMS_DATA_ACCESSに対するEXECUTE権限を持ちます。
  • PDB_DBAロールを持つADMINユーザーは、Autonomous Databaseインスタンスの任意の表ハイパーリンクをリストまたは無効化できます。

DBMS_DATA_ACCESSサブプログラムの概要

この項では、Autonomous Databaseで提供されるDBMS_DATA_ACCESSサブプログラムについて説明します。

サブプログラム 説明

GET_PREAUTHENTICATED_URLプロシージャ

このプロシージャは、表ハイパーリンクを生成します。

EXTEND_URLプロシージャ

このプロシージャは、表ハイパーリンクの有効期間を延長します。

INVALIDATE_URLプロシージャ

このプロシージャは、表ハイパーリンクを無効化します。

LIST_ACTIVE_URLSファンクション

この関数は、現在アクティブなすべての表ハイパーリンクをリストします。

親トピック: DBMS_DATA_ACCESSパッケージ

GET_PREAUTHENTICATED_URLプロシージャ

このプロシージャは、表ハイパーリンクを生成します。

2つのフォームがあり、1つは特定のオブジェクト(表またはビュー)の表ハイパーリンクを生成するためのフォームです。sql_statementパラメータを使用してオーバーロードされた形式では、SQL文の表ハイパーリンクが生成されます。

構文

DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL( 
    schema_name           IN VARCHAR2,
    schema_object_name    IN VARCHAR2,
    application_user_id   IN VARCHAR2,
    expiration_minutes    IN NUMBER,
    expiration_count      IN NUMBER,
    service_name          IN VARCHAR2,
    column_lists          IN CLOB,
    inherit_acl           IN BOOLEAN  DEFAULT FALSE,
    result                OUT CLOB);

DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL( 
    sql_statement         IN CLOB,
    application_user_id   IN VARCHAR2,
    default_bind_values   IN CLOB,
    expiration_minutes    IN NUMBER,
    expiration_count      IN NUMBER,
    service_name          IN VARCHAR2,
    column_lists          IN CLOB,
    inherit_acl           IN BOOLEAN  DEFAULT FALSE,
    result                OUT CLOB);

パラメータ

パラメータ 説明

schema_name

オブジェクトのオーナーを指定します。

schema_object_name

スキーマ・オブジェクト(表またはビュー)を指定します。

sql_statement

SELECT文の問合せテキストを指定します。バインド変数のサポートは、NUMBERおよびVARCHAR2列タイプで使用できます。

application_user_id

アプリケーション・ユーザーID値を指定します。表ハイパーリンクにアクセスすると、表ハイパーリンクの生成時に指定されたapplication_user_idの値は、次の方法で使用できます。

sys_context('DATA_ACCESS_CONTEXT$', 'USER_IDENTITY')

アプリケーション・コンテキストでこの値を使用するVPDポリシーを定義して、アプリケーション・ユーザーに表示される行を制限できます。

default_bind_values

1つ以上のバインド変数のデフォルト値(バインド変数で指定されたsql_statement用)を指定します。

これにより、表のハイパーリンク・コンシューマは、問合せパラメータとしてバインド値を指定せずに、デフォルトのバインド値を使用して表のハイパーリンク・データにアクセスできます。

expiration_minutes

表ハイパーリンクの有効期間(分)。

最大許容有効期限は90日(129600分)です。値が129600より大きい値に設定されている場合、使用される値は129600分(90日)です。

expiration_minutesがNULL以外の値として指定されている場合、expiration_countをNULL以外の値に設定しないでください。両方を同時にNULL以外にすることはできません。

デフォルト値: expiration_minutesが指定されていない場合、またはexpiration_minutesがNULLとして指定されている場合、値は90日(129600分)に設定されます。

expiration_count

表ハイパーリンクで許可されるアクセス数。

デフォルト値はありません。

expiration_countが指定されておらず、expiration_minutesが指定されていない場合、expiration_minutesは90日(129600分)に設定されます。

expiration_countがNULL以外の値として指定されている場合、expiration_minutesをNULL以外の値に設定しないでください。両方を同時にNULL以外にすることはできません。

service_name

表ハイパーリンクの使用時にデータ取得に使用するデータベース・サービス。この表ハイパーリンクの保守に使用するサービス・レベルの保証とリソースを指定します。たとえば、オブジェクトまたはSQL文へのアクセスはサービスHIGHまたはMEDIUMにマップできますが、別のオブジェクトまたはSQL文へのアクセスはLOWサービスにマップできます。サポートされている値は、HIGH、MEDIUM、LOWです。

デフォルト値はLOWです。

column_lists

列でオプションを指定するJSON値。column_listsパラメータで指定されるサポートされているオプションは、次の1つ以上です。

  • order_by_columns: ソートをサポートする列を指定します。

  • filter_columns: フィルタリングをサポートする列を指定します

  • default_color_columns: 指定した列にデフォルトの色付けのみを使用するように指定します。

  • group_by_columns: 指定した列に対してグループ化を許可することを指定します(指定した列をグループ化してデータを表示することが許可されます)。

column_listsパラメータは、表のハイパーリンク機能を定義する列のJSON配列のリストを含むJSONです。このパラメータを使用して、1つ以上のオプション(order_by_columns、filter_columns、default_color_columnsまたはgroup_by_columns)の列を指定します。

形式は次のとおりです。

"column_lists" : {
        "order_by_columns": [order_by_columns_list],
        "filter_columns": [filter_columns_list],
        "default_color_columns": [default_color_columns_list],
        "group_by_columns": [group_by_columns_list]
},

たとえば: 

"column_lists" : {
            "order_by_columns": ["NAME", "DEPARTMENT"],
            "filter_columns": ["ID", "NAME", "DEPARTMENT"],
            "default_color_columns": ["DEPARTMENT"],
            "group_by_columns": ["DEPARTMENT"]
},

デフォルトの値

order_by_columnsおよびfilter_columnsオプションにcolumn_listsが指定されていない場合、すべての列に対してソートおよびフィルタリングが有効になります。

group_by_columnsにcolumn_listsが指定されていない場合、グループ化オプションはどの列でも有効になりません。デフォルトでは、group_by_columnsとして有効化するように定義された列もfilter_columnsとして有効化されます。

inherit_acl

ACLを継承するには、このパラメータの値をTRUEに設定します。継承がtrueの場合、受信表ハイパーリンク・コンシューマのIPアドレスは、データへのアクセスを許可する前に、プロデューサ・データベースのACLリストを使用して検証されます。

パラメータが指定されていないか、パラメータ値がFALSEに設定されている場合、ACLチェックは適用されません。

プロデューサ・データベースにACLが構成されていない場合、inherit_acl値は無視され、ACLチェックなしでデータ・アクセスが許可されます。

デフォルト値はFALSEです。

result

操作の結果を示すJSON。

使用上のノート

  • Autonomous Databaseインスタンスには、アクティブな表ハイパーリンクが128個制限されています。

  • ブラウザから表ハイパーリンクを使用する場合、次のオプションがサポートされています。
    • 表ハイパーリンクに?view=table問合せパラメータを追加して、返されたデータを色付けせずに表形式で表示します(デフォルト)。
    • 返されたデータを表形式で表示し、列値に基づいて事前設定された色で色付けする列を選択します。これを行うには、表ハイパーリンクに?view=table&colored_column_names=column_name_1,column_name_2、...column_name_n問合せパラメータを追加します。column_name_1からcolumn_name_nは、色付けする列の名前です。
    • 返されたデータを表形式で表示し、?view=table&colored_column_types=data_type問合せパラメータを追加して、事前設定された色で色付けする特定の列データ型を選択します。サポートされているdata_typeパラメータ値は、VARCHARおよびNONEです。

    • sql_statementパラメータ値は、SELECT文である必要があります。SELECT文では、バインド変数がサポートされています。

      SELECT文にバインド変数が含まれていて、値がdefault_bind_valuesパラメータに設定されていない場合は、データにアクセスするときに、生成された表ハイパーリンクに問合せパラメータとしてバインド変数値を追加する必要があります。

      default_bind_valuesパラメータを含めると、データにアクセスするときに、default_bind_valuesパラメータにデフォルト値が指定されている場合、バインド変数の値を省略できます。問合せパラメータとしてバインド変数値を明示的に指定することで、default_bind_valuesで指定されたデフォルトのバインド変数値をオーバーライドできます。

  • プライベート・エンドポイントを含むAutonomous Databaseインスタンスで表ハイパーリンクを生成すると、結果には"https://private-endpoint/adb/p/parurl-token/data"という形式の値を持つprivate_preauth_urlという名前が含まれます。

    プライベート・エンドポイントを使用してAutonomous Databaseインスタンスに表ハイパーリンクを生成し、プライベート・エンドポイントが「パブリック・アクセスの許可」を有効にして構成されている場合、結果にはパブリック・エンドポイントのpreauth_urlとprivate_preauth_urlの両方が含まれます。

    詳細は、プライベート・エンドポイントの構成およびパブリック・アクセスを許可したプライベート・エンドポイントの使用を参照してください。

例- 特定のオブジェクトに対して生成される表ハイパーリンク

次の例では、STUDENTS_VIEWの表ハイパーリンクを生成します。 

DECLARE
   status CLOB;
   BEGIN
   DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL(
      schema_name => 'USER1',
      schema_object_name => 'STUDENTS_VIEW',
      expiration_minutes => 120,
      service_name => 'HIGH',
      result => status);
   dbms_output.put_line(status);
END;
/

例- SQL文に対して生成される表ハイパーリンク

次の例では、SELECT SQL文の表ハイパーリンクを生成します。 

DECLARE
   status CLOB;
   par_url_app_string CLOB;
   BEGIN
       par_url_app_string := 1919292929;
       DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL(
            sql_statement => 'SELECT student_id, student_name FROM STUDENTS_VIEW ORDER BY student_id',
            application_user_id => par_url_app_string,
            expiration_count => 25,
            result => status);
END;
/

例- バインド変数を持つSQL文に対して生成される表ハイパーリンク

次の例では、SELECT文でバインド変数を使用して表ハイパーリンクを生成します。 

set serveroutput on 
DECLARE
  status clob; 
BEGIN
  DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL(
    sql_statement => 'select * from TREE_DATA WHERE COUNTY = :countyNAME',
    expiration_minutes => 3000,
    result => status);
    dbms_output.put_line('status : '||status);
END;
/

生成された表ハイパーリンクを使用するには、バインド変数値を渡す必要があります。次の例では、生成されたテーブル ハイパーリンクを使用して、最初の郡のツリー データにアクセスします。

https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/gTlbq...example/data?countyNAME=First

表のハイパーリンクを使用したバインド変数によるデータへのアクセス

次の例では、SELECT文でバインド変数を使用し、表ハイパーリンクを生成するためにdefault_bind_valuesパラメータを含めます。 

set serveroutput on 
DECLARE
  status clob; 
BEGIN
  DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL(
    sql_statement = 'SELECT * FROM TREE_DATA WHERE COUNTY = :countyNAME',
    default_bind_values => '{"countyNAME" : "First"}',
    expiration_minutes => 3000,
    result => status);
    dbms_output.put_line('status : '||status);
END;
/

この場合、デフォルトのバインド変数値が使用され、値を問合せパラメータとして指定する必要はありません。たとえば:

curl https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K6X...example/data
curl https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K6X...example/data

{"items":[
{"COUNTY":"First","SPECIES":"Pine","HEIGHT":16},
{"COUNTY":"First","SPECIES":"Spruce","HEIGHT":6},
{"COUNTY":"First","SPECIES":"Hawthorn","HEIGHT":19},
{"COUNTY":"First","SPECIES":"Cherry","HEIGHT":20},
{"COUNTY":"First","SPECIES":"Chestnut","HEIGHT":51}],
"hasMore":false,
"limit":100,
"offset":0,
"count":6,
"links":
[
{"rel":"self",
"href":"https://dataaccess.adb.us-ashburn-1.oraclecloudapps.com/adb/p/gTlbq...example/data"}
]}

問合せパラメータとして値を明示的に指定することで、デフォルトのバインド変数値をオーバーライドできます。たとえば:

curl https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K6X...example/data?countyNAME=MAIN

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

例- グループ化列を含む特定のオブジェクトに対して生成される表ハイパーリンク

次の例では、「グループ化基準」列が指定されている特定の表に対して表ハイパーリンクを生成します。

DECLARE
   status CLOB;
   BEGIN
      DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL(
          schema_name => 'ADMIN',
          schema_object_name    => 'TREE_DATA',
          expiration_minutes    => 360,
          service_name          => 'HIGH',
          column_lists          => {"group_by_columns": ["COUNTY", "SPECIES"]}',
          result                => status);

       dbms_output.put_line(status);
    END;
/

EXTEND_URLプロシージャ

このプロシージャは、表ハイパーリンクの有効期間を延長します。

構文

DBMS_DATA_ACCESS.EXTEND_URL( 
    id                              IN VARCHAR2,
    extend_expiration_minutes_by    IN NUMBER,
    extend_expiration_count_by      IN NUMBER,
    result                          OUT CLOB);

パラメータ

パラメータ 説明

id

拡張する表ハイパーリンクのIDを指定します。

extend_expiration_minutes_by

表ハイパーリンクの有効期限を延長する分数。有効期限は、現在の有効期限にextend_expiration_minutes_byの値を加えた値に設定されます。

extend_expiration_minutes_byに現在の有効期限を加えた値は、129600 (90日に対応)を超えないようにする必要があります。

extend_expiration_minutes_byがnullの場合、extend_expiration_count_byはnullにできません。同時に両方をNULLにすることはできません。

デフォルト値はNULLです。

extend_expiration_count_by

表ハイパーリンクのアクセス数は、この数によって拡張されます。有効期限数は、現在の有効期限数にextend_expiration_count_byの値を加えた値に設定されます。

extend_expiration_count_byがnullの場合、extend_expiration_minutes_byはnullにできません。同時に両方をNULLにすることはできません。

デフォルト値はNULLです。

result

操作の結果を示すJSON。

例- 表ハイパーリンクの有効期限(分)の拡張

set serveroutput on
declare
  status clob;
  js_status json_object_t;
  js_arr    json_array_t;
  url_id varchar2(4000);
begin
  -- Initially sets the expiration time to 60 minutes
  dbms_data_access.get_preauthenticated_url(
    schema_name        => 'SCOTT',     -- Schema name
    schema_object_name => 'EMPLOYEE',  -- Schema object name
    expiration_minutes => 60,          -- Expiration minutes
    service_name       => 'HIGH',
    result             => status);
   js_status := json_object_t.parse(status);
  url_id := js_status.get_string('id');
  dbms_output.put_line('The url id of url: ' || url_id);
  dbms_output.put_line('Initial Expiration Time: ' ||
                       js_status.get_string('expiration_ts'));
  -- Extend the expiration minutes by 1 day, the url would now expire
  -- 24 hours later than the previous expiration time
  dbms_data_access.extend_url(
    id                           => url_id,
    extend_expiration_minutes_by => 1440,
    result                       => status);
   -- List urls created
  status := dbms_data_access.list_active_urls;
  js_arr := json_array_t.parse(status);
  for indx in 0.. js_arr.get_size - 1
  loop
    js_status := TREAT (js_arr.get (indx) AS json_object_t);
    if js_status.get_string('id') = url_id then
      dbms_output.put_line('New Expiration Time : ' ||
                            js_status.get_string('expiration_time'));
      exit;
    end if;
  end loop;
end;
/

例- 表ハイパーリンクの有効期限の延長数

set serveroutput on
declare  status clob;
  js_status json_object_t;
  js_arr    json_array_t;
  url_id varchar2(4000);
begin
  -- Initially sets the expiration count to 100
  dbms_data_access.get_preauthenticated_url(
    schema_name        => 'SCOTT',     -- Schema name
    schema_object_name => 'EMPLOYEE',  -- Schema object name
    expiration_count   => 100,         -- Expiration count
    service_name       => 'HIGH',
    result             => status);
  js_status := json_object_t.parse(status);
  url_id := js_status.get_string('id');
  dbms_output.put_line('The url id of url: ' || url_id);
  dbms_output.put_line('Initial Expiration Count: ' ||
                       js_status.get_string('expiration_count'));
  -- Extends access count by 100 so url would expire after 200 accesses
  dbms_data_access.extend_url(
    id                         => url_id,
    extend_expiration_count_by => 100,
    result                     => status);
  -- List urls created
  status := dbms_data_access.list_active_urls;
  js_arr := json_array_t.parse(status);
  for indx in 0.. js_arr.get_size - 1
  loop
    js_status := TREAT (js_arr.get (indx) AS json_object_t);
     if js_status.get_string('id') = url_id then
      dbms_output.put_line('New Expiration Count : ' ||
                            js_status.get_string('expiration_count'));
      exit;
    end if;
  end loop;
end;
/

INVALIDATE_URLプロシージャ

このプロシージャは、表ハイパーリンクを無効化します。

構文

DBMS_DATA_ACCESS.INVALIDATE_URL(
    id                  IN VARCHAR2,
    kill_sessions       IN BOOLEAN DEFAULT FALSE,
    result              OUT CLOB);

パラメータ

パラメータ 説明

id

オブジェクトのオーナーを指定します。

kill_sessions

デフォルトでは、表ハイパーリンクを使用してデータにアクセスしている可能性がある既存のセッションは強制終了されません。TRUEの場合、このパラメータは、無効化によってデータ・セットへの継続的なアクセスが残されないように、このような既存のセッションを強制終了することを指定します。

有効な値: TRUE | FALSE。

result

無効化が成功か失敗かを示すJSONを提供します(CLOB)。

LIST_ACTIVE_URLSファンクション

この関数は、現在アクティブなすべての表ハイパーリンクおよび表ハイパーリンク・グループをリストします。

構文

DBMS_DATA_ACCESS.LIST_ACTIVE_URLS RETURN CLOB;

パラメータ

パラメータ 説明
RETURN

戻り値はJSON配列です。

例

DECLARE
   result CLOB;
   BEGIN
       result := DBMS_DATA_ACCESS.LIST_ACTIVE_URLS;
       DBMS_OUTPUT.PUT_LINE(result);
   END;
[{"id":"pT36lYHFGA4s3UXSNBCRO13v3D4_example1",
"created_by":"SCOTT",
"service_name":"HIGH",
"expiration_time":"2025-07-28T16:38:02.723Z",
"expiration_count":10,
"access_count":0,
"created":"2025-04-29T16:38:02.977Z",
"inherit_acl":true,
"is_group_url":false,
"group_ids":[null],
"sql_statement":"select * FROM TREE_DATA WHERE COUNTY = :county"}]

使用上のノート

  • DBMS_DATA_ACCESS.LIST_ACTIVE_URLSの動作は、実行者によって異なります。実行者がADMINまたはPDB_DBAロールを持つユーザーの場合、ファンクションは、表ハイパーリンクを生成したユーザーに関係なく、すべてのアクティブな表ハイパーリンクをリストします。実行者がADMINユーザーではなく、PDB_DBAロールを持つユーザーでない場合、リストには、実行者が生成したアクティブな表ハイパーリンクのみが含まれます。

  • プライベート・エンドポイントを含むAutonomous Databaseインスタンスで表ハイパーリンクを生成してリストすると、結果には"https://private-endpoint/adb/p/parurl-token/data"という形式の値を持つprivate_preauth_urlという名前が含まれます。

    プライベート・エンドポイントを含むAutonomous Databaseインスタンスで表ハイパーリンクを生成してリストし、プライベート・エンドポイントが「パブリック・アクセスの許可」を有効にして構成されている場合、結果にはパブリック・エンドポイントのpreauth_urlとprivate_preauth_urlの両方が含まれます。

    詳細は、プライベート・エンドポイントの構成およびパブリック・アクセスを許可したプライベート・エンドポイントの使用を参照してください。

  • 表ハイパーリンクがグループ・メンバーである場合、DBMS_DATA_ACCESS.LIST_ACTIVE_URLSレスポンス・エントリには、1つ以上のIDを含むnull以外の値を含むgroup_idsが表示されます。IDには、表ハイパーリンク(グループ・メンバー)がメンバーである表ハイパーリンク・グループIDが表示されます。