3 複数のデータベースに対するOracle REST Data Servicesの構成
Oracle REST Data Servicesでは、複数のデータベースに接続する機能がサポートされています。この項では、リクエストを適切なデータベースにルーティングするための異なる戦略を説明します。
3.1 ローカル構成を使用したORDSのデプロイ
デフォルトでは、ORDS構成はORDS構成ディレクトリ・ファイル内で保持されます。これらのファイルは、ords configコマンドライン・コマンドを使用して管理するのが最良であり、手動で変更できます。
3.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つのステップを行います。
-
データベース接続情報の構成
-
どのリクエストをどのデータベースにルーティングするかの構成
3.1.2 追加のデータベースの構成
最初にOracle REST Data Servicesを構成するとき、defaultという名前のデフォルトのデータベース接続を構成します。installコマンドを使用して追加のデータベース接続を作成できます。
ヒント:
installコマンドの完全なヘルプを表示するには、次のように入力します。
ords install --help
ords --config <configuration folder> install3.1.3 拡張ルーティング
ノート:
カスタム・マッピングが構成されている場合、データベース・プール名を使用したデフォルト・マッピングは有効になっていません。関連項目:
追加のデータベースの構成3.1.4 リクエスト・パスに基づくルーティング
- ファイル
<ords_config_folder>/databases/<database_name>/pathsを開くか作成します - このデータベースによって提供されるパスを入力します。
pathsファイルの場所の例
ords_conf/
+-- databases/
| +-- db1/
| | +-- wallet/
| | +-- paths
| | +-- pool.xml
| +-- db2/
| +-- wallet/
| +-- paths
| +-- pool.xml
+-- globals/ords_conf/databases/db1/pathssalesords_conf/databases/db2/pathsords_conf/databases/db2/pathssupport
/finance/department1前述のルールは、次のすべてのリクエストと一致します。
http://example.com/ords/sales --> db1
http://example.com/ords/sales/leads --> db1
https://www.example.com/ords/sales/forecasting.report?month=jan --> db1 (If www.example.com resolves to the same system as example.com.)
http://example.com/ords/support --> db2
http://example.com/ords/finance/department1 --> db23.1.5 リクエスト・ホスト名に基づくルーティング
hostnamesファイルを使用して、ホスト名に基づいたリクエスト・ルーティング・ルールを作成できます。これを行うには、次のステップを実行します:
- ファイル
<ords_config_folder>/databases/<database_name>/hostnamesを開くか作成します。 - このデータベースによって提供されるホスト名を追加します。
ords_conf/
+-- databases/
| +-- db1/
| | +-- wallet/
| | +-- hostnames
| | +-- pool.xml
| +-- db2/
| +-- wallet/
| +-- hostnames
| +-- pool.xml
+-- globals/例: ords_conf/databases/db1/hostnames
www.example.com
example.orgords_conf/databases/db2/hostnamesfoo.bar.com前述のルールは、次のようにリクエストを対応するデータベース接続に一致させます。
http://www.example.com/ords/ --> db1
http://example.org:8080/ords/f?p=1:1 --> db1
https://foo.bar.com/ords/myschema/resource --> db2前述のルールは、次のリクエストに一致しません。
http://example.com/ords/ (The hostname is missing the www.)
http://foo.bar.net/ords/myschema/resource --> db2 (hostname is different3.2 中央構成サーバーを使用したORDSのデプロイ
この項では、中央構成サーバーを使用してORDSをデプロイする方法について説明します。
概要
デフォルトでは、Oracle REST Data Services (ORDS)構成は、ローカルの、ORDS構成ディレクトリ内のglobal/settings.xmlやdatabases/default/pool.xmlなどのファイル内にあります。または、ORDSで、中央構成サーバーAPIと呼ばれるREST APIからその構成を取得できます。
- 中央に管理されている構成では、ORDS構成の更新、管理および保護を1箇所で実行するようになります。
- ORDSプールは必要に応じて動的にロードされます。これは、ORDSの起動時間を短くするために役立ちます。
- グローバル構成リソース
- プール構成リソース
通常、中央構成サーバーは、複数のORDSノードまたはデータベース・プール構成を管理しているときのみ必要です。
前提条件
- 指定された中央構成サーバーAPIを実装するセキュアなREST API
- ORDSのグローバルおよびデータベース・プール情報がOpenAPI仕様で定義されている
- OAuth2.0認可サーバー(アクセス・トークンを発行するため)
- セキュアな中央構成へのアクセスのための資格証明を格納するOracleウォレットを作成できる
関連項目:
ORDS中央構成OpenAPI3.2.2 データベース・マッピング
ORDSが中央構成を使用してデプロイされているときは、最初にグローバル構成設定のみが取得されます。適切なプール構成は、データベース接続が必要なORDSに対してリクエストが発行された後にのみ、後続のリクエストで取得されキャッシュされます。グローバル構成リソースにより、プール構成リソース用にsearchのHREFテンプレートが提供されます。ORDSにより、このテンプレートを使用してそのプール構成がリクエストされます。searchのHREFはテンプレート化されています。つまり、{host}文字列は、特定のプールを識別する値に置き換えられます。
{host}文字列を置換して適切なプール構成を指定するには、次の2つの方法のどちらかを使用します:
- リクエスト・ホストによる方法
- ヘッダーによる方法
3.2.2.1 リクエスト・ホストによる方法
リクエスト・ホストによる方法は、searchのhrefにある{host}文字列を置き換えるための、デフォルトの方法です。ORDSリクエストのホストが使用されます。
この方法は、使用するプール構成の特定にORDSサービスのサブ・ドメインを使用できる場合に役立ちます。
例
href="https://central-config.example.com:8585/central/v1/config/pool/{host}"GET: https://mydatabase.servername.com/ords/hr/employees/mydatabase.servername.comはリクエスト・ホストです。
https://central-config.example.com:8585/central/v1/config/pool/mydatabase.servername.com3.2.2.2 ヘッダーによる方法
適切なプールを示すためにサブ・ドメインを使用できない場合は、リクエスト・ヘッダーを使用できます。security.externalHostMappingHeader設定を使用して、グローバル構成で、使用するヘッダーを指定します。
例
グローバル構成:
href="https://central-config.example.com:8585/central/v1/config/pool/{host}"GET: -Header "poolname: mydatabase" https://www.servername.com/ords/hr/employees/https://central-config.example.com:8585/central/v1/config/pool/mydatabase3.2.3 グローバル構成設定
- JSON形式である必要があります
- グローバル設定が
settingsオブジェクトで定義されている必要があります。 - プール構成リソースを示すために、末尾が
{host}テンプレート・パラメータである関連するSearchリンクが含まれています。
ORDSグローバル設定のレスポンスの例
{
"settings": {
"restEnabledSql.active": true,
"feature.sdw": true,
"security.externalHostMappingHeader": "poolname"
},
"links": [
[
{
"rel": "collection",
"href": "https://central-config.example.com:8585/central/v1/config/"
},
{
"rel": "self",
"href": "https://central-config.example.com:8585/central/v1/config/"
},
{
"rel": "search",
"href": "https://central-config.example.com:8585/central/v1/config/pool/{host}",
"templated": true
}
]
]
}3.2.4 データベース・プール構成設定
- JSON形式である必要があります
database.pool.settingsオブジェクトで定義されているプール設定。- Oracle Autonomous Databaseのデータベース・プールを構成するときは、プール構成ファイルに、その
db.wallet.zip構成プロパティの内容がBase64でエンコードされて含まれている必要があります
例3-1 db.wallet.zip
ADB-Sインスタンス・ウォレットのbase64表現を提供するdb.wallet.zipファイルを使用したプール構成レスポンスの例。
ノート:
db.usernameとdb.passwordをsettingsとして指定できます。ただし、ADB-Sインスタンス・ウォレットをbase64に変換する前にそれに資格証明を含めることをお薦めします。
{
"database": {
"pool": {
"name": "mydatabase",
"settings": {
"db.wallet.zip.service":"mydb_low",
"db.wallet.zip": "UEsDBBQACAgIAOMid1IAAAAAAAAAAAAAAAALAAAAY3dhbGxldC5zc28BdRuH4TjA...",
"feature.sdw": true,
"plsql.gateway.mode": "proxied",
"restEnabledSql.active": true
}
}
}
}例3-2 db.customURL
プール接続の詳細を示すdb.customURLを使用したプール構成レスポンスの例。
{
"database": {
"pool": {
"name": "mydatabase",
"settings": {
"db.username" : "ORDS_PUBLIC_USER",
"db.password" : "ORDS PUBLIC USER PASSWORD",
"db.connectionType" : "customurl",
"db.customURL" : "jdbc:oracle:thin:@(description=(retry_count=3)(address_list=(load_balance=on)
(address=(protocol=tcp)(host=adb.ap-sydney-1.oraclecloud.com)(port=1521)))
(connect_data=(service_name=database_pool_1_high.adb.oraclecloud.com)))",
"feature.sdw": true,
"plsql.gateway.mode": "proxied",
"restEnabledSql.active": true
}
}
}
}3.2.4.1 eTagの使用
プール構成のレスポンスには、eTagを含める必要があります。ORDSでは、プール構成に対する変更を識別するために、eTagが使用されます。eTagが変更されていない場合は、ORDSによりプールの構成設定がリフレッシュされません。
3.2.4.2 インスタンス・ウォレットへの資格証明の追加
この項では、インスタンス・ウォレットに資格証明を追加する方法について説明します。
ORDSランタイム・ユーザー用のデータベース資格証明の追加は、settingsのdb.usernameとdb.passwordを使用して指定できます。ただし、それらの資格証明をADB-Sインスタンス・ウォレットに含めてからそのdb.wallet.zip設定を使用してbase64形式で提供する方法をお薦めします。
次のコマンドを使用して、ORDSランタイム・ユーザーの資格証明を含めることができます。プロンプトが表示されたら、インスタンス・ウォレットのパスワードを指定します。
mkstore -wrl <path to the instance wallet> -createCredential <servicename> <ORDS Runtime user name>
<ORDS Runtime user password>3.2.5 セキュリティ
中央構成APIは、Basic認証またはOAuth2を使用して保護できます。アクセス・トークンの取得やBasic認証リクエストの発行に必要な資格証明とその他の情報は、ORDS資格証明ウォレットを使用して提供されます。
- リソース所有者のパスワード資格証明による権限付与
- クライアント資格証明による権限付与
mkstoreユーティリティを使用して、ORDS資格証明ウォレットを作成できます。
ノート:
SQLclでは、適切なORDS資格証明ウォレットの作成やインスタンスのADB-Sインスタンス・ウォレットの変更に使用できるmkstoreコマンドが用意されています。
表3-1 ORDS資格証明ウォレットでの格納
| シークレット別名 | シークレット値 | 説明 |
|---|---|---|
oauth:client_credentials_mode:[Server Name] |
次のいずれかの値である必要があります:
|
クライアント資格証明をトークン・リクエストに追加する方法を決定します。
デフォルト値は |
oauth:client_id:[Server Name] |
クライアント・アプリケーションのclient_id
|
grant_type=client_credentialsとともに使用します |
oauth:client_secret:[Server Name] |
クライアント・アプリケーションのクライアント・シークレット | grant_type=client_credentialsの場合に使用します |
oauth:grant_type:[Server Name] |
使用する場合は、次のいずれかである必要があります:
|
oauth:username:[hostname]が含まれている場合、この値はデフォルトでpasswordに設定されます。それ以外の場合、デフォルト値はclient_credentialsです。 |
oauth:password:[Server Name] |
認証が必要なユーザーのpassword
|
grant_type=passwordとともに使用します |
oauth:scope:[Server Name] |
「Access Token Scope」で定義されているアクセス・スコープ仕様に準拠します。 | リクエスト・アクセスのOAuth 2.0スコープ |
oauth:token_endpoint:[Server Name] |
「Token Endpoint」で定義されているアクセス・トークン・エンドポイントの絶対URL | ORDSクライアントでは、トークン・リクエストにアクセスするときにPOSTメソッドが使用されます。
|
oauth:username:[Server Name] |
認証が必要なユーザーのusername
|
grant_type=passwordの場合に使用します |
3.2.5.1 OAuth2.0認証用のウォレットのエントリを作成する方法のデモンストレーション
この項の例では、権限付与タイプがOAuth2.0クライアント資格証明である場合の、mkstoreユーティリティを使用したウォレット設定方法を実際に示します。
SQLclのmkstoreユーティリティを使用してウォレットを設定
sql /nolog
SQL> mkstore -wrl /tmp/wallet -createOAuth2.0認証用のウォレットのエントリを作成
central-config.example.comです。sql /nolog
SQL> mkstore -wrl /tmp/wallet -createEntry oauth:grant_type:central-config.example.com client_credentials
SQL> mkstore -wrl /tmp/wallet -createEntry oauth:token_endpoint:central-config.example.com https://myauthserver.com/oauth/token
SQL> mkstore -wrl /tmp/wallet -createEntry oauth:client_id:central-config.example.com SeqlyQGW4iKgHd@cQ4Xnkg..
SQL> mkstore -wrl /tmp/wallet -createEntry oauth:client_secret:central-config.example.com SuBNKFsft£t924Dsfgsh..3.2.6 中央構成デプロイメントでのORDSの起動
ORDSは、ords serveコマンドに次のJavaオプションが含まれていると、中央構成デプロイメントが必要であることを認識します。
bin/ords --java-options "-Dconfig.url=[ORDS Global Configuration Resource Location]
-Dconfig.wallet=[ORDS Credentials Wallet Location]" serve-Dconfig.url: ORDSにグローバル構成リソースを示します。そのサーバーがORDS資格証明ウォレット内のシークレットの参照に使用されます。例:
-Dconfig.url=https://central-config.example.com:8585/central/v1/config/-Dconfig.wallet: ORDS資格証明ウォレットの場所をORDSに示します。自動ログインにより、Oracleウォレットに含まれているシークレットを使用してアクセス・トークンを取得し、グローバル・リソースとプール・リソースにアクセスできるようにします。例:
-Dconfig.wallet=/tmp/wallet
コマンド・プロンプトで、ords serveコマンドの発行元からの、ORDSが中央構成デプロイメントで実行されていることを示す通知が表示されます。その後、ORDSは、構成されているデータベース・プールに対する受信HTTPSリクエストが到着するまで待機します。