1. インストレーション、構成および開発ガイド
  2. ORDSデータベースAPIの有効化

11 ORDSデータベースAPIの有効化

この項では、Oracle REST Data Services (ORDS)データベースAPIを有効化する方法について説明します。

ORDSデータベースAPIは、Oracle REST Data Servicesに埋め込まれているデータベース管理およびモニタリングREST APIです。データベースのバージョンおよび構成に応じて、ORDSデータベースAPIは、プラガブル・データベースの管理、データのエクスポート、データベース・パフォーマンスのレビューなどのサービスを提供します。デフォルトでは、ORDSを初めてインストールするとき、ORDSデータベースAPI機能は無効になっています。

11.1 ORDSデータベースAPIを有効化するための基本設定

この項では、ORDSデータベースAPIを有効にするための基本設定について説明します。

ORDSデータベースAPIを有効にするには、database.api.enabledプロパティをtrueに設定した後、ORDSを再起動します。
java -jar ords.war set-property database.api.enabled true
ORDSデータベースAPIにアクセスするには、使用可能な次の認証方法のいずれかを使用できます。
  • データベース・ユーザー名とパスワードを使用したデータベース認証
  • SQL管理者ロールまたはシステム管理者ロールを持つ中間層ユーザーによる認証

注意:

特定のロールによってのみアクセス可能な特定のエンドポイントがあります。Oracle DatabaseのREST APIのドキュメントには、各エンドポイントにアクセスできるロールに関する情報が記載されています。
データベース認証を有効にするには、次のコード・スニペットに示すようにrestEnabledSql.activeプロパティをtrueに設定してから、ORDSを再起動する必要があります。

java -jar ords.war set-property restEnabledSql.active true

データベース認証の場合は、スキーマを使用してデータベース内でデータベースAPI問合せを実行する前に、管理者スキーマがORDS対応であり、11gR2環境でDBAロールを付与されていること、または12c以上のバージョンのデータベースでPDB_DBAロールが付与されていることを確認します。これは、データベースを使用する非CDBまたはプラガブル・データベースごとに実行します。詳細は、「Oracle DatabaseスキーマのREST対応」および「ORDS_ADMIN.ENABLE_SCHEMA」の項を参照してください。

注意:

次の例では、sqlplusコマンドライン・ユーティリティを使用してSALESPDBデータベースにシステム・ユーザーとして接続し、そのデータベースにPDBADMINユーザーを構成します。データベースに接続してステップを実行するメカニズムは、環境設定によって異なります。
たとえば、ORDS Database APIサービス用のSALESPDBデータベースでPDBADMINスキーマを使用するには、データベースで次のコマンドを使用します。
sqlplus system@SALESPDB
GRANT PDB_DBA TO PDBADMIN;
BEGIN
ORDS_ADMIN.ENABLE_SCHEMA(p_schema => 'PDBADMIN');
END;
/

PDBADMINユーザーは、これで、ORDSデータベースAPIサービスを使用できるようになります。

データベース内の表をリストするには、GETリクエストをhttps://<server>/ords/salespdb/pdbadmin/_/db-api/stable/database/objects/tables/に送信します。

リクエスト上に、ユーザー名とパスワードを指定する必要があります。ブラウザを使用している場合は、ORDSにより、リクエストにログインして認証するためのリンクが提供されます。認証されると、ブラウザはアクセスCookieを持ち、そのCookieが失効するまでユーザー資格証明を指定する必要がありません。

同じサービスは、curlなどのコマンドライン・ユーティリティを使用してアクセスできます。

curl --user pdbadmin:password https://<server>/ords/salespdb/pdbadmin/_/db-api/stable/database/objects/tables/

使用可能なORDSデータベースAPIサービスを記述したOpenAPI V3ドキュメントには、https://<server>/ords/<my database>/<my admin schema>/_/db-api/stable/metadata-catalog/openapi.jsonからアクセスできます。https://<server>/ords/<my database>/<my admin schema>/_/db-api/stable/databases/pdbs/を除いて、他のすべてのORDSデータベースAPIサービスが使用可能になります。

関連トピック

11.2 ORDSデータベースAPIを有効化するための拡張設定

この項では、様々なデータベース・トポロジでORDSデータベースAPIを使用するための構成オプションについて説明します。

11.2.1 プラガブル・データベースのライフサイクル管理

この項では、プラガブル・データベース(PDB)ライフサイクル管理操作を有効にする方法について説明します。プラガブル・データベース管理はコンテナ・データベース(CDB)で実行され、作成、クローニング、接続、切断および削除操作が含まれます。

コンテナ・データベース内でORDS対応のスキーマを指定することはできません。PDBライフサイクル管理操作を実行するには、デフォルトのCDB管理者資格証明であるdb.cdb.adminUserおよびdb.cdb.adminUser.passwordが接続プールで定義されている必要があります。この場合、URIにユーザー・スキーマを指定する必要はありません。

デフォルトCDB管理者の資格証明を定義するには、次の手順を実行します。

  1. CDB管理者ユーザーを作成し、SYSDBA権限を付与します。この例では、ユーザーはC##DBAPI_CDB_ADMINと呼ばれます。ただし、適切な共通ユーザー名を使用することはできます。
    CREATE USER C##DBAPI_CDB_ADMIN IDENTIFIED BY <PASSWORD>;
GRANT SYSDBA TO C##DBAPI_CDB_ADMIN CONTAINER = ALL;
  2. 接続プールのdb.cdb.adminUserおよびdb.cdb.adminUser.passwordプロパティを設定します。
    echo db.cdb.adminUser=C##DBAPI_CDB_ADMIN as SYSDBA > cdbAdmin.properties
echo db.cdb.adminUser.password=<PASSWORD> >> cdbAdmin.properties
java -jar ords.war set-properties --conf apex_pu cdbAdmin.properties
rm cdbAdmin.properties

ORDSロールのSQL管理者を使用して、https://<server>/ords/_/db-api/stable/database/pdbs/サービスにアクセスする必要があります。

11.2.2 PDBライフサイクル管理の無効化

この項では、PDBライフサイクル管理サービスを無効にする方法について説明します。

https://<server>/ords/_/db-api/stable/databases/pdbs/で、ORDSデータベースAPIの有効化およびPDB関連サービスの無効化を実行できます。

オプションのCDB管理者の資格証明が設定されていない場合、ユーザーがhttps://<server>/ords/_/db-api/stable/databases/pdbs/にアクセスしようとするとHTTP 503 Service Unavailableレスポンスが生成されます。

ORDSインストールに対してPDB操作が無効になっていることを明確に示すには、次のコード・スニペットに示すように、database.api.management.services.disabledプロパティをtrueに設定してから、ORDSを再起動します。 

java -jar ords.war set-property database.api.management.services.disabled true

これにより、レスポンスHTTP 503 Service Unavailableに説明的な理由が生成されます。

11.3 デフォルト管理者の作成

この項では、非CDBまたはPDB接続用のデフォルトの管理者ユーザーを作成および使用する方法について説明します。

ORDSデータベースAPIサービス操作はスキーマ固有ではありません。接続プールにデフォルトの管理者資格証明であるdb.adminUserおよびdb.adminUser.passwordを構成することで、対応するSQL文をデフォルトの管理者ユーザーとして実行できます。スキーマにDBAロールが割り当てられている場合は、指定されたORDS対応スキーマを使用して、ORDSデータベースAPIエンドポイントを実行できます。ただし、デフォルトの管理者資格証明が構成されている場合は、これを行う必要はありません。

注意:

ユーザー資格証明は、すべてのプラガブル・データベースで同じである必要があるため、CDBに共通ユーザーを作成することをお薦めします。

デフォルトの管理者を作成してDBAロールを付与するには、次の手順を実行します。

  1. デフォルトの管理者ユーザーを作成し、DBAロールを付与します。この例では、ユーザーはC##_DBAPI_DEFAULT_ADMINと呼ばれます。ただし、次のコード・スニペットに示すように、任意の適切な共通ユーザー名を使用できます。
    CREATE USER C##_DBAPI_DEFAULT_ADMIN IDENTIFIED BY <PASSWORD> CONTAINER = ALL;
    GRANT DBA TO C##_DBAPI_DEFAULT_ADMIN CONTAINER = ALL;
  2. 次のコード・スニペットに示すように、接続プールのdb.adminUserおよびdb.adminUser.passwordプロパティを設定します。
    echo db.adminUser=C##_DBAPI_PDB_ADMIN > pdbAdmin.properties
    echo db.adminUser.password=<PASSWORD> >> pdbAdmin.properties
    java -jar ords.war set-properties --conf apex_pu pdbAdmin.properties
    rm pdbAdmin.properties

URIリクエストにスキーマを指定する必要はありません。

たとえば、https://<server>/ords/salespdb/_/db-api/stable/database/datapump/jobs/では、salespdb,内のすべてのデータ・ポンプ・ジョブがリストされ、そのデータベース内の問合せはdb.adminUserユーザーとして実行されます。

ORDSロールSQL管理者は、データベースAPIサービスを使用する必要があります。

11.4データベースAPI環境サービスの構成

この項では、ORDSデータベースAPI環境サービスの構成方法について説明します。

ORDS 19.2リリース以降では、ORDSがインストールされているシステムで一連の環境サービス操作を実行できます。

たとえば、次のエンドポイントはOracleホームで検出されたすべてのデータベースをリストします。

https://<server>/ords/_/db-api/stable/environment/databases/

ORDSデータベースAPI環境サービスを使用するには、ORDSシステム管理者ロールが必要です。環境サービスにより、ホスト・マシン上のデータベースのOracleホームに関する情報、およびデータベースを作成または削除する際のOracle Database Configuration AssistantへのRESTfulインタフェースが提供されます。

プラガブル・データベースのライフサイクル管理と同様に、環境サービスは無効にできます。

環境サービスを無効にするには、次のようにdatabase.api.management.services.disabledプロパティをtrueに設定してORDSを再起動します。

java -jar ords.war set-property database.api.management.services.disabled true