266 UTL_URL

UTL_URLパッケージには、ESCAPEおよびUNESCAPEの2つのファンクションがあります。

UTL_URLの使用方法

概要
例外
例

概要

Uniform Resource Locator(URL)は、ページや画像などのWebリソースを識別する文字列です。URLを使用すると、Hypertext Transfer Protocol(HTTP)を介してこのようなリソースにアクセスできます。たとえば、OracleのWebサイトのURLは次のとおりです。

http://www.oracle.com

通常、URLには英語のアルファベット文字、数字および句読点記号が含まれます。このような文字は、未予約文字と呼ばれます。マルチバイト・キャラクタやバイナリ・オクテット・コードなどの他の文字は、WebブラウザまたはWebサーバーが正確に処理されるようにエスケープする必要があります。ドル記号($)、疑問符(?)、コロン(:)および等号(=)など一部の句読点文字は、URLのデリミタとして予約されています。このような文字は、予約文字と呼ばれます。このような文字を処理するには、デリミタとして文字を扱うのではなく、エスケープする必要があります。

未予約文字は次のとおりです。

AからZ、aからzおよび0から9。
ハイフン(-)、アンダースコア(_)、ピリオド(.)、感嘆符(!)、チルダ(~)、アスタリスク(*)、アクセント(')、左カッコ(()、右カッコ())。

予約文字は次のとおりです。

セミコロン(;)、スラッシュ(/)、疑問符(?)、コロン(:)、アット・マーク(@)、アンパサンド(&)、等号(=)、プラス記号(+)、ドル記号($)、パーセント記号(%)およびカンマ(,)。

UTL_URLパッケージは、URL文字のエスケープおよびエスケープ解除のメカニズムを提供する2つのファンクションを備えています。UTL_HTTPパッケージを経由してURLがWebページをフェッチする前に、このエスケープ・ファンクションを使用してURLをエスケープします。URLから情報を抽出する前に、エスケープ解除ファンクションを使用して、エスケープされたURLのエスケープを解除します。

詳細は、Request For Comments(RFC)ドキュメントのRFC2396を参照してください。ここで説明するURLのエスケープおよびエスケープ解除のメカニズムは、HTMLの仕様で説明されている、メカニズムをエンコードするx-www-form-urlencodedとは異なります。

http://www.w3.org/TR/html

例外

表266-1に、UTL_URLパッケージのAPIが起動されたときに発生する可能性のある例外を示します。

表266-1 UTL_URLの例外

例外	エラー・コード	理由
`BAD_URL`	`29262`	URLに含まれているエスケープ・コード列が不適切です。
`BAD_FIXED_WIDTH_CHARSET`	`29274`	固定長マルチバイト・キャラクタ・セットはURLキャラクタ・セットとして許可されていません。

例

x-www-form-urlencodedエンコーディングは、UTL_URL.ESCAPEファンクションを使用して次のように実装できます。

CREATE OR REPLACE FUNCTION form_url_encode (
   data    IN VARCHAR2,
   charset IN VARCHAR2) RETURN VARCHAR2 AS 
BEGIN 
  RETURN utl_url.escape(data, TRUE, charset); -- note use of TRUE
END;

form-URL-encode schemeを使用してエンコードしたデータをデコードする場合は、次のファンクションによってデコード・スキームが実装されます。

CREATE OR REPLACE FUNCTION form_url_decode(
   data    IN VARCHAR2, 
   charset IN VARCHAR2) RETURN VARCHAR2 AS
BEGIN 
  RETURN utl_url.unescape(
     replace(data, '+', ' '), 
     charset); 
END;

UTL_URLサブプログラムの要約

表266-2 UTL_URLパッケージのサブプログラム

サブプログラム	説明
ESCAPEファンクション	`%2-digit-hex-code`形式を使用してエスケープされた、不正な文字(およびオプションで予約文字)を含むURLを戻します。
UNESCAPEファンクション	エスケープ文字列をエスケープ解除し、URLの元の形式にします。`%XX`エスケープ文字列を元の文字に変換します。

ESCAPEファンクション

このファンクションは、%2-digit-hex-code形式を使用してエスケープされた、不正な文字(およびオプションで予約文字)を含むURLを戻します。

構文

UTL_URL.ESCAPE (
   url                   IN VARCHAR2 CHARACTER SET ANY_CS,
   escape_reserved_chars IN BOOLEAN  DEFAULT  FALSE,
   url_charset           IN VARCHAR2 DEFAULT  utl_http.body_charset)
 RETURN VARCHAR2;

パラメータ

表266-3 ESCAPEファンクションのパラメータ

パラメータ	説明
`url`	元のURL。
`escape_reserved_chars`	URLの予約文字をエスケープする必要があるかどうかを示します。`TRUE`に設定すると、URLの予約文字および不正な文字の両方がエスケープされます。それ以外の場合、不正なURL文字のみがエスケープされます。デフォルト値は`FALSE`です。
`url_charset`	文字(シングルバイトまたはマルチバイト)のエスケープに際して、%hex-code形式でエスケープする前に、その文字をどのキャラクタ・セットに変換すべきかを指定します。`url_charset`が`NULL`の場合、データベース・キャラクタ・セットとみなされ、キャラクタ・セットの変換は行われません。現在`UTL_HTTP`パッケージの本体キャラクタ・セットのデフォルトである`ISO-8859-1`がデフォルト値です。キャラクタ・セットは、Internet Assigned Numbers Authority(IANA)またはOracleのネーミング規則で命名できます。

使用上の注意

このファンクションを使用して、URL仕様RFC 2396で定義された不正な文字を含むURLをエスケープします。URLの適切な文字は次のとおりです。

AからZ、aからzおよび0から9。
ハイフン(-)、アンダースコア(_)、ピリオド(.)、感嘆符(!)、チルダ(~)、アスタリスク(*)、アクセント(')、左カッコ(()、右カッコ())。

予約文字は次のとおりです。

セミコロン(;)、スラッシュ(/)、疑問符(?)、コロン(:)、アット・マーク(@)、アンパサンド(&)、等号(=)、プラス記号(+)、ドル記号($)およびカンマ(,)。

予約文字の多くは、URLでデリミタとして使用されます。前述の文字以外については、escape_urlを使用してエスケープする必要があります。また、URLの問合せ文字列で名前と値の組合せに予約文字を使用するには、別々に文字をエスケープする必要があります。escape_urlは文字をエスケープする必要があるかどうかを認識できません。これは、文字がいったんURLに組み込まれると、実際のデリミタからは認識不可能になるためです。たとえば、$logon=scott/tigerという名前と値の組合せをURLの問合せ文字列に渡すには、$および/を%24logon=scott%2Ftigerとして個別にエスケープし、URLで使用します。

通常は、エスケープの対象でない予約文字(デリミタ)も含めてURL全体をエスケープします。次に例を示します。

utl_url.escape('http://www.acme.com/a url with space.html')

戻り値

http://www.acme.com/a%20url%20with%20space.html

他の状況では、予約文字を含む値を使用した問合せ文字列を送信できます。この場合、escape_reserved_charsをTRUEに設定して対象の値のみを完全にエスケープし、URLの残りの部分に連結します。次に例を示します。

url := 'http://www.acme.com/search?check=' || utl_url.escape
('Is the use of the "$" sign okay?', TRUE);

この式は、'Is the use of the "$" sign okay?'の疑問符(?)、ドル記号($)および空白文字をエスケープしていますが、問合せ文字列の使用を示すURLのsearchの後の?はエスケープされていません。

WebページをフェッチするWebサーバーでは、ユーザーのデータベースと異なるキャラクタ・セットを使用することがあります。この場合は、Webサーバーのキャラクタ・セットにurl_charsetを指定し、エスケープする必要のある文字がターゲットのキャラクタ・セットでエスケープされるようにします。たとえば、ASCII WebサーバーにアクセスするEBCDICデータベースのユーザーは、US7ASCIIを使用してURLをエスケープする必要があります。これにより、空白が%40 (EBCDICでの空白のhexコード)ではなく、%20 (ASCIIでの空白のhexコード)にエスケープされます。

このファンクションは、URL形式の妥当性は検証しません。

UNESCAPEファンクション

このファンクションは、URLに含まれるエスケープ文字列をエスケープ解除して元の形式にし、%XXエスケープ文字列を元の文字に変換します。

構文

UTL_URL.UNESCAPE (
   url            IN VARCHAR2 CHARACTER SET ANY_CS,
   url_charset    IN VARCHAR2 DEFAULT utl_http.body_charset)
                  RETURN VARCHAR2;

パラメータ

表266-4 UNESCAPEファンクションのパラメータ

パラメータ説明

パラメータ	説明
`url`	エスケープ解除するURL。
`url_charset`	文字のエスケープが解除された後、その文字は`source_charset`キャラクタ・セットにあるとみなされ、`source_charset`からデータベース・キャラクタ・セットに変換されます。その後、URLが戻されます。`source_charset`が`NULL`の場合、データベース・キャラクタ・セットとみなされ、キャラクタ・セットの変換は行われません。現在`UTL_HTTP`パッケージの本体キャラクタ・セットのデフォルトであるISO-8859-1がデフォルト値です。キャラクタ・セットは、Internet Assigned Numbers Authority (IANA)またはOracleのネーミング規則で命名できます。

url

エスケープ解除するURL。

url_charset

文字のエスケープが解除された後、その文字はsource_charsetキャラクタ・セットにあるとみなされ、source_charsetからデータベース・キャラクタ・セットに変換されます。その後、URLが戻されます。source_charsetがNULLの場合、データベース・キャラクタ・セットとみなされ、キャラクタ・セットの変換は行われません。現在UTL_HTTPパッケージの本体キャラクタ・セットのデフォルトであるISO-8859-1がデフォルト値です。キャラクタ・セットは、Internet Assigned Numbers Authority (IANA)またはOracleのネーミング規則で命名できます。

使用上の注意

URLを受信するWebサーバーでは、ユーザーのデータベースと異なるキャラクタ・セットを使用することがあります。この場合は、Webサーバーのキャラクタ・セットにurl_charsetを指定し、エスケープを解除する必要のある文字がソースのキャラクタ・セットでエスケープ解除されるようにします。たとえば、ASCII WebサーバーからURLを受信するEBCDICデータベースのユーザーは、US7ASCIIを使用してURLのエスケープを解除する必要があります。これにより、%20 (0x20はASCIIでの空白のhexコード)が?ではなく、空白としてエスケープ解除されます(0x20はEBCDICで有効な文字ではないため)。

このファンクションは、URL形式の妥当性は検証しません。