Caching Proxy API 參照資訊
變數
撰寫 API 程式時,您可以使用 Caching Proxy 變數來提供遠端用戶端和伺服器系統的相關資訊。
附註:
- 使用者定義的變數名稱不可以用 SERVER_ 作為字首。Caching Proxy
API 函數會保留以 SERVER_ 開頭的任何變數給伺服器,因此這些變數為唯讀。
此外,字首 HTTP_ 和 PROXY_ 也保留給 HTTP 標頭。
- 用戶端傳送的所有要求標頭(例如:Set-Cookie),字首都是 HTTP_,並可擷取其值。如果要存取本身是要求標頭的變數,請以 HTTP_ 作為變數名稱的字首。您也可以使用 httpd_setvar() 預先定義的函數建立新變數。如需這些標頭的詳細資料,請參閱來自預先定義的函數和巨集的回覆碼。
- HTTP_ 和 PROXY_ 這兩個變數字首是用來表示,變數是套用到要求的標頭或回應的標頭。
HTTP_ 字首是指在用戶端與 Caching Proxy 之間傳遞的變數。
PROXY_ 字首是指在 Caching Proxy 與原始伺服器(或 Proxy 鏈的下一個伺服器)之間傳遞的變數。
這些變數只有在要求處理程序步驟期間才有效。
- 擷取 HTTP_* 變數可提供對 Proxy 伺服器的用戶端要求中的標頭值。
- 設定 HTTP_* 變數可設定從 Proxy 伺服器傳送到用戶端的回應標頭。
- 擷取 PROXY_* 變數可提供從內容伺服器傳回到 Proxy 伺服器的標頭值。
- 設定 PROXY_* 變數可設定從 Proxy 伺服器傳送到內容伺服器(或到 Proxy 鏈的下一個伺服器)的要求標頭。
圖 2示範當 Caching Proxy 處理用戶端要求時,如何使用這些字首。
- 部分變數為唯讀。唯讀變數代表您可以從要求或回應中擷取的值,並可使用於 httpd_getvar() 預先定義的函數中。
如果您嘗試利用 httpd_setvar() 函數來變更唯讀變數,會產生回覆碼 HTTPD_READ_ONLY。
- 未識別為唯讀的變數,可在 httpd_getvar() 或 httpd_setvar() 預先定義的函數中讀取及設定。這些變數代表您可以從要求或回應中擷取的值;或您可以在處理要求或回應時設定或建立的值。
變數定義
註:
不是以 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 要求。
傳回的值包括如下:
- 0 - 在快取中找不到要求。
- 1 - 在快取中找到要求。
- CACHE_MISS
- 唯寫。用來強制快取遺失。有效值如下:
- CACHE_TASK
- 唯讀。可識別是否使用快取。傳回的值包括如下:
- 0 - 該要求不存取或更新快取。
- 1 - 該要求由快取提供服務。
- 2 - 所要求的物件在快取中,但需要重新驗證。
- 3 - 所要求的物件不在快取中,可能已新增。
此變數可使用於 PostAuthorization、PostExit、ProxyAdvisor 或 Log 步驟中。
- CACHE_UPDATE
- 唯讀。可識別 Proxy 要求是否更新快取。
傳回的值包括如下:
- 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-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 屬性來指定)。
例如,GET 或 POST。
- 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
- 決定要追蹤的資訊量。回覆值包括:
- OFF - 不追蹤。
- V - 詳細模式。
- VV - 非常詳細模式。
- MTV - 太過詳細模式。
- 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 所示範,授權程序的起始是伺服器授權和鑑別程序的首要步驟。
在 Caching Proxy 中,鑑別是授權程序的一部分;只有在需要授權時它才會發生。
鑑別和授權程序
Proxy 伺服器會遵循這些步驟來處理需要授權的要求。
- 首先,Proxy 伺服器會檢查其配置檔以判定是否有 Authorization 指引。
- 如果配置檔中有 Authorization 指引,則伺服器會呼叫定義在該指引中的授權函數,並開始進行2 步驟的鑑別。
- 如果沒有 Authorization 指引,則伺服器會執行預設授權,然後直接繼續進行3 步驟的鑑別程序。
- Proxy 伺服器開始鑑別程序時,會先檢查用戶端要求中是否有 HTTP_authenticate 標頭。
- 如果有這個標頭,則伺服器會繼續進行鑑別程序(請參閱3 步驟)。
- 如果沒有這個標頭,必須由另一個方法執行鑑別。
- Proxy 伺服器會先檢查 Proxy 配置檔中是否有 Authentication 指引。
- 如果配置檔中有 Authentication 指引,則伺服器會呼叫定義在該指引中的鑑別函數。
- 如果沒有指引,則伺服器會執行預設鑑別。
如果您的 Caching Proxy 外掛程式提供它自己的授權程序,它會置換預設伺服器授權和鑑別。
因此,如果配置檔中有 Authorization 指引,其相關聯的外掛程式函數也必須處理任何必要的鑑別。
有提供預先定義的 HTTPD_authenticate() 函數供您使用。
提供三種方式用於在授權外掛程式中進行鑑別:
- 撰寫您自己的個別授權和鑑別外掛程式。在 Proxy 配置檔中,請同時使用 Authorization 和 Authentication 指引來指定這些函數。請務必在授權外掛程式函數中併入 HTTPD_authenticate() 函數呼叫。
在執行 Authorization 步驟時,它會執行授權外掛程式函數,再由該函數呼叫鑑別外掛程式函數。
- 撰寫您自己的授權外掛程式函數,但是讓它呼叫預設伺服器鑑別。
在 Proxy 配置檔中,請使用 Authorization 指引來指定函數。
在此情況下,您不需要 Authentication 指引。
請務必在授權外掛程式函數中呼叫 HTTPD_authenticate() 函數。
在執行 Authorization 步驟時,它會執行授權外掛程式函數,再由該函數呼叫預設伺服器鑑別。
- 撰寫您自己的授權外掛程式函數,並在其中包含所有必要的鑑別處理。
請勿在授權外掛程式中使用 HTTPD_authenticate() 函數。
在 Proxy 配置檔中,請使用 Authorization 指引來指定授權外掛程式。
在此情況下,您不需要 Authentication 指引。
在執行 Authorization 步驟時,它會執行授權外掛程式函數以及所包含的任何鑑別。
如果您的 Caching Proxy 外掛程式沒有提供它自己的授權程序,您仍然可以利用下列方法提供自訂的鑑別:
- 撰寫您自己的鑑別外掛程式函數。在 Proxy 配置檔中,請使用 Authentication 指引來指定函數。
在此情況下,您不需要 Authorization 指引。
在執行 Authorization 步驟時,它會執行預設伺服器授權,再由此授權呼叫鑑別外掛程式函數。
請記住下列各點:
- 如果配置檔中沒有任何 Authorization 指引,或其指定的外掛程式函數拒絕處理該要求而傳回 HTTP_NOACTION,則會發生伺服器的預設授權。
- 如果配置檔中有 Authorization 指引,且其外掛程式函數包含 HTTPD_authenticate(),則伺服器會呼叫 Authentication 指引所指定的任何鑑別函數。
如果您未定義任何 Authentication 指引,或其指定的外掛程式函數拒絕處理該要求而傳回 HTTP_NOACTION,則會發生伺服器的預設鑑別。
- 如果配置檔中有 Authorization 指引,但其外掛程式函數不包含 HTTPD_authenticate(),則伺服器不會呼叫任何鑑別函數。
您必須撰寫自己的鑑別處理作為授權外掛程式函數的一部分,或自己呼叫其他鑑別模組。
- 如果授權函數傳回代碼 401 或 407,Caching Proxy 會自動產生盤查(提示瀏覽器傳回使用者 ID 和密碼)。不過,您仍然必須在 Caching Proxy 中配置保護設定,以便這個動作會正確執行。
變式快取
使用變式快取來快取資料,其為原始文件的已修改形式 (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/。