277 UTL_HTTP
UTL_HTTP
パッケージは、SQLとPL/SQLからHypertext Transfer Protocol (HTTP)のコールアウトを行います。これを使用すると、HTTPを経由してインターネット上のデータにアクセスできます。
パッケージでHTTPSを使用してWebサイトからデータをフェッチする場合は、Oracle Walletが必要で、Oracle Walletは、orapki
ユーティリティを使用して作成できます。HTTPS以外のフェッチの場合は、Oracle Walletは必要ありません。
この章のトピックは、次のとおりです:
参照:
-
Wallet Managerの詳細は、『Oracle Databaseエンタープライズ・ユーザー・セキュリティ管理者ガイド』を参照してください。
277.1 UTL_HTTPの概要
UTL_HTTP
パッケージを使用すると、Web(HTTP)サーバーと通信するPL/SQLプログラムを記述できます。UTL_HTTP
には、SQL問合せで使用できるファンクションも含まれています。
このパッケージは、HTTPSとも呼ばれるSecured Socket Layer protocol (SSL)上のHTTPをサポートしています。また、リモートWebサーバーで認証をするためにウォレットでクライアント証明書を送信することで、SSLクライアント認証もサポートしています。
他のインターネット関連のデータ・アクセス・プロトコル(ファイル転送プロトコル(FTP)やGopherなど)も、これらのプロトコルをサポートしているHTTPプロキシ・サーバーを使用することでサポートされます。
277.2 UTL_HTTPのセキュリティ・モデル
このパッケージは実行者権限のパッケージです。起動するユーザーには、接続するリモート・ネットワーク・ホストに割り当てられたアクセス制御リストによってconnect
権限が付与されている必要があります。また、Oracle Walletに格納されている資格証明を使用してリモートWebサーバーに対してユーザー自身を認証するためのuse-client-certificates
権限とuse-passwords
権限も必要となります。
ノート:
ファイングレイン・アクセスの管理の詳細は、『Oracle Databaseセキュリティ・ガイド』を参照してください。
277.3 UTL_HTTPの定数
UTL_HTTP
パッケージは、パラメータ値の指定時に使用するいくつかの定数を定義します。
表277-1 UTL_HTTPの定数 - HTTPバージョン
名前 | タイプ | 値 | 説明 |
---|---|---|---|
|
|
|
|
|
|
|
|
表277-2 UTL_HTTPの定数 - デフォルト・ポート
名前 | タイプ | 値 | 説明 |
---|---|---|---|
|
|
|
Webサーバーまたはプロキシ・サーバーがリスニングするデフォルトのTCP/IPポート(80)。 |
|
|
|
HTTPS WebサーバーがリスニングするデフォルトのTCP/IPポート(443)。 |
表277-3 UTL_HTTPの定数 - HTTP 1.1のステータス・コード
名前 | タイプ | 値 | 説明 |
---|---|---|---|
|
|
|
クライアントは要求を継続する必要があります。この仮の応答を使用して、サーバーで要求の最初の部分が受信され、まだ拒否されていないことをクライアントに通知します。 |
|
|
|
サーバーは、Upgradeメッセージ・ヘッダー・フィールドを介して、クライアントによる、この接続で使用されているアプリケーション・プロトコルの変更要求を解釈し、それらに応じます。サーバーは、101応答を終了する空の行の直後にある応答のUpgradeヘッダー・フィールドで定義されているプロトコルにプロトコルを切り替えます。 |
|
|
|
応答は成功しました。応答とともに戻される情報は、要求で使用されたメソッドによって異なります。 |
|
|
|
リクエストが完了し、新規のリソースが作成されました。 |
|
|
|
リクエストの処理は承認されましたが、処理がまだ完了していません。要求は、実際に処理が行われる際に拒否される可能性があるため、最終的には処理されない場合もあります。 |
|
|
|
エンティティヘッダーに戻されるメタ情報は、オリジナル・サーバーから収集可能な最終的なセットではなく、ローカルまたはサードパーティ・コピーから収集されます。 |
|
|
|
サーバーは、要求を満たしましたが、エンティティ本体を戻す必要はありません。また、更新されたメタ情報を戻す場合もあります。 |
|
|
|
サーバーは要求を満たしました。ユーザー・エージェントは、要求の送信元ドキュメント・ビューをリセットする必要があります。応答にはエンティティを含めないでください。 |
|
|
|
サーバーは、リソースに対するGET要求の一部を満たしました。 |
|
|
|
要求されたリソースが一連の表現のいずれかに対応しています。各表現には固有の場所があり、ユーザー(またはユーザー・エージェント)が適切な表現を選択し、要求をその表現の場所にリダイレクトできるようにエージェントドリブンのネゴシエーション情報が提供されます。 |
|
|
|
要求されたリソースが新規永続URIに割り当てられています。このリソースを今後参照するには、戻されたURIのいずれかを使用する必要があります。 |
|
|
|
要求されたリソースが一時的に別のURIに存在しています。 |
|
|
|
要求への応答が別のURIに存在している可能性があります。この応答は、リソースに対してGETメソッドを使用して取得する必要があります。 |
|
|
|
クライアントが条件付きGET要求を実行し、アクセスは許可されているが、ドキュメントは変更されていない場合、サーバーはこのステータス・コードで応答します。 |
|
|
|
要求されたリソースには、「位置」フィールドで指定されているプロキシを使用してアクセスする必要があります。「位置」フィールドには、プロキシのURIが指定されています。 |
|
|
|
要求されたリソースが一時的に別のURIに存在しています。 |
|
|
|
構文の形式が正しくないため、サーバーがリクエストを理解できませんでした。 |
|
|
|
リクエストにはユーザー認証が必要です。クライアントは、適切なAuthorizationヘッダー・フィールドを使用してリクエストを繰り返すことができます。リクエストに認可資格証明がすでに含まれている場合は、401レスポンスはこの資格証明に対して認可が拒否されたことを示しています。 |
|
|
|
このコードは将来使用するために予約されています。 |
|
|
|
サーバーは、要求を解釈しましたが、要求を満たすことを拒否しています。 |
|
|
|
Request-URIに一致するものが見つかりませんでした。 |
|
|
|
リクエストによって識別されたリソースは、リクエストで送信されたAcceptヘッダーによって受入れ不可となったコンテンツ特性を含むレスポンス・エンティティを生成することのみが可能です。 |
|
|
|
このコードは401(Unauthorized)と似ていますが、クライアントが最初にプロキシから認証を受ける必要があることを示します。 |
|
|
|
サーバーが待機するように設定されていた時間内に、クライアントがリクエストを生成しませんでした。 |
|
|
|
リソースの現在の状態と競合しているため、リクエストを完了できませんでした。 |
|
|
|
要求されたリソースはサーバーで使用できなくなりました。転送アドレスが不明です。 |
|
|
|
サーバーは、 |
|
|
|
1つ以上の要求ヘッダー・フィールドに指定されている事前条件が、サーバーでのテストでfalseと評価されました。 |
|
|
|
サーバーが処理できる長さをリクエスト・エンティティが超えているため、サーバーはリクエストの処理を拒否しています。 |
|
|
|
サーバーが解釈できる長さをRequest-URIが超えているため、サーバーはリクエストの処理を拒否しています。 |
|
|
|
リクエストされたメソッドに対するリクエストのエンティティが、リクエストされたリソースではサポートされていない形式であるため、サーバーはリクエストの処理を拒否しています。 |
|
|
|
要求にRange要求ヘッダー・フィールドが含まれている場合、サーバーはこのステータス・コードの応答を戻します。このフィールドの範囲指定子の値は選択したリソースの現在のエクステントにオーバーラップせず、要求にIf-Range要求ヘッダー・フィールドは含まれませんでした。 |
|
|
|
このサーバーがExpect要求ヘッダー・フィールドに指定されている期待値を満たすことができなかったか、またはサーバーがプロキシの場合は、ネクスト・ホップ・サーバーが要求を満たすことができなかった明確な証拠がサーバーに存在します。 |
|
|
|
サーバーでは、リクエストを実行するために必要な機能がサポートされていません。 |
|
|
|
ゲートウェイまたはプロキシとして動作しているサーバーが、要求を満たすためにアクセスしたアップストリーム・サーバーから無効な応答を受信しました。 |
|
|
|
サーバーは現在、サーバーの一時的な過負荷状態またはメンテナンスのため、リクエストを処理できません。 |
|
|
|
ゲートウェイまたはプロキシとして動作しているサーバーが、URI(HTTP、FTP、LDAPなど)で指定されているアップストリーム・サーバー、または要求の完了の試行時にアクセスする必要があるその他の補助サーバー(DNSなど)からタイムリな応答を受信しませんでした。 |
|
|
|
サーバーは、リクエスト・メッセージで使用されていたHTTPプロトコル・バージョンをサポートしていないか、サポートすることを拒否しています。 |
277.4 UTL_HTTPの例外
例外は、UTL_HTTPパッケージで問題が発生したことを示しています。
次の表は、これらの例外を示しています。デフォルトでは要求の実行に失敗すると、UTL_HTTP
によりrequest_failed
例外が発生します。set_detailed_excp_support
により詳細な例外が発生するようにパッケージが設定されている場合、残りの例外は直接発生します(ただし、end_of_body
例外は除きます。この例外は、設定にかかわらず、READ_TEXT
、READ_LINE
およびREAD_RAW
により呼び出されます)。
表277-4 UTL_HTTPの例外
例外 | エラー・コード | 理由 | 発生した場所 |
---|---|---|---|
|
|
インタフェースに渡された引数が不適切です。 |
|
|
|
要求されたURLの構成が不適切です。 |
|
|
|
HTTP応答本体の終わりに到達しています。 |
|
|
|
ヘッダーが見つかりません。 |
|
|
|
|
|
|
|
|
|
|
|
リモート・ネットワーク・ホストまたはOracle Wallet内の資格証明へのアクセスが拒否されました。 |
|
|
|
HTTP要求の現在の状態では |
|
|
|
完全に読み込まれた文字はありません。応答本体の終わりにマルチバイト文字の一部が検出されました。 |
|
|
|
Webサーバーとの通信でHTTPプロトコルのエラーが発生しました。 |
|
|
|
要求の実行に失敗しました。 |
|
|
|
オープンされている要求または応答が多すぎます。 |
detailed_exceptionが有効な場合の |
|
|
データが読み込まれず、読込みタイムアウトが発生しました。 |
|
|
|
要求されたURLのスキームが不明です。 |
|
ノート:
partial_multibyte_char
およびtransfer_timeout
の例外は、UTL_TCP
で定義された同じ例外の複製です。これらは、パッケージを使用するときにUTL_TCP
の知識を必要としなくても済むように、このパッケージで定義されています。これらの例外は複製であるため、このパッケージのpartial_multibyte_char
およびtransfer_timeout
例外を補足する例外ハンドルは、UTL_TCP
の例外も捕捉します。
REQUEST
およびREQUEST_PIECES
では、なんらかの例外が発生してdetailed_exception
が無効な場合に、request_failed
例外が発生します。
277.5 UTL_HTTPの例
次の例では、UTL_HTTP
の使用方法を示します。
277.5.1 UTL_HTTPの一般的な使用方法
これは、UTL_HTTP
の使用方法の一般的な例です。
SET SERVEROUTPUT ON SIZE 40000 DECLARE req UTL_HTTP.REQ; resp UTL_HTTP.RESP; value VARCHAR2(1024); BEGIN UTL_HTTP.SET_PROXY('proxy.my-company.com', 'corp.my-company.com'); req := UTL_HTTP.BEGIN_REQUEST('http://www-hr.corp.my-company.com'); UTL_HTTP.SET_HEADER(req, 'User-Agent', 'Mozilla/4.0'); resp := UTL_HTTP.GET_RESPONSE(req); LOOP UTL_HTTP.READ_LINE(resp, value, TRUE); DBMS_OUTPUT.PUT_LINE(value); END LOOP; UTL_HTTP.END_RESPONSE(resp); EXCEPTION WHEN UTL_HTTP.END_OF_BODY THEN UTL_HTTP.END_RESPONSE(resp); END;
277.5.2 UTL_HTTPのHTTP応答ヘッダーの取出し
この例は、UTL_HTTP
がHTTP応答ヘッダーを取得する方法を示しています。
SET SERVEROUTPUT ON SIZE 40000 DECLARE req UTL_HTTP.REQ; resp UTL_HTTP.RESP; name VARCHAR2(256); value VARCHAR2(1024); BEGIN UTL_HTTP.SET_PROXY('proxy.my-company.com', 'corp.my-company.com'); req := UTL_HTTP.BEGIN_REQUEST('http://www-hr.corp.my-company.com'); UTL_HTTP.SET_HEADER(req, 'User-Agent', 'Mozilla/4.0'); resp := UTL_HTTP.GET_RESPONSE(req); DBMS_OUTPUT.PUT_LINE('HTTP response status code: ' || resp.status_code); DBMS_OUTPUT.PUT_LINE('HTTP response reason phrase: ' || resp.reason_phrase); FOR i IN 1..UTL_HTTP.GET_HEADER_COUNT(resp) LOOP UTL_HTTP.GET_HEADER(resp, i, name, value); DBMS_OUTPUT.PUT_LINE(name || ': ' || value); END LOOP; UTL_HTTP.END_RESPONSE(resp); END;
277.5.3 UTL_HTTPのHTTP認証の処理
このコード・サンプルは、UTL_HTTP
がHTTP認証を処理する方法を示しています。
SET serveroutput ON SIZE 40000 CREATE OR REPLACE PROCEDURE get_page (url IN VARCHAR2, username IN VARCHAR2 DEFAULT NULL, password IN VARCHAR2 DEFAULT NULL, realm IN VARCHAR2 DEFAULT NULL) AS req UTL_HTTP.REQ; resp UTL_HTTP.RESP; my_scheme VARCHAR2(256); my_realm VARCHAR2(256); name VARCHAR2(256); value VARCHAR2(256); BEGIN -- Turn off checking of status code. We will check it by ourselves. UTL_HTTP.SET_RESPONSE_ERROR_CHECK(FALSE); req := UTL_HTTP.BEGIN_REQUEST(url); IF (username IS NOT NULL) THEN UTL_HTTP.SET_AUTHENTICATION(req, username, password); -- Use HTTP Basic Authen. Scheme END IF; resp := UTL_HTTP.GET_RESPONSE(req); IF (resp.status_code = UTL_HTTP.HTTP_UNAUTHORIZED) THEN UTL_HTTP.GET_AUTHENTICATION(resp, my_scheme, my_realm, FALSE); DBMS_OUTPUT.PUT_LINE('Web proxy server is protected.'); DBMS_OUTPUT.PUT('Please provide the required ' || my_scheme || ' authentication username/password for realm ' || my_realm || ' for the proxy server.'); UTL_HTTP.END_RESPONSE(resp); RETURN; ELSIF (resp.status_code = UTL_HTTP.HTTP_PROXY_AUTH_REQUIRED) THEN UTL_HTTP.GET_AUTHENTICATION(resp, my_scheme, my_realm, TRUE); DBMS_OUTPUT.PUT_LINE('Web page ' || url || ' is protected.'); DBMS_OUTPUT.PUT('Please provide the required ' || my_scheme || ' authentication username/password for realm ' || my_realm || ' for the Web page.'); UTL_HTTP.END_RESPONSE(resp); RETURN; END IF; FOR i IN 1..UTL_HTTP.GET_HEADER_COUNT(resp) LOOP UTL_HTTP.GET_HEADER(resp, i, name, value); DBMS_OUTPUT.PUT_LINE(name || ': ' || value); END LOOP; UTL_HTTP.END_RESPONSE(resp); END;
277.5.4 UTL_HTTPのHTTP Digest認証の処理
このコード・サンプルは、UTL_HTTP
がHTTP Digest認証を処理する方法を示しています。
declare url varchar2(32767); q utl_http.req; p utl_http.resp; pstatus pls_integer; begin url := 'http://slc10tzv.us.oracle.com:3000/digest.html'; q := utl_http.begin_request(url); utl_http.set_authentication(q, username => 'utlhttp_user', password => 'welcome', scheme => 'Digest'); p := utl_http.get_response(q); pstatus := p.status_code; -- status code returned from get_response should be 200 dbms_output.put_line('-- response status: ' || p.status_code); utl_http.end_response(p); utl_http.end_request(q); EXCEPTION WHEN OTHERS THEN utl_http.end_request(q); end; / -- response status: 200"
277.5.5 UTL_HTTPのCookieの取出しおよびリストア
この例は、UTL_HTTPを使用してCookieを取得およびリストアする方法を示しています。
CREATE TABLE my_cookies ( session_id INTEGER, name VARCHAR2(256), value VARCHAR2(1024), domain VARCHAR2(256), expire DATE, path VARCHAR2(1024), secure VARCHAR2(1), version INTEGER); CREATE SEQUENCE session_id; SET SERVEROUTPUT ON SIZE 40000 REM Retrieve cookies from UTL_HTTP CREATE OR REPLACE FUNCTION save_cookies RETURN PLS_INTEGER AS cookies UTL_HTTP.COOKIE_TABLE; my_session_id PLS_INTEGER; secure VARCHAR2(1); BEGIN /* assume that some cookies have been set in previous HTTP requests. */ UTL_HTTP.GET_COOKIES(cookies); SELECT session_id.nextval INTO my_session_id FROM DUAL; FOR i in 1..cookies.count LOOP IF (cookies(i).secure) THEN secure := 'Y'; ELSE secure := 'N'; END IF; INSERT INTO my_cookies VALUES (my_session_id, cookies(i).name, cookies(i).value, cookies(i).domain, cookies(i).expire, cookies(i).path, secure, cookies(i).version); END LOOP; RETURN my_session_id; END; / REM Retrieve cookies from UTL_HTTP CREATE OR REPLACE PROCEDURE restore_cookies (this_session_id IN PLS_INTEGER) AS cookies UTL_HTTP.COOKIE_TABLE; cookie UTL_HTTP.COOKIE; i PLS_INTEGER := 0; CURSOR c (c_session_id PLS_INTEGER) IS SELECT * FROM my_cookies WHERE session_id = c_session_id; BEGIN FOR r IN c(this_session_id) LOOP i := i + 1; cookie.name := r.name; cookie.value := r.value; cookie.domain := r.domain; cookie.expire := r.expire; cookie.path := r.path; IF (r.secure = 'Y') THEN cookie.secure := TRUE; ELSE cookie.secure := FALSE; END IF; cookie.version := r.version; cookies(i) := cookie; END LOOP; UTL_HTTP.CLEAR_COOKIES; UTL_HTTP.ADD_COOKIES(cookies); END; /
277.5.6 UTL_HTTPのプライベートのWalletおよびCookieの表によるHTTP要求
この例は、UTL_HTTP
がウォレットおよびCookie表を使用して要求コンテキストを作成してから、そのウォレットおよびCookie表を使用してHTTP要求を行う方法を示しています。
SET SERVEROUTPUT ON SIZE 40000 CREATE OR REPLACE PROCEDURE DISPLAY_PAGE(url IN VARCHAR2) AS request_context UTL_HTTP.REQUEST_CONTEXT_KEY; req UTL_HTTP.REQ; resp UTL_HTTP.RESP; data VARCHAR2(1024); BEGIN -- Create a request context with its wallet and cookie table request_context := UTL_HTTP.CREATE_REQUEST_CONTEXT( wallet_path => 'file:/oracle/wallets/test/wallet', wallet_password => '******', enable_cookies => TRUE, max_cookies => 300, max_cookies_per_site => 20); -- Make a HTTP request using the private wallet and cookie -- table in the request context req := UTL_HTTP.BEGIN_REQUEST( url => url, request_context => request_context); resp := UTL_HTTP.GET_RESPONSE(req); BEGIN LOOP UTL_HTTP.READ_TEXT(resp, data); DBMS_OUTPUT.PUT(data); END LOOP; EXCEPTION WHEN UTL_HTTP.END_OF_BODY THEN UTL_HTTP.END_RESPONSE(resp); END; -- Destroy the request context UTL_HTTP.DESTROY_REQUEST_CONTEXT(request_context); END; BEGIN DISPLAY_PAGE('https://www.example.com/'); END; /
277.5.7 UTL_HTTPによるプロキシ・サーバーの使用
この例では、Oracle Database接続でのプロキシ・サーバーの使用を示します。
UTL_HTTP.REQUEST
プロシージャは、プロキシ・サーバーのホスト名とポート番号を使用して、Oracle Database内からHTTPS URLにアクセスします。
SELECT UTL_HTTP.REQUEST('<URL>', '<proxy_hostname>:<proxy_port_number>', '<wallet_directory>', '<wallet_password>') FROM DUAL;
ノート:
デフォルトでは、UTL_HTTP.REQUEST
プロシージャを使用すると、"proxy"引数を省略するかNULL
として設定することができます。
277.6 UTL_HTTPのデータ構造
データ構造は、要求、応答、Cookie、接続および要求コンテキストを表現するために使用されます。
277.6.1 REQタイプ
このPL/SQLレコード・タイプを使用して、HTTP要求を表します。
構文
TYPE req IS RECORD ( url VARCHAR2(32767), method VARCHAR2(64), http_version VARCHAR2(64));
パラメータ
表277-5 REQタイプのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP要求のURL。 |
|
URLにより識別されたリソースで実行されるメソッド。 |
|
要求の送信に使用されるHTTPプロトコルのバージョン。 |
使用上のノート
インタフェースbegin_request
からREQ
に戻される情報は読取り専用です。レコードのフィールド値を変更しても、要求には影響はありません。
REQ
レコード・タイプには名前がprivate_
という接頭辞で始まる他のフィールドがあります。このフィールドはプライベートで、UTL_HTTP
パッケージの実装で使用することを目的としています。これらのフィールドは変更しないでください。
277.6.2 REQUEST_CONTEXT_KEYタイプ
このタイプは、要求コンテキストへのキーを表すために使用します。
要求コンテキストとは、HTTP要求で使用するプライベートのWalletおよびCookieの表を保持しているコンテキストのことです。プライベートのWalletおよびCookieの表は、パッケージに保持されているセッション全体の表とは異なり、データベース・セッション内の他のHTTP要求と共有されません。
構文
SUBTYPE request_context_key IS PLS_INTEGER;
使用上のノート
セキュリティを強化するために、UTL_HTTP
ではPL/SQLプログラムにより要求コンテキストを作成できます。要求コンテキストはプライベート・コンテキストで、HTTP要求時およびHTTP応答の受信時に同じデータベース・セッション内の他のプログラムと共有されない、WalletおよびCookieの表を保持しています。PL/SQLプログラムで機密情報(認証の資格証明書など)を含むWalletやCookieを使用する場合は、要求コンテキストを使用する必要があります。
277.6.3 RESPタイプ
このPL/SQLレコード・タイプは、HTTP応答を表します。
構文
TYPE resp IS RECORD ( status_code PLS_INTEGER, reason_phrase VARCHAR2(256), http_version VARCHAR2(64));
パラメータ
表277-6 RESPタイプのパラメータ
パラメータ | 説明 |
---|---|
|
Webサーバーにより戻されるステータス・コード。Webサーバーにより処理されるHTTP要求の結果を示す3桁の整数です。 |
|
ステータス・コードを記述するWebサーバーにより戻される短いテキスト・メッセージ。Webサーバーにより処理されるHTTP要求の結果を簡潔に説明します。 |
|
HTTP応答に使用されるHTTPプロトコルのバージョン。 |
使用上のノート
インタフェースGET_RESPONSE
からRESP
に戻される情報は読取り専用です。RESP
レコード・タイプには名前がprivate_
という接頭辞で始まる他のフィールドがあります。このフィールドはプライベートで、UTL_HTTP
パッケージの実装で使用することを目的としています。これらのフィールドは変更しないでください。
277.6.4 COOKIEタイプおよびCOOKIE_TABLEタイプ
COOKIE
タイプは、HTTP Cookieを表すPL/SQLレコード・タイプです。COOKIE_TABLE
タイプは、HTTP Cookieのコレクションを表すPL/SQL索引付き表タイプです。
構文
TYPE cookie IS RECORD ( name VARCHAR2(256), value VARCHAR2(1024), domain VARCHAR2(256), expire TIMESTAMP WITH TIME ZONE, path VARCHAR2(1024), secure BOOLEAN, version PLS_INTEGER, comment VARCHAR2(1024)); TYPE cookie_table IS TABLE OF cookie INDEX BY binary_integer;
COOKIEレコード・タイプのフィールド
表277-7に、COOKIE
およびCOOKIE_TABLE
レコード・タイプのフィールドを示します。
表277-7 COOKIEおよびCOOKIE_TABLEタイプのフィールド
フィールド | 説明 |
---|---|
|
HTTP Cookieの名前。 |
|
Cookieの値。 |
|
Cookieが有効なドメイン。 |
|
Cookieの期限が切れる時刻。 |
|
Cookieを適用するURLのサブセット。 |
|
セキュリティ保護された手段でのみWebサーバーにCookieを戻す必要があります。 |
|
Cookieが準拠するHTTP Cookie仕様のバージョン。NetscapeのCookieの場合、このフィールドは |
|
Cookieの用途を記述したコメント。NetscapeのCookieの場合、このフィールドは |
使用上のノート
PL/SQLプログラムは通常、UTL_HTTP
パッケージに格納されたCookie情報を調査または変更しません。Cookieは、パッケージが透過的に保持します。UTL_HTTP
パッケージ内部で保持され、データベース・セッションの期間のみ存続します。データベース・セッションの期間以降もCookieの保持を必要とするPL/SQLアプリケーションは、GET_COOKIES
を使用してCookieを読み取り、データベース表に永続的に格納し、次のデータベース・セッションでADD_COOKIES
を使用してパッケージにCookieを再度格納できます。cookie
レコードのすべてのフィールド(ただしcommentフィールドは除く)は、格納する必要があります。Cookie情報は変更しないでください。変更すると、Webサーバーでアプリケーション・エラーが発生したり、PL/SQLおよびWebサーバー・アプリケーションのセキュリティが損なわれることがあります。「Cookieの取出しおよびリストア」を参照してください。
277.6.5 CONNECTIONタイプ
このPL/SQLレコード・タイプを使用して、HTTP 1.1プロトコルの仕様に従い、HTTP要求が完了した後に永続的に保持されるネットワーク接続のリモート・ホストおよびTCP/IPポートを表します。永続的なネットワーク接続は、後続のHTTP要求により同じホストおよびポートに対して再利用できます。ネットワーク接続の待機時間が回避されるため、後続のHTTP要求は高速に処理されます。connection_table
は、connection
のPL/SQL表です。
Webサーバーに直接HTTPを永続的に接続する場合は、host
およびport
フィールドにWebサーバーのホスト名およびTCP/IPポート番号が含まれます。proxy_host
およびproxy_port
フィールドは設定されません。プロキシを使用してWebサーバーへの接続に以前使用されていたHTTPに永続的に接続する場合は、proxy_host
およびproxy_port
フィールドにプロキシ・サーバーのホスト名およびTCP/IPポート番号が含まれます。hostおよびportフィールドは設定されません。これは、プロキシ・サーバーに接続している間、永続的接続が特定のターゲットWebサーバーにバインドされないことを示します。プロキシ・サーバーへのHTTPの永続的接続を使用して、プロキシを使用するターゲットWebサーバーにアクセスできます。
SSL
フィールドは、Secured Socket Layer (SSL)がHTTPの永続的接続で使用されているかどうかを示します。HTTPS要求は、SSLを介して作成されたHTTP要求です。プロキシを使用して接続したHTTPS (SSL)の永続的接続の場合は、hostおよびportフィールドにターゲットHTTPS Webサーバーのホスト名およびTCP/IPポート番号が含まれます。これらのフィールドは常に設定されます。プロキシ・サーバーを使用してHTTPS Webサーバーに永続的にHTTPS接続を行った場合は、同じターゲットWebサーバーに別の要求を行う場合にのみ再利用できます。
構文
TYPE connection IS RECORD ( host VARCHAR2(256), port PLS_INTEGER, proxy_host VARCHAR2(256), proxy_port PLS_INTEGER, ssl BOOLEAN); TYPE connection_table IS TABLE OF connection INDEX BY BINARY_INTEGER;
277.7 UTL_HTTPの操作
次のトピックでは、UTL_HTTP
がSQLおよびPL/SQLからHTTP要求を行う方法に関する情報を提供します。
277.7.1 UTL_HTTPの操作フロー
UTL_HTTP
パッケージは、HTTPプロトコルへのアクセスを提供します。
インタフェースは、次の図に示す順序でコールする必要があります。そうでない場合、例外が発生します。
随時、次をコールできます。
-
Cookieを操作する非プロトコル・インタフェース
-
GET_COOKIE_COUNT
-
GET_COOKIES
-
ADD_COOKIES
-
CLEAR_COOKIES
-
-
永続的接続
-
GET_PERSISTENT_CONN_COUNT
-
GET_PERSISTENT_CONNS
-
CLOSE_PERSISTENT_CONN
-
CLOSE_PERSISTENT_CONNS
-
-
UTL_HTTP
パッケージの属性および構成を現行のセッションで操作するインタフェース-
SET_PROXY
-
GET_PROXY
-
SET_COOKIE_SUPPORT
-
GET_COOKIE_SUPPORT
-
SET_FOLLOW_REDIRECT
-
GET_FOLLOW_REDIRECT
-
SET_BODY_CHARSET
-
GET_BODY_CHARSET
-
SET_PERSISTENT_CONN_SUPPORT
-
GET_PERSISTENT_CONN_SUPPORT
-
SET_DETAILED_EXCP_SUPPORT
-
GET_DETAILED_EXCP_SUPPORT
-
SET_WALLET
-
SET_TRANSFER_TIMEOUT
-
GET_TRANSFER_TIMEOUT
-
-
UTL_HTTP
パッケージの最新の詳細な例外コードおよびメッセージを現行のセッションで取り出すインタフェース-
GET_DETAILED_SQLCODE
-
GET_DETAILED_SQLERRM
ノート:
要求および応答のインタフェースによっては、現行のセッションでパッケージの属性および構成を操作するインタフェースと同じ名前を設定できる場合があります。これらは、要求または応答を操作するインタフェースのオーバーロード・バージョンです。
-
277.7.2 UTL_HTTPの単純なHTTPのフェッチ
REQUEST
およびREQUEST_PIECES
は、Uniform Resource Locator(URL)の文字列を使用し、サイトに接続して、そのサイトで取得したデータ(通常はHTML)を戻します。
同一マシン(同一の権限や環境変数など)でブラウザを使用してURLに接続できない場合、REQUEST
またはREQUEST_PIECES
で、そのURLへの接続が成功することは期待できません。
REQUEST
またはREQUEST_PIECES
に失敗した場合(たとえば、例外が発生した場合やHTML形式のエラー・メッセージが戻された場合で、URL引数は正しいと考えられる場合)は、ブラウザで同じURLに接続を試みて、ユーザーのマシンからネットワークの可用性を検証します。ユーザーのブラウザにプロキシ・サーバー・セットがある場合、そのセットは、オプションのproxy
パラメータを使用してREQUEST
またはREQUEST_PIECES
の各コールごとに設定する必要があります。
ノート:
UTL_HTTP
では、環境変数を使用してそのプロキシ動作を指定することもできます。たとえば、UNIXでは、環境変数http_proxy
をURLに設定することによって、そのサービスをHTTP要求のプロキシ・サーバーとして使用するように指定します。また、環境変数no_proxy
をドメイン名に設定することによって、そのドメインのURLではHTTPプロキシ・サーバーを使用しないように指定します。UTL_HTTP
パッケージがOracle Databaseサーバーで実行される場合、データベース・インスタンスの開始時に設定された環境設定が使用されます。
277.7.3 UTL_HTTP HTTP要求
サブプログラムのHTTP要求グループは、HTTP要求を開始し、属性を操作し、要求情報をWebサーバーに送信します。要求が作成されると、現行のセッションのHTTP Cookieサポート、リダイレクトへの準拠、本体文字セット、永続的接続のサポートおよび転送タイムアウトのデフォルト設定が継承されます。これらの設定は、要求インタフェースをコールすることにより変更できます。
参照:
277.7.4 UTL_HTTP HTTP応答
サブプログラムのHTTP応答グループは、GET_RESPONSEから取得したHTTP応答を操作し、Webサーバーから応答情報を受信します。
応答が要求に対して作成されると、要求からHTTP Cookieサポート、リダイレクトへの準拠、本体文字セット、永続的接続のサポートおよび転送タイムアウトについての設定が継承されます。応答インタフェースをコールすることにより変更できるのは、本体文字セットのみです。
参照:
277.7.8 UTL_HTTPのセッションの設定
HTTP要求がデータベースのユーザー・セッション内で実行される場合、セッションの設定によりUTL_HTTP
の構成およびデフォルトの動作を操作します。
要求が作成されると、現行のセッションのHTTP Cookieサポート、リダイレクトへの準拠、本体文字セット、永続的接続のサポートおよび転送タイムアウトのデフォルト設定が継承されます。これらの設定は、要求インタフェースをコールすることにより後で変更できます。要求に対する応答が作成されると、この要求からこれらの設定が継承されます。応答インタフェースをコールすることにより後で変更できるのは、本体文字セットのみです。
参照:
277.7.9 UTL_HTTPの要求コンテキスト
UTL_HTTP
パッケージは、すべてのHTTP要求と応答が共有できる共通のWalletおよびCookieの表をデータベース・セッション内に保持します。これによって、セッション内でWalletを共有したり、Cookieにアプリケーション状態を保持することが容易になります。ただし、同じデータベース・セッション内の他のアプリケーションとは共有しないWalletまたはCookieにプライベート情報を格納するアプリケーションの場合は、固有のWalletおよびCookieの表を保持する要求コンテキストを定義し、それを使用してHTTP要求を行うことができます。
参照:
277.8 UTL_HTTPのサブプログラム・グループ
この項ではUTL_HTTP
サブプログラムについて説明します。これらは、機能ごとにグループ化されています。
277.8.1 UTL_HTTPの単一コール・サブプログラムでの単純なHTTPのフェッチ
REQUEST
およびREQUEST_PIECES
は、Uniform Resource Locator(URL)の文字列を使用し、サイトに接続して、そのサイトで取得したデータ(通常はHTML)を戻します。
表277-8 UTL_HTTPのサブプログラム—単一コールでの単純なHTTPのフェッチ
サブプログラム | 説明 |
---|---|
指定したURLから取り出したデータの最初の2000バイトまでを戻します。このファンクションは、SQL問合せで直接使用できます。 |
|
指定したURLから取り出したデータについて、2000バイト・ピースのPL/SQL表を戻します。 |
277.8.2 UTL_HTTPのセッションの設定サブプログラム
この表では、UTL_HTTP
のセッションの設定サブプログラムをリストし、簡単に説明します。
表277-9 UTL_HTTPのサブプログラム—セッションの設定
サブプログラム | 説明 |
---|---|
将来のHTTP要求すべての本体におけるデフォルトの文字セットを取り出します。 |
|
現在のCookieのサポート設定を取り出します。 |
|
|
|
現行のセッションでのfollow_redirectの設定を取り出します。 |
|
永続的接続のサポートが有効かどうかをチェックし、現行のセッションでの永続的接続の最大回数を取得します。 |
|
現在のプロキシ設定を取り出します。 |
|
応答エラー・チェックが設定されているかどうかをチェックします。 |
|
現在のネットワーク転送のタイムアウト値を取り出します。 |
|
メディア・タイプが |
|
将来のHTTP要求がHTTP Cookieをサポートするかどうかを設定し、現在のデータベース・ユーザー・セッションで保持されるCookieの最大数を設定します。 |
|
|
|
|
|
将来のHTTP要求がHTTP 1.1の永続的接続をサポートするかどうかを設定し、現在のデータベース・ユーザー・セッションで保持される永続的接続の最大回数を設定します。 |
|
HTTPまたは他のプロトコルの要求で使用するプロキシを設定します。 |
|
Webサーバーがエラーを示すステータス・コード(4xxまたは5xx)を戻した場合に、 |
|
|
|
Secure Sockets Layer(SSL)、つまり、HTTPSを経由するHTTP要求すべてに使用するOracle Walletを設定します。 |
277.8.3 UTL_HTTPのHTTP要求サブプログラム
この表では、UTL_HTTP
HTTP要求をリストし、簡単に説明します。
表277-10 UTL_HTTPのサブプログラム—HTTP要求
サブプログラム | 説明 |
---|---|
新しいHTTP要求を開始します。 |
|
HTTP要求ヘッダーを設定します。要求ヘッダーは、設定後ただちにWebサーバーに送信されます。 |
|
HTTP要求ヘッダーのHTTP認証情報を設定します。Webサーバーが要求を認証するにはこの情報が必要です。 |
|
Oracle Walletに格納されているユーザー名とパスワードの資格証明を使用して、Webサーバーで認証される要求に必要なHTTP要求ヘッダーのHTTP認証情報を設定します。 |
|
メディア・タイプが |
|
要求のHTTP Cookieのサポートを有効または無効にします。 |
|
GET_RESPONSEファンクションでの要求に対するHTTP応答において、HTTPリダイレクトの指示に |
|
要求のHTTP 1.1の永続的接続のサポートを有効または無効にします。 |
|
HTTP要求本体にテキスト行を書き込み、改行文字( |
|
HTTP要求本体にバイナリ・データを書き込みます。 |
|
HTTP要求本体にテキスト・データを書き込みます。 |
277.8.4 UTL_HTTPのHTTP要求コンテキスト・サブプログラム
UTL_HTTP
要求コンテキスト・サブプログラムは、要求コンテキストを作成または破棄します。
次の表では、UTL_HTTP
HTTP要求コンテキストをリストし、簡単に説明します。
表277-11 UTL_HTTPのサブプログラム—HTTP要求コンテキスト
サブプログラム | 説明 |
---|---|
|
|
|
277.8.5 UTL_HTTPのHTTP応答サブプログラム
この表では、UTL_HTTP
のHTTP応答サブプログラムを示し、簡単に説明しています。
表277-12 UTL_HTTPのサブプログラム—HTTP応答
サブプログラム | 説明 |
---|---|
HTTP応答を終了します。HTTP要求および応答を完了します。 |
|
Webサーバーが受け入れる要求に必要なHTTP認証情報を、HTTP応答ヘッダーの指示に従って取り出します。 |
|
応答で戻されたn回目のHTTP応答ヘッダーの名前および値を戻します。 |
|
特定のヘッダー名を持つ応答に戻されたHTTP応答ヘッダーの値を戻します。 |
|
応答で戻されたHTTP応答ヘッダーの数を戻します。 |
|
HTTP応答を読み込みます。ファンクションが戻ると、ステータス行およびHTTP応答ヘッダーが読み込まれて処理されます。 |
|
HTTP応答本体を行末までテキスト形式で読み込み、コール元が提供したバッファに出力を戻します。 |
|
HTTP応答本体をバイナリ形式で読み込み、コール元が指定したバッファに出力を戻します。 |
|
HTTP応答本体をテキスト形式で読み込み、コール元が指定したバッファに出力を戻します。 |
|
メディア・タイプがtextで、文字セットが |
277.8.6 UTL_HTTPのHTTP Cookieサブプログラム
HTTP Cookieサブプログラムは、UTL_HTTP
パッケージのCookieを管理します。
次の表では、UTL_HTTP
のCookieサブプログラムを示し、簡単に説明しています。
表277-13 UTL_HTTPのサブプログラム—HTTP Cookie
サブプログラム | 説明 |
---|---|
要求コンテキストまたは |
|
要求コンテキストまたは |
|
要求コンテキストまたは |
|
要求コンテキストまたは |
277.8.7 UTL_HTTPのHTTPの永続的接続サブプログラム
この表では、UTL_HTTP
HTTPの永続的接続サブプログラムをリストし、簡単に説明します。
表277-14 UTL_HTTPのサブプログラム—HTTPの永続的接続
サブプログラム | 説明 |
---|---|
現在のデータベース・セッションで |
|
現在のデータベース・セッションで |
|
|
|
|
277.9 UTL_HTTPサブプログラムの要約
この表は、UTL_HTTP
サブプログラムを示し、簡単に説明しています。
表277-16 UTL_HTTPパッケージのサブプログラム
サブプログラム | 説明 | グループ |
---|---|---|
要求コンテキストまたは |
||
新しいHTTP要求を開始します。 |
||
要求コンテキストまたは |
||
現在のデータベース・セッションで |
||
現在のデータベース・セッションで |
||
|
||
WalletおよびCookieの表に対する、 |
||
HTTP要求を終了します。 |
||
HTTP応答を終了します。HTTP要求および応答を完了します。 |
||
Webサーバーが受け入れる要求に必要なHTTP認証情報を、HTTP応答ヘッダーの指示に従って取り出します。 |
||
将来のHTTP要求すべての本体におけるデフォルトの文字セットを取り出します。 |
||
すべてのWebサーバーにより設定された |
||
現在のCookieのサポート設定を取り出します。 |
||
すべてのWebサーバーにより設定された |
||
|
||
最後に発生した例外の詳細な |
||
最後に発生した例外の詳細な |
||
現行のセッションでのfollow_redirectの設定を取り出します。 |
||
応答で戻されたn回目のHTTP応答ヘッダーの名前および値を戻します。 |
||
特定のヘッダー名を持つ応答に戻されたHTTP応答ヘッダーの値を戻します。 |
||
応答で戻されたHTTP応答ヘッダーの数を戻します。 |
||
|
||
将来のHTTP要求がHTTP 1.1の永続的接続をサポートするかどうかを確認し、現在のデータベース・ユーザー・セッションで保持される永続的接続の最大回数を設定します。 |
||
永続的接続のサポートが有効かどうかを確認し、現行のセッションでの永続的接続の最大回数を取得します(「セッションの設定サブプログラム」を参照)。 |
||
|
||
現在のプロキシ設定を取り出します。 |
||
HTTP応答を読み込みます。ファンクションが戻ると、ステータス行およびHTTP応答ヘッダーが読み込まれて処理されます。 |
||
応答エラー・チェックが設定されているかどうかをチェックします。 |
||
現在のネットワーク転送のタイムアウト値を取り出します。 |
||
HTTP応答本体を行末までテキスト形式で読み込み、コール元が提供したバッファに出力を戻します。 |
||
HTTP応答本体をバイナリ形式で読み込み、コール元が指定したバッファに出力を戻します。 |
||
HTTP応答本体をテキスト形式で読み込み、コール元が指定したバッファに出力を戻します。 |
||
指定したURLから取り出したデータの最初の2000バイトまでを戻します。このファンクションは、SQL問合せで直接使用できます。 |
||
指定したURLから取り出したデータについて、2000バイト・ピースのPL/SQL表を戻します。 |
||
HTTP要求ヘッダーのHTTP認証情報を設定します。Webサーバーが要求を認証するにはこの情報が必要です。 |
||
Oracle Walletに格納されているユーザー名とパスワードの資格証明を使用して、Webサーバーで認証される要求に必要なHTTP要求ヘッダーのHTTP認証情報を設定します。 |
||
メディア・タイプが |
||
メディア・タイプが |
||
メディア・タイプがtextで、文字セットが |
||
要求のHTTP Cookieのサポートを有効または無効にします。 |
||
将来のHTTP要求がHTTP Cookieをサポートするかどうかを設定し、現在のデータベース・ユーザー・セッションで保持されるCookieの最大数を設定します。 |
||
|
||
|
||
|
||
HTTP要求ヘッダーを設定します。要求ヘッダーは、設定後ただちにWebサーバーに送信されます。 |
||
要求のHTTP 1.1の永続的接続のサポートを有効または無効にします。 |
||
HTTPまたは他のプロトコルの要求で使用するプロキシを設定します。 |
||
Webサーバーがエラーを示すステータス・コード(4xxまたは5xx)を戻した場合に、 |
||
|
||
Secure Sockets Layer(SSL)、つまり、HTTPSを経由するHTTP要求すべてに使用するOracle Walletを設定します。 |
||
HTTP要求本体にテキスト行を書き込み、改行文字(UTL_TCPで定義されるCRLF)を使用して行を終了します。 |
||
HTTP要求本体にバイナリ・データを書き込みます。 |
||
HTTP要求本体にテキスト・データを書き込みます。 |
277.9.1 ADD_COOKIESプロシージャ
このプロシージャは、要求コンテキストまたはUTL_HTTP
パッケージのセッション状態のいずれかにCookieを追加します。
構文
UTL_HTTP.ADD_COOKIES ( cookies IN cookie_table, request_context IN request_context_key DEFAULT NULL);
パラメータ
表277-17 ADD_COOKIESプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
追加されるCookie。 |
|
Cookieを追加する要求コンテキスト。 |
使用上のノート
パッケージが現在保持するCookieは、新しいCookieが追加されるまでクリアされません。
277.9.2 BEGIN_REQUESTファンクション
このファンクションは、新しいHTTP要求を開始します。UTL_HTTP
はターゲットWebサーバーまたはプロキシ・サーバーへのネットワーク接続を確立し、HTTP要求行を送信します。PL/SQLプログラムは、他のインタフェースをコールして要求を継続し、完了します。
URLには、サーバーへの要求を認証するために必要なユーザー名とパスワードが含まれている場合があります。書式は次のとおりです。
scheme://[user[:password]@]host[:port]/[...]
参照:
構文
UTL_HTTP.BEGIN_REQUEST ( url IN VARCHAR2, method IN VARCHAR2 DEFAULT 'GET', http_version IN VARCHAR2 DEFAULT NULL, request_context IN request_context_key DEFAULT NULL, https_host IN VARCHAR2 DEFAULT NULL) RETURN req;
パラメータ
表277-18 BEGIN_REQUESTファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP要求のURL。 |
|
URLにより識別されたリソースで実行されるメソッド。 |
|
要求を送信するHTTPプロトコルのバージョン。プロトコル・バージョンの形式は |
|
この |
|
ホスト名を表す文字列。 ワイルドカードで始まらない文字列は、Server Name Indication (SNI)のホスト名として使用されます。 ワイルドカードで始まる文字列は、HTTPS要求時にリモート・サーバーの証明書の共通名(CN)との照合に使用されます。 NULLである場合、SNIには特定のURL内のホスト名が使用されます。 |
使用上のノート
-
このファンクションに引数として渡されたURLについては、URL仕様RFC 2396による不正な文字(空白など)の検証は行われません。コールを実行する場合は、
UTL_URL
パッケージを使用してこのような文字をエスケープする必要があります。URLはUS-ASCII文字のみで構成する必要があります。URLで有効な文字のリストは、「UTL_URL」を参照してください。URLはUS-ASCII文字のみで構成する必要があるので注意してください。それ以外の文字のURLでの使用は避けてください。 -
BEGIN_REQUEST
は、長さが32767バイト以下のURLを送信できます。ただし、受け入れることができるURLの長さの制限はWebサーバーごとに異なります。多くの場合、この制限は4000バイトです。この制限を超えた場合の結果は、Webサーバーによって異なります。たとえば、Webサーバーが応答を戻さずにHTTP接続を削除する場合があります。この場合、続けてGET_RESPONSEファンクションを実行すると、PROTOCOL_ERROR
例外が発生します。URLの
QUERY_STRING
(疑問符(?)の後の情報)が長い場合、URLは長くなります。通常、POST
メソッドを使用して、要求本体でこのパラメータ指定を送信することをお薦めします。req := UTL_HTTP.BEGIN_REQUEST (url=>the_url, method=>'POST'); UTL_HTTP.SET_HEADER (r => req, name => 'Content-Type', value => 'application/x-www-form-urlencoded'); UTL_HTTP.SET_HEADER (r => req, name => 'Content-Length', value =>' <length of data posted in bytes>'); UTL_HTTP.WRITE_TEXT (r => req, data => 'p1 = value1&p2=value2...'); resp := UTL_HTTP.GET_RESPONSE (r => req); ...
プログラマは、特定のWebサーバーがこの方法で提供されたデータを受け入れるかどうかを決定する必要があります。
-
HTTPSを介してWebサーバーにアクセスするには、Oracle Walletを設定する必要があります。Oracle Walletの設定方法については、「SET_WALLETプロシージャ」を参照してください。SSLクライアント認証を使用するには、クライアント証明書をWallet内に格納し、コール側はWalletに対する
use-client-certificates
権限を所有する必要があります。権限の付与については、『Oracle Databaseセキュリティ・ガイド』の外部ネットワーク・サービスへのファイングレイン・アクセスの管理に関する項を参照してください。 -
リモートWebサーバーに直接接続するか、またはHTTPプロキシを介して間接的に接続するには、
UTL_HTTP
に、リモートWebサーバー・ホストまたはプロキシ・ホストそれぞれへのconnect
ACL権限が必要です。
277.9.3 CLEAR_COOKIESプロシージャ
このプロシージャは、要求コンテキストまたはUTL_HTTP
パッケージのセッション状態のいずれかに保持されているCookieをすべてクリアします。
構文
UTL_HTTP.CLEAR_COOKIES ( request_context IN request_context_key DEFAULT NULL);
パラメータ
表277-19 CLEAR_COOKIESプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
Cookieをクリアする要求コンテキスト。 |
277.9.4 CLOSE_PERSISTENT_CONNプロシージャ
このプロシージャは、現在のデータベース・セッションでUTL_HTTP
パッケージが保持するHTTPの永続的接続をクローズします。
構文
UTL_HTTP.CLOSE_PERSISTENT_CONN ( conn IN connection);
パラメータ
表277-20 CLOSE_PERSISTENT_CONNプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
クローズするHTTP永続的接続。 |
277.9.5 CLOSE_PERSISTENT_CONNSプロシージャ
このプロシージャは、現在のデータベース・セッションでUTL_HTTP
パッケージが保持するHTTPの永続的接続のグループをクローズします。このプロシージャは、パターンを一致させる方法を使用して、クローズする永続的接続を判別します。
共通のプロパティ(特定のホストへのすべての接続やすべてのSSL接続など)を共有するHTTP永続的接続のグループをクローズするには、特定のパラメータを設定して残りのパラメータをNULL
にします。このプロシージャがコールされたときにNULL
に設定されていたパラメータは、クローズする接続の判別に使用されません。
たとえば、次のコールをプロシージャに使用して、foobar
への永続的接続をすべてクローズします。
UTL_HTTP.CLOSE_PERSISTENT_CONNS(host => 'foobar');
次のプロシージャ・コールによって、TCP/IPポート80のfoobar
を介した永続的接続がすべて閉じられます。
UTL_HTTP.CLOSE_PERSISTENT_CONNS(proxy_host => 'foobar', proxy_port => 80);
次のコールをプロシージャに使用して、永続的接続をすべてクローズします。
UTL_HTTP.CLOSE_PERSISTENT_CONNS;
構文
UTL_HTTP.CLOSE_PERSISTENT_CONNS ( host IN VARCHAR2 DEFAULT NULL, port IN PLS_INTEGER DEFAULT NULL, proxy_host IN VARCHAR2 DEFAULT NULL, proxy_port IN PLS_INTEGER DEFAULT NULL, ssl IN BOOLEAN DEFAULT NULL);
パラメータ
表277-21 CLOSE_PERSISTENT_CONNSプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
永続的接続をクローズするホスト。 |
|
永続的接続をクローズするポート番号。 |
|
永続的接続をクローズするプロキシ・ホスト。 |
|
永続的接続をクローズするプロキシ・ポート。 |
|
永続的なSSL接続をクローズします。 |
使用上のノート
異なるTCP/IPポートでの同じWebサーバーへの接続は、個別にカウントされます。Webサーバーのホスト名は、元のHTTP要求のURLで指定されたとおりに識別されます。したがって、ドメイン名を持つ完全修飾されたホスト名は、ドメイン名のないホスト名とは別にカウントされます。
このプロシージャがコールされたときにパラメータでNULL
値を使用すると、パッケージでクローズする永続的接続を決定したときに、コール元がその値を無視することを意味します。特定の永続的接続をクローズする場合に永続的接続でNULL
に設定されているパラメータの値のみをNULL
に設定するには、CLOSE_PERSISTENT_CONN
プロシージャを使用して、特定の永続的接続をクローズします。
277.9.6 CREATE_REQUEST_CONTEXTファンクション
このファンクションは、要求コンテキストを作成します。要求コンテキストとは、HTTP要求時にプライベートで使用するWalletおよびCookieを保持しているコンテキストのことです。これによって、HTTP要求では、同じデータベース・セッションでHTTP要求をする他のアプリケーションと共有されないWalletおよびCookieの表を使用できます。
構文
UTL_HTTP.CREATE_REQUEST_CONTEXT ( wallet_path IN VARCHAR2 DEFAULT NULL, wallet_password IN VARCHAR2 DEFAULT NULL, enable_cookies IN BOOLEAN DEFAULT TRUE, max_cookies IN PLS_INTEGER DEFAULT 300, max_cookies_per_site IN PLS_INTEGER DEFAULT 20) RETURN request_context_key;
パラメータ
表277-22 CREATE_REQUEST_CONTEXTファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
Oracle Walletを含むディレクトリ・パス。形式は |
|
Walletのオープンに必要なパスワード。Walletの自動ログインが有効の場合は、パスワードを省略して |
|
この要求コンテキストを使用しているHTTP要求が、HTTP Cookieをサポートするかどうかを設定します。 |
|
この要求コンテキストで保持されるCookieの最大合計数を設定します。 |
|
この要求コンテキストで保持されるWebサイトごとのCookieの最大数を設定します。 |
戻り値
作成された要求コンテキスト。
例
DECLARE request_context UTL_HTTP.REQUEST_CONTEXT_KEY; req utl_http.req; BEGIN request_context := UTL_HTTP.CREATE_REQUEST_CONTEXT( wallet_path => 'file:/oracle/wallets/test_wallets', wallet_password => NULL, enable_cookies => TRUE, max_cookies => 300, max_cookies_per_site => 20); req := UTL_HTTP.BEGIN_REQUEST( url => 'http://www.example.com/', request_context => request_context); END;
277.9.7 DESTROY_REQUEST_CONTEXTプロシージャ
このプロシージャは、UTL_HTTP
の要求コンテキストを破棄します。HTTP要求またはHTTP応答で要求コンテキストが使用されている場合、その要求コンテキストを破棄することはできません。
構文
UTL_HTTP.DESTROY_REQUEST_CONTEXT ( request_context request_context_key);
パラメータ
表277-23 DESTROY_REQUEST_CONTEXTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
request_context |
破棄する要求コンテキスト。 |
例
DECLARE request_context UTL_HTTP.REQUEST_CONTEXT_KEY; BEGIN request_context := UTL_HTTP.CREATE_REQUEST_CONTEXT(…); … UTL_HTTP.DESTROY_REQUEST_CONTEXT(request_context); END;
277.9.8 END_REQUESTプロシージャ
このプロシージャは、HTTP要求を終了します。要求の完了および応答の待機を行わずにHTTP要求を終了するために、プログラムでこのプロシージャをコールできます。または、プログラムは要求の開始、応答の待機、応答のクローズという通常の順序を経て要求を終了することもできます。ネットワーク接続は常にクローズされ、再利用されることはありません。
参照:
構文
UTL_HTTP.END_REQUEST ( r IN OUT NOCOPY req);
パラメータ
表277-24 END_REQUESTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP要求。 |
277.9.9 END_RESPONSEプロシージャ
このプロシージャは、HTTP応答を終了します。HTTP要求および応答を完了します。この要求でHTTP 1.1の永続的接続を使用している場合を除き、ネットワーク接続もクローズされます。
参照:
構文
UTL_HTTP.END_RESPONSE ( r IN OUT NOCOPY resp);
パラメータ
表277-25 END_RESPONSEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP応答。 |
277.9.10 GET_AUTHENTICATIONプロシージャ
このプロシージャは、Webサーバーが受け付ける要求に必要とされるHTTP認証情報をHTTP応答ヘッダーの指示に従って取り出します。
参照:
構文
UTL_HTTP.GET_AUTHENTICATION( r IN OUT NOCOPY resp, scheme OUT VARCHAR2, realm OUT VARCHAR2, for_proxy IN BOOLEAN DEFAULT FALSE);
パラメータ
表277-26 GET_AUTHENTICATIONプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP応答。 |
|
要求されたHTTP認証のスキーム。 |
|
要求されたHTTP認証のレルム。 |
|
WebサーバーではなくHTTPプロキシ・サーバーにアクセスするために必要なHTTP認証情報を戻します。デフォルトは |
使用上のノート
ドキュメントが保護されていることをWebクライアントが認識していない場合、そのドキュメントを取り出すには少なくとも2つのHTTP要求が必要です。最初のHTTP要求で、Webクライアントは必要な認証情報を提供せずに要求を作成します。したがって、この要求は拒否されます。Webクライアントは、GET_AUTHENTICATION
をコールすることにより、認証対象となる要求に必要な認証情報を判別します。Webクライアントは2回目の要求を行い、SET_AUTHORIZATION
を使用して必要な認証情報を提供します。Webサーバーが認証情報を検証できると、要求は正常に処理され、要求したドキュメントが戻されます。要求を行う前に、認証情報が必要であることをWebクライアントが認識している場合は、最初の要求で必要な認証情報を提供できます。これにより、余分な要求を行わずに済みます。
277.9.11 GET_BODY_CHARSETプロシージャ
このプロシージャは、将来のHTTP要求すべての本体におけるデフォルトの文字セットを取り出します。
参照:
構文
UTL_HTTP.GET_BODY_CHARSET ( charset OUT NOCOPY VARCHAR2);
パラメータ
表277-27 GET_BODY_CHARSETプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
将来のHTTP要求すべての本体におけるデフォルトの文字セット。 |
277.9.12 GET_COOKIE_COUNTファンクション
このファンクションは、要求コンテキストまたはUTL_HTTP
パッケージのセッション状態のいずれかに保持されているCookieの数を戻します。
構文
UTL_HTTP.GET_COOKIE_COUNT ( request_context IN request_context_key DEFAULT NULL) RETURN PLS_INTEGER;
パラメータ
表277-28 GET_COOKIE_COUNTファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
Cookieの数が戻される要求コンテキスト。 |
277.9.13 GET_COOKIE_SUPPORTプロシージャ
このプロシージャは、現在のCookieサポート設定を取り出します。
参照:
構文
UTL_HTTP.GET_COOKIE_SUPPORT ( enable OUT BOOLEAN, max_cookies OUT PLS_INTEGER, max_cookies_per_site OUT PLS_INTEGER);
パラメータ
表277-29 GET_COOKIE_SUPPORTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
将来のHTTP要求がHTTP Cookieをサポートするかどうかを設定します( |
|
現在のデータベース・ユーザー・セッションで保持されるCookieの最大合計数を示します。 |
|
現行のセッションで各Webサイトについて保持されるCookieの最大合計数を示します。 |
277.9.14 GET_COOKIESファンクション
このファンクションは、要求コンテキストまたはUTL_HTTP
パッケージのセッション状態のいずれかに保持されているCookieをすべて戻します。
構文
UTL_HTTP.GET_COOKIES ( cookies IN OUT NOCOPY cookie_table, request_context IN request_context_key DEFAULT NULL);
パラメータ
表277-30 GET_COOKIESファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
戻されるCookie。 |
|
Cookieが戻される要求コンテキスト。 |
277.9.15 GET_DETAILED_EXCP_SUPPORTプロシージャ
このプロシージャは、UTL_HTTP
パッケージが詳細な例外を呼び出すかどうかをチェックします。
参照:
構文
UTL_HTTP.GET_DETAILED_EXCP_SUPPORT ( enable OUT BOOLEAN);
パラメータ
表277-31 GET_DETAILED_EXCP_SUPPORTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
|
277.9.16 GET_DETAILED_SQLCODEファンクション
このファンクションは、最後に発生した例外の詳細なSQLCODE
を取り出します。
参照:
構文
UTL_HTTP.GET_DETAILED_SQLCODE RETURN PLS_INTEGER;
277.9.17 GET_DETAILED_SQLERRMファンクション
このファンクションは、最後に発生した例外の詳細なSQLERRM
を取り出します。
参照:
構文
UTL_HTTP.GET_DETAILED_SQLERRM RETURN VARCHAR2;
277.9.18 GET_FOLLOW_REDIRECTプロシージャ
このプロシージャは、現行のセッションでのfollow_redirect設定を取り出します。
参照:
構文
UTL_HTTP.GET_FOLLOW_REDIRECT ( max_redirects OUT PLS_INTEGER);
パラメータ
表277-32 GET_FOLLOW_REDIRECTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
将来のHTTP要求すべてに対するリダイレクトの最大回数。 |
277.9.19 GET_HEADERプロシージャ
このプロシージャは、応答で戻されたn回目のHTTP応答ヘッダーの名前および値を戻します。
参照:
構文
UTL_HTTP.GET_HEADER ( r IN OUT NOCOPY resp, n IN PLS_INTEGER, name OUT NOCOPY VARCHAR2, value OUT NOCOPY VARCHAR2);
パラメータ
表277-33 GET_HEADERプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP応答。 |
|
n番目に戻されるヘッダー。 |
|
HTTP応答ヘッダーの名前。 |
|
HTTP応答ヘッダーの値。 |
使用上のノート
リモートWebサーバーから戻された応答本体がchunked transfer encoding形式でエンコードされている場合、応答本体の末尾で戻される追跡ヘッダーが応答に追加され、応答ヘッダーのカウントが更新されます。応答本体の末尾に到達した後、応答を終了する前に追加ヘッダーを取り出すことができます。
277.9.20 GET_HEADER_BY_NAMEプロシージャ
このプロシージャは、特定のヘッダー名を持つ応答に戻されたHTTP応答ヘッダーの値を戻します。
参照:
構文
UTL_HTTP.GET_HEADER_BY_NAME( r IN OUT NOCOPY resp, name IN VARCHAR2, value OUT NOCOPY VARCHAR2, n IN PLS_INTEGER DEFAULT 1);
パラメータ
表277-34 GET_HEADER_BY_NAMEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP応答。 |
|
値が戻されるHTTP応答ヘッダーの名前。 |
|
HTTP応答ヘッダーの値。 |
|
戻すように指定した名前によりn番目に発生するHTTP応答ヘッダー。デフォルトは1です。 |
使用上のノート
リモートWebサーバーから戻された応答本体がchunked transfer encoding形式でエンコードされている場合、応答本体の末尾で戻される追跡ヘッダーが応答に追加され、応答ヘッダーのカウントが更新されます。応答本体の末尾に到達した後、応答を終了する前に追加ヘッダーを取り出すことができます。
277.9.21 GET_HEADER_COUNTファンクション
このファンクションは、応答で戻されたHTTP応答ヘッダーの数を戻します。
参照:
構文
UTL_HTTP.GET_HEADER_COUNT ( r IN OUT NOCOPY resp) RETURN PLS_INTEGER;
パラメータ
表277-35 GET_HEADER_COUNTファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP応答。 |
使用上のノート
リモートWebサーバーから戻された応答本体がchunked transfer encoding形式でエンコードされている場合、応答本体の末尾で戻される追跡ヘッダーが応答に追加され、応答ヘッダーのカウントが更新されます。応答本体の末尾に到達した後、応答を終了する前に追加ヘッダーを取り出すことができます。
277.9.22 GET_PERSISTENT_CONN_COUNTファンクション
このファンクションは、UTL_HTTP
パッケージにより現在永続的に保持されているネットワーク接続数をWebサーバーに戻します。
構文
UTL_HTTP.GET_PERSISTENT_CONN_COUNT RETURN PLS_INTEGER;
使用上のノート
異なるTCP/IPポートでの同じWebサーバーへの接続は、個別にカウントされます。Webサーバーのホスト名は、元のHTTP要求のURLで指定されたとおりに識別されます。したがって、ドメイン名を持つ完全修飾されたホスト名は、ドメイン名のないホスト名とは別にカウントされます。
277.9.23 GET_PERSISTENT_CONN_SUPPORTプロシージャ
このプロシージャは、永続的接続のサポートが有効かどうかをチェックし、現行のセッションでの永続的接続の最大回数を取得します。
参照:
構文
UTL_HTTP.GET_PERSISTENT_CONN_SUPPORT ( enable OUT BOOLEAN, max_conns OUT PLS_INTEGER);
パラメータ
表277-36 GET_PERSISTENT_CONN_SUPPORTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
永続的接続サポートが有効にされている場合は |
|
現行のセッションで保持される永続的接続の最大数。 |
277.9.24 GET_PERSISTENT_CONNSプロシージャ
このプロシージャは、UTL_HTTP
パッケージにより現在永続的に保持されているネットワーク接続をすべてWebサーバーに戻します。
構文
UTL_HTTP.get_persistent_conns ( connections IN OUT NOCOPY connection_table);
パラメータ
表277-37 GET_PERSISTENT_CONNSプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
永続的に保持されているネットワーク接続。 |
使用上のノート
異なるTCP/IPポートでの同じWebサーバーへの接続は、個別にカウントされます。Webサーバーのホスト名は、元のHTTP要求のURLで指定されたとおりに識別されます。したがって、ドメイン名を持つ完全修飾されたホスト名は、ドメイン名のないホスト名とは別にカウントされます。
277.9.25 GET_PROXYプロシージャ
このプロシージャは、現在のプロキシ設定を取り出します。
参照:
構文
UTL_HTTP.GET_PROXY ( proxy OUT NOCOPY VARCHAR2, no_proxy_domains OUT NOCOPY VARCHAR2);
パラメータ
表277-38 GET_PROXYプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
プロキシをすべての要求に対して使用しないホストおよびドメインのリスト。 |
277.9.26 GET_RESPONSEファンクション
このファンクションは、HTTP応答を読み込みます。
ファンクションが戻ると、ステータス行およびHTTP応答ヘッダーが読み込まれて処理されます。ステータス・コード、理由、HTTPプロトコルのバージョンは応答レコードに格納されます。このファンクションは、HTTPヘッダー・セクションを完了します。
参照:
構文
UTL_HTTP.GET_RESPONSE ( r IN OUT NOCOPY req, return_info_response IN BOOLEAN DEFAULT FALSE) RETURN resp;
パラメータ
表277-39 GET_RESPONSEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP応答。 |
|
100情報レスポンスを戻すか戻さないか。
|
例外
-
詳細例外を無効にした場合:
ORA-29273 REQUEST_FAILED
- 要求の実行に失敗しました。詳細なエラー・メッセージを取得するには、GET_DETAILED_EXCP_SUPPORTプロシージャとGET_DETAILED_SQLERRMファンクションを使用します。 -
詳細例外を有効にした場合:
ORA-29261 BAD_ARGUMENT
- 渡された引数の一部が無効です。 -
レスポンス・エラー検査を有効にした場合:
ORA-29268 HTTP_CLIENT_ERROR
- レスポンス・コードは400範囲内にあります。ORA-29269 HTTP_SERVER_ERROR
- レスポンス・コードは500範囲内にあります。
使用上のノート
-
例外が発生したかしないかに関係なく、このファンクションが戻ると要求は終了します。END_REQUESTプロシージャを起動する必要はありません。
-
URLリダイレクトが行われると、
REQ
レコードのURLおよびmethodフィールドは、最後にリダイレクトされたURL、およびそのURLへのアクセスに使用されたメソッドに更新されます。
例
特定の状況では(HTTPクライアントによって開始された、または開始されていない)、HTTPサーバーは1xx
情報レスポンスを戻す場合があります。このようなレスポンスを予期していないユーザーは、レスポンスを無視して通常のレスポンスの受信に進むようにGET_RESPONSE
に指示できます。ユーザーがこのようなレスポンスを予期している場合、ユーザーはレスポンスを戻すようにGET_RESPONSE
に指示できます。
たとえば、ユーザーが大きな要求本体を含むHTTP
POST
要求を発行する場合に、サーバーがデータを送信する前に要求を受け入れるように、HTTPサーバーを検査できます。このためには、ユーザーは追加のEXPECT: 100-CONTINUE
要求ヘッダーを送信し、要求本体の送信に進む前に、サーバーから100 CONTINUE
レスポンスがあるかどうか検査できます。その後、ユーザーは通常のHTTPレスポンスを受け取ります。
次に、コードの例を示します。
DECLARE data VARCHAR2(1024) := '...'; req utl_http.req; resp utl_http.resp; BEGIN req := utl_http.begin_request('http://www.acme.com/receiver', 'POST'); utl_http.set_header(req, 'Content-Length', length(data)); -- Ask HTTP server to return "100 Continue" response utl_http.set_header(req, 'Expect', '100-continue'); resp := utl_http.get_response(req, TRUE); -- Check for and dispose "100 Continue" response IF (resp.status_code <> 100) THEN utl_http.end_response(resp); raise_application_error(20000, 'Request rejected'); END IF; utl_http.end_response(resp); -- Now, send the request body utl_http.write_text(req, data); -- Get the regular response resp := utl_http.get_response(req); utl_http.read_text(resp, data); utl_http.end_response(resp); END;
277.9.27 GET_RESPONSE_ERROR_CHECKプロシージャ
このプロシージャは、応答エラー・チェックが設定されているかどうかをチェックします。
参照:
構文
UTL_HTTP.GET_RESPONSE_ERROR_CHECK ( enable OUT BOOLEAN);
パラメータ
表277-40 GET_RESPONSE_ERROR_CHECKプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
応答エラー・チェックが設定されている場合は |
277.9.28 GET_TRANSFER_TIMEOUTプロシージャ
このプロシージャは、将来のHTTP要求に対するデフォルトのタイムアウト値を取り出します。
参照:
構文
UTL_HTTP.GET_TRANSFER_TIMEOUT ( timeout OUT PLS_INTEGER);
パラメータ
表277-41 GET_TRANSFER_TIMEOUTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
ネットワーク転送のタイムアウト値(秒)。 |
277.9.29 READ_LINEプロシージャ
このプロシージャは、HTTP応答本体を行末までテキスト形式で読み込み、コール元が提供したバッファに出力を戻します。
行末は、UTL_TCPのread_line
ファンクションで定義されます。HTTP応答本体の終端に到達した場合、end_of_body
例外が発生します。テキスト・データは、応答本体の文字セットからデータベース文字セットに自動的に変換されます。
参照:
構文
UTL_HTTP.READ_LINE( r IN OUT NOCOPY resp, data OUT NOCOPY VARCHAR2 CHARACTER SET ANY_CS, remove_crlf IN BOOLEAN DEFAULT FALSE);
パラメータ
表277-42 READ_LINEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP応答。 |
|
テキスト形式のHTTP応答本体。 |
|
|
使用上のノート
UTL_HTTP
パッケージは、HTTP 1.1 chunked transfer-encodingをサポートしています。応答ヘッダーで指定されたchunked transfer-encoding形式で応答本体が戻された場合、パッケージは自動的にチャンクをデコードし、チャンクを解除した形式の応答本体を戻します。
転送のタイムアウトがこの応答の要求で設定されている場合、read_line
は、タイムアウトが発生するまでの間、各データ・パケットが読み込まれるまで待機します。タイムアウトが発生すると、このプロシージャは読込みを停止し、正常に読み込んだデータをすべて戻します。正常に読み込まれたデータがない場合は、transfer_timeout
例外が発生します。例外を処理し、読込み操作を後で再試行できます。
マルチバイト文字の一部が応答本体の終わりで検出された場合、read_line
は読込みを中止し、正常かつ完全に読み込まれたマルチバイト文字をすべて戻します。正常に読み込まれた文字がない場合は、partial_multibyte_char
例外が発生します。read_raw
プロシージャを使用して例外を処理し、部分的なマルチバイト文字のバイトをバイナリとして読み込むことができます。マルチバイト文字の一部が渡されていない状態でタイムアウトが発生し、応答本体の途中でマルチバイト文字の残りの部分が表示された場合は、transfer_timeout
例外が発生します。例外を処理し、読込み操作を後で再試行できます。
Content-Type
応答ヘッダーによって指定されている応答本体の文字セットが不明であるか、Oracleではサポートされていない場合に、応答本体をテキストとして読み取ろうとすると、「ORA-01482: 指定された文字セットはサポートされていません。」という例外が発生します。応答本体は、READ_RAW
プロシージャを使用してバイナリとして読み込むか、SET_BODY_CHARSET
プロシージャを使用して、その応答本体の文字セットを明示的に設定することで再度テキストとして読み込むことができます。
277.9.30 READ_RAWプロシージャ
このプロシージャは、HTTP応答本体をバイナリ形式で読み込み、コール元が提供したバッファに出力を戻します。
HTTP応答本体の終端に到達した場合、end_of_body
例外が発生します。
参照:
構文
UTL_HTTP.READ_RAW( r IN OUT NOCOPY resp, data OUT NOCOPY RAW, len IN PLS_INTEGER DEFAULT NULL);
パラメータ
表277-43 READ_RAWプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP応答。 |
|
バイナリ形式のHTTP応答本体。 |
|
読み込むデータのバイト数。 |
使用上のノート
UTL_HTTP
パッケージは、HTTP 1.1 chunked transfer-encodingをサポートしています。応答ヘッダーで指定されたchunked transfer-encoding形式で応答本体が戻された場合、パッケージは自動的にチャンクをデコードし、チャンクを解除した形式の応答本体を戻します。
転送のタイムアウトがこの応答の要求で設定されている場合、read_raw
は、タイムアウトが発生するまでの間、各データ・パケットが読み込まれるまで待機します。タイムアウトが発生すると、read_raw
は読込みを停止し、正常に読み込んだデータをすべて戻します。正常に読み込まれたデータがない場合は、transfer_timeout
例外が発生します。例外を処理し、読込み操作を後で再試行できます。
277.9.31 READ_TEXTプロシージャ
このプロシージャは、HTTP応答本体をテキスト形式で読み込み、コール元が提供したバッファに出力を戻します。
HTTP応答本体の終端に到達した場合、end_of_body
例外が発生します。テキスト・データは、応答本体の文字セットからデータベース文字セットに自動的に変換されます。
参照:
構文
UTL_HTTP.READ_TEXT( r IN OUT NOCOPY resp, data OUT NOCOPY VARCHAR2 CHARACTER SET ANY_CS, len IN PLS_INTEGER DEFAULT NULL);
パラメータ
表277-44 READ_TEXTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP応答。 |
|
テキスト形式のHTTP応答本体。 |
|
読み込まれるデータの最大文字数。 |
使用上のノート
UTL_HTTP
パッケージは、HTTP 1.1 chunked transfer-encodingをサポートしています。応答ヘッダーで指定されたchunked transfer-encoding形式で応答本体が戻された場合、パッケージは自動的にチャンクをデコードし、チャンクを解除した形式の応答本体を戻します。
転送のタイムアウトがこの応答の要求で設定されている場合、read_text
は、タイムアウトが発生するまでの間、各データ・パケットが読み込まれるまで待機します。タイムアウトが発生すると、このプロシージャは読込みを停止し、正常に読み込んだデータをすべて戻します。正常に読み込まれたデータがない場合は、transfer_timeout
例外が発生します。例外を処理し、読込み操作を後で再試行できます。
マルチバイト文字の一部が応答本体の終わりで検出された場合、read_text
は読込みを中止し、正常かつ完全に読み込まれたマルチバイト文字をすべて戻します。正常に読み込まれた文字がない場合は、partial_multibyte_char
例外が発生します。read_raw
プロシージャを使用して例外を処理し、部分的なマルチバイト文字のバイトをバイナリとして読み込むことができます。マルチバイト文字の一部が渡されていない状態でタイムアウトが発生し、応答本体の途中でマルチバイト文字の残りの部分が表示された場合は、transfer_timeout
例外が発生します。例外を処理し、読込み操作を後で再試行できます。
Content-Type
応答ヘッダーによって指定されている応答本体の文字セットが不明であるか、Oracleでサポートされていない場合に、応答本体をテキストとして読み込もうとすると、「ORA-01482: 指定された文字セットはサポートされていません。
」という例外が発生します。応答本体は、READ_RAW
プロシージャを使用してバイナリとして読み込むか、SET_BODY_CHARSET
プロシージャを使用して、その応答本体の文字セットを明示的に設定することで再度テキストとして読み込むことができます。
277.9.32 REQUESTファンクション
このファンクションは、指定したURLから取り出したデータの最初の2000バイトまでを戻します。
このファンクションは、SQL問合せで直接使用できます。URLには、サーバーへの要求を認証するために必要なユーザー名とパスワードが含まれている場合があります。書式は次のとおりです。
scheme://[user[:password]@]host[:port]/[...]
プロキシ文字列の中で指定するプロキシのユーザー名またはパスワード、あるいはその両方を定義できます。書式は次のとおりです。
[http://][user[:password]@]host[:port][/]
構文
UTL_HTTP.REQUEST ( url IN VARCHAR2, proxy IN VARCHAR2 DEFAULT NULL, wallet_path IN VARCHAR2 DEFAULT NULL, wallet_password IN VARCHAR2 DEFAULT NULL, https_host IN VARCHAR2 DEFAULT NULL) RETURN VARCHAR2;
プラグマ
pragma restrict_references (request, wnds, rnds, wnps, rnps);
パラメータ
表277-45 REQUESTファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
URL。 |
|
(オプション)HTTP要求時に使用するプロキシ・サーバーを指定します。プロキシ設定の完全な形式については、 |
|
(オプション)クライアント側のWalletを指定します。クライアント側のWalletには、HTTPS要求に必要な信頼されている認証局のリストが含まれています。
|
|
(オプション)Walletのオープンに必要なパスワードを指定します。 |
|
ホスト名を表す文字列。 ワイルドカードで始まらない文字列は、Server Name Indication (SNI)のホスト名として使用されます。 ワイルドカードで始まる文字列は、HTTPS要求時にリモート・サーバーの証明書の共通名(CN)との照合に使用されます。 NULLである場合、SNIには特定のURL内のホスト名が使用されます。 |
戻り値
戻りタイプは長さ2000以下の文字列で、引数URLへのHTTP要求から戻されたHTML結果から最初の2000バイトまでが含まれます。
例外
INIT_FAILED REQUEST_FAILED
使用上のノート
このファンクションに引数として渡されたURLでは、URL仕様RFC 2396に従った不正文字(空白など)の検証は行われません。コール元は、UTL_URLパッケージを使用して、このような文字をエスケープする必要があります。URLで有効な文字のリストについては、パッケージのコメントを参照してください。URLはUS-ASCII文字のみで構成する必要があるので注意してください。それ以外の文字のURLでの使用は避けてください。
Oracle Walletの使用方法については、SET_WALLET
ファンクションのマニュアルを参照してください。Oracle Walletは、HTTPS Webサーバーへのアクセスに必要です。
応答エラー・チェックがオンにされないかぎり、Webサーバーから4xxまたは5xxの応答を受信してもこのファンクションが例外を呼び出すことはありません。そのかわりに、Webサーバーからフォーマット・エラー・メッセージが戻されます。
<HTML> <HEAD> <TITLE>Error Message</TITLE> </HEAD> <BODY> <H1>Fatal Error 500</H1> Can't Access Document: http://home.nothing.comm. <P> <B>Reason:</B> Can't locate remote host: home.nothing.comm. <P> <P><HR> <ADDRESS><A HREF="http://www.w3.org"> CERN-HTTPD3.0A</A></ADDRESS> </BODY> </HTML>
例
SQL> SELECT UTL_HTTP.REQUEST('http://www.my-company.com/') FROM DUAL; UTL_HTTP.REQUEST('HTTP://WWW.MY-COMPANY.COM/') <html> <head><title>My Company Home Page</title> <!--changed Jan. 16, 19 1 row selected.
firewallの内側にいる場合は、proxy
パラメータを含めます。たとえば、Oracle firewall内には、www-proxy
.my-company.com
という名前のプロキシ・サーバーがある場合があります。
SQLPLUS> SELECT UTL_HTTP.REQUEST('http://www.my-company.com', 'www-proxy.us.my-company.com') FROM DUAL;
277.9.33 REQUEST_PIECESファンクション
このファンクションは、指定したURLから取り出したデータについて、2000バイト・ピースのPL/SQL表を戻します。
プロキシ文字列の中で指定するプロキシのユーザー名またはパスワード、あるいはその両方を定義できます。書式は次のとおりです。
[http://][user[:password]@]host[:port][/]
構文
TYPE html_pieces IS TABLE OF VARCHAR2(2000) INDEX BY BINARY_INTEGER; UTL_HTTP.REQUEST_PIECES ( url IN VARCHAR2, max_pieces IN NATURAL DEFAULT 32767, proxy IN VARCHAR2 DEFAULT NULL, wallet_path IN VARCHAR2 DEFAULT NULL, wallet_password IN VARCHAR2 DEFAULT NULL, https_host IN VARCHAR2 DEFAULT NULL) RETURN html_pieces;
プラグマ
PRAGMA RESTRICT_REFERENCES (request_pieces, WNDS, RNDS, WNPS, RNPS);
パラメータ
表277-46 REQUEST_PIECESファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
URL。 |
|
(オプション) |
|
(オプション)HTTP要求時に使用するプロキシ・サーバーを指定します。プロキシ設定の完全な形式については、 |
|
(オプション)クライアント側のWalletを指定します。クライアント側のWalletには、HTTPS要求に必要な信頼されている認証局のリストが含まれています。 wallet_pathの形式は、たとえば、PCでは Oracle Walletの設定方法については、 |
|
(オプション)Walletのオープンに必要なパスワードを指定します。 |
|
ホスト名を表す文字列。 ワイルドカードで始まらない文字列は、Server Name Indication (SNI)のホスト名として使用されます。 ワイルドカードで始まる文字列は、HTTPS要求時にリモート・サーバーの証明書の共通名(CN)との照合に使用されます。 NULLである場合、SNIには特定のURL内のホスト名が使用されます。 |
戻り値
REQUEST_PIECES
は、UTL_HTTP
.HTML_PIECES
タイプのPL/SQL表を戻します。PL/SQL表の各要素は、最大長2,000の文字列です。REQUEST_PIECES
により戻されるPL/SQL表の要素は、そのURLに対してHTTP要求から取得した連続データです。
例外
INIT_FAILED REQUEST_FAILED
使用上のノート
このファンクションに引数として渡されたURLでは、URL仕様RFC 2396に従った不正文字(空白など)の検証は行われません。コール元は、UTL_URL
パッケージを使用して、このような文字をエスケープする必要があります。URLで有効な文字のリストについては、パッケージのコメントを参照してください。URLはUS-ASCII文字のみで構成する必要があるので注意してください。それ以外の文字のURLでの使用は避けてください。
このファンクションにより戻されるPL/SQL表の各エントリ(情報の断片)は、容量を完全に満たさない場合があります。このファンクションでは、前の断片が完全に満たされる前に、次の断片にデータが到着し始めます。
Oracle Walletの使用方法については、SET_WALLET
ファンクションのマニュアルを参照してください。Oracle Walletは、HTTPS Webサーバーへのアクセスに必要です。
応答エラー・チェックがオンにされないかぎり、Webサーバーから4xxまたは5xxの応答を受信してもこのファンクションが例外を呼び出すことはありません。そのかわりに、Webサーバーからフォーマット・エラー・メッセージが戻されます。
<HTML> <HEAD> <TITLE>Error Message</TITLE> </HEAD> <BODY> <H1>Fatal Error 500</H1> Can't Access Document: http://home.nothing.comm. <P> <B>Reason:</B> Can't locate remote host: home.nothing.comm. <P> <P><HR> <ADDRESS><A HREF="http://www.w3.org"> CERN-HTTPD3.0A</A></ADDRESS> </BODY> </HTML>
例
SET SERVEROUTPUT ON DECLARE x UTL_HTTP.HTML_PIECES; len PLS_INTEGER; BEGIN x := UTL_HTTP.REQUEST_PIECES('http://www.oracle.com/', 100); DBMS_OUTPUT.PUT_LINE(x.count || ' pieces were retrieved.'); DBMS_OUTPUT.PUT_LINE('with total length '); IF x.count < 1 THEN DBMS_OUTPUT.PUT_LINE('0'); ELSE len := 0; FOR i in 1..x.count LOOP len := len + length(x(i)); END LOOP; DBMS_OUTPUT.PUT_LINE(len); END IF; END; / -- Output Statement processed. 4 pieces were retrieved. with total length 7687
277.9.34 SET_AUTHENTICATIONプロシージャ
このプロシージャは、HTTP要求ヘッダーのHTTP認証情報を設定します。Webサーバーが要求を認証するにはこの情報が必要です。
参照:
UTL_HTTPの認証スキーム
チャレンジおよび応答ワークフローは次のとおりです。
- クライアントがサーバーにHTTP要求を送信します。
- サーバーがクライアントに401 (Unauthorized)応答ステータスで応答します。また、少なくとも1つの認証スキーム・チャレンジを含むWWW-Authenticate応答ヘッダーを使用して、認可方法に関する情報を提供します。
ノート:
サーバーが複数のチャレンジで応答する場合は、優先度が最も高いアルゴリズムから始めて、それよりも優先度が低いアルゴリズムへと優先順に応答します。 - クライアントが、アルゴリズム、レルム、nonceなど、チャレンジ・ヘッダーの値を使用して作成された資格証明とともに認可要求ヘッダーを含む要求を発行することにより、サーバーに対して自身を認証します。
ノート:
UTL_HTTPでは、Digest SHA-256アルゴリズムがサポートされています。
Digest認証
認証スキームは、UTL_HTTP.SET_AUTHENTICATIONコールを使用して、Webサーバーによって認可されるHTTP要求ヘッダーに設定されます。Digestは、UTL_HTTPでサポートされている認証スキームの1つです。その他の認証スキームは、Basic、AWS、AWS4、BMCおよびAZUREです。
Digest認証スキームを使用したUTL_HTTPの要求および応答フローは、次のとおりです。
- UTL_HTTP.BEGIN_REQUEST- このファンクションは、WebサーバーにHTTP要求を送信します。
- UTL_HTTP.SET_AUTHENTICATION- このファクションは、HTTP要求ヘッダーの認証情報を設定します
- ULT_HTTP.GET_RESPONSE- このファンクションは、Webサーバーから応答を取得します
- サーバーは、チャレンジ・ヘッダーとともに「401 Unauthorized」と応答します。
- SHA 256アルゴリズムを使用して、チャレンジ・ヘッダーの値でDigest資格証明を作成します。
- 要求の再送信には、Digest資格証明とともに認可要求ヘッダーが含まれます。
- サーバーは要求を処理し、応答します(通常は200-OK)。
構文
UTL_HTTP.SET_AUTHENTICATION( r IN OUT NOCOPY req, username IN VARCHAR2, password IN VARCHAR2, scheme IN VARCHAR2 DEFAULT 'Basic', for_proxy IN BOOLEAN DEFAULT FALSE);
パラメータ
表277-47 SET_AUTHENTICATIONプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP要求。 |
|
HTTP認証のユーザー名。 |
|
HTTP認証のパスワード。 |
|
HTTP認証方式。 |
|
HTTP認証情報がWebサーバーではなくHTTPプロキシ・サーバーにアクセスするためのものであるかどうかを識別します。デフォルトは |
使用上のノート
サポートされている認証方式は、HTTP基本認証およびAmazon S3認証です。
277.9.35 SET_AUTHENTICATION_FROM_WALLETプロシージャ
このプロシージャは、Oracle Walletに格納されているユーザー名とパスワードの資格証明を使用して、Webサーバーで認証される要求に必要なHTTP要求ヘッダーのHTTP認証情報を設定します。
参照:
構文
UTL_HTTP.SET_AUTHENTICATION_FROM_WALLET( r IN OUT NOCOPY req, alias IN VARCHAR2, scheme IN VARCHAR2 DEFAULT 'Basic', for_proxy IN BOOLEAN DEFAULT FALSE);
パラメータ
表277-48 SET_AUTHENTICATION_FROM_WALLETプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP要求。 |
|
Oracle Walletに格納されているユーザー名とパスワードを識別して取得するための別名。 |
|
HTTP認証方式。 |
|
HTTP認証情報がWebサーバーではなくHTTPプロキシ・サーバーにアクセスするためのものであるかどうかを識別します。デフォルトは |
使用上のノート
-
Wallet内のパスワードの資格証明を使用するには、
UTL_HTTP
ユーザーにWalletに対するuse-passwords
権限が必要です。 -
サポートされている認証方式は、HTTP基本認証方式およびAmazon S3認証方式です。
例
Walletを作成し、Walletにユーザー名とパスワードを入力する場合
> mkstore -wrl /oracle/wallets/test_wallet -create Enter password: ****** Enter password again: ****** > mkstore –wrl /oracle/wallets/test_wallet –createCredential hr-access jsmith Your secret/Password is missing in the command line Enter your secret/Password: **** Re-enter your secret/Password: **** Enter wallet password: ******
データベース管理者が、Walletに対するuse-passwords権限をユーザーに付与する場合
BEGIN DBMS_NETWORK_ACL_ADMIN.CREATE_ACL( acl => 'wallet-acl.xml', description => 'Wallet ACL', principal => 'SCOTT', is_grant => TRUE, privilege => 'use-passwords'); DBMS_NETWORK_ACL_ADMIN.ASSIGN_WALLET_acl( acl => 'wallet-acl.xml', wallet_path => 'file: /oracle/wallets/test_wallet'); END;
Wallet内のユーザー名とパスワードを使用する場合
DECLARE req UTL_HTTP.req; BEGIN UTL_HTTP.SET_WALLET(path => 'file:/oracle/wallets/test_wallet'); req := UTL_HTTP.BEGIN_REQUEST(…); UTL_HTTP.SET_AUTHENTICATION_FROM_WALLET(req, 'hr-access'); … END;
277.9.36 SET_BODY_CHARSETプロシージャ
このプロシージャはオーバーロードされています。各機能の説明は構文宣言の箇所に併記してあります。
参照:
構文
メディア・タイプがtext
で、文字セットがContent-Type
ヘッダーで指定されていない場合、将来のすべてのHTTP要求本体におけるデフォルトの文字セットを設定します。要求または応答のメディア・タイプがtext
で、文字セット情報がContent-Type
ヘッダーに含まれていない場合は、HTTPプロトコルの標準仕様に従い、要求または応答の本体文字セットはデフォルトのISO-8859-1
になります。要求に対して作成された応答は、現行のセッションの本体文字セットではなく、要求のデフォルトの本体文字セットを継承します。データベース・ユーザー・セッションでは、デフォルトの本体文字セットはISO-8859-1です。デフォルトの本体文字セットの設定は将来の要求に対してのみ影響を与え、既存の要求に影響はありません。要求が作成された後、要求を操作するその他のSET_BODY_CHARSET
プロシージャを使用して、本体文字セットを変更できます。
UTL_HTTP.SET_BODY_CHARSET ( charset IN VARCHAR2 DEFAULT NULL);
メディア・タイプがtext
で、文字セットがContent-Type
ヘッダーで指定されていない場合は、要求本体のデフォルトの文字セットを設定します。要求または応答のメディア・タイプがtextで、文字セット情報がContent-Type
ヘッダーに含まれていない場合は、HTTPプロトコルの標準仕様に従い、要求または応答の本体文字セットはデフォルトのISO-8859-1
になります。このプロシージャを使用して、要求がセッションのデフォルト設定を継承するデフォルトの本体文字セットを変更します。
UTL_HTTP.SET_BODY_CHARSET( r IN OUT NOCOPY req, charset IN VARCHAR2 DEFAULT NULL);
メディア・タイプがtextで、文字セットがContent-Type
ヘッダーで指定されていない場合は、応答本体の文字セットを設定します。HTTPプロトコルの標準仕様ごとに、要求または応答のメディア・タイプがtextで、文字セット情報がContent-Type
ヘッダーに含まれていない場合は、要求または応答の本体文字セットはデフォルトのISO-8859-1になります。このプロシージャを使用して、応答が要求から継承するデフォルトの本体文字セットを変更します。
UTL_HTTP.SET_BODY_CHARSET( r IN OUT NOCOPY resp, charset IN VARCHAR2 DEFAULT NULL);
パラメータ
表277-49 SET_BODY_CHARSETプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP応答。 |
|
応答本体のデフォルトの文字セット。文字セットは、OracleまたはInternet Assigned Numbers Authority(IANA)のネーミング規則で命名できます。 |
277.9.37 SET_COOKIE_SUPPORTプロシージャ
このオーバーロードされたプロシージャは、Cookieサポートを処理します。各機能の説明は構文宣言の箇所に併記してあります。
構文
要求のHTTP Cookieのサポートを有効または無効にします。このプロシージャを使用して、要求がセッションのデフォルト設定を継承するCookieのサポート設定を変更します。
UTL_HTTP.SET_COOKIE_SUPPORT( r IN OUT NOCOPY REQ, enable IN BOOLEAN DEFAULT TRUE);
将来のHTTP要求がHTTP Cookieをサポートするかどうかを設定し、現在のデータベース・ユーザー・セッションで保持されるCookieの最大数を設定します。
UTL_HTTP.SET_COOKIE_SUPPORT ( enable IN BOOLEAN, max_cookies IN PLS_INTEGER DEFAULT 300, max_cookies_per_site IN PLS_INTEGER DEFAULT 20);
パラメータ
表277-50 SET_COOKIE_SUPPORTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP要求。 |
|
HTTP Cookieサポートを有効にする場合は |
|
現行のセッションで保持されるCookieの最大合計数を設定します。 |
|
現行のセッションでWebサイトごとに保持されるCookieの最大合計数を設定します。 |
使用上のノート
CookieのサポートがHTTP要求に対して有効である場合、現行のセッションで保存され、要求に適用可能なCookieはすべて、HTTP Cookieの仕様標準に基づき、その要求でWebサーバーに戻されます。Cookieのサポートが要求に対して有効である場合は、要求への応答に設定されたCookieが現行のセッションに保存され、後続の要求でWebサーバーに戻されます。CookieのサポートがHTTP要求に対して無効である場合は、その要求でCookieはWebサーバーに戻されず、要求への応答に設定されたCookieは現行のセッションで保存されません。ただし、Set-Cookie
HTTPヘッダーは応答からの取出しが可能です。
データベース・ユーザー・セッションでは、すべてのHTTP要求に対してCookieのサポートがデフォルトで有効にされています。Cookieのサポートのデフォルト設定(有効または無効)が影響するのは将来の要求に対してのみであり、既存の要求には影響ありません。要求が作成された後、要求を操作するその他のSET_COOKIE_SUPPORT
プロシージャを使用して、Cookieのサポートの設定を変更できます。
現行のセッションにデフォルトで保存されるCookieの最大数は、各サイトにつき20、合計で300です。
Cookieの最大合計数または各Webサイトに対するCookieの最大数を減少させる場合は、減少後の最大数まで最も古いCookieからパージされます。現行のセッションに保存されたHTTP Cookieは、データベース・セッションの期間のみ存続します。永続的に格納されるCookieはありません。Cookieのサポートを無効にしても、現行のセッションに保存されたCookieはクリアされません。
GET_COOKIES
およびADD_COOKIES
を使用したCookieの取出し、保存およびリストアを行う方法は、「例」を参照してください。
277.9.38 SET_DETAILED_EXCP_SUPPORTプロシージャ
このプロシージャは、UTL_HTTP
パッケージが詳細な例外を呼び出すように設定します。
デフォルトでは、HTTP要求が失敗すると、UTL_HTTP
によりrequest_failed
例外が発生します。エラーの詳細情報を参照するには、GET_DETAILED_SQLCODE
およびGET_DETAILED_SQLEERM
を使用します。
参照:
構文
UTL_HTTP.SET_DETAILED_EXCP_SUPPORT ( enable IN BOOLEAN DEFAULT FALSE);
パラメータ
表277-51 SET_DETAILED_EXCP_SUPPORTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
|
277.9.39 SET_FOLLOW_REDIRECTプロシージャ
このプロシージャは、GET_RESPONSE
ファンクションで現在または将来指定される要求に対するHTTP応答において、HTTPリダイレクトの指示にUTL_HTTP
が従う最大回数を設定します。
構文
このプロシージャを使用して、リダイレクトの最大回数を設定します。
UTL_HTTP.SET_FOLLOW_REDIRECT ( max_redirects IN PLS_INTEGER DEFAULT 3);
このプロシージャを使用して、要求がセッションのデフォルト設定を継承するリダイレクトの最大回数を変更します。
UTL_HTTP.SET_FOLLOW_REDIRECT( r IN OUT NOCOPY req, max_redirects IN PLS_INTEGER DEFAULT 3);
パラメータ
表277-52 SET_FOLLOW_REDIRECTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP要求。 |
|
リダイレクトの最大回数。リダイレクトを無効にするには0(ゼロ)に設定します。 |
使用上のノート
max_redirects
が正の値に設定されている場合、GET_RESPONSEファンクションは、HTTP応答のステータス・コード301、302および307 (HTTP HEADおよびHTTP GETメソッドの場合)、303 (すべてのHTTPメソッドの場合)に対してリダイレクトされたURLに自動的に従います。さらにHTTP要求(要求メソッドはステータス・コード303のHTTP GETに変更されます)が新しい場所で再試行されます。リダイレクトされない最後の場所に到達するか、エラーが発生するか、または無限ループを回避するためにリダイレクトの最大回数に到達するまで、リダイレクトが実行されます。REQ
レコードのURLおよびmethodフィールドは、最後にリダイレクトされたURL、およびそのURLへのアクセスに使用されたメソッドに更新されます。リダイレクトの最大回数を0 (ゼロ)に設定し、自動リダイレクトを無効にします。
現行のセッションでは自動リダイレクトに従わないように設定していますが、個別にHTTP要求を指定してFOLLOW_REDIRECT
ファンクションのリダイレクト指示に従うように設定できます。その逆の設定も可能です。
データベース・ユーザー・セッションにおけるリダイレクトのデフォルト最大回数は3です。デフォルト値が影響を与えるのは将来の要求に対してのみであり、既存の要求に影響はありません。
リダイレクトを有効にするには、GET_RESPONSE
の前にSET_FOLLOW_REDIRECT
プロシージャをコールする必要があります。
277.9.40 SET_HEADERプロシージャ
このプロシージャは、HTTP要求ヘッダーを設定します。要求ヘッダーは、設定後ただちにWebサーバーに送信されます。
参照:
構文
UTL_HTTP.SET_HEADER ( r IN OUT NOCOPY req, name IN VARCHAR2, value IN VARCHAR2);
パラメータ
表277-53 SET_HEADERプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP要求。 |
|
HTTP要求ヘッダーの名前。 |
|
HTTP要求ヘッダーの値。 |
使用上のノート
HTTPプロトコルの標準では、複数のHTTPヘッダーに同じ名前を付けることができます。したがって、既存のヘッダーと同じ名前を付けても置換されません。
HTTP 1.1を使用して要求を作成する場合、UTL_HTTP
によりホストのヘッダーが自動的に設定されます。
このプロシージャを使用してContent-Type
ヘッダーを設定すると、UTL_HTTP
は、ヘッダー値から文字セット情報を探します。文字セット情報が存在する場合は、要求本体の文字セットとして設定されます。SET_BODY_CHARSET
プロシージャを使用すると、後でこの設定を変更できます。
Transfer-Encodingヘッダーにchunked
の値を設定すると、WRITE_TEXT、WRITE_LINE
およびWRITE_RAW
プロシージャによって作成された要求本体が、
UTL_HTTP
によって自動的にエンコードされます。HTTP 1.1ベースのWebサーバーまたはCGIプログラムは、HTTP 1.1 chunked transfer-encoding形式でエンコードされた要求本体をサポートしていません。
277.9.41 SET_PERSISTENT_CONN_SUPPORTプロシージャ
このオーバーロードされたプロシージャは、永続的接続サポートを提供します。異なる機能については、構文宣言に説明されています。
参照:
構文
将来のHTTP要求がHTTP 1.1の永続的接続をサポートする必要があるかどうかを設定し、現在のデータベース・ユーザー・セッションで保持される永続的接続の最大数を設定します。
UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT( enable IN BOOLEAN DEFAULT FALSE, max_conns IN PLS_INTEGER DEFAULT 0);
要求のHTTP 1.1の永続的接続のサポートを有効または無効にします。
UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT( r IN OUT NOCOPY req, enable IN BOOLEAN DEFAULT FALSE);
パラメータ
表277-54 SET_PERSISTENT_CONN_SUPPORTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
ネットワークを永続的に接続するには |
maximum_conns |
接続の最大数 |
|
HTTP要求。 |
使用上のノート
永続的接続のサポートがHTTP要求に対して有効である場合、要求が適切に完了した後、パッケージはWebサーバーまたはプロキシ・サーバーへのネットワーク接続をパッケージ内でオープンにしたまま保持し、同じサーバーへの後続の要求でHTTP 1.1プロトコルの各仕様を再利用します。永続的接続がサポートされている場合、ネットワーク接続の待機時間が回避されるため、後続のHTTP要求は高速に処理できます。永続的接続のサポートが要求に対して無効である場合、要求が完了すると、パッケージは常に、HTTPヘッダー「Connection: close」をHTTP要求中で自動的に送信し、ネットワーク接続をクローズします。この設定は、HTTP 1.0プロトコルに準拠したHTTP要求には影響ありません。これは、要求が完了した後、ネットワーク接続が常にクローズされるためです。
要求を作成する際に、ターゲットWebサーバー(またはプロキシ・サーバー)が使用可能であれば、パッケージはこのターゲットとの既存の永続的接続を再利用しようとします。使用可能なサーバーがない場合、新しいネットワーク接続が開始されます。要求に対する永続的接続サポートの設定が影響するのは、要求が完了した後にネットワーク接続をクローズするかどうかということについてのみです。
このプロシージャを使用して、要求がセッションのデフォルト設定を継承する永続的接続のサポート設定を変更します。
UTL_HTTP
で永続的接続を使用すると、同じサーバーから複数のWebページをフェッチする時間を短縮できる一方で、データベース・サーバーの貴重なシステム・リソース(ネットワーク接続)が消費されることにユーザーは注意してください。また、データベース・サーバーで多くのネットワーク接続がオープンにされたままである場合、永続的接続を過度に使用すると、データベース・サーバーのスケーラビリティが低下することがあります。ネットワーク接続は、後続の要求により即時使用される場合にのみオープンにし、不要な場合にはクローズしてください。「例」に示すように、セッションではデフォルトの永続的接続のサポートは無効に設定し、個々のHTTP要求で永続的接続を有効にします。
データベース・セッションにおける永続的接続の最大数のデフォルト値は0 (ゼロ)です。永続的接続を実際に有効にするには、永続的接続の最大数を正の値に設定する必要があります。そうでない場合は、接続は永続的に保持されません。
永続的接続を使用する必要がある場合は、BEGIN_REQUESTファンクションをコールする前に、maximum_connsパラメータを受け取るオーバーロードをコールする必要があります。このようにしなければ、他の形式のSET_PERSISTENT_CONN_SUPPORT
がコールされた場合であっても、現在の要求に対して永続的接続が有効になりません。
例
セッション・レベルでのhttp要求の中でSET_PERSISTENT_CONN_SUPPORTを使用して、それぞれの要求後にアクティブな永続接続を示します。
DECLARE pieces utl_http.html_pieces; conns utl_http.connection_table; BEGIN -- Turns on persistent connection support for the request_pieces call. utl_http.set_persistent_conn_support(true, 1); FOR i IN 1..10 LOOP pieces := utl_http.request_pieces('http://www.example.com/'); -- Shows the active persistent connection utl_http.get_persistent_conns(conns); FOR j IN 1..conns.count LOOP dbms_output.put_line('Persistent connection '||j||': '||conns(j).host||':'||conns(j).port); END LOOP; END LOOP; -- Turns off persistent connection support. Set active max persistent connection to 0 to close all active connections. utl_http.set_persistent_conn_support(false, 0); END; /
SET_PERSISTENT_CONN_SUPPORTをHTTP要求内で使用することで、それぞれの要求の中で永続接続を個々に使用して同じホストで複数のURLをフェッチする方法を示します。
DECLARE -- Table to store the URLs TYPE vc2_table IS TABLE OF VARCHAR2(256) INDEX BY BINARY_INTEGER; paths VC2_TABLE; PROCEDURE fetch_pages(paths IN vc2_table) AS req UTL_HTTP.REQ; resp UTL_HTTP.RESP; data VARCHAR2(1024); BEGIN -- Set the proxy server UTL_HTTP.SET_PROXY('www-proxy.example.com:80', ''); FOR i IN 1..paths.count LOOP req := UTL_HTTP.BEGIN_REQUEST(paths(i)); -- Use persistent connections except for the last request IF (i < paths.count) THEN -- Use a persistent connection for the current request UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT(req, TRUE); END IF; resp := UTL_HTTP.GET_RESPONSE(req); -- Display the results of the response DBMS_OUTPUT.PUT_LINE('-'); DBMS_OUTPUT.PUT_LINE('URL: ' || paths(i)); DBMS_OUTPUT.PUT_LINE('HTTP Response Status Code: ' || resp.status_code); DBMS_OUTPUT.PUT_LINE('HTTP Response Reason Phrase: ' || resp.reason_phrase); DBMS_OUTPUT.PUT_LINE('HTTP Response Version: ' || resp.http_version); BEGIN LOOP UTL_HTTP.READ_TEXT(resp, data); -- do something with the data END LOOP; EXCEPTION WHEN UTL_HTTP.END_OF_BODY THEN NULL; END; UTL_HTTP.END_RESPONSE(resp); END LOOP; END; BEGIN -- Set a maximum of 1 persistent connection, but start with persistent connections -- off UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT(FALSE, 1); -- Create a list of URLs paths(1) := 'http://www.example.com/technetwork/index.html'; paths(2) := 'http://www.example.com/us/products/index.html'; fetch_pages(paths); END; /
277.9.42 SET_PROXYプロシージャ
このプロシージャは、HTTPまたは他のプロトコルの要求に使用するプロキシを設定します。ただし、no_proxy_domains
に指定されたドメインに属するホストに関するものは除きます。
no_proxy_domains
は、プロキシ・サーバーを経由するかわりに宛先のHTTPサーバーにHTTP要求を直接送信する必要があるドメインまたはホストのカンマ、セミコロンまたはスペース区切りのリストです。
参照:
構文
UTL_HTTP.SET_PROXY ( proxy IN VARCHAR2, no_proxy_domains IN VARCHAR2);
パラメータ
表277-55 SET_PROXYプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
プロキシをすべての要求に対して使用しないホストおよびドメインのリスト。 |
使用上のノート
プロキシには、プロキシ・サーバーがリスニングするオプションのTCP/IPポート番号を含めることができます。構文は、[http://]host[:port][/]
(www-proxy.my-company.com:80
など)です。プロキシのポートを指定していない場合は、ポート80を仮定します。
オプションで、ドメインまたはホストごとにポート番号を指定できます。ポート番号が指定されていると、非プロキシの制限が適用されるのは、特定のドメインまたはホスト(corp.my-company.com、eng.my-company.com:80
など)のポートでの要求のみです。no_proxy_domains
の値がNULL
でプロキシが設定されている場合、要求はすべてプロキシを経由して送信されます。プロキシが設定されていない場合、UTL_HTTP
により要求がターゲットWebサーバーに直接送信されます。
プロキシ文字列の中で指定するプロキシのユーザー名またはパスワード、あるいはその両方を定義できます。書式は次のとおりです。
[http://][user[:password]@]host[:port][/]
データベース・サーバー・インスタンスの開始時にプロキシが設定されている場合は、環境変数http_proxy
およびno_proxy
のプロキシ設定が想定されます。このプロシージャにより設定されたプロキシ設定は、初期の設定より優先されます。
277.9.43 SET_RESPONSE_ERROR_CHECKプロシージャ
このプロシージャは、Webサーバーがエラーを示すステータス・コード(4xxまたは5xx)を戻した場合に、GET_RESPONSE
が例外を呼び出すかどうかを設定します。
たとえば、要求したURLが宛先のWebサーバーで見つからない場合、404(ドキュメントが見つからない)の応答ステータス・コードが戻されます。
参照:
構文
UTL_HTTP.SET_RESPONSE_ERROR_CHECK ( enable IN BOOLEAN DEFAULT FALSE);
パラメータ
表277-56 SET_RESPONSE_ERROR_CHECKプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
応答エラーをチェックする場合は |
使用上のノート
ステータス・コードがエラーを示す4xxまたは5xxで、このプロシージャが有効である場合は、GET_RESPONSE
がHTTP_CLIENT_ERROR
またはHTTP_SERVER_ERROR
例外を呼び出します。SET_RESPONSE_ERROR_CHECK
がFALSE
に設定されている場合は、ステータス・コードがエラーを示してもGET_RESPONSE
は例外を呼び出しません。
デフォルトでは、応答エラー・チェックはオフになっています。
SET_RESPONSE_ERROR_CHECK
をFALSE
に設定すると、GET_RESPONSE
ファンクションによってその他の例外が発生する可能性があります。
277.9.44 SET_TRANSFER_TIMEOUTプロシージャ
このプロシージャは、Webサーバーまたはプロキシ・サーバーからHTTP応答を読み込むまでUTL_HTTP
パッケージが試行する、将来のすべてのHTTP要求についてのデフォルトのタイムアウト値を設定します。
このタイムアウト値を使用して、WebサーバーからWebページを取り出す間、ビジー状態のWebサーバーや通信量の多いネットワークによりPL/SQLプログラムがブロックされることを回避します。
参照:
構文
UTL_HTTP.SET_TRANSFER_TIMEOUT ( timeout IN PLS_INTEGER DEFAULT 60);
パラメータ
表277-57 SET_TRANSFER_TIMEOUTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
ネットワーク転送のタイムアウト値(秒)。 |
使用上のノート
タイムアウトのデフォルト値は60秒です。
277.9.45 SET_WALLETプロシージャ
このプロシージャは、Secure Sockets Layer(SSL)、つまりHTTPSを経由するHTTP要求すべてに使用するOracle Walletを設定します。
UTL_HTTP
パッケージがSSLを介してHTTPサーバーと通信する場合、HTTPサーバーは認証局が署名したデジタル証明書をUTL_HTTP
パッケージに示し、身分を証明します。Oracle Walletには、UTL_HTTP
パッケージのユーザーが信頼する認証局のリストが含まれています。Oracle Walletは、HTTPS要求を作成するために必要です。
参照:
-
ファイングレイン・アクセスの管理は、『Oracle Databaseセキュリティ・ガイド』を参照してください。
構文
UTL_HTTP.SET_WALLET ( path IN VARCHAR2, password IN VARCHAR2 DEFAULT NULL);
パラメータ
表277-58 SET_WALLETプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
Oracle Walletを含むディレクトリ・パス。形式は wallet_pathの形式は、たとえば、PCでは Oracleウォレットのかわりにオペレーティング・システムの証明書ストアを使用する場合は、 |
|
Walletのオープンに必要なパスワード。Walletの自動ログインが有効の場合は、パスワードを省略して
|
使用上のノート
Oracle Walletを設定するには、ORAPKI
ユーティリティを使用してWalletを作成します。HTTPS要求を成功させるには、リモートHTTPS Webサーバーの証明書に署名した認証局がWalletに設定されたトラスト・ポイントであることが必要です。
Walletが作成されると、トラスト・ポイントとして認識された認証局に移入されます。リモートHTTPS Webサーバーの証明書に署名した認証局がトラスト・ポイントにない場合、または新しいルート証明書を持っている場合は、その認証局のルート証明書を取得し、Walletのトラスト・ポイントとしてインストールする必要があります。
参照:
Wallet Managerの詳細は、『Oracle Database Advanced Securityガイド』を参照してください。
277.9.46 WRITE_LINEプロシージャ
このプロシージャは、HTTP要求本体にテキスト行を書き込み、改行文字(UTL_TCP
で定義されるCRLF)を使用して行を終了します。
HTTP要求本体と同じデータが送信されると、HTTP要求ヘッダーのセクションはただちに完了します。テキスト・データは、データベース文字セットから要求本体の文字セットに自動的に変換されます。
参照:
構文
UTL_HTTP.WRITE_LINE( r IN OUT NOCOPY req, data IN VARCHAR2 CHARACTER SET ANY_CS);
パラメータ
表277-59 WRITE_LINEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP要求。 |
|
HTTP要求本体に組み込まれて送信されるテキスト行。 |
使用上のノート
HTTPクライアントは、リモートWebサーバーに対し、送信する要求本体の長さを常に知らせる必要があります。データ量があらかじめわかっている場合、Content-Length
ヘッダーを要求に設定できます。この場合、コンテンツの長さが文字数ではなくバイト数で計測されます。要求本体の長さがあらかじめわかっていない場合は、HTTP 1.1 chunked transfer-encoding形式を使用して要求本体を送信できます。要求本体はチャンクで送信されます。この場合、チャンクが送信される前に各チャンクの長さが送信されます。Transfer-Encoding: chunkedヘッダーが設定されると、UTL_HTTP
パッケージは、要求本体に対してchunked transfer-encodingを透過的に実行します。HTTP 1.1ベースのWebサーバーまたはCGIプログラムは、HTTP 1.1 chunked transfer-encoding形式でエンコードされた要求本体をサポートしていません。詳細は、SET_HEADER
プロシージャを参照してください。
Content-Length
ヘッダーを送信する場合は、データベース文字セットから要求本体の文字セットに変換された後、ヘッダーで指定した長さとテキストの要求本体のバイト数での長さを同じにする必要があります。2つの文字セットのうちいずれかがマルチバイト文字セットである場合、要求本体の文字セットの正確なバイト数での長さをあらかじめ知ることはできません。この場合、明示的に文字セットの変換を実行し、結果のバイト長を判別し、文字セットの自動変換を回避するためにWRITE_RAW
プロシージャを使用してContent-Length
ヘッダーおよび結果を送信します。または、リモートWebサーバーまたはCGIプログラムが対応する場合は、HTTP 1.1 chunked transfer-encoding形式を使用して要求本体を送信できます。この場合、UTL_HTTP
は、チャンクの長さを透過的に処理します。
277.9.47 WRITE_RAWプロシージャ
このプロシージャは、HTTP要求本体にバイナリ・データを書き込みます。HTTP要求本体と同じデータが送信されると、HTTP要求ヘッダーのセクションはただちに完了します。
参照:
構文
UTL_HTTP.WRITE_RAW( r IN OUT NOCOPY REQ, data IN RAW);
パラメータ
表277-60 WRITE_RAWプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP要求。 |
|
HTTP要求本体に組み込まれて送信されるバイナリ・データ。 |
使用上のノート
HTTPクライアントは、リモートWebサーバーに対し、送信する要求本体の長さを常に知らせる必要があります。データ量があらかじめわかっている場合、Content-Length
ヘッダーを要求に設定できます。この場合、コンテンツの長さが文字数ではなくバイト数で計測されます。要求本体の長さがあらかじめわかっていない場合は、HTTP 1.1 chunked transfer-encoding形式を使用して要求本体を送信できます。要求本体はチャンクで送信されます。この場合、チャンクが送信される前に各チャンクの長さが送信されます。Transfer-Encoding:chunked
ヘッダーが設定されていると、UTL_HTTP
は、要求本体に対してchunked transfer-encodingを透過的に実行します。HTTP 1.1ベースのWebサーバーまたはCGIプログラムは、HTTP 1.1 chunked transfer-encoding形式でエンコードされた要求本体をサポートしていません。詳細は、SET_HEADER
プロシージャを参照してください。
277.9.48 WRITE_TEXTプロシージャ
このプロシージャは、HTTP要求本体にテキスト・データを書き込みます。
HTTP要求本体と同じデータが送信されると、HTTP要求ヘッダーのセクションはただちに完了します。テキスト・データは、データベース文字セットから要求本体の文字セットに自動的に変換されます。
参照:
構文
UTL_HTTP.WRITE_TEXT( r IN OUT NOCOPY REQ, data IN VARCHAR2 CHARACTER SET ANY_CS);
パラメータ
表277-61 WRITE_TEXTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
HTTP要求。 |
|
HTTP要求本体に組み込まれて送信されるテキスト・データ。 |
使用上のノート
HTTPクライアントは、リモートWebサーバーに対し、送信する要求本体の長さを常に知らせる必要があります。データ量があらかじめわかっている場合、Content-Length
ヘッダーを要求に設定できます。この場合、コンテンツの長さが文字数ではなくバイト数で計測されます。要求本体の長さがあらかじめわかっていない場合は、HTTP 1.1 chunked transfer-encoding形式を使用して要求本体を送信できます。要求本体はチャンクで送信されます。この場合、チャンクが送信される前に各チャンクの長さが送信されます。Transfer-Encoding: chunked
ヘッダーが設定されていると、UTL_HTTP
は、要求本体に対してchunked transfer-encodingを透過的に実行します。HTTP 1.1ベースのWebサーバーまたはCGIプログラムは、HTTP 1.1 chunked transfer-encoding形式でエンコードされた要求本体をサポートしていません。詳細は、SET_HEADER
プロシージャを参照してください。
Content-Length
ヘッダーを送信する場合は、データベース文字セットから要求本体の文字セットに変換された後、ヘッダーで指定した長さとテキストの要求本体のバイト数での長さを同じにする必要があります。2つの文字セットのうちいずれかがマルチバイト文字セットである場合、要求本体の文字セットの正確なバイト数での長さをあらかじめ知ることはできません。この場合、明示的に文字セットの変換を実行し、結果のバイト長を判別し、文字セットの自動変換を回避するためにWRITE_RAW
プロシージャを使用してContent-Length
ヘッダーおよび結果を送信します。または、リモートWebサーバーまたはCGIプログラムが対応する場合は、HTTP 1.1 chunked transfer-encoding形式を使用して要求本体を送信できます。この場合、UTL_HTTP
は、チャンクの長さを透過的に処理します。