2 Oracle REST Data Servicesの構成(詳細)

この項では、リクエストをルーティングして複数のデータベースに接続するようにOracle REST Data Servicesを構成する方法を説明し、その他の構成情報については、その他のドキュメント・ソースを参照します。

注意:

Oracle REST Data Servicesは、構成の変更を行った後に再起動する必要があります。アプリケーションを再起動する方法はアプリケーション・サーバーのマニュアルを参照してください。

トピック:

• 複数データベースの構成

• Oracle RAC Fast Connection Failoverのサポート

• セキュリティ、キャッシュ、前処理と後処理、環境、およびExcel設定の構成

• REST対応SQLサービス設定の構成

• 問合せから戻される行の最大数の構成

• カスタム・エラー・ページの構成

• Oracle REST Data Servicesで使用するRESTfulサービスの開発

2.1 複数データベースの構成

Oracle REST Data Servicesでは、複数のデータベースに接続する機能がサポートされています。この項では、リクエストを適切なデータベースにルーティングするための異なる戦略を説明します。

トピック:

• リクエストURLについて

• 追加のデータベースの構成

• リクエスト・パスの接頭辞に基づくルーティング

• リクエストURLの接頭辞に基づくルーティング

2.1.1 リクエストURLについて

Oracle REST Data Servicesは、リクエストを適切なデータベースにルーティングするための多数の異なる戦略をサポートしています。これらの戦略はすべて、リクエストURLを調べ、URLのどこかの一致に基づいてデータベースを選択することを利用しています。それは、リクエストURLの関連する部分をまとめるのに役立ちます。次のURLについて考えます。

https://www.example.com/ords/sales/f?p=1:1

このURLは、次のセクションで構成されています。

• プロトコル: https

• ホスト名: www.example.com

• コンテキスト・ルート: /ords

  コンテキスト・ルートは、アプリケーション・サーバー上のOracle REST Data Servicesがデプロイされている場所です。

• リクエスト・パス: /sales/f?p=1.1

  これは、リクエストURLのコンテキスト・ルートからの相対となる部分です。

異なるアプリケーションに対しては、リクエスト・パス内の特定の接頭辞またはリクエストURL全体の特定の接頭辞に基づいてリクエストをルーティングすることが重要です。

複数データベースを構成するには、次の2つのステップを行います。

1. データベース接続情報の構成

2. どのリクエストをどのデータベースにルーティングするかの構成

2.1.2 追加のデータベースの構成

最初にOracle REST Data Servicesを構成するとき、apexという名前のデフォルトのデータベース接続を構成します。setupコマンドを使用して追加のデータベース接続を作成できます。

ヒント:

setupコマンドの完全なヘルプを表示するには、次のように入力します。

java -jar ords.war help setup

データベース接続を作成するには、次のように入力します。

java -jar ords.war setup --database <database name>

説明:

• <database name>データベース接続に付ける名前です。

データベースを構成するために必要な情報を入力するように求められます。追加のデータベースを設定したあと、リクエストが適切なデータベースまでルーティングされる方法のルールを定義します。

2.1.3 リクエスト・パスの接頭辞に基づくルーティング

map-urlコマンドを使用してリクエストのルーティング・ルールを作成します。

ヒント:

map-urlコマンドの完全なヘルプを表示するには、次のように入力します。

java -jar ords.war help map-url

URLのリクエスト・パスの一部の接頭辞の一致に基づいてリクエストをルーティングする場合は、map-urlコマンドを次のように使用します。

java -jar ords.war map-url --type base-path --workspace-id <workspace name> <path prefix> <database name>

説明:

• <workspace name>この接続用のRESTfulサービスが定義されているOracle Application Expressワークスペースの名前です。RESTfulサービスを使用していない場合は省略できます。

• <path prefix>は、必ずリクエスト・パスの先頭にある接頭辞です。

• <database name>は、前のステップで設定したデータベース接続の名前です。

2.1.3.1 リクエスト・パスの接頭辞に基づくルーティングの例

Oracle REST Data Servicesがexample.comという名前のシステムに/ordsというコンテキスト・パスでデプロイされているとすると、次のルールを作成します。

java -jar ords.war map-url --type base-path --workspace-id sales_rest /sales sales_db

このルールは、https://example.com/ords/sales/...に一致するすべてのリクエストがsales_dbというデータベース接続にルーティングされることを意味します。sales_dbデータベースに定義されているsales_restワークスペースで、RESTfulサービスの定義が検索されます。

前述のルールは、次のすべてのリクエストと一致します。

https://example.com/ords/sales/f?p=1:1
https://example.com/ords/sales/leads/
https://www.example.com/ords/sales/forecasting.report?month=jan  (If www.example.com resolves to the same system as example.com.)

前述のルールは、次のリクエストのいずれにも一致しません。

http://example.com/ords/sales/f?p=1:1  (The protocol is wrong.)
https://example.com:8080/ords/sales/f?p=1:1  (The port is wrong: 443 is default for https, but don't specify if using default.)
https://example.com/ords/f?p=1:1  (Missing the /sales prefix.)
https://example.com/pls/sales/leads/  (The context path is wrong.)

2.1.4 リクエストURLの接頭辞に基づくルーティング

リクエストURLの接頭辞の一致に基づいてリクエストをルーティングする場合は、map-urlコマンドを次のように使用します。

java -jar ords.war map-url --type base-url --workspace-id <workspace name> <url prefix> <database name>

説明:

• <workspace name>この接続用のRESTfulサービスが定義されているOracle Application Expressワークスペースの名前です。RESTfulサービスを使用していない場合は省略できます。

• <url prefix>は、リクエストURLの先頭に必要な接頭辞です。

• <database name>は、データベース接続の名前です。

2.1.4.1 リクエストURLの接頭辞に基づくルーティングの例

Oracle REST Data Servicesがexample.comという名前のシステムに/ordsというコンテキスト・パスでデプロイされているとすると、次のルールを作成します。

java -jar ords.war map-url --type base-url --workspace-id sales_rest https://example.com/ords/sales sales_db

このルールは、https://example.com/ords/sales/...に一致するすべてのリクエストがsales_dbというデータベース接続にルーティングされることを意味します。sales_dbデータベースに定義されているsales_restワークスペースで、RESTfulサービスの定義が検索されます。

前述のルールは、次のすべてのリクエストと一致します。

https://example.com/ords/sales/f?p=1:1
https://example.com/ords/sales/leads/
https://example.com/ords/sales/forecasting.report?month=jan

前述のルールは、次のリクエストのいずれにも一致しません。

http://example.com/ords/sales/f?p=1:1  (The protocol is wrong.)
https://example.com:8080/ords/sales/f?p=1:1  (The port is wrong: 443 is default for https, but don't specify if using default.)
https://example.com/ords/f?p=1:1  (Missing the /sales segment of the base URL.)
https://example.com/pls/sales/leads/  (The context path is wrong.)
https://www.example.com/ords/sales/forecasting.report?month=jan  (The host name is wrong.)

2.2 Oracle REST Data Servicesでのマルチテナント・アーキテクチャの使用

この項では、Oracle REST Data Serviceをマルチテナント・コンテナ・データベースへインストール、構成、アップグレードおよびアンインストールする概要を示します。

• CDB環境でのOracle REST Data Servicesのインストール

• CDB環境でのOracle REST Data Servicesのアップグレード

• CDBで複数リリースを有効にするためのOracle REST Data Servicesの移行

• CDB環境でのOracle REST Data Servicesのアンインストール

2.2.1 CDB環境でのOracle REST Data Servicesのインストール

この項では、マルチテナント・コンテナ・データベース(CDB)環境にOracle REST Data Servicesをインストールする方法について説明します。

Oracle Database 12cリリース1 (12.1)では、マルチテナント・アーキテクチャが導入されています。このデータベース・アーキテクチャには、ルート・コンテナCDB$ROOT、シード・データベースPDB$SEEDおよび複数のプラガブル・データベース(PDB)を含むマルチテナント・コンテナ・データベース(CDB)が含まれます。PDBは、ユーザーおよびアプリケーションからは、非CDBであるかのように見えます。各PDBは、Oracle Databaseリリース11gの個別のデータベース・インスタンスに相当します。

ルート・コンテナCDB$ROOTは、メタデータ・リンクまたはオブジェクト・リンクを使用してすべてのPDBにアクセス可能な共通オブジェクトを保持します。シード・データベースPDB$SEEDは、新しいプラガブル・データベースをシードするために新しいPDBを作成する際に使用されます。Oracle Database 12cマルチテナント・アーキテクチャの主なメリットは、CPUやメモリーなどのデータベース・リソースをすべてのPDBで共有できることです。また、このアーキテクチャでは、アップグレード、パッチ、バックアップなどのタスクにおいて、複数のデータベースを1つのデータベースとして扱うことができます。

複数のリリースがある場合のインストール・プロセスは、次の項で説明します。

• 複数リリースを有効にするインストール

注意:

(インストール時にルートに接続されていない) PDBに直接インストールする場合の詳細は、「コマンドライン・プロンプトを使用した拡張インストール」を参照してください。

Oracle REST Data ServicesのCDBインストールのインストール前タスク

• PDBが読取り/書込みモードでオープン(マウント済またはクローズ済ではない)であることを確認します(PDB$SEED以外。これは読取り専用モードのままです)。詳細は、『Oracle Multitenant管理者ガイド』を参照してください

• デフォルトの表領域および一時表領域がORDS_METADATAスキーマによって使用され、ORDS_PUBLIC_USERユーザーが存在し、表領域名がわかっていることを確認します。インストール・プロシージャはそれらのユーザーを作成しますが、表領域は作成しません。

注意:

ORDS_METADATAおよびORDS_PUBLIC_USERがシード・コンテナにインストールされ、デフォルトの表領域および一時表領域がPDB$SEEDに存在します。これらの表領域がまだ存在していない場合、PDB$SEEDに表領域を作成する必要があります。詳細は、『Oracle Multitenant管理者ガイド』を参照してください

2.2.1.1 複数リリースを有効にするインストール

この項では、マルチテナント環境でOracle REST Data Servicesおよびパッチ・セットの複数リリースをPDBで使用している場合のインストール・プロセスについて説明します。

Oracle REST Data ServicesをCDBにインストールすると、プロキシ・ユーザーのOracle REST Data Servicesパブリック・ユーザー(ORDS_PUBLIC_USER)がルート・コンテナにインストールされ、共通ユーザーになります。ORDS_METADATAスキーマは、Oracle REST Data Servicesのメタデータを含むローカル・ユーザーです。ORDS_METADATAスキーマおよびORDS_PUBLIC_USERの両方がシード・コンテナ(PDB$SEED)およびすべてのプラガブル・データベースにインストールされます。

ORDS_METADATAはローカル・ユーザーとしてインストールされているため、プラガブル・データベースに複数のOracle REST Data Servicesリリースをインストールする柔軟性が提供されます。

2.2.1.1.1 コマンドラインからのインストール

インストールを実行するには、ルート(CDB$ROOT)コンテナでSYS AS SYSDBA資格証明を指定する必要があります。

2.2.1.1.2 拡張インストール

この項では、Oracle REST Data ServicesをCDBにインストールして複数のOracle REST Data Servicesリリースを有効にするための拡張インストール・プロンプトについて説明します。

Oracle REST Data ServicesをCDBにインストールして複数のOracle REST Data Servicesのリリースを有効にするには、次のステップを実行します。

1. Oracle REST Data Servicesのインストール・キットを解凍したフォルダに移動します。

2. 次のコマンドを入力します。

   java -jar ords.war install advanced

3. プロンプト表示されたら、CDBのデータベース接続情報を入力します。

   Enter the name of the database server[localhost]:
   Enter the database listen port [1521]:
   Enter 1 to specify the database service name, or 2 to specify the database SID [1]:
   Enter the database service name:(for example, cdb.example.com)

4. Oracle REST Data Servicesのインストールを検証します。

   Enter 1 if you want to verify/install Oracle REST Data Services schema or 2 to skip this step [1]:

5. 受け入れるか、1 (デフォルト)を入力して、CDBとそのPDBすべてにOracle REST Data Servicesをインストールします。

   Enter the database password for ORDS_PUBLIC_USER:
   Confirm password:
   Requires to login with administrator privileges to verify Oracle REST Data Services schema.
   
   Enter the administrator username: SYS
   Enter the database password for SYS AS SYSDBA:
   Confirm password:

   Retrieving information....
   Your database connection is to a CDB.  ORDS common user ORDS_PUBLIC_USER will be
   created in the CDB.  ORDS schema will be installed in the PDBs.
   Root CDB$ROOT - create ORDS common user
   PDB PDB$SEED - install ORDS 18.2.0.<JulianDay.Time> (mode is READ ONLY, open for 
   READ/WRITE)
   PDB PDBName1 - install ORDS 18.2.0.<JulianDay.Time>
   PDB PDBName2 - install ORDS 18.2.0.<JulianDay.Time>
   

   Enter 1 if you want to install ORDS or 2 to skip this step [1]:

6. [Enter]を押してインストールを続行します。

7. 入力を求めるメッセージが表示されたら、必要に応じて追加情報を入力します。詳細は、「コマンドライン・プロンプトを使用した拡張インストール」を参照してください。

注意:

プラガブル・マッピング機能を使用するための詳細は、「Oracle REST Data Servicesによって、すべてのPDBをアドレス可能にする(プラガブル・マッピング)」を参照してください。

2.2.1.1.3 サイレント・インストール

サイレント・インストールでは、Oracle REST Data Servicesのパラメータ・ファイルからプロパティが読み込まれます。

サイレント・インストールを実行するには、次のコマンドを入力します。

java –jar ords.war install simple
java –jar ords.war

2.2.2 CDB環境でのOracle REST Data Servicesのアップグレード

Oracle REST Data Servicesの新しいリリースを使用する場合、簡易または詳細インストールを実行すると、CDBおよびそのプラガブル・データベース(PDB)でのOracle REST Data Servicesのスキーマのアップグレードが自動的に発生します。

次に例を示します。

java -jar ords.war

Oracle REST Data Servicesがすでにインストールまたはアップグレードされている場合は、メッセージにOracle REST Data Servicesスキーマ・バージョンが表示され、情報の入力を要求されません。

2.2.2.1 CDBで複数リリースを有効にするためのOracle REST Data Servicesの移行

この項では、CDBのOracle REST Data Servicesを移行して複数のリリースを有効にする方法について説明します。

リリース18.2.0以降、CDB$ROOTコンテナにインストールされているOracle REST Data ServicesスキーマおよびORDS_METADATAがある場合、アップグレード中に共通のORDS_METADATAスキーマがローカル・スキーマとしてPDBに移行されます。Oracle Database 12.1.0.2以降のリリースでは、この変更がサポートされます。

2.2.3 Oracle REST Data Servicesによって、すべてのPDBをアドレス可能にする(プラガブル・マッピング)

プラガブル・マッピングは、CDB内のすべてのPDBをOracle REST Data Servicesによってアドレス可能にする機能を示します。この機能を使用するには、この項の指示に従ってください。

Oracle REST Data Services構成ファイルにdb.serviceNameSuffixパラメータが含まれている場合、これはOracle REST Data ServicesプールがCDBを指し、そのCDBに接続されているPDBをOracle REST Data Servicesによってアドレス可能にすることを示しています。

db.serviceNameSuffixパラメータの値は、データベースのDB_DOMAINデータベース初期化パラメータの値と一致している必要があり、ピリオド(.)で始まる必要があります。db.serviceNameSuffixパラメータの値を設定するには、次の手順を実行します。

1. SQL*Plusで、SYSDBA権限を持つユーザーとしてルートに接続します。

2. DB_DOMAINデータベース初期化パラメータの値を確認します。

   SQL> show parameter DB_DOMAIN
   

3. SQL*Plusを終了します。

   SQL> exit
   

4. DB_DOMAIN値が空ではない場合、コマンドラインでdb.serviceNameSuffixパラメータのキーと値およびそのDB_DOMAINを作成するコマンドを入力します。これは、このエントリをOracle REST Data Servicesの構成ファイルに追加するために使用されます。

   echo db.serviceNameSuffix=.value-of-DB_DOMAIN > snsuffix.properties
   

   たとえば、DB_DOMAINがexample.comに設定されている場合、次を入力します。

   echo db.serviceNameSuffix=.example.com > snsuffix.properties
   

5. db.serviceNameSuffixパラメータ値が定義されていない場合、次の形式でコマンドを入力して構成ファイルにエントリを追加します。

   java -jar ords.war set-properties --conf pool-name snsuffix.properties
   

   ここで、pool-nameは次のいずれかになります。

   • PL/SQLゲートウェイ構成のpoolName

   • Oracle REST Data Services RESTful Services構成のpoolName_pu

   • Application Express RESTfulサービス構成のpoolName_rt

   例1: CDBのPDBをグローバルでアドレス可能にします。次のコマンドを入力してdefaultsを指定します。

   java -jar ords.war set-properties --conf defaults snsuffix.properties

   注意:

   ほとんどのユース・ケースでは、例1で示した方法(すべてのプールのプロパティをdefaults.xmlファイルを使用して設定)が最も適しています。

   例2: CDBのPDBをPL/SQLゲートウェイにアドレス可能にし、プール名をapexにします。次のコマンドを入力します。

   java -jar ords.war set-properties --conf apex snsuffix.properties
   

   たとえば、apexによって指定されているデータベースにexample.comのDB_DOMAIN値があり、2つのPDB(pdb1.example.comおよびpdb2.example.com)がある場合、最初のPDBはパスが/ords/pdb1/で始まるURLにマップされ、2番目のPDBはパスが/ords/pdb2/で始まるURLにマップされます。

   例3: CDBのPDBをOracle REST Data Services RESTfulサービスにアドレス可能にし、プール名をapex_puにします。次のコマンドを入力します。

   java -jar ords.war set-properties --conf apex_pu snsuffix.properties
   

   例4: CDBのPDBをApplication Express RESTfulサービスにアドレス可能にし、プール名をapex_rtにします。次のコマンドを入力します。

   java -jar ords.war set-properties --conf apex_rt snsuffix.properties

2.2.4 CDB環境でのOracle REST Data Servicesのアンインストール

Oracle REST Data ServicesをCDBからアンインストールするには、uninstallコマンドを使用します。

次に例を示します。

java -jar ords.war uninstall

Oracle REST Data ServicesがCDBとそのプラガブル・データベース(PDB)から削除されます。

2.3 Oracle RAC Fast Connection Failoverのサポート

Oracle REST Data Servicesは、Oracle Real Application Clusters (Oracle RAC)のFast Connection Failover (FCF)機能をサポートします。

Oracle REST Data Servicesは、WebLogic、Tomcatなど、サポートするすべてのApplication Server環境でUniversal Connection Pool (UCP)とともに実行されます。また、UCPはFast Connection Failoverをサポートします。FCFを有効化するには、Oracle Notification Service (ONS)が有効化されている必要があります。ONSを有効化するには、次のコード・スニペットに示すように、Oracle REST Data Services defaults.xml構成ファイルにあるプロパティのリストにエントリを追加します。

<entry key="jdbc.enableONS">true</entry>
<entry key= "jdbc.ONSConfig">nodes=racnode1:4200,racnode2:4200\nwalletfile=/oracle11/onswalletfile</entry>

ONSは、Fast Application Notification (FAN)イベントを送信するために使用されるメッセージング機能です。ONSが有効化されている場合、Oracle REST Data Servicesでは、FCFが自動的に有効になります。フェイル・オーバーや、ロード・バランシングなどのその他の高度なFCF機能など、特定のFCF機能を有効化するには、次のコード・スニペットに示すようにカスタム接続に対応するエントリを構成ファイルに追加する必要があります。

<entry key="db.connectionType">customurl</entry>
<entry key="db.customURL">jdbc:oracle:thin:@(DESCRIPTION=(FAILOVER=ON)(ADDRESS_LIST=
		(LOAD_BALANCE=ON)(ADDRESS=(PROTOCOL=TCP)(HOST=prod_scan.example.com)(PORT=1521)))
		(CONNECT_DATA=(SERVICE_NAME=ISPRD)))|</entry>

defaults.xml構成ファイルを更新した後、Oracle REST Data Servicesを再起動するまで変更は有効になりません。

UCPはFast Connection Failoverをサポートします。FCFは、FANイベントをリッスンし、それに応答することで次の2つのシナリオに対応します。

• 計画外の停止: RACはインスタンス障害を検出するとFAN Downイベントを生成し、それをFCFが捕捉します。 FCFは失敗したインスタンスへのすべての接続を終了し、それ以降のすべてのリクエストを、残っているRACインスタンスに送ります。

• 計画的な停止: たとえば、データベース管理者(DBA)が、一部のメンテナンス・アクティビティを実行するためにRACインスタンスを正常にシャットダウンすることがあります。インスタンス・シャットダウンはFAN Planned Downイベントを生成し、それをFCFが捕捉します。 続いてFCFはすべての新しいリクエストを他のRACインスタンスに送り、現在アクティブなトランザクションを排出するか完了させます。

注意:

長い間実行されているトランザクションは、強制終了が必要な場合があります。

2.4 セキュリティ、キャッシュ、前処理と後処理、環境、およびExcel設定の構成

セキュリティ、キャッシュ、前処理と後処理、環境およびExcel設定の構成は、「SQL Developerを使用したOracle REST Data Servicesの管理(オプション)」を参照してください。

2.5 REST対応SQLサービス設定の構成

この項では、REST対応SQLサービスを構成する方法について説明します。

注意:

REST対応SQLサービスを有効にすると、Oracle RESTデータ・サービス対応のデータベース・スキーマに対する認証が有効になります。これにより、データベース・パスワードを使用して、データベース・スキーマがHTTPS経由でアクセス可能になります。Oracleでは、強力かつ安全なデータベース・パスワードを指定することをお薦めします

REST対応SQLサービスは、Oracle RESTデータ・サービスの機能の1つです。デフォルトでは、REST対応SQLサービスがオフになっています。REST対応SQLサービスおよびREST対応SQLエクスポート・サービスを有効にするには、次のステップを実行します。

1. Oracle REST Data Servicesの構成ファイルが保存されているフォルダを検索します。

2. defaults.xmlファイルを開き、<entry key="restEnabledSql.active">true</entry>を追加します。

3. ファイルを保存します。

4. Oracle REST Data Servicesを再起動します。

2.6 問合せから戻される行の最大数の構成

問合せから戻される行の最大数を構成するには、次のステップを実行します。

1. Oracle REST Data Servicesの構成ファイルが保存されているフォルダを検索します。

2. defaults.xmlファイルを開き、misc.pagination.maxRowsパラメータの値を次のように更新します。<entry key="misc.pagination.maxRows">1500</entry>

   注意:

   misc.pagination.maxRowsのデフォルト値は500です。

3. ファイルを保存します。

4. Oracle REST Data Servicesを再起動します。

2.7 カスタム・エラー・ページの構成

この項では、Oracle REST Data Servicesにより生成されたエラー・ページではなく、カスタム・エラー・ページを構成する方法について説明します。

カスタム・エラー・ページを構成するには、次のステップを実行します。

1. Oracle REST Data Servicesの構成ファイルが保存されているフォルダを検索します。

2. defaults.xmlファイルを開き、error.externalPathパラメータの値を更新します。

   <entry key="error.externalPath">/path/to/error/pages/folder/</entry>

   説明:

   • /path/to/error/pages/folderは、エラー・ページを定義するファイルが格納されているフォルダのパスです。ファイルは、{status}.html形式で格納されます。

     ここで、{status}は、カスタム・エラー・ページを作成するHTTPステータス・コードです。

3. ファイルを保存します。

4. Oracle REST Data Servicesを再起動します。

例2-1 HTTP 404ステータス・コードのカスタム・エラー・ページの構成

「HTTP 404 – Not Found」ステータスのカスタム・エラー・ページを構成するには、次のステップを実行します。

1. 404.htmlという名前のファイルを作成します。

2. /usr/local/share/ords/error-pages/フォルダに保存します。

3. /usr/local/share/ords/errro-pages/フォルダを指すように、error.externalPathパラメータを構成します。

4. ファイルを保存します。

5. Oracle REST Data Servicesを再起動します。

2.8 Oracle REST Data Servicesで使用するRESTfulサービスの開発

Oracle REST Data Servicesで使用するRESTfulサービスを開発する方法の詳細は、「Oracle REST Data Servicesアプリケーションの開発」を参照してください。