高速缓存代理 API 参考信息

变量

编写 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
只读。标识是否使用了高速缓存。返回的值包括以下各项:

可以在授权后、退出后、代理顾问或记录步骤中使用此变量。

CACHE_UPDATE
只读。标识代理请求是否更新了高速缓存。返回的值包括以下各项:
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
定义代理的高速缓存中存储的文档何时到期。抽取此变量的过程适用于客户机请求中的头。设置此变量会影响对内容服务器的请求中的头值。例如:
Mon, 01 Mar 2002 19:41:17 GMT
GATEWAY_INTERFACE
只读。包含服务器正在使用的 API 的版本。例如,ICSAPI/2.0
GC_BIAS
只写。此浮点值会影响正在考虑进行垃圾回收的文件的垃圾回收决策。将输入的值乘以该文件类型的高速缓存代理质量设置以确定排名。 质量设置在 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 顾问程序插件抽取。
GC_FILENAME
只读。标识正在考虑进行垃圾回收的文件。此变量只能由 GC 顾问程序插件抽取。
GC_FILESIZE
只读。标识正在考虑进行垃圾回收的文件的大小。此变量只能由 GC 顾问程序插件抽取。
GC_LAST_ACCESS
只读。标识最近一次访问文件的时间。此变量只能由 GC 顾问程序插件抽取。
GC_LAST_CHECKED
只读。标识最近一次检查文件的时间。此变量只能由 GC 顾问程序插件抽取。
GC_LOAD_DELAY
只读。标识检索文件所花的时间。此变量只能由 GC 顾问程序插件抽取。
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 伪指令定义此字符串。只能在服务器初始化步骤期间读取此变量。
LAST_MODIFIED
抽取此变量的过程适用于客户机请求中的头。设置此变量会影响对内容服务器的请求中的头值。例如:
Mon, 01 Mar 1998 19:41:17 GMT
LOCAL_VARIABLES
只读。所有用户定义的变量。
MAXACTIVETHREADS
只读。活动线程的最大数目。
NOTMODIFIED_TO_OK
强制对客户机进行完整响应。在退出前和代理顾问步骤中有效。
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
包含部分转换的路径。请在名称转换步骤中使用此变量。
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
只读。返回一个数字值,以给出拥有所请求对象的节点。可以在退出后、代理顾问或记录步骤中使用此变量,仅当服务器是使用远程高速缓存访问 (RCA) 的高速缓存阵列的一部分时,此变量才有意义。
RCA_TIMEOUTS
只读。返回一个数字值,该值包含对所有同级的 RCA 请求的超时总(聚集)数。可以在任何步骤中使用此变量。
REDIRECT_*
只读。包含与变量名对应的错误代码的重定向字符串(例如,REDIRECT_URL)。可以在 Apache Web 服务器的在线文档(网址为 http://httpd.apache.org/docs-2.0/custom-error.html)中找到可能的 REDIRECT_ 变量的列表。
REFERRER_URL
只读。包含浏览器的最新 URL 位置。它允许客户机为服务器指定从中获取了请求 URL 的资源的地址 (URL)。例如:
http://www.company.com/homepage
REMOTE_ADDR
包含 Web 浏览器的 IP 地址(如果该 Web 浏览器存在)。例如,45.23.06.8
REMOTE_HOST
包含 Web 浏览器的主机名(如果该 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 属性指定)。例如,GETPOST
REQUEST_PORT
只读。返回 URL 中指定的端口号,或根据协议返回缺省端口。
RESPONSE_CONTENT_TYPE
只读。当使用 POST 方法发送信息时,此变量包含所具有的数据的类型。您可以在代理服务器配置文件中创建自己的内容类型并将其映射到查看器。例如,text/html
RESPONSE_CONTENT_LENGTH
只读。当使用 POST 方法发送信息时,此变量包含数据的字符数。服务器在使用标准输入转发信息时通常不会发送文件结束标志。如果有需要,那么可以使用 CONTENT_LENGTH 值来确定输入字符串的结尾。例如,7034
RULE_FILE_PATH
只读。包含配置文件的标准文件系统路径和文件名。
SSL_SESSIONID
只读。如果在 SSL 连接中接收到当前请求,那么将返回 SSL 会话标识。如果在 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 相同。

认证和授权

首先,简短地查看一下术语:

认证
验证与此请求相关联的安全性令牌以确定请求者的身份的过程。
授权
使用安全性令牌来确定请求者是否可以访问资源的过程。

图 3描述了代理服务器的认证和授权过程。

图 3. 代理服务器认证和授权过程
授权和认证流程图

图 3中所演示的那样,启动授权过程是服务器授权和认证过程的第一个步骤。

在高速缓存代理中,认证是授权过程的一部分;仅当需要授权时才会执行认证。

认证和授权过程

代理服务器在处理需要授权的请求时遵循下列步骤。

  1. 首先,代理服务器检查其配置文件以确定是否有 Authorization 伪指令。
  2. 代理服务器通过检查 HTTP_authenticate 头是否在客户机请求中存在来开始认证过程。
  3. 代理服务器检查 authentication 伪指令在代理配置文件中是否存在。

如果高速缓存代理插件提供了自己的授权过程,那么它会覆盖缺省服务器授权和认证。因此,如果配置文件中有 Authorization 伪指令,那么与这些伪指令相关联的插件函数还必须处理任何必要的认证。提供了预定义 HTTPD_authenticate() 函数供您使用。

在授权插件中提供了三种认证方式。

如果高速缓存代理插件未提供自己的授权过程,那么您仍然可以通过使用以下方法提供定制认证:

执行授权步骤时,该步骤将执行缺省服务器授权,然后该授权又调用您的认证插件函数。

请注意以下几点:

变体高速缓存

请使用变体高速缓存来高速缓存作为原始文档 (URI) 的已修改形式的数据。高速缓存代理处理 API 生成的变体。变体是基本文档的不同版本。

一般来说,当源服务器发送变体时,它们无法对这些变体进行同样的标识。高速缓存代理仅支持插件创建的变体(例如,代码页转换)。如果某个插件根据 HTTP 头中未包含的条件创建变体,那么它必须包含退出前或授权后步骤函数以创建一个伪头,以便高速缓存代理可以正确标识现有变体。

例如,使用转换器 API 程序以根据浏览器发送的 User-Agent 头的值来修改用户请求的数据。在 close 函数中,将已修改的内容保存到文件,或指定一个缓冲区长度并将该缓冲区作为数据自变量进行传递。然后使用变体高速缓存函数 httpd_variant_insert() 和 httpd_variant_lookup() 将该内容放置在高速缓存中。

API 示例

要帮助您开始编写自己的高速缓存代理 API 函数,请查看 Edge Components 安装 CD-ROM 的 samples 目录中提供的样本程序。可以在 WebSphere® Application Server Web 站点 www.ibm.com/software/webservers/appserv/ 获得其他信息。