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サブプログラムについて説明します。

サブプログラム 説明

ADD_MEMBERプロシージャ

このプロシージャは、既存の表ハイパーリンクをメンバーとして表ハイパーリンク・グループに追加します。

CREATE_URLプロシージャ

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

EXTEND_URLプロシージャ

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

GET_PREAUTHENTICATED_URLプロシージャ

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

このプロシージャの使用は推奨されていません。かわりに、CREATE_URLプロシージャを使用してください。

INVALIDATE_URLプロシージャ

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

LIST_ACTIVE_URLSファンクション

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

LIST_MEMBERSプロシージャ

この手順では、表ハイパーリンク・グループのメンバーをリストします。

REMOVE_MEMBERプロシージャ

このプロシージャは、表ハイパーリンク・グループからメンバーを削除します。
  • ADD_MEMBERプロシージャ
    このプロシージャは、既存の表ハイパーリンクをメンバーとして表ハイパーリンク・グループに追加します。
  • CREATE_URLプロシージャ
    このプロシージャは、表ハイパーリンクまたは表ハイパーリンク・グループを生成します。表ハイパーリンク・グループでは、単一のURLを使用して複数の表ハイパーリンクにアクセスできます。このプロシージャはオーバーロードされています。
  • GET_PREAUTHENTICATED_URLプロシージャ
    このプロシージャは、表ハイパーリンクを生成します。
  • EXTEND_URLプロシージャ
    このプロシージャは、表ハイパーリンクまたは表ハイパーリンク・グループの存続期間を拡張します。
  • INVALIDATE_URLプロシージャ
    このプロシージャは、表ハイパーリンクまたは表ハイパーリンク・グループを無効にします。
  • LIST_ACTIVE_URLSファンクション
    このファンクションは、現在アクティブな表ハイパーリンクおよび表ハイパーリンク・グループをすべてリストします。
  • LIST_MEMBERSプロシージャ
    このプロシージャは、表ハイパーリンク・グループのメンバーをリストします。
  • REMOVE_MEMBERプロシージャ
    このプロシージャは、表ハイパーリンク・グループからメンバーを削除します。

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

ADD_MEMBERプロシージャ

このプロシージャは、既存の表ハイパーリンクをメンバーとして表ハイパーリンク・グループに追加します。

構文

DBMS_DATA_ACCESS.ADD_MEMBER(
    id        IN VARCHAR2,
    member_id       IN BOOLEAN DEFAULT FALSE,
    result          OUT CLOB);

パラメータ

パラメータ 説明

id

表ハイパーリンク・グループの識別子を指定します。
member_id

グループに追加する表ハイパーリンクの識別子を指定します。

result

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

例

DECLARE
    status CLOB;
    BEGIN
       DBMS_DATA_ACCESS.ADD_MEMBER(
        id => 'Vd1Px7QWASdqDbnndiuwTAyyEstv82PCHqS_example',
        member_id => 'Zdd1Px7QWASdqDbnndiuwTAyyEstv82PCHlS_example',
        result => status);           
       dbms_output.put_line(status);
    END;
/

CREATE_URLプロシージャ

このプロシージャは、表ハイパーリンクまたは表ハイパーリンク・グループを生成します。表ハイパーリンク・グループでは、単一のURLを使用して複数の表ハイパーリンクにアクセスできます。このプロシージャはオーバーロードされています。

構文

DBMS_DATA_ACCESS.CREATE_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.CREATE_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);

DBMS_DATA_ACCESS.CREATE_URL( 
    sqls                  IN CLOB,
    application_user_id   IN VARCHAR2,
    expiration_minutes    IN NUMBER,
    expiration_count      IN NUMBER,
    service_name          IN VARCHAR2,
    inherit_acl           IN BOOLEAN   DEFAULT FALSE,
    result                OUT CLOB);

パラメータ

パラメータ 説明

sqls

SELECT文またはスキーマ・オブジェクトのJSON配列を指定します。

JSON配列の形式の詳細は、次の説明を参照してください。

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。

sqlsパラメータとして指定したJSON配列の形式は次のとおりです。

属性の名前 必須 説明
name いいえ グループ・メンバー名を指定します。名前が指定されていない場合、プロシージャはデフォルト名を作成します。
description いいえ グループ・メンバー摘要
sql_statement

sql_statement またはschema_object_nameの指定は必須です

メンバーのSQL文

詳細は、SELECT文を使用した表ハイパーリンクの生成を参照してください。

schema_name いいえ

メンバーのスキーマ名。schema_object_nameで指定された表/ビューが現在のスキーマで使用できない場合にのみ、 schema_name値を指定します

詳細は、「表またはビューの表ハイパーリンクの生成」を参照してください。

schema_object_name

sql_statementまたはschema_object_nameの指定は必須です

メンバーの表/ビュー名

詳細は、「表またはビューの表ハイパーリンクの生成」を参照してください。

default_bind_variable いいえ バインド変数を含むsql_statementsにのみ適用可能

詳細は、SELECT文を使用した表ハイパーリンクの生成を参照してください。

column_lists いいえ グループ以外の表ハイパーリンクの作成に定義されたものと同じです。

詳細は、「列で指定されたUI機能を使用した表ハイパーリンクの生成」を参照してください。

使用上のノート

  • 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.CREATE_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.CREATE_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.CREATE_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.CREATE_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

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

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

DECLARE
   status CLOB;
   BEGIN
      DBMS_DATA_ACCESS.CREATE_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;
/

例

DECLARE
   status CLOB;
   BEGIN
      DBMS_DATA_ACCESS.CREATE_URL(
          sqls => '[{"name": "employee", "description": "employee description", "schema_name":"admin", "schema_object_name":"employee"},
              {"name":"tree", "description": "tree description", "sql_statement": "select * from admin.tree_data"}]',
          expiration_count     => 10,
          service_name         => 'HIGH',
          result               => status);
       dbms_output.put_line(status);
    END;
/

GET_PREAUTHENTICATED_URLプロシージャ

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

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

ノート

このプロシージャの使用は推奨されていません。かわりに、CREATE_URLプロシージャを使用してください。

構文

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。

使用上のノート

  • このプロシージャの使用は推奨されていません。かわりに、CREATE_URLプロシージャを使用してください。

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

  • プライベート・エンドポイントを含む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。

使用上のノート

表ハイパーリンク・グループidを使用すると、DBMS_DATA_ACCESS.ADD_MEMBERで追加されたメンバーを除くすべてのメンバー表ハイパーリンクがプロシージャによって拡張されます。DBMS_DATA_ACCESS.ADD_MEMBERを使用して表ハイパーリンク・グループに追加されたメンバーは、独立した表ハイパーリンク無効化値を保持し、DBMS_DATA_ACCESS.EXTEND_URLを使用して個別に拡張できます。

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

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

このパラメータはオプション。

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

有効な値: TRUE | FALSE。

result

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

使用上のノート

DBMS_DATA_ACCESS.INVALIDATE_URL idパラメータが表ハイパーリンク・グループの場合、DBMS_DATA_ACCESS.ADD_MEMBERで追加されたグループ・メンバーを除いて、このプロシージャはグループおよびすべてのグループ・メンバーを無効化します。DBMS_DATA_ACCESS.INVALIDATE_URLを実行すると、DBMS_DATA_ACCESS.ADD_MEMBERで追加されたメンバーは独立した表ハイパーリンク無効化値を保持し、DBMS_DATA_ACCESS.INVALIDATE_URLを使用してこれらの表ハイパーリンクを個別に無効化できます。

例

DECLARE
    status CLOB;
    BEGIN
       DBMS_DATA_ACCESS.INVALIDATE_URL(
        id => 'Vd1Px7QWASdqDbnndiuwTAyyEstv82PCHqS_example',
        result => status);           
       dbms_output.put_line(status);
    END;
/

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,
"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が表示されます。

LIST_MEMBERSプロシージャ

この手順では、表ハイパーリンク・グループのメンバーをリストします。

構文

DBMS_DATA_ACCESS.LIST_MEMBERS(
    id              IN VARCHAR2,
    result          OUT CLOB);

パラメータ

パラメータ 説明

id

表ハイパーリンク・グループの識別子を指定します。

result

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

例

DECLARE
    status CLOB;
    BEGIN
       DBMS_DATA_ACCESS.LIST_MEMBERS(
         id => 'aGnHVyZ4vBo4_Fq2R0A2G2-y6TdUKRHeveqyGJ3_example',
         result => status);           
      dbms_output.put_line(status);
    END;
/

REMOVE_MEMBERプロシージャ

このプロシージャは、表ハイパーリンク・グループからメンバーを削除します。

構文

DBMS_DATA_ACCESS.REMOVE_MEMBER(
    id              IN VARCHAR2,
    member_id       IN BOOLEAN DEFAULT FALSE,
    result          OUT CLOB);

パラメータ

パラメータ 説明

id

表ハイパーリンク・グループの識別子を指定します。
member_id

表ハイパーリンク・グループから削除するグループ・メンバーの識別子を指定します。

result

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

使用上のノート

  • member_id値は表ハイパーリンク・グループIDにできません(is_group_urlはfalseである必要があります)。

  • 削除されたメンバーが、DBMS_DATA_ACCESS.ADD_MEMBERを使用してグループに追加された既存の表ハイパーリンクである場合、そのメンバーはグループから削除されますが、表ハイパーリンクは明示的に無効化されるか期限切れになるまで直接アクセスできます。

  • 表ハイパーリンク・グループに1つのメンバーのみが含まれ、そのメンバーが削除された場合、グループは無効化されます。

例

DECLARE
    status CLOB;
    BEGIN
       DBMS_DATA_ACCESS.REMOVE_MEMBER(
        id => 'Vd1Px7QWASdqDbnndiuwTAyyEstv82PCHqS_example',
        member_id => 'Zdd1Px7QWASdqDbnndiuwTAyyEstv82PCHlS_example',
        result => status);           
       dbms_output.put_line(status);
    END;
/