Oracle Cloud Infrastructureドキュメント

DBMS_DATA_ACCESSパッケージ

DBMS_DATA_ACCESSパッケージは、データ・セットの事前認証済リクエスト(PAR) URLを生成および管理するためのルーチンを提供します。

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

DBMS_DATA_ACCESS概要

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

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

  • PAR URLの生成
  • PAR URLの手動無効化
  • アクティブなPAR URLのリスト

DBMS_DATA_ACCESSセキュリティ・モデル

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

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

DBMS_DATA_ACCESSサブプログラムの概要

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

サブプログラム 説明

GET_PREAUTHENTICATED_URLプロシージャ

このプロシージャは、PAR URLを生成します。

EXTEND_URLプロシージャ

このプロシージャは、PAR URLの存続期間を拡張します。

INVALIDATE_URLプロシージャ

このプロシージャは、PAR URLを無効化します。

LIST_ACTIVE_URLSファンクション

この関数は、現在アクティブなすべてのPAR URLをリストします。

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

GET_PREAUTHENTICATED_URLプロシージャ

このプロシージャは、PAR URLを生成します。

2つのフォームがあり、1つは特定のオブジェクト(表またはビュー)のPAR URLを生成するためのフォームです。sql_statementパラメータを使用してオーバーロードされた形式では、SQL文のPAR 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,
    result                OUT CLOB);

DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL( 
    sql_statement         IN CLOB,
    application_user_id   IN VARCHAR2,
    expiration_minutes    IN NUMBER,
    expiration_count      IN NUMBER,
    service_name          IN VARCHAR2,
    column_lists          IN CLOB,
    result                OUT CLOB);

パラメータ

パラメータ 説明

schema_name

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

schema_object_name

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

sql_statement

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

application_user_id

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

sys_context('DATA_ACCESS_CONTEXT$', 'USER_IDENTITY')

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

expiration_minutes

PAR URLの有効期間(分)。

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

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

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

expiration_count

PAR URLで許可されるアクセス数。

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

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

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

service_name

PAR URLの使用時にデータ取得に使用するデータベース・サービス。このPAR URLのサービスに使用されるサービス・レベルの保証およびリソースを指定します。たとえば、オブジェクトまたは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パラメータは、PAR-URL機能を定義する列の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として有効化されます。

result

操作の結果を示すJSON。

使用上のノート

  • Autonomous Databaseインスタンスには、128のアクティブPAR URLの制限があります。

  • ブラウザからPAR URLを使用する場合、次のオプションがサポートされています:
    • PAR URLに?view=table問合せパラメータを追加して、返されたデータを色付けせずに表形式で表示します(デフォルト)。
    • 返されたデータを表形式で表示し、列値に基づいて事前設定された色で色付けする列を選択します。これを行うには、PAR URLに?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です。

例- 特定のオブジェクトに対して生成されるPAR URL

次の例では、STUDENTS_VIEWのPAR URLを生成します。 

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ステートメント用に生成されたPAR URL

次の例では、SELECT SQL文のPAR URLを生成します。 

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文に対して生成されたPAR URL

次の例では、SELECT文でバインド変数を使用してPAR URLを生成します。 

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

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

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

例- グループ化基準列がある特定のオブジェクトに対して生成されたPAR URL

次の例では、「グループ化基準」列が指定されている特定の表のPAR 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プロシージャ

このプロシージャは、PAR 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

拡張するPAR URLのIDを指定します。

extend_expiration_minutes_by

PAR URLの有効期限を延長する分数。有効期限は、現在の有効期限に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

PAR URLに対するアクセス数は、この数によって拡張されます。有効期限数は、現在の有効期限数にextend_expiration_count_byの値を加えた値に設定されます。

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

デフォルト値はNULLです。

result

操作の結果を示すJSON。

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

例- PAR 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 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プロシージャ

このプロシージャは、PAR URLを無効化します。

構文

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

パラメータ

パラメータ 説明

id

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

kill_sessions

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

有効な値: TRUE | FALSE。

result

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

LIST_ACTIVE_URLSファンクション

この関数は、現在アクティブなすべてのPAR URLをリストします。

構文

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": "89fa6081-ec6b-4179-9b06-a93af8fbd4b7",
        "schema_name": "SCOTT",
        "schema_object_name": "EMPLOYEE",
        "created_by": "ADMIN",
        "application_user_id": "AMIT",
        "expiration_time": "2023-01-14T23:41:01.029Z",
        "expiration_count": 100,
        "access_count": 9,
        "created": "2023-01-10T19:41:01.285Z"
    },
    {
        "id": "263d2cd7-3bc0-41a7-8cb9-438a2d843481",
        "sql_statement": "select name from v$pdbs",
        "created_by": "ADMIN",
        "application_user_id": "AMIT",
        "expiration_time": "2023-01-15T00:04:30.578Z",
        "expiration_count": 100,
        "access_count": 0,
        "created": "2023-01-10T20:04:30.607Z"
    }
]

使用上のノート

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