Caching Proxy API 參照資訊

變數

撰寫 API 程式時,您可以使用 Caching Proxy 變數來提供遠端用戶端和伺服器系統的相關資訊。

附註:

變數定義

註:
不是以 HTTP_ 或 PROXY_ 字首為開頭的標頭變數語義不明確。 為避免語義不明確,請一律在變數名稱的標頭中使用 HTTP_ 或 PROXY_ 字首。
ACCEPT_RANGES
包含 Accept-Ranges 回應標頭的值,此值指定內容伺服器是否可以回應範圍要求。 請使用 PROXY_ACCEPT_RANGES 來擷取內容伺服器傳送至 Proxy 的標頭值。 請使用 HTTP_ACCEPT_RANGES 來設定從 Proxy 傳送到用戶端的標頭值。
註:
ACCEPT_RANGES 語義不明確。為避免語義不明確,請改用 HTTP_ACCEPT_RANGES 和 PROXY_ACCEPT_RANGES。
ALL_VARIABLES
唯讀。包含所有 CGI 變數。例如:
     ACCEPT_RANGES BYTES
     CLIENT_ADDR 9.67.84.3
AUTH_STRING
唯讀。如果伺服器支援用戶端鑑別,則此字串包含用來鑑別用戶端的未解碼認證。
AUTH_TYPE
唯讀。如果伺服器支援用戶端鑑別,且 Script 受到保護,則此變數包含用來鑑別用戶端的方法。 例如,Basic
CACHE_HIT
唯讀。可識別是否在快取中找到 Proxy 要求。 傳回的值包括如下:
CACHE_MISS
唯寫。用來強制快取遺失。有效值如下:
CACHE_TASK
唯讀。可識別是否使用快取。傳回的值包括如下:

此變數可使用於 PostAuthorization、PostExit、ProxyAdvisor 或 Log 步驟中。

CACHE_UPDATE
唯讀。可識別 Proxy 要求是否更新快取。 傳回的值包括如下:
CLIENT_ADDRCLIENTADDR
與 REMOTE_ADDR 相同。
CLIENTMETHOD
與 REQUEST_METHOD 相同。
CLIENT_NAMECLIENTNAME
與 REMOTE_HOST 相同。
CLIENT_PROTOCOLCLIENTPROTOCOL
包含用戶端用來提出要求的通訊協定名稱和版本。 例如,HTTP/1.1
CLIENT_RESPONSE_HEADERS
唯讀。會傳回包含伺服器傳送至用戶端之標頭的緩衝區。
CONNECTIONS
唯讀。它包含要提供的連線數,或作用中要求數。 例如,15
CONTENT_CHARSET
text/* 的回應字集,例如,US ASCII。擷取此變數適用於用戶端的 content-charset 標頭。 設定它會影響內容伺服器要求中的 content-encoding 標頭。
CONTENT_ENCODING
會指定文件使用的編碼,例如,x-gzip。擷取此變數適用於用戶端的 content-encoding 標頭。 設定它會影響內容伺服器要求中的 content-encoding 標頭。
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)」。例如:
http://www.anynet.com/~userk/main.htm
DOCUMENT_URI
與 DOCUMENT_URL 相同。
DOCUMENT_ROOT
唯讀。包含文件根路徑,如傳遞規則所定義。
ERRORINFO
指定錯誤碼以判定錯誤頁面。例如,blocked
EXPIRES
定義 Proxy 快取中儲存的文件何時到期。擷取此變數適用於用戶端要求的標頭。 設定它會影響內容伺服器要求中的標頭值。 例如:
Mon, 01 Mar 2002 19:41:17 GMT
GATEWAY_INTERFACE
唯讀。包含伺服器使用的 API 版本。 例如,ICSAPI/2.0
GC_BIAS
唯寫。此浮點數值會影響正考量進行記憶體回收的檔案之記憶體回收決策。 輸入的值會乘以該檔案類型的 Caching Proxy 品質設定,來決定等級。 品質設定範圍是從 0.0 到 0.1,而且是由 Proxy 配置檔 (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 標頭值。 它也可以用來設定介於 Proxy 和用戶端之間回應串流的新 Cookie。 不管是否有重複的標頭,設定此變數將造成在文件要求串流中建立新的 Set-Cookie 標頭。
HTTP_HEADERS
唯讀。用來擷取所有用戶端要求的標頭。
HTTP_REASON
設定此變數會影響 HTTP 回應中的原因字串。 設定它也會影響用戶端 Proxy 回應中的原因字串。 擷取此變數會將內容伺服器回應中的原因字串傳回至 Proxy。
HTTP_RESPONSE
設定此變數會影響 HTTP 回應中的回應碼。 設定它也會影響用戶端 Proxy 回應中的狀態碼。 擷取此變數會將內容伺服器回應中的狀態碼傳回至 Proxy。
HTTP_STATUS
包含 HTTP 回應碼和原因字串。例如,200 OK
HTTP_USER_AGENT
包含 User-Agent 要求標頭的值,它是用戶端 Web 瀏覽器的名稱,例如,Netscape Navigator / V2.02。設定此變數會影響用戶端 Proxy 回應中的標頭。 擷取此變數適用於用戶端要求的標頭。
INIT_STRING
唯讀。ServerInit 指引定義此字串。此變數只能在「伺服器起始設定」步驟期間加以讀取。
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
若為基本鑑別 (BA),則包含解碼的密碼。例如,password
PATH
包含完全轉換的路徑。
PATH_INFO
包含 Web 瀏覽器傳送的其他路徑資訊。 例如,/foo
PATH_TRANSLATED
包含 PATH_INFO 所含之路徑資訊的已解碼版本或已轉換版本。例如:
d:\wwwhome\foo
/wwwhome/foo
PPATH
包含部分轉換的路徑。請在 Name Translation 步驟中使用此路徑。
PROXIED_CONTENT_LENGTH
唯讀。傳回實際透過 Proxy 伺服器傳送的回應資料長度。
PROXY_ACCESS
定義該要求是否為 Proxy 要求。例如,NO
PROXY_CONTENT_TYPE
包含透過 HTTPD_proxy() 提出之 Proxy 要求的 Content-Type 標頭。 以 POST 方法傳送資訊時,此變數包含所併入的資料類型。 您可以在 Proxy 伺服器配置檔中建立自己的內容類型,並將它對映到檢視器。 擷取此變數適用於內容伺服器回應的標頭值。 設定它會影響內容伺服器要求的標頭。 例如:
application/x-www-form-urlencoded
PROXY_CONTENT_LENGTH
透過 HTTPD_proxy() 提出之 Proxy 要求的 Content-Length 標頭。 以 POST 方法傳送資訊時,此變數包含資料的字元數。 當伺服器使用標準輸入轉遞資訊時,通常不會傳送檔案結束旗標。 必要的話,您可以使用 CONTENT_LENGTH 值來判定輸入字串的結尾。 擷取此變數適用於內容伺服器回應的標頭值。 設定它會影響內容伺服器要求的標頭。 例如:
7034
PROXY_COOKIE
讀取的這個變數包含原始伺服器設定的 Set-Cookie 標頭值。 它也可以用來設定要求串流中的新 Cookie。 不管是否有重複的標頭,設定此變數將造成在文件要求串流中建立新的 Set-Cookie 標頭。
PROXY_HEADERS
唯讀。用來擷取 Proxy 標頭。
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
如果伺服器支援用戶端鑑別,且 Script 受到保護,則此變數包含為了鑑別而傳遞的使用者名稱。 例如,joeuser
REQHDR
唯讀。包含用戶端傳送的標頭清單。
REQUEST_CONTENT_TYPE
唯讀。會傳回要求內文的內容類型。例如:
application/x-www-form-urlencoded
REQUEST_CONTENT_LENGTH
唯讀。以 POST 方法傳送資訊時,此變數包含資料的字元數。 當伺服器使用標準輸入轉遞資訊時,通常不會傳送檔案結束旗標。 必要的話,您可以使用 CONTENT_LENGTH 值來判定輸入字串的結尾。 例如,7034
REQUEST_METHOD
唯讀。包含用來傳送要求的方法(在 HTML 格式中以 METHOD 屬性來指定)。 例如,GETPOST
REQUEST_PORT
唯讀。會傳回 URL 所指定的埠號,或基於通訊協定的預設埠。
RESPONSE_CONTENT_TYPE
唯讀。以 POST 方法傳送資訊時,此變數包含所併入的資料類型。 您可以在 Proxy 伺服器配置檔中建立自己的內容類型,並將它對映到檢視器。 例如,text/html
RESPONSE_CONTENT_LENGTH
唯讀。以 POST 方法傳送資訊時,此變數包含資料的字元數。 當伺服器使用標準輸入轉遞資訊時,通常不會傳送檔案結束旗標。 必要的話,您可以使用 CONTENT_LENGTH 值來判定輸入字串的結尾。 例如,7034
RULE_FILE_PATH
唯讀。包含配置檔的完整檔案系統路徑和檔名。
SSL_SESSIONID
唯讀。如果在 SSL 連線中接收到現行要求,會傳回 SSL 階段作業 ID。 如果在 SSL 連線中未接收到現行要求,則會傳回空值。
SCRIPT_NAME
包含要求的 URL。
SERVER_ADDR
唯讀。包含 Proxy 伺服器的本端 IP 位址。
SERVER_NAME
唯讀。包含 Proxy 伺服器主機名稱或此要求的內容伺服器之 IP 位址。例如,www.ibm.com
SERVER_PORT
唯讀。包含用戶端要求要傳送至的 Proxy 伺服器的埠號。 例如,80
SERVER_PROTOCOL
唯讀。包含用來提出要求的通訊協定名稱和版本。 例如,HTTP/1.1
SERVER_ROOT
唯讀。包含其中已安裝 Proxy 伺服器程式的目錄。
SERVER_SOFTWARE
唯讀。包含 Proxy 伺服器的名稱和版本。
STATUS
包含 HTTP 回應碼和原因字串。例如,200 OK。
TRACE
決定要追蹤的資訊量。回覆值包括:
URI
讀取/寫入。與 DOCUMENT_URL 相同。
URI_PATH
唯讀。只會傳回 URL 的路徑部分。
URL
讀取/寫入。與 DOCUMENT_URL 相同。
URL_MD4
唯讀。會傳回現行要求的潛在快取檔的檔名。
USE_PROXY
可識別要和現行要求產生關聯的 Proxy。指定 URL。例如,http://myproxy:8080
USERID
與 REMOTE_USER 相同。
USERNAME
與 REMOTE_USER 相同。

鑑別和授權

首先,以下是術語的快速檢閱:

鑑別
與此要求相關聯的安全記號驗證,以確定要求者的身分。
授權
使用安全記號來判定要求者對資源是否有存取權的程序。

圖 3 描述 Proxy 伺服器的鑑別和授權程序。

圖 3. Proxy 伺服器鑑別和授權程序
授權和鑑別程序圖

圖 3 所示範,授權程序的起始是伺服器授權和鑑別程序的首要步驟。

在 Caching Proxy 中,鑑別是授權程序的一部分;只有在需要授權時它才會發生。

鑑別和授權程序

Proxy 伺服器會遵循這些步驟來處理需要授權的要求。

  1. 首先,Proxy 伺服器會檢查其配置檔以判定是否有 Authorization 指引。
  2. Proxy 伺服器開始鑑別程序時,會先檢查用戶端要求中是否有 HTTP_authenticate 標頭。
  3. Proxy 伺服器會先檢查 Proxy 配置檔中是否有 Authentication 指引。

如果您的 Caching Proxy 外掛程式提供它自己的授權程序,它會置換預設伺服器授權和鑑別。 因此,如果配置檔中有 Authorization 指引,其相關聯的外掛程式函數也必須處理任何必要的鑑別。 有提供預先定義的 HTTPD_authenticate() 函數供您使用。

提供三種方式用於在授權外掛程式中進行鑑別:

如果您的 Caching Proxy 外掛程式沒有提供它自己的授權程序,您仍然可以利用下列方法提供自訂的鑑別:

在執行 Authorization 步驟時,它會執行預設伺服器授權,再由此授權呼叫鑑別外掛程式函數。

請記住下列各點:

變式快取

使用變式快取來快取資料,其為原始文件的已修改形式 (URI)。 Caching Proxy 會處理 API 產生的變式。變式是基本文件的不同版本。

一般而言,當原始伺服器傳送變式時,伺服器無法識別變式。 Caching Proxy 只支援由外掛程式建立的變式(例如:字碼頁轉換)。 如果外掛程式建立變式時所根據的準則不是在 HTTP 標頭中,它必須包含 PreExit 或 PostAuthorization 步驟函數來建立虛擬標頭,使 Caching Proxy 能夠正確識別現有的變式。

例如,使用 Transmogrifier API 程式,根據瀏覽器傳送的 User-Agent 標頭值來修改使用者要求的資料。在 close 函數中,將已修改的內容儲存到檔案,或指定緩衝區長度,並以資料引數傳遞該緩衝區。 然後使用變式快取函數 httpd_variant_insert() 和 httpd_variant_lookup(),將內容放置到快取中。

API 範例

為了協助您開始使用自己的 Caching Proxy API 函數,請查看 Edge Component 安裝光碟中 samples 目錄所提供的程式範例。 . 如需相關資訊,請參閱 WebSphere® Application Server 網站:www.ibm.com/software/webservers/appserv/