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 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.3 セキュリティ、キャッシュ、前処理と後処理、環境、およびExcel設定の構成
セキュリティ、キャッシュ、前処理と後処理、環境およびExcel設定の構成は、「SQL Developerを使用したOracle REST Data Servicesの管理(オプション)」を参照してください。
2.4 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.5 問合せから戻される行の最大数の構成
-
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.6 ウィルス・スキャン用のICAPサーバー統合の構成
この項では、ウイルス・スキャン用にICAPサーバーと統合するようにORDSを構成する方法について説明します。
ORDS PL/SQLゲートウェイでは、ファイル・アップロード時に、Internet Content Adaptation Protocol (ICAP)準拠のウイルス・スキャン・サーバーにウイルス・スキャンの職責を任せることができます。ウィルス・スキャン・サーバーのホスト名とポートは、icap.server
、icap.port
およびicap.secure.port
グローバル構成プロパティで指定します。
APEXではORDS PL/SQLゲートウェイが使用されます。このICAP統合は、構成すると、APEXでのファイル・アップロードにも適用されます。
-
Oracle REST Data Servicesの構成ファイルが保存されているフォルダを検索します。
-
defaults.xml
ファイルを開いて、次のエントリを追加します。<entry key="icap.port">1234</entry> <entry key="icap.server">name_or_ip</entry>
-
ファイルを保存します。
Oracle REST Data Servicesを再起動します。
- ICAPバージョン1.0
- AVSCANという名前のウイルス対策サービス
- action=SCANに対応しているウイルス対策サービス
- 4バイト以上のプレビュー
- X-Infectionという名前のヘッダーを返す
RESPMOD icap://<icap_server>:<icap_port>/AVSCAN?action=SCAN ICAP/1.0
Host: <icap_server>:<icap_port>
Preview: 4
Allow: 204
Encapsulated: req-hdr=0 res-hdr=153 res-body=200
2.7 Kerberos設定を使用したORDSの構成
この項では、ORDSをKerberosファイルベースのチケット・キャッシュを参照し、ORDS実行権限を持つOracle Database Kerberos認証済ユーザーに接続するように構成する方法について説明します。
- 外部認証を使用した新規ユーザーの作成
- 環境変数の設定
- 有効なチケットの指定
- ORDSプール設定の追加
2.7.1 コマンドライン・インタフェースを使用したKerberos設定によるORDSの構成
この項では、Kerberos設定でORDSを構成する方法について説明します。ORDSは、Kerberosファイルベースのチケット・キャッシュを参照し、コマンドライン・インタフェースを使用してOracle Database Kerberos認証済ユーザーに接続するように構成できます。
次のコマンドを使用して、Kerberos設定でORDSを構成します。
java -jar ords.war configdir configkrb
java -jar ords.war setup
java -jar ords.war set-property --conf apex_pu oracle.net.authentication_services "(KERBEROS5)"
java -jar ords.war set-property --conf apex_pu oracle.net.kerberos5_mutual_authentication true
export KRB5_CONFIG=<path to krb5.conf>
export KRB5CCNAME=<path to credential cache>
kinit <principal>
2.8 カスタム・エラー・ページの構成
この項では、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.9 ORDSメタデータ・キャッシュの構成
この項では、ORDSメタデータ・キャッシュの構成方法について説明します。
RESTサービスの数が増加するにつれて、対応するメタデータのデータベースを問い合せるオーバーヘッドが、サービス・パフォーマンスおよびスループット全体に悪影響を与える可能性があります。時間の経過とともに、ORDS_METADATA
ビューの問合せの完了に時間がかかるようになります。これらの問合せは、リクエストごとに実行されます。ORDSメタデータ・キャッシュは、ORDS_METADATA
ビューの問合せが各リクエストにとって高負荷になる程度までサービス数が増加したときに、RESTサービスの全体的なレスポンス時間を改善するのに役立ちます。ORDSメタデータ・キャッシュでは、権限およびモジュール・メタデータのコピーをメモリーに一時的に保持して、RESTサービス・リクエストの受信時に実行されるデータベース問合せの数を減らすことができます。メタデータに対する変更が後続のリクエストにすぐに適用されるように、キャッシュはデフォルトで無効になっています。
表2-1 ORDSメタデータ・キャッシュの構成プロパティ
プロパティ | データ型 | デフォルト値 | 説明 |
---|---|---|---|
cache.metadata.enabled |
ブール値 | false |
メタデータ・キャッシュを有効または無効にする設定を指定します。 |
cache.metadata.timeout |
期間 | 30s |
メタデータ・レコードがキャッシュに残る期間を決定するための設定を指定します。期間が長いほど、適用された変更の表示に時間がかかります。 |
2.10 Oracle REST Data Servicesで使用するRESTfulサービスの開発
Oracle REST Data Servicesで使用するRESTfulサービスを開発する方法の詳細は、「Oracle REST Data Servicesアプリケーションの開発」を参照してください。
2.11 ORDS管理者権限の管理
ORDS_ADMIN
PL/SQLパッケージへのアクセス権は、ORDS_ADMINISTRATOR_ROLE
を介してプロビジョニングします。ORDS_ADMIN
パッケージを介してこのロールをプロビジョニングして、追加のORDS管理者を作成できます。
2.11.1 ユーザーへのORDS_ADMINISTRATOR_ROLEのプロビジョニング
この項では、ORDS_ADMINISTRATOR_ROLE
ロールをユーザーにプロビジョニングする方法について説明します。
データベースのGRANT
コマンドまたはORDS_ADMIN.PROVISION_ADMIN_ROLE
PL/SQLメソッド(ORDS管理者)を使用して、ORDS_ADMINISTRATOR_ROLE
ロールをユーザーにプロビジョニングできます。
例2-2 Grantコマンドの使用
GRANT ORDS_ADMINISTRATOR_ROLE TO HR_ADMIN;
例2-3 ORDS_ADMINパッケージ・メソッドの使用
BEGIN
ORDS_ADMIN.PROVISION_ADMIN_ROLE(
p_user => 'HR_ADMIN');
END;
/
2.11.2 ユーザーからのORDS_ADMINISTRATOR_ROLEのプロビジョニング解除
この項では、ORDS_ADMINISTRATOR_ROLE
をユーザーからプロビジョニング解除する方法について説明します。
ORDS管理者は、データベースのREVOKE
コマンドまたはORDS_ADMIN.UNPROVISION_ROLES
PL/SQLメソッドを使用して、ORDS_ADMINISTRATOR_ROLE
をユーザーからプロビジョニング解除できます。
例2-4 REVOKEコマンドの使用
REVOKE ORDS_ADMINSTRATOR_ROLE FROM HR_ADMIN;
例2-5 ORDS_ADMINパッケージ・メソッドの使用
BEGIN
ORDS_ADMIN.UNPROVISION_ROLES(
p_user => 'HR_ADMIN',
p_administrator_role => TRUE);
END;
/
2.12 ORDS実行権限の管理
ORDS_RUNTIME_ROLE
データベース・ロールを使用すると、ユーザーはランタイム・ユーザーとして機能できます。ランタイム・ユーザーはORDSサービス・インスタンスで必要なランタイム接続リソースを管理および構成できます。ORDS_PUBLIC_USER
は、そのようなデータベース・ユーザーの1つです。追加のランタイム・ユーザーがプロビジョニングされると、異なる宛先アドレスと接続プールを持つが同じOracleデータベース・コンテナでホストされる、個別のORDSサービス・インスタンスを構成できます。
ランタイム・ユーザーには他のユーザーへのプロキシに必要な権限が累積されるため、他の目的で再利用しないことをお薦めします。ランタイム・ユーザーには、ORDS_RUNTIME_ROLE
ロールに加えてCREATE SESSION
権限のみが必要です。
2.12.1 ユーザーへのORDS_RUNTIME_ROLEのプロビジョニング
この項では、ORDS_RUNTIME_ROLE
ロールをユーザーにプロビジョニングする方法について説明します。
ORDS管理者は、データベースのGRANT
コマンドまたはORDS_ADMIN.PROVISION_ADMIN_ROLE
PL/SQLメソッドを使用して、ORDS_RUNTIME_ROLE
ロールをユーザーにプロビジョニングできます。
例2-6 Grantコマンドの使用
GRANT ORDS_RUNTIME_ROLE TO ORDS_PUBLIC_USER_2;
例2-7 ORDS_ADMINパッケージ・メソッドの使用
BEGIN
ORDS_ADMIN.PROVISION_RUNTIME_ROLE(
p_user => 'ORDS_PUBLIC_USER_2');
END;
/
2.12.2 ユーザーからのORDS_RUNTIME_ROLEのプロビジョニング解除
この項では、ORDS_RUNTIME_ROLE
ロールをユーザーからプロビジョニングを解除する方法について説明します
管理者は、データベースのREVOKE
コマンドまたはORDS_ADMIN.UNPROVISION_ROLES
PL/SQLメソッドを使用して、ORDS_RUNTIME_ROLE
をユーザーからプロビジョニング解除できます。
例2-8 REVOKEコマンドの使用
REVOKE ORDS_RUNTIME_ROLE FROM ORDS_RUNTIME_USER_2;
例2-9 ORDS_ADMINパッケージ・メソッドの使用
BEGIN
ORDS_ADMIN.UNPROVISION_ROLES(
p_user => 'ORDS_RUNTIME_USER_2',
p_runtime_role => TRUE);
END;
/