2 Oracle REST Data Servicesの構成(詳細)
この項では、リクエストをルーティングして複数のデータベースに接続するようにOracle REST Data Servicesを構成する方法を説明し、その他の構成情報については、その他のドキュメント・ソースを参照します。
注意:
Oracle REST Data Servicesは、構成の変更を行った後に再起動する必要があります。アプリケーションを再起動する方法はアプリケーション・サーバーのマニュアルを参照してください。
トピック:
2.1 複数データベースの構成
Oracle REST Data Servicesでは、複数のデータベースに接続する機能がサポートされています。この項では、リクエストを適切なデータベースにルーティングするための異なる戦略を説明します。
トピック:
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つのステップを行います。
-
データベース接続情報の構成
-
どのリクエストをどのデータベースにルーティングするかの構成
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をマルチテナント・コンテナ・データベースへインストール、構成、アップグレードおよびアンインストールする概要を示します。
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.2 拡張インストール
この項では、Oracle REST Data ServicesをCDBにインストールして複数のOracle REST Data Servicesリリースを有効にするための拡張インストール・プロンプトについて説明します。
-
Oracle REST Data Servicesのインストール・キットを解凍したフォルダに移動します。
-
次のコマンドを入力します。
java -jar ords.war install advanced
-
プロンプト表示されたら、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)
-
Oracle REST Data Servicesのインストールを検証します。
Enter 1 if you want to verify/install Oracle REST Data Services schema or 2 to skip this step [1]:
-
受け入れるか、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]:
-
[Enter]を押してインストールを続行します。
-
入力を求めるメッセージが表示されたら、必要に応じて追加情報を入力します。詳細は、「コマンドライン・プロンプトを使用した拡張インストール」を参照してください。
注意:
プラガブル・マッピング機能を使用するための詳細は、「Oracle REST Data Servicesによって、すべてのPDBをアドレス可能にする(プラガブル・マッピング)」を参照してください。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
パラメータの値を設定するには、次の手順を実行します。
-
SQL*Plusで、SYSDBA権限を持つユーザーとしてルートに接続します。
-
DB_DOMAIN
データベース初期化パラメータの値を確認します。SQL> show parameter DB_DOMAIN
-
SQL*Plusを終了します。
SQL> exit
-
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
-
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.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>
<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を再起動するまで変更は有効になりません。
-
計画外の停止: 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では、強力かつ安全なデータベース・パスワードを指定することをお薦めします-
Oracle REST Data Servicesの構成ファイルが保存されているフォルダを検索します。
-
defaults.xml
ファイルを開き、<entry key="restEnabledSql.active">true</entry>
を追加します。 -
ファイルを保存します。
-
Oracle REST Data Servicesを再起動します。
2.6 問合せから戻される行の最大数の構成
-
Oracle REST Data Servicesの構成ファイルが保存されているフォルダを検索します。
-
defaults.xml
ファイルを開き、misc.pagination.maxRows
パラメータの値を次のように更新します。<entry key="misc.pagination.maxRows">1500</entry>
注意:
misc.pagination.maxRows
のデフォルト値は500です。 -
ファイルを保存します。
-
Oracle REST Data Servicesを再起動します。
2.7 カスタム・エラー・ページの構成
この項では、Oracle REST Data Servicesにより生成されたエラー・ページではなく、カスタム・エラー・ページを構成する方法について説明します。
カスタム・エラー・ページを構成するには、次のステップを実行します。
-
Oracle REST Data Servicesの構成ファイルが保存されているフォルダを検索します。
-
defaults.xml
ファイルを開き、error.externalPath
パラメータの値を更新します。<entry key="error.externalPath">/path/to/error/pages/folder/</entry>
説明:
-
/path/to/error/pages/folder
は、エラー・ページを定義するファイルが格納されているフォルダのパスです。ファイルは、{status}.html
形式で格納されます。ここで、
{status}
は、カスタム・エラー・ページを作成するHTTPステータス・コードです。
-
-
ファイルを保存します。
-
Oracle REST Data Servicesを再起動します。
例2-1 HTTP 404ステータス・コードのカスタム・エラー・ページの構成
「HTTP 404 – Not Found」ステータスのカスタム・エラー・ページを構成するには、次のステップを実行します。
-
404.html
という名前のファイルを作成します。 -
/usr/local/share/ords/error-pages/
フォルダに保存します。 -
/usr/local/share/ords/errro-pages/
フォルダを指すように、error.externalPath
パラメータを構成します。 -
ファイルを保存します。
-
Oracle REST Data Servicesを再起動します。
2.8 Oracle REST Data Servicesで使用するRESTfulサービスの開発
Oracle REST Data Servicesで使用するRESTfulサービスを開発する方法の詳細は、「Oracle REST Data Servicesアプリケーションの開発」を参照してください。