1. インストレーション、構成および開発ガイド
  2. Oracle REST Data Servicesの構成(詳細)

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

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

ノート:

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

トピック:

複数データベースの構成

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

トピック:

リクエスト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. どのリクエストをどのデータベースにルーティングするかの構成

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

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

ヒント:

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

java -jar ords.war help setup

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

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

説明:

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

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

関連トピック

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

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>は、前のステップで設定したデータベース接続の名前です。

関連トピック

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

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.)

リクエスト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>は、データベース接続の名前です。

リクエスト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.)

                  

               

            

            
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インスタンスに送り、現在アクティブなトランザクションを排出するか完了させます。
                           
    
                        
    • 
                     

                  

                  

                     

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

                  

               

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

               

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

               

            

            
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. 
                        
  2. 
                           
    defaults.xmlファイルを開き、<entry key="restEnabledSql.active">true</entry>を追加します。
                           
    
                        
    3. 
                        
  3. 
                           
    ファイルを保存します。 
    
                        
    4. 
                        
  4. 
                           
    Oracle REST Data Servicesを再起動します。
    
                        
    5. 
                     

                  

               

            

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

               

                  

                  
問合せから戻される行の最大数を構成するには、次のステップを実行します。
                     
    
                        
  1. 
                           
    Oracle REST Data Servicesの構成ファイルが保存されているフォルダを検索します。
    
                        
    2. 
                        
  2. 
                           
    defaults.xmlファイルを開き、misc.pagination.maxRowsパラメータの値を次のように更新します。<entry key="misc.pagination.maxRows">1500</entry>
    
                           
    
                              
    ノート:
    misc.pagination.maxRowsのデフォルト値は500です。
                           
    
                        
    3. 
                        
  3. 
                           
    ファイルを保存します。 
    
                        
    4. 
                        
  4. 
                           
    Oracle REST Data Servicesを再起動します。
    
                        
    5. 
                     

                  

               

            

            
ウィルス・スキャン用のICAPサーバー統合の構成

               

                  
この項では、ウイルス・スキャン用にICAPサーバーと統合するようにORDSを構成する方法について説明します。

                  
ORDS PL/SQLゲートウェイでは、ファイル・アップロード時に、Internet Content Adaptation Protocol (ICAP)準拠のウイルス・スキャン・サーバーにウイルス・スキャンの職責を任せることができます。ウィルス・スキャン・サーバーのホスト名とポートは、icap.server、icap.portおよびicap.secure.portグローバル構成プロパティで指定します。
                  

                  
APEXではORDS PL/SQLゲートウェイが使用されます。このICAP統合は、構成すると、APEXでのファイル・アップロードにも適用されます。

                  
ICAPサーバーと統合するようにORDSを構成するには、次のステップを実行します。
                     
    
                        
  1. 
                           
                           
    Oracle REST Data Servicesの構成ファイルが保存されているフォルダを検索します。
    
                           
                        
    2. 
                        
  2. 
                           
                           
    defaults.xmlファイルを開いて、次のエントリを追加します。 
                           
    
                           
                           
    
                              
    <entry key="icap.port">1234</entry>
<entry key="icap.server">name_or_ip</entry>
    
                              
    
                           
                        
    3. 
                        
  3. 
                           
                           
    ファイルを保存します。
    
                           
                           
    Oracle REST Data Servicesを再起動します。
    
                           
                        
    4. 
                     

                  

                  
ICAPサーバーが次の要件に対応している必要があります。
                     
    
                        
  • ICAPバージョン1.0
    • 
                        
  • AVSCANという名前のウイルス対策サービス
    • 
                        
  • action=SCANに対応しているウイルス対策サービス
    • 
                        
  • 4バイト以上のプレビュー
    • 
                        
  • X-Infectionという名前のヘッダーを返す
    • 
                     

                  

                  
構成後、PL/SQL Gatewayを介してファイルがアップロードされると、ORDSによって次のようなリクエストが作成されます。
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

               

            

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

               

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

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

                  
    
                     
  1. 
                        
    Oracle REST Data Servicesの構成ファイルが保存されているフォルダを検索します。
    
                     
    2. 
                     
  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. 
                     
  3. 
                        
    ファイルを保存します。 
    
                     
    4. 
                     
  4. 
                        
    Oracle REST Data Servicesを再起動します。
    
                     
    5. 
                  

                  

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

                  

                  
                  

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

                     
    
                        
  1. 
                           
    404.htmlという名前のファイルを作成します。
                           
    
                        
    2. 
                        
  2. 
                           
    /usr/local/share/ords/error-pages/フォルダに保存します。
                           
    
                        
    3. 
                        
  3. 
                           
    /usr/local/share/ords/errro-pages/フォルダを指すように、error.externalPathパラメータを構成します。
                           
    
                        
    4. 
                        
  4. 
                           
    ファイルを保存します。
    
                        
    5. 
                        
  5. 
                           
    Oracle REST Data Servicesを再起動します。
    
                        
    6. 
                     

                  

                  
               

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

               

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

               

            

            
ORDS管理者権限の管理

               

                  
ORDS_ADMIN PL/SQLパッケージへのアクセス権は、ORDS_ADMINISTRATOR_ROLEを介してプロビジョニングします。ORDS_ADMINパッケージを介してこのロールをプロビジョニングして、追加のORDS管理者を作成できます。
                  

               

               
ユーザーへの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;
/

                        

                     
                  

               

               
ユーザーからの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;
 /

                        

                     
                  

               

            

            
ORDS実行権限の管理

               

                  
ORDS_RUNTIME_ROLEデータベース・ロールを使用すると、ユーザーはランタイム・ユーザーとして機能できます。ランタイム・ユーザーはORDSサービス・インスタンスで必要なランタイム接続リソースを管理および構成できます。ORDS_PUBLIC_USERは、そのようなデータベース・ユーザーの1つです。追加のランタイム・ユーザーがプロビジョニングされると、異なる宛先アドレスと接続プールを持つが同じOracleデータベース・コンテナでホストされる、個別のORDSサービス・インスタンスを構成できます。
                  

                  
ランタイム・ユーザーには他のユーザーへのプロキシに必要な権限が累積されるため、他の目的で再利用しないことをお薦めします。ランタイム・ユーザーには、ORDS_RUNTIME_ROLEロールに加えてCREATE SESSION権限のみが必要です。
                  

               

               
ユーザーへの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;
/

                        

                     
                  

               

               
ユーザーからの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;
 /