225 UTL_HTTP

構文

UTL_HTTP.ADD_COOKIES (
   cookies          IN  cookie_table,
   request_context  IN  request_context_key DEFAULT NULL);

パラメータ

表225-17 ADD_COOKIESプロシージャのパラメータ

パラメータ	説明
`cookies`	追加されるCookie。
`request_context`	Cookieを追加する要求コンテキスト。`NULL`の場合、Cookieは`UTL_HTTP`パッケージのセッション状態に追加されます。

使用上の注意

パッケージが現在保持する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,
   request_context   IN  request_context_key DEFAULT NULL)
RETURN req;

パラメータ

表225-18 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`です。
`request_context`	この`HTTP`要求で使用するプライベートのWalletおよびCookieの表を保持する要求コンテキスト。このパラメータが`NULL`の場合、現在のデータベース・セッションで共有しているWalletおよびCookieの表がかわりに使用されます。

使用上の注意

このファンクションに引数として渡されたURLについては、URL仕様RFC 2396による不正な文字(空白など)の検証は行われません。コールを実行する場合は、UTL_URLパッケージを使用してこのような文字をエスケープする必要があります。URLはUS-ASCII文字のみで構成する必要があります。URLで有効な文字のリストは、第239章「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権限が必要です。

CLEAR_COOKIESプロシージャ

このプロシージャは、要求コンテキストまたはUTL_HTTPパッケージのセッション状態のいずれかに保持されているCookieをすべて消去します。

関連項目:

構文

UTL_HTTP.CLEAR_COOKIES (
   request_context  IN  request_context_key DEFAULT NULL);

パラメータ

表225-19 CLEAR_COOKIESプロシージャのパラメータ

パラメータ	説明
`request_context`	Cookieを消去する要求コンテキスト。`NULL`の場合、`UTL_HTTP`パッケージのセッション状態に保持されているCookieがかわりに消去されます。

CLOSE_PERSISTENT_CONNプロシージャ

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

関連項目:

構文

UTL_HTTP.CLOSE_PERSISTENT_CONN (
   conn  IN connection);

パラメータ

表225-20 CLOSE_PERSISTENT_CONNプロシージャのパラメータ

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

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

パラメータ

表225-21 CLOSE_PERSISTENT_CONNSプロシージャのパラメータ

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

使用上の注意

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

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

CREATE_REQUEST_CONTEXTファンクション

このファンクションは、要求コンテキストを作成します。要求コンテキストとは、HTTP要求時にプライベートで使用するWalletおよびCookieを保持しているコンテキストのことです。これによって、HTTP要求では、同じデータベース・セッションでHTTP要求をする他のアプリケーションと共有されないWalletおよびCookieの表を使用できます。

関連項目:

「要求コンテキスト」および「HTTP要求コンテキスト・サブプログラム」

構文

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;

パラメータ

表225-22 CREATE_REQUEST_CONTEXTファンクションのパラメータ

パラメータ	説明
`wallet_path`	Oracle Walletを含むディレクトリ・パス。形式は`file:directory-path`です。
`wallet_password`	Walletのオープンに必要なパスワード。Walletの自動ログインが有効の場合は、パスワードを省略して`NULL`に設定する必要があります。Walletの詳細は、『Oracle Database Advanced Security管理者ガイド』を参照してください。
`enable_cookies`	この要求コンテキストを使用しているHTTP要求が、HTTP Cookieをサポートするかどうかを設定します。`TRUE`の場合はサポートが有効になり、`FALSE`の場合はサポートが無効になります。
`max_cookies`	この要求コンテキストで保持されるCookieの最大合計数を設定します。
`max_cookies_per_site`	この要求コンテキストで保持される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;

DESTROY_REQUEST_CONTEXTプロシージャ

このプロシージャは、UTL_HTTPの要求コンテキストを破棄します。HTTP要求またはHTTP応答で要求コンテキスが使用されている場合、その要求コンテキストを破棄することはできません。

関連項目:

「要求コンテキスト」および「HTTP要求コンテキスト・サブプログラム」

構文

UTL_HTTP.DESTROY_REQUEST_CONTEXT (
   request_context    request_context_key);

パラメータ

表225-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;

END_REQUESTプロシージャ

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

関連項目:

構文

UTL_HTTP.END_REQUEST (
   r  IN OUT NOCOPY req);

パラメータ

表225-24 END_REQUESTプロシージャのパラメータ

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

END_RESPONSEプロシージャ

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

関連項目:

構文

UTL_HTTP.END_RESPONSE (
   r  IN OUT NOCOPY resp);

パラメータ

表225-25 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);

パラメータ

表225-26 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);

パラメータ

表225-27 GET_BODY_CHARSETプロシージャのパラメータ

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

GET_COOKIE_COUNTファンクション

このファンクションは、要求コンテキストまたはUTL_HTTPパッケージのセッション状態のいずれかに保持されているCookieの数を戻します。

関連項目:

構文

UTL_HTTP.GET_COOKIE_COUNT (
   request_context  IN  request_context_key DEFAULT NULL) 
 RETURN PLS_INTEGER;

パラメータ

表225-28 GET_COOKIE_COUNTファンクションのパラメータ

パラメータ	説明
`request_context`	Cookieの数が戻される要求コンテキスト。`NULL`の場合は、`UTL_HTTP`パッケージのセッション状態に保持されているCookieの数が戻されます。

GET_COOKIE_SUPPORTプロシージャ

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

関連項目:

構文

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

パラメータ

表225-29 GET_COOKIE_SUPPORTプロシージャのパラメータ

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

GET_COOKIESファンクション

このファンクションは、要求コンテキストまたはUTL_HTTPパッケージのセッション状態のいずれかに保持されているCookieをすべて戻します。

関連項目:

構文

UTL_HTTP.GET_COOKIES (
   cookies          IN  OUT NOCOPY cookie_table,
   request_context  IN             request_context_key DEFAULT NULL);

パラメータ

表225-30 GET_COOKIESファンクションのパラメータ

パラメータ	説明
`cookies`	戻されるCookie。
`request_context`	Cookieが戻される要求コンテキスト。`NULL`の場合、`UTL_HTTP`パッケージのセッション状態に保持されているCookieがかわりに戻されます。

GET_DETAILED_EXCP_SUPPORTプロシージャ

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

関連項目:

構文

UTL_HTTP.GET_DETAILED_EXCP_SUPPORT (
   enable  OUT BOOLEAN);

パラメータ

表225-31 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);

パラメータ

表225-32 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);

パラメータ

表225-33 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);

パラメータ

表225-34 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;

パラメータ

表225-35 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);

パラメータ

表225-36 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);

パラメータ

表225-37 GET_PERSISTENT_CONNSプロシージャのパラメータ

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

使用上の注意

GET_PROXYプロシージャ

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

関連項目:

構文

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

パラメータ

表225-38 GET_PROXYプロシージャのパラメータ

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

GET_RESPONSEファンクション

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

関連項目:

構文

UTL_HTTP.GET_RESPONSE (
   r                       IN OUT NOCOPY req,
   return_info_response    IN BOOLEAN DEFAULT FALSE) 
RETURN resp;

パラメータ

表225-39 GET_RESPONSEファンクションのパラメータ

パラメータ説明

r

HTTP応答。

return_info_response

100情報レスポンスを戻すか戻さないか。

TRUEを指定すると、get_responseはHTTPサーバーから100情報レスポンスを受信したときにこのレスポンスを戻します。100レスポンスが戻された場合、リクエストは終了しません。
FALSEを指定すると、APIはHTTPサーバーから受信した100情報レスポンスをすべて無視し、後続の100以外のレスポンスをかわりに戻します。デフォルトはFALSEです。

例外

詳細例外を無効にした場合:

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;

GET_RESPONSE_ERROR_CHECKプロシージャ

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

関連項目:

構文

UTL_HTTP.GET_RESPONSE_ERROR_CHECK (
   enable  OUT BOOLEAN);

パラメータ

表225-40 GET_RESPONSE_ERROR_CHECKプロシージャのパラメータ

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

GET_TRANSFER_TIMEOUTプロシージャ

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

関連項目:

構文

UTL_HTTP.GET_TRANSFER_TIMEOUT (
   timeout  OUT PLS_INTEGER);

パラメータ

表225-41 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);

パラメータ

表225-42 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);

パラメータ

表225-43 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);

パラメータ

表225-44 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);

パラメータ

表225-45 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>

例

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;

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

パラメータ

表225-46 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(len); 
  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);

パラメータ

表225-47 SET_AUTHENTICATIONプロシージャのパラメータ

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

使用上の注意

サポートされている認証方式は、HTTP基本認証およびAmazon S3認証です。

SET_AUTHENTICATION_FROM_WALLETプロシージャ

このプロシージャは、Oracle Walletに格納されているユーザー名とパスワードの資格証明を使用して、Webサーバーで認証される要求に必要なHTTP要求ヘッダーの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);

パラメータ

表225-48 SET_AUTHENTICATION_FROM_WALLETプロシージャのパラメータ

パラメータ	説明
`r`	HTTP要求。
`alias`	Oracle Walletに格納されているユーザー名とパスワードを識別して取得するための別名。
`scheme`	HTTP認証方式。`Basic`(HTTP基本認証方式)または`AWS`(Amazon S3認証方式)のいずれか。デフォルトはBasicです。
`for_proxy`	HTTP認証情報がWebサーバーではなくHTTPプロキシ・サーバーにアクセスするためのものであるかどうかを識別します。デフォルトは`FALSE`です。

使用上の注意

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;

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

パラメータ

表225-49 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);

パラメータ

表225-50 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要求に対して無効である場合は、その要求で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の取出し、保存およびリストアを行う方法については、「例」を参照してください。

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

パラメータ

表225-51 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);

パラメータ

表225-52 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);

パラメータ

表225-53 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要求が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);

パラメータ

表225-54 SET_PERSISTENT_CONN_SUPPORTプロシージャのパラメータ

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

使用上の注意

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

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

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

UTL_HTTPで永続的接続を使用すると、同じサーバーから複数のWebページをフェッチする時間を短縮できる一方で、データベース・サーバーの貴重なシステム・リソース(ネットワーク接続)が消費されることにユーザーは注意してください。また、データベース・サーバーで多くのネットワーク接続がオープンにされたままである場合、永続的接続を過度に使用すると、データベース・サーバーのスケーラビリティが低下することがあります。ネットワーク接続は、後続の要求により即時使用される場合にのみオープンにし、不要な場合にはクローズしてください。次に示すように、セッションではデフォルトの永続的接続のサポートは無効に設定し、個々のHTTP要求で永続的接続を有効にします。

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

例

セッション・レベルでの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.us.oracle.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.oracle.com/technetwork/index.html';
   paths(2) := 'http://www.oracle.com/us/products/index.html';

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

パラメータ

表225-55 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);

パラメータ

表225-56 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);

パラメータ

表225-57 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要求を作成するために必要です。

関連項目:

セッションの設定およびセッションの設定サブプログラム
『Oracle Databaseセキュリティ・ガイド』のPL/SQLネットワーク・ユーティリティ・パッケージでのファイングレイン・アクセスの管理に関する項

構文

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

パラメータ

表225-58 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の自動ログインが有効の場合は、パスワードを省略してNULLに設定する必要があります。自動ログインWalletを作成するためのOracle Wallet ManagerおよびORAPKIユーティリティの使用方法については、『Oracle Database Advanced Security管理者ガイド』の自動ログインが有効なウォレットの使用に関する項を参照してください。

使用上の注意

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

パラメータ

表225-59 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つのキャラクタ・セットのうちいずれかがマルチバイト・キャラクタ・セットである場合、要求本体のキャラクタ・セットの正確なバイト数での長さをあらかじめ知ることはできません。この場合、明示的にキャラクタ・セットの変換を実行し、結果のバイト長を判別し、キャラクタ・セットの自動変換を回避するためにWRITE_RAWプロシージャを使用してContent-Lengthヘッダーおよび結果を送信します。または、リモート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);

パラメータ

表225-60 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要求ヘッダーのセクションはただちに完了します。テキスト・データは、データベース・キャラクタ・セットから要求本体のキャラクタ・セットに自動的に変換されます。

関連項目: