UTL_HTTPを使用してパブリック・ホストにHTTPリクエストを送信するための詳細を提供します。

たとえば、パブリック・ホストwww.example.comのHTTPリクエストを送信するには、ホストのアクセス制御リストを作成します。

BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
         host => 'www.example.com',
         ace =>  xs$ace_type( privilege_list => xs$name_list('http'),
                              principal_name => 'ADMIN',
                              principal_type => xs_acl.ptype_db));
END;

次に、HTTPリクエストを送信します。

SELECT UTL_HTTP.REQUEST(url => 'https://www.example.com/') FROM dual;

Autonomous DatabaseでのUTL_HTTPの制限の詳細は、PL/SQLパッケージ・ノートAutonomous Databaseを参照してください。

UTL_HTTPを使用して、プライベート・ホストでHTTPリクエストを発行するステップについて説明します。

プライベート・エンドポイントにあるターゲット・ホストにリクエストを送信するには、ソース・データベースのOracle Cloud Infrastructure VCNからターゲット・ホストにアクセスできる必要があります。たとえば:

• Both the source database and the target host are in the same Oracle Cloud Infrastructure VCN.

• ソース・データベースとターゲット・ホストは、ペアになっている異なるOracle Cloud Infrastructure VCNにあります。

• ターゲット・ホストが、ソース・データベースのOracle Cloud Infrastructure VCNにFastConnectまたはVPNを使用して接続されているオンプレミス・ネットワークです。

Autonomous Databaseがプライベート・エンドポイントにある場合、顧客管理ウォレットを使用してUTL_HTTPコールを行うこともできます。詳細は、顧客管理Walletを使用した外部コールの作成を参照してください。

プライベート・エンドポイント上のターゲットに対してUTL_HTTPリクエストを行うには:

1. ホストのアクセス制御リストを作成します。

   たとえば:

   BEGIN
      DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
            host => 'www.example.com',
            ace => xs$ace_type( privilege_list => xs$name_list('http'),
                                principal_name => 'ADMIN',
                                principal_type => xs_acl.ptype_db),
                                private_target => TRUE);
   END;
   /

   この例に示すように、ホストのアクセス制御リストを作成するときに、private_targetパラメータに値TRUEを指定します。

   ノート
   
   ROUTE_OUTBOUND_CONNECTIONSをPRIVATE_ENDPOINTに設定した場合、このAPIではprivate_targetパラメータをTRUEに設定する必要はありません。詳細は、プライベート・エンドポイントを使用したアウトバウンド接続のセキュリティの強化を参照してください。

2. HTTPリクエストを送信します:

   SELECT UTL_HTTP.REQUEST(
                   url => 'https://www.example.com/',
                   https_host => 'www.example.com') 
                FROM dual;

Autonomous DatabaseでのUTL_HTTPの制限の詳細は、PL/SQLパッケージ・ノートAutonomous Databaseを参照してください。

Autonomous Databaseインスタンスがプライベート・エンドポイント上にある場合、プロキシを使用してUTL_HTTPでHTTPリクエストを送信できます。

1. プロキシ・サーバーでHTTP_PROXY ACLを設定します。

   たとえば:

   BEGIN
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
          host =>'www-proxy-example.com',
          ace  => xs$ace_type(privilege_list => xs$name_list('HTTP_PROXY'),
                              principal_name => 'APPUSER1',
                              principal_type => xs_acl.ptype_db),
                              private_target => TRUE);
   END;
   /

   この例に示すように、プロキシ・サーバーのアクセス制御リストを作成するときに、private_targetパラメータに値TRUEを指定します。

   ノート
   
   ROUTE_OUTBOUND_CONNECTIONSをPRIVATE_ENDPOINTに設定した場合、このAPIではprivate_targetパラメータをTRUEに設定する必要はありません。詳細は、プライベート・エンドポイントを使用したアウトバウンド接続のセキュリティの強化を参照してください。
2. リモートWebサーバーでHTTP ACLを設定します。

   たとえば:

   BEGIN
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
           host =>'example.com',
           ace => xs$ace_type( privilege_list => xs$name_list('HTTP'),
                               principal_name => 'APPUSER1',
                               principal_type => xs_acl.ptype_db)
   END;
   /

3. UTL_HTTPのウォレットおよびプロキシを設定します。

   たとえば:

   BEGIN
      UTL_HTTP.SET_WALLET('');
      UTL_HTTP.SET_PROXY('www-proxy-example:80');
   END;
   /

4. HTTPリクエストを送信します:

   SELECT UTL_HTTP.REQUEST(    
                       url         => 'https://www.example.com/',
                       https_host  => 'www.example.com')
                FROM dual;

資格証明オブジェクトをUTL_HTTP.SET_CREDENTIALプロシージャに渡す方法について説明します。

UTL_HTTP.SET_CREDENTIALプロシージャは、HTTP要求ヘッダーのHTTP認証情報を設定します。Webサーバーが要求を認証するにはこの情報が必要です。

UTL_HTTP.SET_CREDENTIALプロシージャを使用すると、資格証明オブジェクトを渡してHTTP認証を設定できます。資格証明オブジェクトはスキーマ・オブジェクトであるため、アクセスできるのは特権ユーザーのみで、資格証明を制御するためのスキーマ・レベルの権限を構成できます。資格証明オブジェクトの受渡しは、認証に使用されるユーザー名/パスワード/キーを格納および管理するための適切でセキュアな方法です。

UTL_HTTP.SET_CREDENTIALプロシージャは、UTL_HTTP.SET_AUTHENTICATIONプロシージャに代わる安全で便利な方法です。

例

...
UTL_HTTP.SET_AUTHENTICATION (l_http_request, 'web_app_user', 'xxxxxxxxxxxx');
...

前述の例に示すように、SET_AUTHENTICATIONプロシージャを起動する場合は、PL/SQL仮パラメータの一部としてクリア・テキストでユーザー名/パスワードを渡す必要があります。様々なPL/SQL自動化またはcronスクリプトにユーザー名/パスワードを埋め込む必要がある場合があります。クリア・テキスト・パスワードの受渡しは、 UTL_HTTP.SET_CREDENTIALプロシージャで対処されるコンプライアンスの問題です。

詳細は、SET_AUTHENTICATIONプロシージャおよびSET_AUTHENTICATION_FROM_WALLETプロシージャを参照してください。

UTL_HTTP.SET_CREDENTIAL構文

UTL_HTTP.SET_CREDENTIAL (
    r          IN OUT NOCOPY req,
    credential IN VARCHAR2,
    scheme     IN VARCHAR2 DEFAULT 'Basic',
    for_proxy  IN BOOLEAN  DEFAULT FALSE);

SET_CREDENTIALプロシージャで資格証明オブジェクトを渡す例:

• 資格証明オブジェクトの作成:

  BEGIN DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name => 'HTTP_CRED',
      username        => 'web_app_user',
      password        => '<password>' );
  END;

  これにより、ユーザー名/パスワードのペアを格納する資格証明オブジェクトが作成されます。

  詳細は、CREATE_CREDENTIALプロシージャを参照してください。

  詳細は、「スケジューラ・ジョブの資格証明の指定」を参照してください。

• UTL_HTTP.SET_CREDENTIALプロシージャを起動します。

  DECLARE
        l_http_request  UTL_HTTP.REQ;
      BEGIN 
        l_http_request := UTL_HTTP.BEGIN_REQUEST('https://www.example.com/v1/dwcsdev/NAME/dwcs_small_xt1.csv');
        UTL_HTTP.SET_CREDENTIAL (l_http_request, 'HTTP_CRED','BASIC');
        ...
  END;
  

  この例では、まずBEGIN_REQUESTプロシージャを起動してリクエストを作成し、SET_CREDENTIALプロシージャを起動してHTTPリクエスト・ヘッダーのHTTP認証情報を設定します。Webサーバーが要求を認証するにはこの情報が必要です。値l_http_requestはHTTPリクエスト、HTTP_CREDは資格証明名、BASICはHTTP認証スキームです。

詳細は、UTL_HTTPを参照してください。

Autonomous DatabaseでのUTL_HTTPの制限の詳細は、PL/SQLパッケージ・ノートAutonomous Databaseを参照してください。