207 <a name="ARPLS070|UTL_HTTP package lets you access data on the Internet over HTTP"> UTL_HTTP

構文

UTL_HTTP.ADD_COOKIES (
   cookies  IN cookie_table);

パラメータ

表207-16 ADD_COOKIESプロシージャのパラメータ

パラメータ	説明
`cookies`	追加されるCookie。

使用上の注意

パッケージが現在保持するCookieは、新しいCookieが追加されるまでクリアされません。

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)
RETURN req;

パラメータ

表207-17 BEGIN_REQUESTファンクションのパラメータ

パラメータ	説明
`url`	HTTP要求のURL。
`method`	URLにより識別されたリソースで実行されるメソッド。
`http_version`	要求の送信に使用されるHTTPプロトコルのバージョン。プロトコル・バージョンの形式は`HTTP/major-version.minor-version`です。`major-version`および`minor-version`は正の値です。このパラメータが`NULL`の場合、`UTL_HTTP`は、サポートされているHTTPプロトコルの最新バージョンを使用して要求を送信します。パッケージがサポートする最新バージョンは1.1ですが、次のバージョンにアップグレード可能です。デフォルトは`NULL`です。

使用上の注意

このファンクションに引数として渡されたURLについては、URL仕様RFC 2396による不正な文字（空白など）の検証は行われません。コールを実行する場合は、UTL_URLパッケージを使用してこのような文字をエスケープする必要があります。URLはUS-ASCII文字のみで構成する必要があります。 URLで有効な文字のリストは、第219章「UTL_URL」を参照してください。URLはUS-ASCII文字のみで構成する必要があるので注意してください。それ以外の文字のURLでの使用は避けてください。
UTL_HTTP.BEGIN_REQUESTは、長さが32767バイト以下のURLを送信できます。ただし、受け入れることができるURLの長さの制限はWebサーバーごとに異なります。多くの場合、この制限は4000バイトです。この制限を超えた場合の結果は、Webサーバーによって異なります。たとえば、Webサーバーが応答を戻さずにHTTP接続を削除する場合があります。この場合、続けてUTL_HTTP.GET_RESPONSEを実行すると、UTL_HTTP.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プロシージャを参照してください。

CLEAR_COOKIESプロシージャ

このプロシージャは、UTL_HTTPパッケージが保持するCookieをすべてクリアします。

関連項目:

構文

UTL_HTTP.CLEAR_COOKIES;

CLOSE_PERSISTENT_CONNプロシージャ

このプロシージャは、現在のデータベース・セッションでUTL_HTTPパッケージが保持するHTTPの永続的接続をクローズします。

関連項目:

構文

UTL_HTTP.CLOSE_PERSISTENT_CONN (
   conn  IN connection);

パラメータ

表207-18 CLOSE_PERSISTENT_CONNプロシージャのパラメータ

パラメータ	説明
`conn`	クローズするHTTP永続的接続。

CLOSE_PERSISTENT_CONNSプロシージャ

このプロシージャは、現在のデータベース・セッションでUTL_HTTPパッケージが保持するHTTPの永続的接続のグループをクローズします。このプロシージャは、パターンを一致させる方法を使用して、クローズする永続的接続を判別します。

共通のプロパティ（特定のホストへのすべての接続やすべてのSSL接続など）を共有するHTTP永続的接続のグループをクローズするには、特定のパラメータを設定して残りのパラメータをNULLにします。このプロシージャがコールされたときにNULLに設定されていたパラメータは、クローズする接続の判別に使用されません。

たとえば、次のコールをプロシージャに使用して、foobarへの永続的接続をすべてクローズします。

UTL_HTTP.CLOSE_PERSISTENT_CONNS(host => 'foobar');

プロシージャに次のコールを使用すると、foobarを介してTCP/IPポート80の永続的接続をすべてクローズします。

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);

パラメータ

表207-19 CLOSE_PERSISTENT_CONNSプロシージャのパラメータ

パラメータ	説明
`host`	永続的接続をクローズするホスト。
`port`	永続的接続をクローズするポート番号。
`proxy_host`	永続的接続をクローズするプロキシ・ホスト。
`proxy_port`	永続的接続をクローズするプロキシ・ポート。
`ssl`	永続的なSSL接続をクローズします。

使用上の注意

異なるTCP/IPポートでの同じWebサーバーへの接続は、個別にカウントされます。Webサーバーのホスト名は、元のHTTP要求のURLで指定されたとおりに識別されます。したがって、ドメイン名を持つ完全修飾されたホスト名は、ドメイン名のないホスト名とは別にカウントされます。

このプロシージャがコールされたときにパラメータでNULL値を使用すると、パッケージでクローズする永続的接続を決定したときに、コール元がその値を無視することを意味します。特定の永続的接続をクローズする場合に永続的接続でNULLに設定されているパラメータの値のみをNULLに設定するには、CLOSE_PERSISTENT_CONNプロシージャを使用して、特定の永続的接続をクローズします。

END_REQUESTプロシージャ

このプロシージャは、HTTP要求を終了します。要求の完了および応答の待機を行わずにHTTP要求を終了するために、プログラムでこのプロシージャをコールできます。または、プログラムは要求の開始、応答の待機、応答のクローズという通常の順序を経て要求を終了することもできます。ネットワーク接続は常にクローズされ、再利用されることはありません。

関連項目:

構文

UTL_HTTP.END_REQUEST (
   r  IN OUT NOCOPY req);

パラメータ

表207-20 END_REQUESTプロシージャのパラメータ

パラメータ	説明
`r`	HTTP要求。

END_RESPONSEプロシージャ

このプロシージャは、HTTP応答を終了します。HTTP要求および応答を完了します。この要求でHTTP 1.1の永続的接続を使用している場合を除き、ネットワーク接続もクローズされます。

関連項目:

構文

UTL_HTTP.END_RESPONSE (
   r  IN OUT NOCOPY resp);

パラメータ

表207-21 END_RESPONSEプロシージャのパラメータ

パラメータ	説明
`r`	HTTP応答。

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);

パラメータ

表207-22 GET_AUTHENTICATIONプロシージャのパラメータ

パラメータ	説明
`r`	HTTP応答。
`scheme`	要求されたHTTP認証のスキーム。
`realm`	要求されたHTTP認証のレルム。
`for_proxy`	WebサーバーではなくHTTPプロキシ・サーバーにアクセスするために必要なHTTP認証情報を戻します。デフォルトは`FALSE`です。

使用上の注意

ドキュメントが保護されていないことをWebクライアントが認識していない場合、そのドキュメントを取り出すには少なくとも2つのHTTP要求が必要です。最初のHTTP要求で、Webクライアントは必要な認証情報を提供せずに要求を作成します。したがって、この要求は拒否されます。 Webクライアントは、GET_AUTHENTICATIONをコールすることにより、認証対象となる要求に必要な認証情報を判別します。 Webクライアントは2回目の要求を行い、SET_AUTHORIZATIONを使用して必要な認証情報を提供します。Webサーバーが認証情報を検証できれば、要求は正常に処理され、要求したドキュメントが戻されます。要求を行う前に、認証情報が必要であることをWebクライアントが認識している場合は、最初の要求で必要な認証情報を提供できます。これにより、余分な要求を行わずに済みます。

GET_BODY_CHARSETプロシージャ

このプロシージャは、将来のHTTP要求すべての本体におけるデフォルトのキャラクタ・セットを取り出します。

関連項目:

構文

UTL_HTTP.GET_BODY_CHARSET (
   charset  OUT NOCOPY VARCHAR2);

パラメータ

表207-23 GET_BODY_CHARSETプロシージャのパラメータ

パラメータ	説明
`charset`	将来のHTTP要求すべての本体におけるデフォルトのキャラクタ・セット。

GET_COOKIE_COUNTファンクション

このファンクションは、すべてのWebサーバーにより設定されたUTL_HTTPパッケージが現在保持するCookieの数を戻します。

関連項目:

構文

UTL_HTTP.GET_COOKIE_COUNT
RETURN PLS_INTEGER;

GET_COOKIE_SUPPORTプロシージャ

このプロシージャは、現在のCookieサポート設定を取り出します。

関連項目:

構文

UTL_HTTP.GET_COOKIE_SUPPORT (
   enable                OUT BOOLEAN,
   max_cookies           OUT PLS_INTEGER,
   max_cookies_per_site  OUT PLS_INTEGER);

パラメータ

表207-24 GET_COOKIE SUPPORTプロシージャのパラメータ

パラメータ	説明
`enable`	将来のHTTP要求がHTTP Cookieをサポートするかどうかを設定します（`TRUE`の場合はサポートし、`FALSE`の場合はサポートしません）。
`max_cookies`	現在のデータベース・ユーザー・セッションで保持されるCookieの最大合計数を示します。
`max_cookies_per_site`	現行のセッションで各Webサイトについて保持されるCookieの最大合計数を示します。

GET_COOKIESファンクション

このファンクションは、すべてのWebサーバーにより設定されたUTL_HTTP パッケージが現在保持するすべてのCookieを戻します。

関連項目:

構文

UTL_HTTP.GET_COOKIES (
   cookies  IN OUT NOCOPY cookie_table);

パラメータ

表207-25 GET_COOKIESファンクションのパラメータ

パラメータ	説明
`cookies`	戻されるCookie。

GET_DETAILED_EXCP_SUPPORTプロシージャ

このプロシージャは、UTL_HTTPパッケージが詳細な例外を呼び出すかどうかをチェックします。

関連項目:

構文

UTL_HTTP.GET_DETAILED_EXCP_SUPPORT (
   enable  OUT BOOLEAN);

パラメータ

表207-26 GET_DETAILED_EXCP_SUPPORTプロシージャのパラメータ

パラメータ	説明
`enable`	`UTL_HTTP`に詳細な例外を発生させる場合は`TRUE`、そうでない場合は`FALSE`に設定します。

GET_DETAILED_SQLCODEファンクション

このファンクションは、最後に発生した例外の詳細なSQLCODEを取り出します。

関連項目:

「エラー条件」および「エラー条件のサブプログラム」

構文

UTL_HTTP.GET_DETAILED_SQLCODE
RETURN PLS_INTEGER;

GET_DETAILED_SQLERRMファンクション

このファンクションは、最後に発生した例外の詳細なSQLERRMを取り出します。

関連項目:

「エラー条件」および「エラー条件のサブプログラム」

構文

UTL_HTTP.GET_DETAILED_SQLERRM
RETURN VARCHAR2;

GET_FOLLOW_REDIRECTプロシージャ

このプロシージャは、現行のセッションでのfollow_redirect設定を取り出します。

関連項目:

構文

UTL_HTTP.GET_FOLLOW_REDIRECT (
   max_redirects  OUT PLS_INTEGER);

パラメータ

表207-27 GET_FOLLOW_REDIRECTプロシージャのパラメータ

パラメータ	説明
`max_redirects`	将来のHTTP要求すべてに対するリダイレクトの最大回数。

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);

パラメータ

表207-28 GET_HEADERプロシージャのパラメータ

パラメータ	説明
`r`	HTTP応答。
`n`	n番目に戻されるヘッダー。
`name`	HTTP応答ヘッダーの名前。
`value`	HTTP応答ヘッダーの値。

使用上の注意

リモートWebサーバーから戻された応答本体がchunked transfer encoding形式でエンコードされている場合、応答本体の末尾で戻される追跡ヘッダーが応答に追加され、応答ヘッダーのカウントが更新されます。応答本体の末尾に到達した後、応答を終了する前に追加ヘッダーを取り出すことができます。

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);

パラメータ

表207-29 GET_HEADER_BY_NAMEプロシージャのパラメータ

パラメータ	説明
`r`	HTTP応答。
`name`	値が戻されるHTTP応答ヘッダーの名前。
`value`	HTTP応答ヘッダーの値。
`n`	戻すように指定した名前によりn番目に発生するHTTP応答ヘッダー。デフォルトは1です。

使用上の注意

GET_HEADER_COUNTファンクション

このファンクションは、応答で戻されたHTTP応答ヘッダーの数を戻します。

関連項目:

構文

UTL_HTTP.GET_HEADER_COUNT (
   r  IN OUT NOCOPY resp)
RETURN PLS_INTEGER;

パラメータ

表207-30 GET_HEADER_COUNTファンクションのパラメータ

パラメータ	説明
`r`	HTTP応答。

使用上の注意

GET_PERSISTENT_CONN_COUNTファンクション

このファンクションは、UTL_HTTPパッケージにより現在永続的に保持されているネットワーク接続数をWebサーバーに戻します。

関連項目:

構文

UTL_HTTP.GET_PERSISTENT_CONN_COUNT
RETURN PLS_INTEGER;

使用上の注意

GET_PERSISTENT_CONN_SUPPORTプロシージャ

このプロシージャは次の項目をチェックします。

永続的接続サポートが有効にされているかどうか。
現行のセッションでの永続的接続の最大数の取得。

関連項目:
「セッションの設定」および「セッションの設定サブプログラム」

構文

UTL_HTTP.GET_PERSISTENT_CONN_SUPPORT (
   enable     OUT BOOLEAN,
   max_conns  OUT PLS_INTEGER);

パラメータ

表207-31 GET_PERSISTENT_CONN_SUPPORTプロシージャのパラメータ

パラメータ	説明
`enable`	永続的接続サポートが有効にされている場合は`TRUE`、そうでない場合は`FALSE`です。
`max_conns`	現行のセッションで保持される永続的接続の最大数。

GET_PERSISTENT_CONNSプロシージャ

このプロシージャは、UTL_HTTPパッケージにより現在永続的に保持されているネットワーク接続をすべてWebサーバーに戻します。

関連項目:

構文

UTL_HTTP.get_persistent_conns (
   connections  IN OUT NOCOPY connection_table);

パラメータ

表207-32 GET_PERSISTENT_CONNSプロシージャのパラメータ

パラメータ	説明
`connections`	永続的に保持されているネットワーク接続。

使用上の注意

GET_PROXYプロシージャ

このプロシージャは、現在のプロキシ設定を取り出します。

関連項目:

構文

UTL_HTTP.GET_PROXY (
   proxy             OUT NOCOPY VARCHAR2,
   no_proxy_domains  OUT NOCOPY VARCHAR2);

パラメータ

表207-33 GET_PROXYプロシージャのパラメータ

パラメータ	説明
`proxy`	`UTL_HTTP`パッケージにより現在使用されているプロキシ（ホストおよびオプションのポート番号）。
`no_proxy_domains`	プロキシをすべての要求に対して使用しないホストおよびドメインのリスト。

GET_RESPONSEファンクション

このファンクションは、HTTP応答を読み込みます。ファンクションが戻ると、ステータス行およびHTTP応答ヘッダーが読み込まれて処理されます。ステータス・コード、理由、HTTPプロトコルのバージョンは応答レコードに格納されます。このファンクションは、HTTPヘッダー・セクションを完了します。

関連項目:

構文

UTL_HTTP.GET_RESPONSE (
   r  IN OUT NOCOPY req)
RETURN resp;

パラメータ

表207-34 GET_RESPONSEファンクションのパラメータ

パラメータ	説明
`r`	HTTP応答。

GET_RESPONSE_ERROR_CHECKプロシージャ

このプロシージャは、応答エラー・チェックが設定されているかどうかをチェックします。

関連項目:

構文

UTL_HTTP.GET_RESPONSE_ERROR_CHECK (
   enable  OUT BOOLEAN);

パラメータ

表207-35 GET_RESPONSE_ERROR_CHECKプロシージャのパラメータ

パラメータ	説明
`enable`	応答エラー・チェックが設定されている場合は`TRUE`、そうでない場合は`FALSE`です。

GET_TRANSFER_TIMEOUTプロシージャ

このプロシージャは、将来のHTTP要求に対するデフォルトのタイムアウト値を取り出します。

関連項目:

構文

UTL_HTTP.GET_TRANSFER_TIMEOUT (
   timeout  OUT PLS_INTEGER);

パラメータ

表207-36 GET_TRANSFER_TIMEOUTプロシージャのパラメータ

パラメータ	説明
`timeout`	ネットワーク転送のタイムアウト値（秒）。

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);

パラメータ

表207-37 READ_LINEプロシージャのパラメータ

パラメータ	説明
`r`	HTTP応答。
`data`	テキスト形式のHTTP応答本体。
`remove_crlf`	`TRUE`の場合、改行文字が削除されます。

使用上の注意

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プロシージャを使用して、その応答本体のキャラクタ・セットを明示的に設定することで再度テキストとして読み込むことができます。

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);

パラメータ

表207-38 READ_RAWプロシージャのパラメータ

パラメータ	説明
`r`	HTTP応答。
`data`	バイナリ形式のHTTP応答本体。
`len`	読み込むデータのバイト数。`len`が`NULL`の場合、このプロシージャは、`data`に割り当てられたバッファを最大限に活用して入力を読み込みます。 HTTP応答本体の末尾に到達するまで、または`transfer_timeout`の時間量が経過するまでに使用できるデータが少ない場合は、実際に戻されるデータ量が指定した量より減る可能性があります。デフォルトは`NULL`です。

使用上の注意

転送のタイムアウトがこの応答の要求で設定されている場合、read_rawは、タイムアウトが発生するまでの間、各データ・パケットが読み込まれるまで待機します。タイムアウトが発生すると、read_rawは読込みを停止し、正常に読み込んだデータをすべて戻します。正常に読み込まれたデータがない場合は、transfer_timeout例外が発生します。例外を処理し、読込み操作を後で再試行できます。

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);

パラメータ

表207-39 READ_TEXTプロシージャのパラメータ

パラメータ	説明
`r`	HTTP応答。
`data`	テキスト形式のHTTP応答本体。
`len`	読み込まれるデータの最大文字数。`len`がNULLの場合、このプロシージャは、`data`に割り当てられたバッファを最大限に活用して入力を読み込みます。 HTTP応答本体の末尾に到達するまで、または`transfer_timeout`の時間量が経過するまでに使用できるデータが少ない場合は、実際に戻されるデータ量が指定した量より減る可能性があります。デフォルトはNULLです。

使用上の注意

転送のタイムアウトがこの応答の要求で設定されている場合、read_textは、タイムアウトが発生するまでの間、各データ・パケットが読み込まれるまで待機します。タイムアウトが発生すると、このプロシージャは読込みを停止し、正常に読み込んだデータをすべて戻します。正常に読み込まれたデータがない場合は、transfer_timeout例外が発生します。例外を処理し、読込み操作を後で再試行できます。

マルチバイト・キャラクタの一部が応答本体の終わりで検出された場合、read_textは読込みを中止し、正常かつ完全に読み込まれたマルチバイト・キャラクタをすべて戻します。正常に読み込まれた文字がない場合は、partial_multibyte_char例外が発生します。read_rawプロシージャを使用して例外を処理し、部分的なマルチバイト・キャラクタのバイトをバイナリとして読み込むことができます。マルチバイト・キャラクタの一部が渡されていない状態でタイムアウトが発生し、応答本体の途中でマルチバイト・キャラクタの残りの部分が表示された場合は、transfer_timeout例外が発生します。例外を処理し、読込み操作を後で再試行できます。

Content-Type応答ヘッダーによって指定されている応答本体のキャラクタ・セットが不明であるか、Oracleでサポートされていない場合に、応答本体をテキストとして読み込もうとすると、「ORA-01482: 指定されたキャラクタ・セットはサポートされていません。」という例外が発生します。応答本体は、READ_RAWプロシージャを使用してバイナリとして読み込むか、SET_BODY_CHARSETプロシージャを使用して、その応答本体のキャラクタ・セットを明示的に設定することで再度テキストとして読み込むことができます。

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)
RETURN VARCHAR2;

プラグマ

pragma restrict_references (request, wnds, rnds, wnps, rnps);

パラメータ

表207-40 REQUESTファンクションのパラメータ

パラメータ	説明
`url`	URL。
`proxy`	（オプション）HTTP要求時に使用するプロキシ・サーバーを指定します。プロキシ設定の完全な形式については、`SET_PROXY`を参照してください。
`wallet_path`	（オプション）クライアント側のWalletを指定します。クライアント側のWalletには、HTTPS要求に必要な信頼されている認証局のリストが含まれています。 `wallet_path`の形式は、たとえば、PCでは`file:c:\WINNT\Profiles\<username>\WALLETS`、UNIXでは`file:/home/<username>/wallets`となります。 `UTL_HTTP`パッケージがOracle Databaseサーバーで実行される場合は、データベース・サーバーからWalletにアクセスします。したがって、Walletのパスにデータベース・サーバーからアクセスできる必要があります。 Oracle Walletの設定方法については、`SET_WALLET`プロシージャを参照してください。HTTPS以外の要求の場合は、Oracle Walletは必要ありません。
`wallet_password`	（オプション）Walletのオープンに必要なパスワードを指定します。

戻り値

戻りタイプは長さ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>

例

SQLPLUS> 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;

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)
RETURN html_pieces;

プラグマ

PRAGMA RESTRICT_REFERENCES (request_pieces, WNDS, RNDS, WNPS, RNPS);

パラメータ

表207-41 REQUEST_PIECESファンクションのパラメータ

パラメータ	説明
`url`	URL。
`max_pieces`	（オプション）`REQUEST_PIECES`が戻すピースの最大数（長さは各2000文字、最後のピースはこれより短くなる場合があります）。指定する場合、引数は正の整数を指定します。
`proxy`	（オプション）HTTP要求時に使用するプロキシ・サーバーを指定します。プロキシ設定の完全な形式については、`SET_PROXY`を参照してください。
`wallet_path`	（オプション）クライアント側のWalletを指定します。クライアント側のWalletには、HTTPS要求に必要な信頼されている認証局のリストが含まれています。 wallet_pathの形式は、たとえば、PCでは`file:c:\WINNT\Profiles\<username>\WALLETS`、UNIXではfile:/home/<username>/walletsとなります。`UTL_HTTP`パッケージがOracle Databaseサーバーで実行される場合は、データベース・サーバーからWalletにアクセスします。したがって、Walletのパスにデータベース・サーバーからアクセスできる必要があります。 Oracle Walletの設定方法については、`SET_WALLET`プロシージャを参照してください。HTTPS以外の要求の場合は、Oracle Walletは必要ありません。
`wallet_password`	（オプション）Walletのオープンに必要なパスワードを指定します。

戻り値

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表の各エントリ（情報の断片）は、容量を完全に満たさない場合があります。このファンクションでは、前の断片が完全に満たされる前に、次の断片にデータが到着し始めます。

<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(i);
  END IF;
END;
/
-- Output
Statement processed.
4 pieces were retrieved.
with total length
7687

SET_AUTHENTICATIONプロシージャ

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

関連項目:

構文

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);

パラメータ

表207-42 SET_AUTHENTICATIONプロシージャのパラメータ

パラメータ	説明
`r`	HTTP要求。
`username`	HTTP認証のユーザー名。
`password`	HTTP認証のパスワード。
`scheme`	HTTP認証方式。デフォルトの`BASIC`は、HTTP基本認証方式を示します。
`for_proxy`	HTTP認証情報がWebサーバーではなくHTTPプロキシ・サーバーにアクセスするためのものであるかどうかを識別します。デフォルトは`FALSE`です。

使用上の注意

HTTP基本認証方式のみがサポートされています。

SET_BODY_CHARSETプロシージャ

このプロシージャはオーバーロードされています。各機能の説明は構文宣言の箇所に併記してあります。

関連項目:

「HTTP応答」および「HTTP応答サブプログラム」
「セッションの設定」および「セッションの設定サブプログラム」

構文

メディア・タイプが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);

パラメータ

表207-43 SET_BODY_CHARSETプロシージャのパラメータ

パラメータ	説明
`r`	HTTP応答。
`charset`	応答本体のデフォルトのキャラクタ・セット。キャラクタ・セットは、OracleまたはInternet Assigned Numbers Authority（IANA）のネーミング規則で命名できます。`charset`が`NULL`の場合、データベース・キャラクタ・セットと想定されます。

SET_COOKIE_SUPPORTプロシージャ

このプロシージャはオーバーロードされています。各機能の説明は構文宣言の箇所に併記してあります。

関連項目:

「HTTP要求」および「HTTP要求サブプログラム」
「セッションの設定」および「セッションの設定サブプログラム」

構文

要求の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);

パラメータ

表207-44 SET_COOKIE_SUPPORTプロシージャのパラメータ

パラメータ	説明
`r`	HTTP要求。
`enable`	HTTP Cookieサポートを有効にする場合は`TRUE`、無効に設定する場合は`FALSE`に設定します。
`max_cookies`	現行のセッションで保持されるCookieの最大合計数を設定します。
`max_cookies_per_site`	現行のセッションでWebサイトごとに保持されるCookieの最大合計数を設定します。

使用上の注意

CookieがHTTP要求に対して有効である場合、現行のセッションで保存され、要求に適用可能なCookieはすべて、HTTP Cookieの仕様標準に基づき、その要求でWebサーバーに戻されます。Cookieサポートが要求に対して有効である場合は、要求に応答して設定されたCookieが現行のセッションに保存され、後続の要求でWebサーバーに戻されます。CookieサポートがHTTP要求に対して無効である場合は、その要求でWebサーバーにCookieは戻されず、要求に応答して設定された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の取出し、保存およびリストアを行う方法については、「例」を参照してください。

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);

パラメータ

表207-45 SET_DETAILED_EXCP_SUPPORTプロシージャのパラメータ

パラメータ	説明
`enable`	`UTL_HTTP`に詳細な例外を直接発生させるように指示する場合は`TRUE`、そうでない場合は`FALSE`に設定します。

SET_FOLLOW_REDIRECTプロシージャ

このプロシージャは、GET_RESPONSEファンクションで現在または将来指定される要求に対するHTTP応答において、HTTPリダイレクトの指示にUTL_HTTPが従う最大回数を設定します。

関連項目:

「HTTP要求」および「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);

パラメータ

表207-46 SET_FOLLOW_REDIRECTプロシージャのパラメータ

パラメータ	説明
`r`	HTTP要求。
`max_redirects`	リダイレクトの最大回数。リダイレクトを無効にするには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プロシージャをコールする必要があります。

SET_HEADERプロシージャ

このプロシージャは、HTTP要求ヘッダーを設定します。要求ヘッダーは、設定後ただちにWebサーバーに送信されます。

関連項目:

構文

UTL_HTTP.SET_HEADER (
   r      IN OUT NOCOPY req,
   name   IN VARCHAR2,
   value  IN VARCHAR2);

パラメータ

表207-47 SET_HEADERプロシージャのパラメータ

パラメータ	説明
`r`	HTTP要求。
`name`	HTTP要求ヘッダーの名前。
`value`	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形式でエンコードされた要求本体をサポートしていません。

SET_PERSISTENT_CONN_SUPPORTプロシージャ

このプロシージャは、要求のHTTP 1.1の永続的接続のサポートを有効または無効にします。

関連項目:

構文

UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT(
   r       IN OUT NOCOPY req,
   enable  IN BOOLEAN DEFAULT FALSE);

パラメータ

表207-48 SET_PERSISTENT_CONN_SUPPORTプロシージャのパラメータ

パラメータ	説明
`r`	HTTP要求。
`enable`	ネットワークを永続的に接続するにはTRUEに設定します。そうでない場合はFALSEに設定します。

使用上の注意

永続的接続がHTTP要求に対して有効である場合、要求が完了した後、パッケージはWebサーバーまたはプロキシ・サーバーへのネットワーク接続をオープンしたまま保持し、同じサーバーへの後続の要求でHTTP 1.1プロトコルの各仕様を再利用します。永続的接続がサポートされている場合、ネットワーク接続の待機時間が回避されるため、後続のHTTP要求は高速に処理されます。永続的接続サポートがHTTP要求に対して無効である場合、要求が完了すると、Connection: close HTTPヘッダーが常にHTTP要求に自動的に送信され、ネットワーク接続はクローズされます。この設定は、HTTP 1.0プロトコルに準拠したHTTP要求には影響ありません。これは、要求が完了した後、ネットワーク接続が常にクローズされるためです。

要求を作成する際に、ターゲットWebサーバー（またはプロキシ・サーバー）が使用可能であれば、パッケージはこのターゲットとの既存の永続的接続を再利用しようとします。使用可能なサーバーがない場合、新しいネットワーク接続が開始されます。要求に対する永続的接続サポートの設定が影響するのは、要求が完了した後にネットワーク接続をクローズするかどうかということについてのみです。

このプロシージャを使用して、要求がセッションのデフォルト設定を継承する永続的接続のサポート設定を変更します。

UTL_HTTPで永続的接続を使用すると、同じサーバーから複数のWebページをフェッチする回数を軽減する一方で、データベース・サーバーのシステム・リソース（ネットワーク接続）が浪費されます。また、データベース・サーバーで多くのネットワーク接続がオープンされたままである場合、永続的接続を過度に使用すると、データベース・サーバーのスケーラビリティが低下します。ネットワーク接続は、後続の要求により即時使用される場合にのみオープンにし、不要な場合にはクローズしてください。通常、セッションではデフォルトの永続的接続サポートを無効にし、個々のHTTP要求で永続的接続を有効にします。詳細は、「例」を参照してください。

データベース・セッションにおける永続的接続の最大数のデフォルト値は0（ゼロ）です。永続的接続を実際に有効にするには、永続的接続の最大数を正の値に設定する必要があります。そうでない場合には、接続は永続的に保持されません。

例

HTTP要求でのSET_PERSISTENT_CONN_SUPPORTの使用

DECLARE
  TYPE vc2_table IS TABLE OF VARCHAR2(256) INDEX BY BINARY_INTEGER;
  paths VC2_TABLE;

UTL_HTTP.fetch_pages(paths IN vc2_table) AS
    url_prefix   VARCHAR2(256) := 'http://www.my-company.com/';
    req          UTL_HTTP.REQ;
    resp         UTL_HTTP.RESP;
    data  VARCHAR2(1024);
  BEGIN
    FOR i IN 1..paths.count LOOP
      req := UTL_HTTP.BEGIN_REQUEST(url_prefix || paths(i));
      -- Use persistent connection except for the last request
      IF (i < paths.count) THEN
        UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT(req, TRUE);
      END IF;
      resp := UTL_HTTP.GET_RESPONSE(req);
      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
  UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT(FALSE, 1);
  paths(1) := '...';
  paths(2) := '...';
  ...
  fetch_pages(paths);
END;

SET_PROXYプロシージャ

このプロシージャは、HTTPプロトコルまたはその他のプロトコルの要求に使用するプロキシを設定します。no_proxy_domainsで指定されたドメインに属するホストへの要求は除外されます。no_proxy_domainsは、ドメインまたはホストをカンマ、セミコロンまたはスペースで区切ったリストです。HTTP要求は、宛先のHTTPサーバーのこれらのドメインまたはホストには、プロキシ・サーバーを経由せずに直接送信されます。

関連項目:

構文

UTL_HTTP.SET_PROXY (
   proxy             IN VARCHAR2,
   no_proxy_domains  IN VARCHAR2);

パラメータ

表207-49 SET_PROXYプロシージャのパラメータ

パラメータ	説明
`proxy`	`UTL_HTTP`パッケージにより使用されるプロキシ（ホストおよびオプションのポート番号）。
`no_proxy_domains`	プロキシをすべての要求に対して使用しないホストおよびドメインのリスト。

使用上の注意

プロキシには、プロキシ・サーバーがリスニングするオプションの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のプロキシ設定が想定されます。このプロシージャにより設定されたプロキシ設定は、初期の設定より優先されます。

SET_RESPONSE_ERROR_CHECKプロシージャ

このプロシージャは、Webサーバーがエラーを示すステータス・コード（4xxまたは5xx）を戻した場合に、GET_RESPONSEが例外を呼び出すかどうかを設定します。たとえば、要求したURLが宛先のWebサーバーで見つからない場合、404（ドキュメントが見つからない）の応答ステータス・コードが戻されます。

関連項目:

構文

UTL_HTTP.SET_RESPONSE_ERROR_CHECK (
   enable  IN BOOLEAN DEFAULT FALSE);

パラメータ

表207-50 SET_RESPONSE_ERROR_CHECKプロシージャのパラメータ

パラメータ	説明
`enable`	応答エラーをチェックする場合は`TRUE`、そうでない場合は`FALSE`です。

使用上の注意

ステータス・コードがエラーを示す4xxまたは5xxで、このプロシージャが有効である場合は、GET_RESPONSEがHTTP_CLIENT_ERRORまたはHTTP_SERVER_ERROR例外を呼び出します。 SET_RESPONSE_ERROR_CHECKがFALSEに設定されている場合は、ステータス・コードがエラーを示してもGET_RESPONSEは例外を呼び出しません。

デフォルトでは、応答エラー・チェックはオフになっています。

SET_RESPONSE_ERROR_CHECKをFALSEに設定すると、GET_RESPONSEファンクションによってその他の例外が発生する可能性があります。

SET_TRANSFER_TIMEOUTプロシージャ

このプロシージャは、Webサーバーまたはプロキシ・サーバーからHTTP応答を読み込むまでUTL_HTTPパッケージが試行する、将来のすべてのHTTP要求についてのデフォルトのタイムアウト値を設定します。このタイムアウト値を使用して、WebサーバーからWebページを取り出す間、ビジー状態のWebサーバーや通信量の多いネットワークによりPL/SQLプログラムがブロックされることを回避します。

関連項目:

構文

UTL_HTTP.SET_TRANSFER_TIMEOUT (
   timeout  IN PLS_INTEGER DEFAULT 60);

パラメータ

表207-51 SET_TRANSFER_TIMEOUTプロシージャのパラメータ

パラメータ	説明
`timeout`	ネットワーク転送のタイムアウト値（秒）。

使用上の注意

タイムアウトのデフォルト値は60秒です。

SET_WALLETプロシージャ

このプロシージャは、Secure Sockets Layer（SSL）、つまりHTTPSを経由するHTTP要求すべてに使用するOracle Walletを設定します。 UTL_HTTPパッケージがSSLを介してHTTPサーバーと通信する場合、HTTPサーバーは認証局が署名したデジタル証明書をUTL_HTTPパッケージに示し、身分を証明します。 Oracle Walletには、UTL_HTTPパッケージのユーザーが信頼する認証局のリストが含まれています。Oracle Walletは、HTTPS要求を作成するために必要です。

関連項目:

構文

UTL_HTTP.SET_WALLET (
   path      IN VARCHAR2,
   password  IN VARCHAR2 DEFAULT NULL);

パラメータ

表207-52 SET_WALLETプロシージャのパラメータ

パラメータ説明

path

Oracle Walletを含むディレクトリ・パス。形式はfile:<directory-path>です。

wallet_pathの形式は、たとえば、PCではfile:c:\WINNT\Profiles\<username>\WALLETS、UNIXではfile:/home/<username>/walletsとなります。UTL_HTTPパッケージがOracle Databaseサーバーで実行される場合は、データベース・サーバーからWalletにアクセスします。したがって、Walletのパスにデータベース・サーバーからアクセスできる必要があります。

password

Walletのオープンに必要なパスワード。パスワードなしの場合、Walletディレクトリ内のWalletの2番目のコピーでオープンする場合があります。この2番目のコピーは読取り専用です。 passwordがNULLの場合、UTL_HTTPパッケージがWalletの2番目の読取り専用コピーをオープンします。

使用上の注意

Oracle Walletを設定するには、Oracle Wallet Managerを使用してWalletを作成します。HTTPS要求を成功させるには、リモートHTTPS Webサーバーの証明書に署名した認証局がWalletに設定されたトラスト・ポイントであることが必要です。

Walletが作成されると、トラスト・ポイントとして認識された認証局に移入されます。リモートHTTPS Webサーバーの証明書に署名した認証局がトラスト・ポイントにない場合、または新しいルート証明書を持っている場合は、認証局のルートの証明書を取得し、Oracle Wallet Managerを使用してWalletのトラスト・ポイントとしてインストールする必要があります。

関連項目:

Wallet Managerの詳細は、『Oracle Database Advanced Security管理者ガイド』を参照してください。

WRITE_LINEプロシージャ

このプロシージャは、HTTP要求本体にテキスト行を書き込み、改行文字（UTL_TCPで定義されるCRLF）を使用して行を終了します。HTTP要求本体と同じデータが送信されると、HTTP要求ヘッダーのセクションはただちに完了します。テキスト・データは、データベース・キャラクタ・セットから要求本体のキャラクタ・セットに自動的に変換されます。

関連項目:

構文

UTL_HTTP.WRITE_LINE(
   r     IN OUT NOCOPY req,
   data  IN VARCHAR2 CHARACTER SET ANY_CS);

パラメータ

表207-53 WRITE_LINEプロシージャのパラメータ

パラメータ	説明
`r`	HTTP要求。
`data`	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つのキャラクタ・セットのうちいずれかがマルチバイト・キャラクタ・セットである場合、要求本体のキャラクタ・セットの正確なバイト数での長さをあらかじめ認識することはできません。この場合、明示的にキャラクタ・セットの変換を実行し、結果のバイト数の長さを判別し、Content-Lengthヘッダーを送信し、WRITE_RAWプロシージャを使用してキャラクタ・セットの自動変換を回避します。または、リモートWebサーバーまたはCGIプログラムが対応する場合は、HTTP 1.1 chunked transfer-encoding形式を使用して要求本体を送信できます。UTL_HTTPはチャンクの長さを透過的に処理します。

WRITE_RAWプロシージャ

このプロシージャは、HTTP要求本体にバイナリ・データを書き込みます。HTTP要求本体と同じデータが送信されると、HTTP要求ヘッダーのセクションはただちに完了します。

関連項目:

構文

UTL_HTTP.WRITE_RAW(
   r     IN OUT NOCOPY REQ,
   data  IN            RAW);

パラメータ

表207-54 WRITE_RAWプロシージャのパラメータ

パラメータ	説明
`r`	HTTP要求。
`data`	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プロシージャを参照してください。

WRITE_TEXTプロシージャ

このプロシージャは、HTTP要求本体にテキスト・データを書き込みます。HTTP要求本体と同じデータが送信されると、HTTP要求ヘッダーのセクションはただちに完了します。テキスト・データは、データベース・キャラクタ・セットから要求本体のキャラクタ・セットに自動的に変換されます。

関連項目: