ORDSを使用した既存のOracle Databaseのデータへのアクセス

既存のOracleデータベースからデータを公開する場合は、RESTレイヤーを介してデータベース表およびビューを公開する必要があります。これを行うには、「独自のデータベース・スキーマを使用」を使用して、Visual Builderにビジネス・オブジェクトおよびサービス接続を作成します。または、Oracle REST Data Services (ORDS)に接続できます。

ビジネス・オブジェクトとORDSの選択に役立つ簡単な概要を次に示します:

ビジネス・オブジェクトはVisual Builderに完全に統合されているため、ビジネス・ルール、関係、RESTサービスなどを簡単に作成できます。 Visual Builderで定義されたセキュリティ・ロールをビジネス・オブジェクトに適用して保護することもできます。さらに、ビジネス・オブジェクトは、フィルタリング、ソートおよびページ区切り用のREST API変換(vb/BusinessObjectTransforms)を自動的に提供します。
ORDSでは、RESTサービス・レイヤーのホスティングと作成は、Visual Builderのoutsideで実行されます。データベースでORDSを有効にすることで、ORDSアプリケーションと、RESTサービスの作成に必要なその他のサポートされているアプリケーションを使用できます。 (使用しているバージョンのORDSを他のOracle Applicationsとともに使用する例は、「Oracle REST Data Servicesの開始」を参照してください。) ビジネス・オブジェクトとは異なり、ORDSは独自のセキュリティ・ロールおよび権限を使用し、独自のフィルタ、ソートおよびページ区切り変換機能を作成する必要があります。ただし、ORDSの利点は、Oracle DB SQLおよびPL/SQL機能を最大限に活用して、必要なビジネス・ロジックで中間レイヤーを作成できることです。 ORDSでは、BLOB/CLOBフィールド、ファンクション、プロシージャなど、より多くのデータベース機能を使用することもできます。

ORDSを介してデータを公開するには、まず、データベース接続に関連付けられているスキーマ内の表およびビューに対してORDSアクセスを有効にする必要があります。 Oracle SQL Developerを使用している場合は、スキーマまたは個々の表またはビューへのRESTアクセスを有効にできます。詳細については、「Oracle SQL Developerユーザーズ・ガイド」の「スキーマ、表またはビューへのRESTアクセスの自動有効化(AutoREST)」を参照してください。

ノート:

データベースがプライベート・サブネット内またはファイアウォールの内側にある場合、ORDSエンドポイントには、Visual Builderでアクセス可能なパブリックIPアドレスが必要です。

Visual BuilderのORDSエンドポイントのマップ

データベース表またはビューがREST対応の場合、個々のエンドポイントまたはOpenAPIカタログを使用して、ORDSエンドポイントをアプリケーション内のRESTサービスとしてマップできます。

個々のエンドポイントをマップするには、エンドポイントURL (https://serverName/ords/schemaName/tableName/など)が必要です。「このエンドポイントからサービス接続を作成」です。各REST操作(GET、POST、DELETEなど)にマップする複数のエンドポイントを定義する必要がある場合があります
多数のエンドポイントを一度に作成できるOpenAPI仕様をマップするには、open-api-catalogをオブジェクトのURL (https://serverName/ords/schemaName/open-api-catalog/tableName/など)に追加します。「OpenAPI仕様を使用したサービス接続の作成」です。デモについては、「このブログ」を参照してください。

ノート:

サービス接続の「接続タイプ」を「動的」に設定すると、サービスではCORSがサポートされます。これは、ORDSエンドポイントがVisual Builderドメインに対してCORSをサポートしていることを示します。つまり、ORDS REST APIがコールされる元のドメイン(たとえば、https://sample.builder.oraclecloud.com)は、エンドポイントの許容オリジン・リストに追加されます。 ORDSエンドポイントのCORS構成に誤字または不一致がある場合、次のエラーが発生する可能性があります:

The REST API that you are connecting to doesn't seem to have Cross Origin Request sharing (CORS) for the Visual Builder domain. 
Try again after adding necessary CORS settings for the REST API you are connecting to.

ORDSエンドポイントでCORSをサポートできるようにするには、ORDSドキュメントの「ブラウザのオリジンについて」の例を参照してください。
ORDSエンドポイントにVisual Builderドメインに対するCORSサポートがない場合は、「接続タイプ」を「CORSのサポートに関係なく、常にプロキシを使用」に設定します。「適切な接続タイプを使用したREST ServicesのCORSの処理」を参照してください。

ORDSデータのソート、問合せおよびページ付け

ORDSバックエンドによって返されるデータをフィルタ処理、ソートおよびページ付けするには、Visual Builderのサービス接続定義の一部として「変換関数の提供」が必要です。 Visual Builderクックブックの「ORDS統合レシピ」で、変換関数のサンプル・コードを見つけます。

固定資格証明を使用したORDS APIへの接続

固定資格証明を使用してORDSエンドポイントへのアクセスを保護するには、認証にOAuth 2.0クライアント資格証明を使用します。

サービス接続の作成時に、サービス接続に次の認証メソッドを使用できます:

認証方式詳細

認証方式	詳細
OAuth 2.0 Client資格証明	これは推奨される認証オプションです。このオプションを使用するには、次の詳細を指定する必要があります: クライアントIDおよびシークレット ORDSからトークンURL。 ORDSなどから`https://example.com/ords/ordstest/oauth/token` 有効範囲これは空白です。

OAuth 2.0 Client資格証明

これは推奨される認証オプションです。

このオプションを使用するには、次の詳細を指定する必要があります:

クライアントIDおよびシークレット ORDSから
トークンURL。 ORDSなどからhttps://example.com/ords/ordstest/oauth/token
有効範囲これは空白です。

ORDSへの接続を作成する前に、RESTサービスを保護するためのロールと権限を作成し、OAuthクライアントをORDSサービスに登録する必要があります。次のステップでは、このプロセスを簡単に説明します。詳細は、「Oracle REST Data Servicesアプリケーションの開発」の「リソースの保護およびアクセス」を参照してください。

ORDSでRESTサービスを保護するためのロールおよび権限を作成します:

begin  ords.create_role('HR Administrator');
        ords.create_privilege(
      p_name => 'example.employees',
      p_role_name => 'HR Administrator',
      p_label => 'Employee Data',
      p_description => 'Provide access to employee HR data');
  commit;end;

権限をリソース(ORDS REST API)に関連付けます:

begin ords.create_privilege_mapping(
      p_privilege_name => 'example.employees',
      p_pattern => '/examples/employees/*');
      commit;end;

/example/employees RESTリソースにアクセスすると、次のように401が未認可になります:

curl -i https://example.com/ords/ordstest/examples/employees/
HTTP/1.1 401 Unauthorized
Content-Type: text/html
Transfer-Encoding: chunked
  
<!DOCTYPE html>
<html>
...
</html>

付与タイプが「クライアント資格証明」のOAuthクライアントを登録します:

begin oauth.create_client(
      p_name => 'Client Credentials Example',
      p_grant_type => 'client_credentials',
      p_privilege_names => 'example.employees',
      p_support_email => 'support@example.com');
 commit;end;

この新しく作成したクライアントに必要なロールを付与します:

begin oauth.grant_client_role(
      p_client_name => 'Client Credentials Example',
      p_role_name => 'HR Administrator' );
 commit;
end;

登録されたクライアントIDおよびシークレットを確認します:

select client_id,client_secret from user_ords_clients where name = 'Client Credentials Example';

次に、固定資格証明を使用してORDSへの接続を作成します:
1. ナビゲータでサービスを開き、+記号をクリックして「サービス接続」を選択します。
2. サービス接続の作成ウィザードで、「エンドポイントで定義」をクリックし、HTTPメソッドを選択してORDSエンドポイントのURLを入力します。
  「仕様で定義」を選択し、オブジェクトに対してORDSのOpenAPI指定のURLを使用して、複数のエンドポイントのサービス接続を定義できます。
3. 「サーバー」タブの「認証」セクションで、認証メソッドとして「OAuth 2.0クライアント資格証明」を選択します。
4. ORDS構成に基づいて、クライアントID、シークレットおよび「トークンURL」フィールドの詳細を指定します。
5. サービス接続をテストします。
ノート:

ORDSエンドポイントをコールしたときにERR_CERT_AUTHORITY_INVALIDエラーが発生した場合、サーバーが完全なSSL証明書チェーンを提供していない可能性があります。

これを修正する方法を次に示します:
- ORDS設定に完全なSSL証明書チェーンが含まれている場合は、フル・チェーンをブラウザに表示するようにORDSサーバーを構成します。
- ORDS設定に完全な証明書チェーンが含まれていない場合は、ORDSサーバーの前にロード・バランサを使用します。ロード・バランサは、完全な証明書チェーンをブラウザに提供 - ただし、ORDS設定ではこれが提供されませんでした。