Caching Proxy API の参照情報

変数

リモート・クライアントおよびサーバー・システムに関する 情報を提供する Caching Proxy 変数を使用して、API プログラムを書くことができます。

注 :

変数定義

注:
HTTP_ または PROXY_ 接頭部が付いていない ヘッダー変数はあいまいです。 あいまいさを避けるために、 ヘッダーの変数名とともに常に HTTP_ または PROXY_ 接頭部を使用してください。
ACCEPT_RANGES
Accept-Ranges 応答ヘッダーの値が入ります。 これは、コンテンツ・サーバーが範囲要求に 応答できるかどうかを指定します。 PROXY_ACCEPT_RANGES を使用して、 コンテンツ・サーバーからプロキシーに送信される ヘッダー値を抽出してください。 HTTP_ACCEPT_RANGES を使用して、 プロキシーからクライアントに送信される ヘッダー値を設定してください。
注:
ACCEPT_RANGES はあいまいです。あいまいさを 排除するには、代わりに HTTP_ACCEPT_RANGES および PROXY_ACCEPT_RANGES を 使用してください。
ALL_VARIABLES
読み取り専用。すべての CGI 変数が入ります。 以下に例を示します。
     ACCEPT_RANGES BYTES
     CLIENT_ADDR 9.67.84.3
AUTH_STRING
読み取り専用。サーバーがクライアント認証をサポートする場合は、このストリングには、クライアントを認証するのに使用される、デコードされていないクレデンシャルが入ります。
AUTH_TYPE
読み取り専用。サーバーがクライアント認証をサポートし、スクリプトが保護されている場合は、この変数にはクライアントの認証に使用される方式が入ります。例えば Basic です。
CACHE_HIT
読み取り専用。キャッシュ内にプロキシー要求が見つかったかどうかを示します。以下の値が戻されます。
CACHE_MISS
書き込み専用。キャッシュ・ミスを強制するかどうかを定義します。 有効な値は次のとおりです。
CACHE_TASK
読み取り専用。キャッシュが使用されたかどうかを識別します。 以下の値が戻されます。

この変数は、PostAuthorization、PostExit、ProxyAdvisor、または Log ステップで使用できます。

CACHE_UPDATE
読み取り専用。プロキシー要求がキャッシュを更新したかどうかを示します。以下の値が戻されます。
CLIENT_ADDR または CLIENTADDR
REMOTE_ADDR と同じ。
CLIENTMETHOD
REQUEST_METHOD と同じ。
CLIENT_NAME または CLIENTNAME
REMOTE_HOST と同じ。
CLIENT_PROTOCOL または CLIENTPROTOCOL
クライアントが要求を出すために使用するプロトコルの名前とバージョンが入ります。 例えば HTTP/1.1 です。
CLIENT_RESPONSE_HEADERS
読み取り専用。サーバーがクライアントに送信するヘッダーを含むバッファーを戻します。
CONNECTIONS
読み取り専用。使用されている接続の数またはアクティブな要求の数が入ります。 例えば 15 です。
CONTENT_CHARSET
text/* 用の応答の文字セットです。例えば US ASCII です。この変数の抽出は、クライアントからのコンテンツ文字セットのヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるコンテンツ文字セットのヘッダーが影響を受けます。
CONTENT_ENCODING
文書で使用されるエンコードを指定します。例えば x-gzip です。この変数の抽出は、クライアントからのコンテンツ・エンコードのヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるコンテンツ・エンコードのヘッダーが影響を受けます。
CONTENT_LENGTH
この変数の抽出は、クライアントの要求から得られるヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるヘッダーの値が影響を受けます。

注:
CONTENT_LENGTH はあいまいです。あいまいさを排除する場合は、HTTP_CONTENT_LENGTH および PROXY_CONTENT_LENGTH を使用してください。
CONTENT_TYPE
この変数の抽出は、クライアントの要求から得られるヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるヘッダーの値が影響を受けます。

注:
CONTENT_TYPE はあいまいです。あいまいさを排除する場合は、HTTP_CONTENT_TYPE および PROXY_CONTENT_TYPE を使用してください。
CONTENT_TYPE_PARAMETERS
その他の MIME 属性が入りますが、 文字セットは入りません。 この変数の抽出は、クライアント要求から得られるヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるヘッダーの値が影響を受けます。
DOCUMENT_URL
URL (Uniform Request Locator) が入ります。 以下に例を示します。
http://www.anynet.com/~userk/main.htm
DOCUMENT_URI
DOCUMENT_URL と同じ。
DOCUMENT_ROOT
読み取り専用。パス・ルールによる定義のとおりの文書ルート・パスが入ります。
ERRORINFO
エラー・ページを判別するエラー・コードを指定します。例えば blocked です。
EXPIRES
プロキシーのキャッシュに保管された文書の有効期限が切れる時期を定義します。この変数の抽出は、クライアント要求から得られるヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるヘッダーの値が影響を受けます。以下に例を示します。
Mon, 01 Mar 2002 19:41:17 GMT
GATEWAY_INTERFACE
読み取り専用。サーバーが使用している API のバージョンが入ります。 例えば ICSAPI/2.0 です。
GC_BIAS
書き込み専用。この浮動小数点値は、 ガーベッジ・コレクションを考慮されている ファイルのガーベッジ・コレクションについての決定に影響します。 入力された値は、そのファイル・タイプの Caching Proxy の品質設定値と乗算され、 ランキングが決定されます。品質設定値は 0.0 から 0.1 の範囲の値であり、 プロキシー構成ファイル (ibmproxy.conf) 内の AddType ディレクティブによって 定義されます。
GC_EVALUATION
書き込み専用。この浮動小数点値によって、 ガーベッジ・コレクションを考慮されている ファイルの除去 (0.0) と保持 (1.0) のどちらを行うかを判別します。 0.0 と 1.0 の間の値はランクによって順位を付けられます。 すなわち、GC_EVALUATION 値 0.1 を持つ ファイルは、GC_EVALUATION 値 0.9 を持つファイルよりも 除去される可能性が高くなります。
GC_EXPIRES
読み取り専用。考慮中のファイルがキャッシュ内で有効期限切れとなるまでの残り秒数を示します。この変数を抽出できるのは、GC Advisor プラグインのみです。
GC_FILENAME
読み取り専用。ガーベッジ・コレクション用に考慮されているファイルを示します。この変数を抽出できるのは、GC Advisor プラグインのみです。
GC_FILESIZE
読み取り専用。ガーベッジ・コレクション用に考慮されているファイルのサイズを示します。この変数を抽出できるのは、GC Advisor プラグインのみです。
GC_LAST_ACCESS
読み取り専用。ファイルが最後にアクセスされた時期を示します。この変数を抽出できるのは、GC Advisor プラグインのみです。
GC_LAST_CHECKED
読み取り専用。ファイルが最後に検査された時期を示します。この変数を抽出できるのは、GC Advisor プラグインのみです。
GC_LOAD_DELAY
読み取り専用。ファイルの検索に掛かる時間を示します。この変数を抽出できるのは、GC Advisor プラグインのみです。
HTTP_COOKIE
この変数には、読み取り時に、クライアントによって 設定された Set-Cookie ヘッダーの値が入ります。 これは、応答ストリーム (プロキシーとクライアントの間) での 新しい cookie の設定に使用することもできます。 この変数を設定すると、重複するヘッダーの有無に関係なく、文書要求ストリームの中に新しい Set-Cookie ヘッダーが作成されます。
HTTP_HEADERS
読み取り専用。すべてのクライアント要求ヘッダーの抽出に使用されます。
HTTP_REASON
この変数を設定すると、HTTP 応答内の理由ストリングが影響を受けます。 また、この設定により、 クライアントに対するプロキシーの応答に含まれる理由ストリングも影響を受けます。 この変数を抽出すると、コンテンツ・サーバーから プロキシーへの応答で理由ストリングが戻されます。
HTTP_RESPONSE
この変数を設定すると、HTTP 応答内の応答コードが影響を受けます。 また、この設定により、クライアントに対するプロキシーの応答に含まれる状況コードも影響を受けます。この変数を抽出すると、 コンテンツ・サーバーからプロキシーへの応答で状況コードが戻されます。
HTTP_STATUS
HTTP 応答コードおよび理由ストリングが入ります。例えば 200 OK です。
HTTP_USER_AGENT
User-Agent 要求ヘッダーの値が入ります。 これは、クライアント Web ブラウザーの名前 (例えば、Netscape Navigator / V2.02) です。この変数を設定すると、クライアントに対するプロキシーの応答に含まれるヘッダーが 影響を受けます。この変数の抽出は、クライアントの要求から得られるヘッダーに適用されます。
INIT_STRING
読み取り専用。このストリングは、ServerInit ディレクティブで定義されます。この変数は、Server Initialization ステップでのみ読み取ることができます。
LAST_MODIFIED
この変数の抽出は、クライアント要求から得られるヘッダーに適用されます。この変数を設定すると、コンテンツ・サーバーへの要求におけるヘッダーの値が影響を受けます。 以下に例を示します。
Mon, 01 Mar 1998 19:41:17 GMT
LOCAL_VARIABLES
読み取り専用。全ユーザー定義変数。
MAXACTIVETHREADS
読み取り専用。アクティブ・スレッドの最大数。
NOTMODIFIED_TO_OK
クライアントへの完全応答を強制します。 PreExit および ProxyAdvisor ステップで有効です。
ORIGINAL_HOST
読み取り専用。要求のホスト名または宛先 IP アドレスを戻します。
ORIGINAL_URL
読み取り専用。クライアント要求で送信された元の URL を戻します。
OVERRIDE_HTTP_NOTRANSFORM
Cache-Control: no-transform ヘッダーがある場合にデータを変更できるようにします。この変数を設定すると、クライアントへの応答ヘッダーが影響を受けます。
OVERRIDE_PROXY_NOTRANSFORM
Cache-Control: no-transform ヘッダーがある場合にデータを変更できるようにします。この変数を設定すると、コンテンツ・サーバーへの要求が影響を受けます。
PASSWORD
基本認証の場合は、デコードされたパスワードが入ります。例えば password です。
PATH
完全変換パスが入ります。
PATH_INFO
Web ブラウザーが送信したものと同様の追加パス情報が入ります。例えば /foo です。
PATH_TRANSLATED
PATH_INFO に入っているパス情報のデコード・バージョンまたは変換バージョンが入ります。以下に例を示します。
d:¥wwwhome¥foo
/wwwhome/foo
PPATH
部分変換パスが入ります。 これは、Name Translation ステップで使用してください。
PROXIED_CONTENT_LENGTH
読み取り専用。プロキシー・サーバーを介して実際に転送される応答データの長さを戻します。
PROXY_ACCESS
要求がプロキシー要求であるかどうかを定義します。 例えば NO です。
PROXY_CONTENT_TYPE
HTTPD_proxy() を介して出されたプロキシー要求の Content-Type ヘッダーが入ります。 情報が POST のメソッドで送信される場合、この変数には組み込まれたデータのタイプが入ります。プロキシー・サーバー構成ファイル内に独自のコンテンツ・タイプを作成し、このコンテンツ・タイプをビューアーにマップすることができます。この変数の抽出は、コンテンツ・サーバーの応答から得られるヘッダー値に適用されます。この変数を設定すると、コンテンツ・サーバーへの要求のヘッダーが影響を受けます。以下に例を示します。
application/x-www-form-urlencoded
PROXY_CONTENT_LENGTH
HTTPD_proxy() を介して出されたプロキシー要求の Content-Length ヘッダー。 情報が POST のメソッドで送信される場合、この変数にはデータの文字数が入ります。一般に、サーバーは、標準入力を用いて情報を転送するときは、 ファイルの終わりフラグを送信しません。必要な場合は、 CONTENT_LENGTH 値を使用すると、入力ストリングの終わりを判別することができます。この変数の抽出は、コンテンツ・サーバーの応答から得られるヘッダー値に適用されます。この変数を設定すると、コンテンツ・サーバーへの要求のヘッダーが影響を受けます。以下に例を示します。
7034
PROXY_COOKIE
この変数には、読み取り時に、 起点サーバーによって設定された Set-Cookie ヘッダーの値が入ります。 これは、要求ストリームでの新しい cookie の設定に使用することもできます。 この変数を設定すると、重複するヘッダーの有無に関係なく、文書要求ストリームの中に新しい Set-Cookie ヘッダーが作成されます。
PROXY_HEADERS
読み取り専用。プロキシー・ヘッダーの抽出に使用されます。
PROXY_METHOD
HTTPD_proxy() を介して作成された要求のメソッドを示します。この変数の抽出は、コンテンツ・サーバーの応答から得られるヘッダー値に適用されます。この変数を設定すると、コンテンツ・サーバーへの要求のヘッダーが影響を受けます。
QUERY_STRING
情報が GET メソッドを使用して送信される場合、 この変数には照会内の疑問符 (?) に続く情報が入ります。 この情報は CGI プログラムによってデコードしなければなりません。以下に例を示します。
NAME=Eugene+T%2E+Fox&ADDR=etfox%7Cibm.net&INTEREST=xyz
RCA_OWNER
読み取り専用。要求されたオブジェクトを所有していたノードを示す数値を戻します。この変数は、PostExit、ProxyAdvisor、 または Log ステップで使用することが可能であり、 サーバーがリモート・キャッシュ・アクセス (RCA) を使用するキャッシュ配列の一部であるときにのみ意味があります。
RCA_TIMEOUTS
読み取り専用。すべてのピアへの RCA 要求で発生したタイムアウトの合計回数を示す数値を戻します。この変数は、どのステップでも使用することができます。
REDIRECT_*
読み取り専用。変数名 (例えば REDIRECT_URL) に対応する、 エラー・コードのリダイレクト・ストリングが入ります。 考えられる REDIRECT_ 変数のリストは、Apache Web サーバーについての オンライン文書に示されています (http://httpd.apache.org/docs-2.0/custom-error.html)。
REFERRER_URL
読み取り専用。ブラウザーの最後の URL ロケーションが入ります。 この変数により、クライアントは、Request-URL の入手元であるリソースのアドレス (URL) を (サーバーに役立つように) 指定できます。以下に例を示します。
http://www.company.com/homepage
REMOTE_ADDR
Web ブラウザーの IP アドレスが入ります (使用可能な場合)。例えば 45.23.06.8 です。
REMOTE_HOST
Web ブラウザーのホスト名が入ります (使用可能な場合)。例えば www.raleigh.ibm.com です。
REMOTE_USER
サーバーがクライアント認証をサポートし、スクリプトが保護されている場合は、この変数は、認証のために渡されたユーザー名が入ります。例えば joeuser です。
REQHDR
読み取り専用。クライアントによって送信された ヘッダーのリストが入ります。
REQUEST_CONTENT_TYPE
読み取り専用。要求本文のコンテンツ・タイプを戻します。 以下に例を示します。
application/x-www-form-urlencoded
REQUEST_CONTENT_LENGTH
読み取り専用。情報が POST のメソッドで送信される場合、この変数にはデータの文字数が入ります。一般に、サーバーは、標準入力を用いて情報を転送するときは、 ファイルの終わりフラグを送信しません。必要な場合は、 CONTENT_LENGTH 値を使用すると、入力ストリングの終わりを判別することができます。例えば 7034 です。
REQUEST_METHOD
読み取り専用。要求の送信に使用されるメソッド (HTML フォームの METHOD 属性によって指定されたとおりの) が入ります。例えば GET または POST です。
REQUEST_PORT
読み取り専用。URL に指定されたポート番号またはプロトコルに基づいたデフォルト・ポートを戻します。
RESPONSE_CONTENT_TYPE
読み取り専用。情報が POST のメソッドで送信される場合、この変数には組み込まれたデータのタイプが入ります。プロキシー・サーバー構成ファイル内に独自のコンテンツ・タイプを作成し、このコンテンツ・タイプをビューアーにマップすることができます。例えば text/html です。
RESPONSE_CONTENT_LENGTH
読み取り専用。情報が POST のメソッドで送信される場合、この変数にはデータの文字数が入ります。一般に、サーバーは、標準入力を用いて情報を転送するときは、 ファイルの終わりフラグを送信しません。必要な場合は、 CONTENT_LENGTH 値を使用すると、入力ストリングの終わりを判別することができます。例えば 7034 です。
RULE_FILE_PATH
読み取り専用。構成ファイルの完全修飾ファイル・システム・パスおよびファイル名が入ります。
SSL_SESSIONID
読み取り専用。現在の要求が SSL 接続上で受信されたものである場合は、SSL セッション ID を戻します。現在の要求が SSL 接続上で受信されたものでない場合は NULL を戻します。
SCRIPT_NAME
要求の URL が入ります。
SERVER_ADDR
読み取り専用。プロキシー・サーバーのローカル IP アドレスが入ります。
SERVER_NAME
読み取り専用。この要求に関するコンテンツ・サーバーのプロキシー・サーバー・ホスト名または IP アドレスが入ります。例えば www.ibm.com です。
SERVER_PORT
読み取り専用。クライアント要求が送信されたプロキシー・サーバーのポート番号が入ります。例えば 80 です。
SERVER_PROTOCOL
読み取り専用。要求を行うときに使用されるプロトコルの名前とバージョンが入ります。例えば HTTP/1.1 です。
SERVER_ROOT
読み取り専用。プロキシー・サーバー・プログラムがインストールされているディレクトリーが入ります。
SERVER_SOFTWARE
読み取り専用。プロキシー・サーバーの名前とバージョンが入ります。
STATUS
HTTP 応答コードおよび理由ストリングが入ります。例えば 200 OK です。
TRACE
情報をトレースする程度を判別します。戻り値は、以下のとおりです。
URI
読み取り/書き込み。DOCUMENT_URL と同じ。
URI_PATH
読み取り専用。 URL のパス部分だけが戻されます。
URL
読み取り/書き込み。DOCUMENT_URL と同じ。
URL_MD4
読み取り専用。現行要求の潜在的なキャッシュ・ファイルのファイル名を戻します。
USE_PROXY
現行要求を関連付けるプロキシーを識別します。 URL を指定します。例えば http://myproxy:8080 です。
USERID
REMOTE_USER と同じ。
USERNAME
REMOTE_USER と同じ。

認証および許可

まず、用語を簡単に説明します。

Authentication
要求側の ID を確認するための、 この要求に関連するセキュリティー・トークンの検証。
Authorization
セキュリティー・トークンを使用して、リソースに対する要求側のアクセス権の有無を 判別するプロセス。

図 3 は、プロキシー・サーバーの Authentication (認証) および Authorization (許可) プロセスを 表しています。

図 3. プロキシー・サーバーの認証および許可 プロセス
認証および許可プロセスのダイアグラム

図 3 に示されているように、 サーバーの許可および認証プロセスの最初のステップは、許可プロセスの開始です。

Caching Proxy において、認証は許可プロセスの一部であり、認証が行われるのは許可が必要な場合のみです。

許可および認証プロセス

プロキシー・サーバーは、許可を必要とする要求を処理するときに以下のステップに従います。

  1. 最初に、プロキシー・サーバーはその構成ファイルを検査して、 許可ディレクティブがあるかどうかを判別します。
  2. プロキシー・サーバーは、認証プロセスを開始して最初に、クライアント要求の中に HTTP_authenticate ヘッダーがあるかどうかを検査 します。
  3. プロキシー・サーバーは、プロキシー構成ファイルの中に認証ディレクティブが存在するかどうかを 検査します。

Caching Proxy プラグインが独自の許可プロセスを備えている場合、そのプロセスがデフォルトのサーバー許可および認証をオーバーライド します。 したがって、構成ファイルに許可ディレクティブがある場合には、 それらに関連するプラグイン関数は、必要な認証を処理する必要もあります。 これに使用するために、事前定義 HTTPD_authenticate() 関数が用意されています。

許可プラグインに認証を備えるには、次の 3 つの方法があります。

Caching Proxy プラグインが独自の許可プロセスを備えていない場合でも、 次の方法を使用すれば、カスタマイズされた認証を用意することができます。

Authorization ステップを実行すると、それがデフォルトのサーバー許可を実行し、 次にその許可が認証プラグイン関数を呼び出します。

以下の点に注意してください。

バリアント・キャッシュ

元の文書 (URI) が変更されたデータをキャッシュする場合は、バリアント・キャッシュを使用します。Caching Proxy は、API によって生成されたバリアントを処理します。バリアントとは、 基本文書の別バージョンです。

一般に、起点サーバーはバリアントを送信するときに、それらがバリアントであることを識別できません。Caching Proxy は、プラグイン (例えば、コード・ページ変換) に よって作成されたバリアントのみをサポートします。HTTP ヘッダーに入っていない基準に基づいてバリアントを 作成するプラグインは、PreExit または PostAuthorization ステップ 関数を組み込んで、Caching Proxy が既存のバリアントを正しく識別できるように疑似ヘッダーを 作成する必要があります。

例えば、ブラウザーが送信する User-Agent ヘッダーの値に基づいて ユーザーが要求したデータを変更するには、Transmogrifier API プログラムを使用します。 close 関数で、変更された内容をファイルに保存するか、 またはバッファー長を指定してデータ引数としてバッファーを渡します。 その後で、バリアント・キャッシュ関数 httpd_variant_insert() および httpd_variant_lookup() を使用して、コンテンツをキャッシュに入れます。

API の例

独自の Caching Proxy API 関数 の作成を始める際に参考にできるよう、Edge components インストール CD-ROM の samples ディレクトリーにサンプル・プログラムが 入っています。. WebSphere® Application Server Web サイト www.ibm.com/software/webservers/appserv/ に追加情報があります。