Oracle APEXでのWebサービスの使用

Autonomous DatabaseインスタンスのOracle APEXから、SOAPとRESTfulの両方のスタイルのWebサービスを操作できます。

Webサービスを使用すると、アプリケーション同士がプラットフォームや言語に依存しない環境でWeb上で相互に通信できるようになります。典型的なWebサービスの使用例には、ビジネス・アプリケーションでHTTPプロトコルを使用して、指定したURLのサービスにリクエストを送信することがあります。サービスは、リクエストを受信すると、これを処理し、レスポンスを返します。Webサービスは、通常、Simple Object Access Protocol (SOAP)またはRepresentational State Transfer (REST)アーキテクチャに基づいています。

RESTデータ・ソースを使用すると、APEX開発者は、様々なRESTエンドポイントからデータ・サービスに宣言的にアクセスできます。これにより、読取りと書込みの両方の操作が可能になります。Oracle APEXでは、リモートRESTデータのスマート・キャッシュ・ルールのサポートに加えて、業界標準のSQLを使用してRESTデータ・ソースの結果を直接操作する独自の機能も提供されます。

APEX_WEB_SERVICEパッケージを使用すると、アプリケーション内のPL/SQLを使用できる任意の場所にあるWebサービスと対話できるため、APEXと他のシステムを統合することができます。このパッケージには、SOAPとRESTfulの両方のスタイルのWebサービスをコールするためのプロシージャとファンクション、およびOAuth 2.0フローの実装を簡略化するためのプロシージャとファンクションが含まれます。

Oracle APEXを使用したプライベート・ホストへのHTTPリクエストの発行

Autonomous DatabaseインスタンスのOracle APEXからプライベート・ホストにHTTPリクエストを送信するには、いくつかの要件があります。

プライベート・エンドポイントまたはオンプレミス・ファイアウォールの背後にあるターゲット・ホストにリクエストを送信するには、ソース・データベースのOracle Cloud Infrastructure VCNからターゲット・ホストにアクセスできる必要があります。

  1. UTL_HTTPを使用したプライベート・ホストへのHTTPリクエストの発行の説明に従って、エンドポイントがHTTPリクエストを送信するための前提条件を満たしていることを確認します。

  2. 目的のホストの次のアクセス制御リストをADMINとして追加します(private_targetパラメータに注意してください)。

    BEGIN
      DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
        host => 'www.example.com',
        ace => XS$ACE_TYPE(
          privilege_list => XS$NAME_LIST('http'),
          principal_name => APEX_APPLICATION.g_flow_schema_owner,
          principal_type => XS_ACL.ptype_db),
        private_target => true);
    END;
    /
ノート

ROUTE_OUTBOUND_CONNECTIONSデータベース・プロパティをPRIVATE_ENDPOINTに設定した場合、APEXからアクセスするために、個々のホストのアクセス制御リストを定義する必要はありません。詳細は、プライベート・エンドポイントを使用したアウトバウンド接続のセキュリティの強化を参照してください。

Oracle APEXで顧客管理Walletを使用した外部コールの実行

Autonomous Database上のOracle APEXは、ほとんどのHTTPSエンドポイントで動作するOracle Walletで事前構成されています。あまり一般的でないSSL証明書または自己署名SSL証明書を使用するサーバーからREST APIを使用する場合、顧客管理ウォレットを構成できます。

Autonomous Database上のOracle APEXは、最も一般的な信頼できるルートおよび中間SSL証明書の90以上を含むOracle Walletで事前構成されています。APEX_WEB_SERVICEパッケージは、アプリケーション開発者が追加の構成を行うことなく、このOracle Walletを自動的に利用します。

あまり一般的でないSSL証明書または自己署名SSL証明書を使用するサーバーからREST APIを使用する場合、顧客管理ウォレットを構成できます。まず、外部コールで顧客管理Walletを使用するための前提条件の構成およびデプロイメントの手順に従います。ウォレットがAutonomous Databaseにデプロイされたら、ウォレットを含むディレクトリ・オブジェクトでREADをAPEXプラットフォーム・スキーマにADMINとして付与します:

BEGIN
  execute immediate 'grant READ on directory WALLET_DIR to ' ||
    APEX_APPLICATION.g_flow_schema_owner;
END;

次に、APEX_WEB_SERVICE APIコールでウォレットを参照する場合は、通常のFILE:接頭辞のかわりにDIR:接頭辞を使用してください。たとえば:

l_resp := APEX_WEB_SERVICE.MAKE_REST_REQUEST(
  p_url         => 'https://www.example.com/',
  p_http_method => 'GET',
  p_wallet_path => 'DIR:WALLET_DIR'
);

APEX管理サービスで「インスタンスの管理」→「インスタンス設定」→「Wallet」→「Walletパス」を選択するか、WALLET_PATHインスタンス・パラメータを設定して、このウォレットをOracle APEXインスタンス全体のデフォルトとして構成することもできます。

事前構成済ウォレットに切り替えるには、WALLET_PATHを空の値に設定します。

詳細は、Oracle APEX管理サービスへのアクセスを参照してください。

Oracle APEXでのWebプロキシを使用した外部コールの実行

Oracle APEXインスタンスでは、外部REST APIコールを行うためにアウトバウンドWebプロキシは必要ありません。プライベート・エンドポイントで構成されたAutonomous Databasesでは、必要に応じてVCNにデプロイされたWebプロキシを使用できます。

Webプロキシを使用するには、次のアクセス制御リストをADMINとして定義します。

BEGIN
  DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
    host           => 'www-proxy.example.com',
    lower_port     => 80,
    ace => XS$ACE_TYPE( 
      privilege_list => XS$NAME_LIST('HTTP_PROXY'),
      principal_name => APEX_APPLICATION.g_flow_schema_owner,
      principal_type => XS_ACL.ptype_db),
    private_target => true);
END;
/

次に、APEX_WEB_SERVICE APIコールでWebプロキシを使用できます。

l_resp := APEX_WEB_SERVICE.MAKE_REST_REQUEST(
  p_url            => 'https://www.example.com/',
  p_http_method    => 'GET',
  p_proxy_override => 'www-proxy.example.com:80'
);

「共有コンポーネント」→「アプリケーション定義」→「プロパティ」ページでプロキシ・サーバー・プロパティを設定するか、「インスタンスの管理」→「セキュリティ」→「インスタンス・プロキシ」からAPEX管理サービスのインスタンス・レベルでWebプロキシを構成することもできます。

Autonomous Databaseがパブリック・エンドポイントで構成されているときにWebプロキシを使用しようとすると、次のエラーが返されます:

ORA-01031: insufficient privileges

UTL_HTTP APIを使用する場合のプロキシの詳細は、UTL_HTTPを使用したプライベート・ホストへのHTTPリクエストの発行を参照してください。

詳細は、Oracle APEX管理サービスへのアクセスを参照してください。

Oracle APEXでのWebサービスの利用に関するノート

Autonomous DatabaseインスタンスからOracle APEXでWebサービスを操作するためのノートを提供します。

Oracle APEXでWebサービスを操作する場合は、次の点に注意してください。

  • すべてのWebサービスが保護されている必要があります。デフォルト・ポート(443)ではHTTPSサービスのみがサポートされます。IPアドレスを介した接続は許可されません。

  • 各Autonomous Databaseインスタンスは、Oracle APEXからパブリック・エンドポイントへのアウトバウンドWebサービス・コールを許可するために、ネットワーク・アクセス制御リスト(ACL)を使用して事前構成されています。

  • APEX_WEB_SERVICEリクエストでは、UTL_HTTP.SET_WALLET APIコールで設定したカスタム・ウォレットは適用されません。

  • ローリング24時間では、APEXワークスペースごとに1,000アウトバウンドWebサービス・リクエストのデフォルト制限があります(これは新しいデータベースに適用され、一部の古いデータベースではより大きな制限がある場合があります)。アウトバウンドWebサービス・コール数の制限に達すると、後続の要求で次のSQL例外が発生し、リクエストはブロックされます:

    ORA-20001: You have exceeded the maximum number of web service requests per workspace. Please contact your administrator.

    MAX_WEBSERVICE_REQUESTSインスタンス・パラメータの値を設定するか、APEX管理サービスで「最大Webサービス・リクエスト」属性を更新することで、アウトバウンドWebサービス・リクエストのデフォルト制限を引き上げまたは削除できます。たとえば、制限を250,000に変更するには、SQLクライアントを使用してADMINとしてデータベースに接続し、次を実行します:

    BEGIN
      APEX_INSTANCE_ADMIN.SET_PARAMETER('MAX_WEBSERVICE_REQUESTS', '250000');
      COMMIT;
    END;
    /

さらに学習するには、次のURLを参照してください。