1. インストレーション、構成および開発ガイド
  2. mod_plsqlからORDSへの移行

5 mod_plsqlからORDSへの移行

この章では、mod_plsqlアプリケーションをOracle REST Data Services (ORDS)に移行する方法を示します。

Oracle REST Data Servicesは、Oracle HTTP Serverおよびmod_plsqlのかわりとなるJava EEベースのサービスです。Oracle HTTP Serverのmod_plsqlアプリケーションは、新しいORDS構成ファイルを定義することでORDSに移行できます。beforeプロシージャ、afterプロシージャ、リクエスト検証ファンクション、owa_customパッケージ、ドキュメント・アップロード・プロシージャおよびドキュメント表などのmod_plsqlのデータベース・リソースは、ORDSへの移行時に変更する必要はありません。

トピック:

5.1 Oracle HTTP Serverのmod_plsqlの認証

Oracle HTTP Serverのmod_plsqlアプリケーションは、データベース・アクセス記述子(DAD)ファイルで構成されます。

次のサンプルmod_plsqlアプリケーションは、Oracle Databaseに対するリクエストを認証するための方法を提供します。
  • 基本認証: ユーザー名とパスワードはDADファイルに格納されるため、エンド・ユーザーはログインする必要がありません。この方法は、公開情報を提供するWebページに便利です。
  • 基本動的認証: ユーザーはブラウザの「HTTP基本認証」ダイアログ・ボックスに資格証明を入力します。ログアウトする唯一の方法は、ブラウザのすべてのインスタンスを閉じることです。
  • カスタム認証: アプリケーションは、ユーザーが記述した認証ファンクションを呼び出して、データベース・レベルではなくアプリケーション内でユーザーを認証できます。

関連トピック

5.2 Oracle HTTP ServerのDADファイルの例

この項では、Oracle HTTP ServerのDADファイルの例を示します。

次のdads.confファイルには、基本認証、基本動的認証およびカスタム認証を示す3つの場所と次のディレクティブが含まれています。
  • PlsqlBeforeProcedure
  • PlsqlAfterProcedure
  • PlsqlRequestValidationFunction
  • PlsqlDocumentTablename
  • PlsqlDocumentProcedure

例5-1 dads.confファイル


# ============================================================================
#                     mod_plsql DAD Configuration File
# ============================================================================
<Location /pls/basic_auth>
  SetHandler pls_handler
  Order deny,allow
  Allow from all
  AllowOverride                     None
  PlsqlDatabaseUsername             PRIVILEGED_USER
  PlsqlDatabasePassword             passwordF0R$0RD5Example
  PlsqlDatabaseConnectString        oracle-ee:1521:ORCLPDB1 ServiceNameFormat
  PlsqlAuthenticationMode           Basic
  PlsqlBeforeProcedure              sample_plsql_app_metadata.beforeProc
  PlsqlAfterProcedure               sample_plsql_app_metadata.afterProc
  PlsqlRequestValidationFunction    sample_plsql_app_metadata.validationFunc
  PlsqlDocumentTablename            privileged_user.doc_table
  PlsqlDocumentProcedure            privileged_user.upload
</Location>
<Location /pls/basic_dynamic_auth>
  SetHandler pls_handler
  Order deny,allow
  Allow from all
  AllowOverride                     None
  PlsqlDatabaseConnectString        oracle-ee:1521:ORCLPDB1 ServiceNameFormat
  PlsqlAuthenticationMode           Basic
  PlsqlBeforeProcedure              sample_plsql_app_metadata.beforeProc
  PlsqlAfterProcedure               sample_plsql_app_metadata.afterProc
  PlsqlRequestValidationFunction    sample_plsql_app_metadata.validationFunc
</location>
<Location /pls/custom_auth>
  SetHandler pls_handler
  Order deny,allow
  Allow from all
  AllowOverride                     None
  PlsqlDatabaseUsername             PRIVILEGED_USER
  PlsqlDatabasePassword             passwordF0R$0RD5Example
  PlsqlDatabaseConnectString        oracle-ee:1521:ORCLPDB1 ServiceNameFormat
  PlsqlAuthenticationMode           CustomOwa
  PlsqlBeforeProcedure              sample_plsql_app_metadata.beforeProc
  PlsqlAfterProcedure               sample_plsql_app_metadata.afterProc
  PlsqlRequestValidationFunction    sample_plsql_app_metadata.validationFunc
</location>

5.3 ORDSへのmod_plsql設定のマッピング

この項では、ORDSへのmod_plsql設定のマッピングを示します。

ORDSでは、Oracle HTTP Serverのmod_plsql DADファイルで定義される場所と同様の構成ファイルを指定できます。各構成ファイルはords_conf/ords/confディレクトリに定義され、構成ファイルはords_conf/ords/url-mapping.xmlファイルを使用して特定のURLにマップされます。ORDSには、mod_plsqlディレクティブを移行する際に使用できる次の構成可能なパラメータがあります。

表5-1 mod_plsqlディレクティブからORDS設定へのマッピング

mod_plsqlの設定 ORDSの設定 説明
PlsqlDatabaseUserName db.username

データベースへのログインに使用するユーザー名を指定します。

ORDSとmod_plsqlは同等です。
PlsqlDatabasePassword db.password

データベースへのログインに使用するパスワードを指定します。

ORDSとmod_plsqlは同等です。
PlsqlDatabaseConnectString

次のような複数の設定があります。

  • db.hostname

  • db.port

  • db.servicename

  • db.sid

Oracle Databaseへの接続を指定します。

ORDSとmod_plsqlは同等です。
PlsqlAuthenticationMode security.requestAuthenticationFunction

アクセスできるように、使用する認証モードを指定します。

security.requestAuthenticationFunctionが指定されていない場合、ORDSの動作はmod_plsqlのBasicモードと同じです。

security.requestAuthenticationFunctionが指定されている場合、ORDSはmod_plsqlのサンプルのdadディレクティブPlsqlAuthenticationMode CustomOwaと同じアクションを実行できます。

ORDSの同等の構成パラメータの例:

<entry key="security.requestAuthenticationFunction">privileged_user.owa_custom.authorize</entry>

ORDSとmod_plsqlは同等です。
PlsqlBeforeProcedure procedure.preProcess

リクエストされたプロシージャのコール前に起動するプロシージャを指定します。

ORDSとmod_plsqlは同等です。
PlsqlAfterProcedure procedure.postProcess

リクエストされたプロシージャのコール後に起動するプロシージャを指定します。

ORDSとmod_plsqlは同等です。
PlsqlRequestValidationFunction security.requestValidationFunction

アプリケーション定義のPL/SQLファンクションを指定します。このファンクションにより、リクエストされたプロシージャのさらなる処理を許可または拒否できます。

ORDSとmod_plsqlは同等です。
PlsqlDocumentTablename owa.docTable

すべてのドキュメントのアップロード先となるデータベース内の表を指定します。

ORDSとmod_plsqlは同等です。

PlsqlDocumentProcedure N/A

ドキュメントのダウンロード開始時にコールするプロシージャを指定します。

ORDSでは、ドキュメント・プロシージャはリクエストされたリソースです。構成ファイルには定義しません。

ORDSとmod_plsqlは同等です。
PlsqlDocumentPath N/A

ORDSには同等のものはありません。
PlsqlDefaultPage misc.defaultPage

URLに何も指定されていない場合にコールするデフォルトのプロシージャを指定します。

ORDSとmod_plsqlは同等です。
PlsqlErrorStyle debug.printDebugToScreen

mod_plsqlエラーのエラー・レポート・モードを指定します。

debug.printDebugToScreenはPlsqlErrorStyle DebugStyleと同等です。それ以外に同等のものはありません。

ORDSとmod_plsqlは同等です。
PlsqlExclusionList security.exclusionList

ブラウザから直接実行することが禁じられているプロシージャ、パッケージまたはスキーマ名のパターンを指定します。

構成可能なパラメータを理解するを参照してください。

ORDSとmod_plsqlは同等です。
PlsqlIdleSessionCleanupInterval jdbc.InactivityTimeout

アイドル・データベース・セッションがクローズされてクリーン・アップされるまでの時間(分数)を指定します。

値は0からN秒です。ここで、0 (デフォルト)はアイドル接続がプールから削除されないことを意味します。

ORDSとmod_plsqlは同等です。
PlsqlMaxRequestsPerSession jdbc.MaxConnectionReuseCount

プーリングされたデータベース接続がクローズされて再オープンされる前に処理する必要のある最大リクエスト数を指定します。

デフォルト値は1000です。

ORDSとmod_plsqlは同等です。
PlsqlInfoLogging N/A 構成可能なパラメータを理解するを参照してください。
PlsqlLogDirectory N/A 構成可能なパラメータを理解するを参照してください。
PlsqlLogEnable N/A 構成可能なパラメータを理解するを参照してください。
PlsqlSessionStateManagement N/A

各リクエストの終了時に、パッケージとセッションの状態をクリーン・アップする方法を指定します。

ORDSは、各リクエストの最後にdbms_session.modify_package_state(dbms_session.reinitialize)を常に実行します。
PlsqlAlwaysDescribeProcedure N/A

mod_plsqlアプリケーションでプロシージャを実行する前に記述する必要があるかどうかを指定します。

ORDSでは、常に最初のアクセスでプロシージャが記述され、その定義がキャッシュされます。シグネチャの変更が検出され、再度キャッシュされます。
PlsqlConnectionValidation N/A

mod_plsqlモジュールが接続プールで終了済接続を検出するために使用するメカニズムを指定します。

ORDSは常に借用時に接続を検証します。
PlsqlFetchBufferSize N/A

owa_util.get_pageまたはowa_util.get_page_rawを使用して、データベースからフェッチする内容のトリップごとの行数を指定します。

結果が32Kを超える場合、ORDSは結果を32K VARCHARまたはCLOBとして生成するため、該当するものはありません。
PlsqlNLSLanguage N/A

NLS_LANG変数を指定します。

ORDS、JavaおよびJDBCではUnicodeが使用されます。
PlsqlTransferMode N/A

PlsqlTransferModeは、データベースからのデータをmod_plsqlアプリケーションに送信するためのモードを指定します。

ORDSでは常にUnicodeが使用されます。
PlsqlBindBucketLengths N/A

コレクション・バインド内の要素数のバインド中に使用する丸めサイズを指定します。

mod_plsqlではほとんど使用されず、JDBCには同等の概念がありません。
PlsqlBindBucketWidths N/A

コレクション・バインド内の要素数のバインド中に使用する丸めサイズを指定します。

mod_plsqlではほとんど使用されず、JDBCには同等の概念がありません。
PlsqlCacheCleanupTime N/A ORDSには同等のものはありません。
PlsqlDMSEnable N/A ORDSはDMSをサポートしていません。
PlsqlSessionCookieName N/A ORDSでは、PL/SQLゲートウェイ・コールのセッション管理は提供されません。
PlsqlCacheDirectory N/A ORDSには同等のものはありません。
PlsqlCacheEnable N/A ORDSには同等のものはありません。
PlsqlCacheMaxAge N/A ORDSには同等のものはありません。
PlsqlCacheMaxSize N/A ORDSには同等のものはありません。
PlsqlCacheTotalSize N/A ORDSには同等のものはありません。
PlsqlCGIEnvironmentList N/A ORDSには同等のものはありません。
PlsqlConnectionTimeout N/A ORDSには同等のものはありません。
PlsqlPathAlias N/A ORDSには同等のものはありません。
PlsqlPathAliasProcedure N/A ORDSには同等のものはありません。
PlsqlUploadAsLongRaw N/A ORDSには同等のものはありません。

5.4 ORDS構成ファイルの例

次の項では、サンプルのmod_plsqlアプリケーションをORDSに移行する方法を示します。

トピック:

5.4.1 基本認証の構成ファイルの例

例5-2 ords_conf/ords/conf/basic_auth.xml


<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
    <comment>Saved on Wed Jul 25 10:22:37 UTC 2018</comment>
    <entry key="db.username">PRIVILEGED_USER</entry>
    <entry key="db.password">!passwordF0R$0RD5Example</entry>
    <!-- Example url -->
    <!-- See url-mapping.xml -->
    <!-- http://localhost:8086/ords/pls/basic_auth/sample_plsql_app.sample_public_proc-->
    <!-- http://localhost:8086/ords/pls/basic_auth/sample_plsql_app.privileged_public_proc-->
    <entry key="procedure.postProcess">sample_plsql_app_metadata.afterProc</entry>
    <entry key="procedure.preProcess">sample_plsql_app_metadata.beforeProc</entry>
    <entry key="security.requestValidationFunction">sample_plsql_app_metadata.validationFunc</entry>
    <entry key="owa.docTable">sample_plsql_app.doc_table</entry>
</properties>

5.4.2 基本動的認証の構成ファイルの例

例5-3 ords_conf/ords/conf/basic_dynamic_auth.xml


<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
    <comment>Saved on Wed Jul 25 10:22:37 UTC 2018</comment>    
    <!--  NOTE THAT IF THIS USER HAS EXECUTE PRIVILEGE ON THE RESOURCE THEN jdbc.auth.enabled IS IGNORED -->
    <!--  IF THIS USER DOES NOT HAVE EXECUTE PRIVILEGE ON THE RESOURCE THEN jdbc.auth.enabled IS INVOKED AND THE CREDENTIALS OF A PRIVILEGED USER HAS TO BE PROVIDED-->
    <entry key="db.username">NON_PRIVILEGED_USER</entry> 
    <entry key="db.password">!passwordF0R$0RD5Example</entry>
    <entry key="jdbc.auth.enabled">true</entry>
    <!-- Example url -->
    <!-- See url-mapping.xml -->
    <!-- INVOKE jdbc.auth.enabled :   http://localhost:8086/ords/pls/basic_dynamic_auth/sample_plsql_app.sample_privileged_proc -->
    <!-- IGNORE jdbc.auth.enabled :   http://localhost:8086/ords/pls/basic_dynamic_auth/sample_plsql_app.sample_public_proc   -->
    <!-- Because jdbc.auth.enabled is ignored when referencing the sample_public_app, the beforeProc,afterProc and validationFunc must be accessible by NON_PRIVILEGED_USER -->
    <!-- The following objects are executed by the same credentials used to access the resource -->
    <!-- If the resource can be accessed by the db.username then that connection is used to access these methods -->
    <!-- If the resource cannot be accessed by the db.username then jdbc.auth.enabled is invoked and those credentials as used to access these methods -->
    <entry key="procedure.postProcess">sample_plsql_app_metadata.afterProc</entry>
    <entry key="procedure.preProcess">sample_plsql_app_metadata.beforeProc</entry>
    <entry key="security.requestValidationFunction">sample_plsql_app_metadata.validationFunc</entry>
</properties>

5.4.3 カスタム認証の構成ファイルの例

例5-4 ords_confs/ords/conf/custom_auth.xml


<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
    <comment>Saved on Wed Jul 25 10:22:37 UTC 2018</comment>
    <entry key="db.username">PRIVILEGED_USER</entry>
    <entry key="db.password">!passwordF0R$0RD5Example</entry>
    <!-- Example url -->
    <!-- See url-mapping.xml -->
    <!-- http://localhost:8086/ords/pls/custom_auth/sample_plsql_app.sample_proc -->
    <!-- privileged_user.owa_custom.authorize requires the following as the custom login -->
    <entry key="procedure.postProcess">sample_plsql_app_metadata.afterProc</entry>
    <entry key="procedure.preProcess">sample_plsql_app_metadata.beforeProc</entry>
    <entry key="security.requestValidationFunction">sample_plsql_app_metadata.validationFunc</entry>
    <entry key="security.requestAuthenticationFunction">privileged_user.owa_custom.authorize</entry>
</properties>

5.5 ORDSとURLのマッピングの例

この項では、ベースパスURLと構成ファイルのマッピングの例を示します。

例5-5 ords_conf/ords/url-mapping.xml

<?xml version="1.0" encoding="UTF-8"?>
<pool-config xmlns="http://xmlns.oracle.com/apex/pool-config">
    <pool name="basic_auth" base-path="/pls/basic_auth" updated="2018-07-17T20:52:29.045Z" />
    <pool name="basic_dynamic_auth" base-path="/pls/basic_dynamic_auth" updated="2018-07-17T20:52:29.045Z" />
    <pool name="custom_auth" base-path="/pls/custom_auth" updated="2018-07-17T20:52:29.045Z" />
</pool-config>

5.6 ORDSのデフォルト構成の例

この項では、ORDSのデフォルト構成設定の例を示します。

default.xmlファイルには、すべての構成で使用されるデータベース接続の詳細が含まれています。

注意:

プロシージャ検証キャッシュをオフにするには、security.maxEntries値を0に設定します。これはOracle HTTP Serverのmod_plsqlをエミュレートするために必要となります。

例5-6 ords_conf/ords/default.xml

<?xml version = '1.0' encoding = 'UTF-8'?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
   <!-- by default security.maxEntries = 2000 which means 2000 procedures validity will be cached-->
   <!-- this is fine for applications like apex where the validation of a procedure does not change  -->
   <!-- for applications migrating from mod_plsql the cache should be disabled so that procedures validity is determined for each request -->
   <!-- this is done by setting security.maxentries to 0 -->
   <entry key="security.maxEntries">0</entry>
   <entry key="db.hostname">oracle-ee</entry>
   <entry key="db.port">1521</entry>
   <entry key="db.servicename">orclpdb1</entry>
</properties>

5.7 ORDS認証

ORDSでは、mod_plsqlからの1対1のマッピングを提供することで、HTTP基本認証を実行できます。ORDSでは、よりセキュアな認証方法を使用できます。

トピック:

関連トピック

5.7.1 基本認証

この項では、ORDSを使用して実装される基本認証について説明します。

データベースの資格証明はORDS構成ファイルに指定します。db.usernameには、リソースへのアクセスに必要な権限が必要となります。

注意:

エントリsecurity.requestAuthenticationFunctionは指定しません。

5.7.2 基本動的認証

この項では、ORDSを使用して基本動的認証を実装する方法について説明します。

リソースへのアクセスに基本動的認証を指定する場合は、ORDS構成ファイルにデフォルトのdb.usernameおよびdb.passwordを指定する必要があります。

次の条件が満たされている場合、このタイプの認証を使用してアクセスできないリソースにアクセスできます。
  • <entry key="jdbc.auth.enabled">true</entry>エントリの値がtrueである。
  • security.requestAuthenticationFunctionエントリが指定されていない。
  • ORDSレスポンスによってブラウザの「基本HTTP認証」ダイアログ・ボックスが表示され、ユーザーが入力する資格証明に必要な権限があり、リソースが使用可能になる。

    注意:

    資格証明をブラウザの「HTTP認証」ダイアログ・ボックスで入力する場合、ログアウトする唯一の方法は、ブラウザのすべてのインスタンスを閉じることです。

5.7.3 カスタム認証

この項では、ORDSを使用してカスタム認証を実装する方法について説明します。

カスタム認証を実行するファンクションを指定します。このファンクションはowa変数にアクセスできます。リソースは、次のファンクションがTRUE値を返す場合にのみ使用できます。

<entry key="security.requestAuthenticationFunction">privileged_user.owa_custom.authorize</entry>

認証ファンクションには、次のコード・スニペットに示すようなシグネチャが必要です。
/**
* OWA_CUSTOM used in mod_plsql when the following is used in the dad configuration file
  PlsqlAuthenticationMode       Custom
  In ORDS environment this can reside in any schema as long as the connection has execute privileges
  In mod_plsql this has to reside in the connections schema as you cannot specify the name of the schema,package or function
  ex: PlsqlAuthenticationMode           CustomOwa
*/
CREATE OR REPLACE PACKAGE OWA_CUSTOM  AS
/**
 * Response:
  >IF Failed
   WWW-Authenticate in response header
   Authorization Required
   You are not authorized to access the requested resource. Check the supplied credentials (e.g., username and password).
 */
FUNCTION authorize RETURN BOOLEAN;
END OWA_CUSTOM ;
/

5.8 ORDSの機能

この項では、mod_plsqlアプリケーションからORDSに移行するときに便利なORDS機能について説明します。

トピック:

5.8.1 検証機能のリクエスト

この項では、リクエスト検証ファンクションの使用について説明します。

リクエスト検証ファンクションは、リソースへのアクセスを制限します。リクエスト検証ファンクションはリクエストされているリソースの名前とともに指定し、レスポンスではTRUE値またはFALSE値が返されます。

リクエスト検証ファンクションがFALSE値を返した場合、ORDSはリクエストを終了します。

例5-7 security.requestValidationFunction

<entry key="security.requestValidationFunction">sample_plsql_app_metadata.validationFunc</entry>

検証ファンクションには任意の名前を選択できます。ただし、シグネチャは次の形式にする必要があります。

CREATE OR REPLACE FUNCTION validationfunc(procedure_name VARCHAR2) RETURN BOOLEAN IS。

5.8.2 事前処理機能

この項では、procedure.preProcess ORDS構成パラメータについて説明します。

procedure.preProcess ORDS構成パラメータには、リクエストされたリソースの前に実行されるプロシージャのカンマ区切りリストを指定できます。

例5-8 procedure.preProcess

次のコード・スニペットの例は、ログインのユースケースを示しています。

<entry key="procedure.preProcess">sample_plsql_app_metadata.beforeProc</entry>

5.8.3 事後処理機能

この項では、procedure.postProcess ORDS構成パラメータについて説明します。

procedure.postProcess ORDS構成パラメータには、リクエストされたリソースの後に実行されるプロシージャのカンマ区切りリストを指定できます。

例5-9 procedure.postProcess

次のコード・スニペットの例は、ログアウトのユースケースを示しています。

<entry key="procedure.postProcess">sample_plsql_app_metadata.afterProc</entry>

5.8.4 ファイル・アップロード機能

この項では、ORDSのファイル・アップロード機能について説明します。

ORDS構成パラメータowa.docTableは、アップロードされたファイルを保持する表名を定義します。

例5-10 表のアップロード

CREATE TABLE DOC_TABLE (
     NAME               VARCHAR(256)   UNIQUE NOT NULL,
     MIME_TYPE          VARCHAR(128),
     DOC_SIZE           NUMBER,
     DAD_CHARSET        VARCHAR(128),
     LAST_UPDATED       DATE,
     CONTENT_TYPE       VARCHAR(128),
     CONTENT            LONG RAW,
     BLOB_CONTENT       BLOB );

例5-11 プロシージャのアップロード

アップロード・ファンクションには任意の名前を選択できます。ただし、シグネチャは次のPOSTリクエストと一致している必要があります。


--The parameters of the procedure should match the parameters of the request
--The procedure is called after ORDS performs the file upload/insert.
--This procedure can rollback the file INSERT as it is in the same transaction as the INSERT
CREATE OR REPLACE PROCEDURE upload (filename VARCHAR2 DEFAULT NULL)

例5-12 ファイル・アップロードのためのCurlコマンド

curl -i -X POST -F 'filename=@helloworld.txt' "http://localhost:8086/ords/pls/basic_auth/example_user1.upload