高速缓存代理 API 参考信息
变量
编写 API 程序时,可以使用高速缓存代理变量,这些变量提供有关远程客户机和服务器系统的信息。
注意:
- 用户定义的变量不能具有 SERVER_ 前缀。高速缓存代理 API 函数将任何以 SERVER_ 开头的变量保留以用于服务器,因此这些变量是只读的。另外,前缀 HTTP_
和 PROXY_ 也已保留以供 HTTP 头使用。
- 由客户机发送的所有请求头(例如 Set-Cookie)将以
HTTP_ 为前缀,并且可以抽取其值。要访问作为请求头的变量,请在变量前面加上前缀
HTTP_。还可以使用 httpd_setvar() 预定义函数创建新的变量。有关这些头的详细信息,请参阅预定义函数和宏的返回码。
- 两个变量前缀 HTTP_ 和 PROXY_
用于指示变量是应用于请求头还是应用于响应头。HTTP_ 前缀表示在客户机与高速缓存代理之间流动的变量。PROXY_ 前缀表示在高速缓存代理与源服务器(或代理链中的下一个服务器)之间流动的变量。这些变量仅在请求处理步骤期间有效。
- 抽取 HTTP_* 变量将使您获得客户机对代理服务器的请求中的某个头的值。
- 设置 HTTP_* 变量将设置从代理服务器发送到客户机的响应头。
- 抽取 PROXY_* 变量将使您获得从内容服务器返回给代理服务器的某个头的值。
- 设置 PROXY_* 变量将设置从代理服务器发送到内容服务器(或发送到代理链中的下一个服务器)的请求头。
图 2 演示了在高速缓存代理处理客户机请求时如何使用这些前缀。
图注:1—客户机 2—高速缓存代理 3—源服务器
- 某些变量是只读的。只读变量表示您可以从请求或响应中抽取的值以及可以在
httpd_getvar() 预定义函数中使用的值。如果尝试使用 httpd_setvar() 函数来更改只读变量,那么将导致返回码
HTTPD_READ_ONLY。
- 可以在 httpd_getvar() 或
httpd_setvar() 预定义函数中读取和设置未标识为只读的变量。这些变量表示您可以从请求或响应中抽取的值;或表示您可以在处理请求或响应时设置或创建的值。
变量定义
注:
未以 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
- 只读。标识高速缓存中是否找到了代理请求。返回的值包括以下各项:
- 0 - 在高速缓存中未找到该请求。
- 1 - 在高速缓存中找到了该请求。
- CACHE_MISS
- 只写。用于强制高速缓存不命中。以下是有效值:
- 0 - 不强制高速缓存不命中。
- 1 - 强制高速缓存不命中。
- CACHE_TASK
- 只读。标识是否使用了高速缓存。返回的值包括以下各项:
- 0 - 请求未访问或更新高速缓存。
- 1 - 从高速缓存中发出了请求。
- 2 - 请求的对象位于高速缓存中,但需要重新验证。
- 3 - 请求的对象未位于高速缓存中,并且可能已添加该对象。
可以在授权后、退出后、代理顾问或记录步骤中使用此变量。
- CACHE_UPDATE
- 只读。标识代理请求是否更新了高速缓存。返回的值包括以下各项:
- 0 - 未更新高速缓存。
- 1 - 更新了高速缓存。
- 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
- 定义代理的高速缓存中存储的文档何时到期。抽取此变量的过程适用于客户机请求中的头。设置此变量会影响对内容服务器的请求中的头值。例如:
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 属性指定)。例如,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 会话标识。如果在 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
- 确定将跟踪的信息量。返回值包括:
- OFF - 不跟踪。
- V - 详细方式。
- VV - 非常详细方式。
- MTV - 极其详细方式。
- 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中所演示的那样,启动授权过程是服务器授权和认证过程的第一个步骤。
在高速缓存代理中,认证是授权过程的一部分;仅当需要授权时才会执行认证。
认证和授权过程
代理服务器在处理需要授权的请求时遵循下列步骤。
-
首先,代理服务器检查其配置文件以确定是否有 Authorization 伪指令。
- 如果 Authorization 伪指令在配置文件中存在,那么服务器将调用该伪指令中定义的
authorization 函数并从步骤 2 开始认证。
- 如果没有 Authorization 伪指令,那么服务器执行缺省授权,然后直接转至步骤
3 中的认证过程。
-
代理服务器通过检查
HTTP_authenticate 头是否在客户机请求中存在来开始认证过程。
- 如果该头存在,那么服务器继续执行认证过程(请参阅步骤 3)。
- 如果该头不存在,那么必须通过另外的方法执行认证。
-
代理服务器检查 authentication 伪指令在代理配置文件中是否存在。
- 如果 authentication 伪指令在该配置文件中存在,那么服务器将调用该伪指令中定义的认证函数。
- 如果没有伪指令,那么服务器执行缺省认证。
如果高速缓存代理插件提供了自己的授权过程,那么它会覆盖缺省服务器授权和认证。因此,如果配置文件中有
Authorization 伪指令,那么与这些伪指令相关联的插件函数还必须处理任何必要的认证。提供了预定义
HTTPD_authenticate() 函数供您使用。
在授权插件中提供了三种认证方式。
- 编写自己的单独授权和认证插件。在代理配置文件中,请同时使用
Authorization 和 Authentication 伪指令来指定这些函数。一定要将
HTTPD_authenticate() 函数调用包含在授权插件函数中。
执行授权步骤时,该步骤将执行您的授权插件函数,然后该函数又调用您的认证插件函数。
- 编写自己的授权插件函数,但只让它调用缺省服务器认证。在代理配置文件中,请使用
Authorization 伪指令来指定您的函数。在这种情况下,您不需要 Authentication 伪指令。一定要在授权插件函数中调用
HTTPD_authenticate() 函数。
执行授权步骤时,该步骤将执行您的授权插件函数,然后该函数又调用缺省服务器认证。
- 编写自己的授权插件函数,并在其中包含所有必需的认证处理。不要在授权插件中使用
HTTPD_authenticate() 函数。在代理配置文件中,请使用
Authorization 伪指令来指定您的授权插件。在这种情况下,您不需要 Authentication 伪指令。
执行授权步骤时,该步骤将执行您的授权插件函数以及该函数中包含的任何认证。
如果高速缓存代理插件未提供自己的授权过程,那么您仍然可以通过使用以下方法提供定制认证:
- 编写您自己的认证插件函数。在代理配置文件中,请使用
Authentication 伪指令来指定您的函数。在这种情况下,您不需要 Authorization 伪指令。
执行授权步骤时,该步骤将执行缺省服务器授权,然后该授权又调用您的认证插件函数。
请注意以下几点:
- 如果配置文件中没有任何 Authorization 伪指令,或者其指定的插件函数通过返回 HTTP_NOACTION 拒绝处理该请求,那么将执行服务器的缺省授权。
- 如果配置文件中有
Authorization 伪指令并且其插件函数包含
HTTPD_authenticate(),那么服务器将调用 Authorization 伪指令中指定的任何认证函数。如果未定义任何 Authentication 伪指令,或者其指定的插件函数通过返回 HTTP_NOACTION 拒绝处理该请求,那么将执行服务器的缺省认证。
- 如果配置文件中有
Authorization 伪指令,但其插件函数不包含
HTTPD_authenticate(),那么服务器不会调用任何认证函数。您必须编写自己的认证处理作为授权插件函数的一部分,或者自己调用其他认证模块。
- 如果您的 authorization 函数返回代码 401 或 407,那么高速缓存代理自动生成一个身份确认(提示浏览器返回用户标识和密码)。然而,您仍必须在高速缓存代理中配置保护设置,以便正确执行此操作。
变体高速缓存
请使用变体高速缓存来高速缓存作为原始文档 (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/ 获得其他信息。