Información de referencia de la API de Caching Proxy

Variables

Al escribir programas de la API, puede utilizar variables de Caching Proxy que proporcionan información acerca del cliente remoto y el sistema servidor.

Notas:

Definiciones de variables

Nota:
Las variables de cabecera que no empiezan por los prefijos HTTP_ o PROXY_ son ambiguas. Para evitar la ambigüedad, utilice siempre el prefijo HTTP_ o PROXY_ con nombres de variable para cabeceras.
ACCEPT_RANGES
Contiene el valor de la cabecera de respuesta Accept-Ranges, que especifica si el servidor de contenido puede responder a solicitudes de rangos. Utilice PROXY_ACCEPT_RANGES para extraer el valor de cabecera que envía el servidor de contenido al proxy. Utilice HTTP_ACCEPT_RANGES para establecer el valor de cabecera que se envía del proxy al cliente.
Nota:
ACCEPT_RANGES es ambigua. Para eliminar la ambigüedad, utilice, en su lugar, HTTP_ACCEPT_RANGES y PROXY_ACCEPT_RANGES.
ALL_VARIABLES
Es de sólo lectura. Contiene todas las variables de CGI. Por ejemplo:
     ACCEPT_RANGES BYTES
     CLIENT_ADDR 9.67.84.3
AUTH_STRING
Es de sólo lectura. Si el servidor da soporte a la autenticación de clientes, esta serie contiene las credenciales no decodificadas que se deben utilizar para autenticar el cliente.
AUTH_TYPE
Es de sólo lectura. Si el servidor da soporte a la autenticación de clientes y el script está protegido, esta serie contiene el método utilizado para autenticar el cliente. Por ejemplo, Basic.
CACHE_HIT
Es de sólo lectura. Identifica si la solicitud del proxy se ha encontrado o no en la memoria caché. Los valores que se devuelven son los siguientes:
CACHE_MISS
Es de sólo escritura. Se utiliza para forzar un fallo de memoria caché. Los valores válidos son los siguientes:
CACHE_TASK
Es de sólo lectura. Identifica si se ha utilizado la memoria caché. Los valores que se devuelven son los siguientes:

Esta variable se puede utilizar en los pasos PostAuthorization, PostExit, ProxyAdvisor o Log.

CACHE_UPDATE
Es de sólo lectura. Identifica si la solicitud del proxy ha actualizado la memoria caché. Los valores que se devuelven son los siguientes:
CLIENT_ADDR or CLIENTADDR
Es igual que REMOTE_ADDR.
CLIENTMETHOD
Es igual que REQUEST_METHOD.
CLIENT_NAME o CLIENTNAME
Es igual que REMOTE_HOST.
CLIENT_PROTOCOL o CLIENTPROTOCOL
Contiene el nombre y la versión del protocolo que el cliente va a utilizar para realizar la solicitud. Por ejemplo, HTTP/1.1.
CLIENT_RESPONSE_HEADERS
Es de sólo lectura. Devuelve un almacenamiento intermedio que contiene las cabeceras que el servidor envía al cliente.
CONNECTIONS
Es de sólo lectura. Contiene el número de conexiones que se van a servir o el número de solicitudes activas. Por ejemplo, 15.
CONTENT_CHARSET
El juego de caracteres de la respuesta de text/*, por ejemplo, US ASCII. La extracción de esta variable es aplicable a la cabecera content-charset desde el cliente. Su establecimiento afecta a la cabecera content-charset en la solicitud al servidor de contenido.
CONTENT_ENCODING
Especifica la codificación que se utiliza en el documento, por ejemplo, x-gzip. La extracción de esta variable es aplicable a la cabecera content-encoding desde el cliente. Su establecimiento afecta a la cabecera content-encoding en la solicitud al servidor de contenido.
CONTENT_LENGTH
La extracción de esta variable es aplicable a la cabecera content-charset desde la solicitud del cliente. Su establecimiento afecta al valor de la cabecera en la solicitud al servidor de contenido.

Nota:
CONTENT_LENGTH es ambigua. Para eliminar la ambigüedad, utilice, en su lugar, HTTP_CONTENT_LENGTH y PROXY_CONTENT_LENGTH.
CONTENT_TYPE
La extracción de esta variable es aplicable a la cabecera content-charset desde la solicitud del cliente. Su establecimiento afecta al valor de la cabecera en la solicitud al servidor de contenido.

Nota:
CONTENT_TYPE es ambigua. Para eliminar la ambigüedad, utilice, en su lugar, HTTP_CONTENT_TYPE y PROXY_CONTENT_TYPE.
CONTENT_TYPE_PARAMETERS
Contiene otros atributos MIME, pero no el juego de caracteres. La extracción de esta variable es aplicable a la cabecera content-charset desde la solicitud del cliente. Su establecimiento afecta al valor de la cabecera en la solicitud al servidor de contenido.
DOCUMENT_URL
Contiene el URL (Uniform Request Locator). Por ejemplo:
http://www.anynet.com/~userk/main.htm
DOCUMENT_URI
Es igual que DOCUMENT_URL.
DOCUMENT_ROOT
Es de sólo lectura. Contiene la vía de acceso raíz al documento, como definen las reglas de paso.
ERRORINFO
Especifica el código de error para determinar la página de error. Por ejemplo, blocked.
EXPIRES
Define cuándo caducan los documentos almacenados en la memoria caché de un proxy. La extracción de esta variable es aplicable a la cabecera content-charset desde la solicitud del cliente. Su establecimiento afecta al valor de la cabecera en la solicitud al servidor de contenido. Por ejemplo:
Mon, 01 Mar 2002 19:41:17 GMT
GATEWAY_INTERFACE
Es de sólo lectura. Contiene la versión de la API que está utilizando el servidor. Por ejemplo, ICSAPI/2.0.
GC_BIAS
Es de sólo escritura. Este valor de coma flotante influye en la recogida de basura del archivo que se va a considerar para la recogida de basura. El valor especificado se multiplica por el valor de calidad del Caching Proxy para ese tipo de archivo para determinar la clasificación. Los valores de calidad se encuentran en un intervalo de 0.0 a 0.1 y los definen las directivas AddType en el archivo de configuración de proxy (ibmproxy.conf).
GC_EVALUATION
Es de sólo escritura. Este valor de coma flotante determina si eliminar (0.0) o conservar (1.0) el archivo que se va a considerar para la recogida de basura. Los valores entre 0.0 y 1.0 se ordenan por rangos, es decir, un archivo con el valor de GC_EVALUATION 0.1 es más probable que se elimine que un archivo con el valor de GC_EVALUATION 0.9.
GC_EXPIRES
Es de sólo lectura. Identifica el número de segundos que quedan hasta que el archivo que se está considerando caduque en la memoria caché. Sólo puede extraer esta variable un plug-in de asesor de GC.
GC_FILENAME
Es de sólo lectura. Identifica el archivo que se va a considerar para la recogida de basura. Sólo puede extraer esta variable un plug-in de asesor de GC.
GC_FILESIZE
Es de sólo lectura. Identifica el tamaño del archivo que se va a considerar para la recogida de basura. Sólo puede extraer esta variable un plug-in de asesor de GC.
GC_LAST_ACCESS
Es de sólo lectura. Identifica cuando se ha accedido al archivo por última vez. Sólo puede extraer esta variable un plug-in de asesor de GC.
GC_LAST_CHECKED
Es de sólo lectura. Identifica cuándo se han comprobado los archivos por última vez. Sólo puede extraer esta variable un plug-in de asesor de GC.
GC_LOAD_DELAY
Es de sólo lectura. Identifica cuánto se ha tardado en recuperar el archivo. Sólo puede extraer esta variable un plug-in de asesor de GC.
HTTP_COOKIE
Cuando se lee, esta variable contiene el valor de la cabecera Set-Cookie establecida por el cliente. También se puede utilizar para establecer una nueva cookie en la secuencia de respuesta (entre el proxy y el cliente). Al establecer esta variable, se crea una nueva cabecera Set-Cookie en la secuencia de solicitudes del documento, independientemente de si existe una cabecera duplicada.
HTTP_HEADERS
Es de sólo lectura. Se utiliza para extraer todas las cabeceras de solicitud del cliente.
HTTP_REASON
El establecimiento de esta variable afecta a la serie de motivo de la respuesta HTTP. Su establecimiento también afecta a la serie de motivo de la respuesta del proxy al cliente. La extracción de esta variable devuelve la serie de motivo en la respuesta del servidor de contenido al proxy.
HTTP_RESPONSE
El establecimiento de esta variable afecta al código de respuesta en la respuesta HTTP. Su establecimiento también afecta al código de estado de la respuesta del proxy al cliente. La extracción de esta variable devuelve el código de estado en la respuesta del servidor de contenido al proxy.
HTTP_STATUS
Contiene el código de respuesta HTTP y la serie de respuesta. Por ejemplo, 200 OK.
HTTP_USER_AGENT
Contiene el valor de la cabecera de solicitud User-Agent, que es el nombre del navegador web del cliente, por ejemplo, Netscape Navigator / V2.02. El establecimiento de esta variable afecta a la cabecera en la respuesta del proxy al cliente. Su extracción se aplica a la cabecera desde la solicitud del cliente.
INIT_STRING
Es de sólo lectura. La directiva ServerInit define esta serie. Esta variable sólo puede ser de lectura durante el paso Server Initialization.
LAST_MODIFIED
La extracción de esta variable es aplicable a la cabecera content-charset desde la solicitud del cliente. Su establecimiento afecta al valor de la cabecera en la solicitud al servidor de contenido. Por ejemplo:
Mon, 01 Mar 1998 19:41:17 GMT
LOCAL_VARIABLES
Es de sólo lectura. Todas las variables definidas por el usuario.
MAXACTIVETHREADS
Es de sólo lectura. Número máximo de hebras activas.
NOTMODIFIED_TO_OK
Fuerza una respuesta completa al cliente. Es válida en los pasos PreExit y ProxyAdvisor.
ORIGINAL_HOST
Es de sólo lectura. Devuelve el nombre de sistema principal o la dirección IP de destino de una solicitud.
ORIGINAL_URL
Es de sólo lectura. Devuelve el URL original enviado en la solicitud del cliente.
OVERRIDE_HTTP_NOTRANSFORM
Habilita la modificación de los datos en presencia de una cabecera Cache-Control: no-transform. El establecimiento de esta variable afecta a la cabecera de respuesta al cliente.
OVERRIDE_PROXY_NOTRANSFORM
Habilita la modificación de los datos en presencia de una cabecera Cache-Control: no-transform. El establecimiento de esta variable afecta a la respuesta al servidor de contenido.
PASSWORD
Para autenticación básica, contiene la contraseña decodificada. Por ejemplo, password.
PATH
Contiene la vía de acceso totalmente convertida.
PATH_INFO
Contiene información de vía de acceso adicional tal como la envía el navegador web. Por ejemplo, /foo.
PATH_TRANSLATED
Contiene la versión decodificada o convertida de la información de vía de acceso contenida en PATH_INFO. Por ejemplo:
d:\wwwhome\foo
/wwwhome/foo
PPATH
Contiene la vía de acceso parcialmente convertida. Utilícela en el paso Name Translation.
PROXIED_CONTENT_LENGTH
Es de sólo lectura. Devuelve la longitud de los datos de respuesta que se han transferido realmente a través del servidor proxy.
PROXY_ACCESS
Define si la solicitud es una solicitud de proxy. Por ejemplo, NO.
PROXY_CONTENT_TYPE
Contiene la cabecera Content-Type de la solicitud de proxy realizada a través de HTTPD_proxy(). Cuando se envía información con el método de POST, esta variable contiene el tipo de datos incluidos. Puede crear un tipo de contenido propio en el archivo de configuración del servidor proxy y correlacionarlo con un visor. La extracción de esta variable se aplica al valor de cabecera desde la respuesta del servidor de contenido. Su establecimiento afecta a la cabecera de la solicitud al servidor de contenido. Por ejemplo:
application/x-www-form-urlencoded
PROXY_CONTENT_LENGTH
Cabecera Content-Length de la solicitud de proxy realizada a través de HTTPD_proxy(). Cuando se envía esta información con el método de POST, esta variable contiene el número de caracteres de datos. Los servidores no suelen enviar un distintivo de final de archivo cuando reenvían la información mediante la entrada estándar. Si es necesario, puede utilizar el valor de CONTENT_LENGTH para determinar el final de la serie de entrada. La extracción de esta variable se aplica al valor de cabecera desde la respuesta del servidor de contenido. Su establecimiento afecta a la cabecera de la solicitud al servidor de contenido. Por ejemplo:
7034
PROXY_COOKIE
Cuando se lee, esta variable contiene el valor de la cabecera Set-Cookie establecida por el servidor de origen. También se puede utilizar para establecer una nueva cookie en la secuencia de solicitudes. Al establecer esta variable, se crea una nueva cabecera Set-Cookie en la secuencia de solicitudes del documento, independientemente de si existe una cabecera duplicada.
PROXY_HEADERS
Es de sólo lectura. Se utiliza para extraer las cabeceras de proxy.
PROXY_METHOD
Método de la solicitud realizada a través de HTTPD_proxy(). La extracción de esta variable se aplica al valor de cabecera desde la respuesta del servidor de contenido. Su establecimiento afecta a la cabecera de la solicitud al servidor de contenido.
QUERY_STRING
Cuando se envía información utilizando un método de GET, esta variable contiene la información que sigue a un interrogante (?) en una consulta. El programa de CGI debe decodificar esta información. Por ejemplo:
NAME=Eugene+T%2E+Fox&ADDR=etfox%7Cibm.net&INTEREST=xyz
RCA_OWNER
Es de sólo lectura. Devuelve un valor numérico que indica el nodo propietario del objeto solicitado. Esta variable se puede utilizar en los pasos PostExit, ProxyAdvisor o Log y sólo tiene sentido cuando el servidor forma parte de una matriz de memoria caché que utiliza el acceso a memoria caché remota (RCA).
RCA_TIMEOUTS
Es de sólo lectura. Devuelve un valor numérico, que contiene el número total (agregado) de tiempos de espera excedidos en las solicitudes de RCA a todos los iguales. Puede utilizar esta variable en cualquier paso.
REDIRECT_*
Es de sólo lectura. Contiene una serie de redirección para el código de error que corresponde al nombre de variable (por ejemplo, REDIRECT_URL). Puede encontrar una lista de variables REDIRECT_ posibles en la documentación en línea de Apache Web Server en http://httpd.apache.org/docs-2.0/custom-error.html.
REFERRER_URL
Es de sólo lectura. Contiene la última ubicación de URL del navegador. Permite al cliente especificar, a beneficio del servidor, la dirección (URL) del recurso del que se ha obtenido Request-URL. Por ejemplo:
http://www.company.com/homepage
REMOTE_ADDR
Contiene la dirección IP del navegador web, si está disponible. Por ejemplo, 45.23.06.8.
REMOTE_HOST
Contiene el nombre de sistema principal del navegador web, si está disponible. Por ejemplo, www.raleigh.ibm.com.
REMOTE_USER
Si el servidor da soporte a la autenticación de clientes y el script está protegido, esta variable contiene el nombre de usuario que se ha pasado para autenticación. Por ejemplo, joeuser.
REQHDR
Es de sólo lectura. Contiene una lista de las cabeceras enviadas por el cliente.
REQUEST_CONTENT_TYPE
Es de sólo lectura. Devuelve el tipo de contenido del cuerpo de la solicitud. Por ejemplo:
application/x-www-form-urlencoded
REQUEST_CONTENT_LENGTH
Es de sólo lectura. Cuando se envía esta información con el método de POST, esta variable contiene el número de caracteres de datos. Los servidores no suelen enviar un distintivo de final de archivo cuando reenvían la información mediante la entrada estándar. Si es necesario, puede utilizar el valor de CONTENT_LENGTH para determinar el final de la serie de entrada. Por ejemplo, 7034.
REQUEST_METHOD
Es de sólo lectura. Contiene el método (tal como se especifica con el atributo METHOD en un formulario HTML) que se utiliza para enviar la solicitud. Por ejemplo, GET o POST.
REQUEST_PORT
Es de sólo lectura. Devuelve el número de puerto especificado en el URL o un puerto predeterminado basado en el protocolo.
RESPONSE_CONTENT_TYPE
Es de sólo lectura. Cuando se envía información con el método de POST, esta variable contiene el tipo de datos incluidos. Puede crear un tipo de contenido propio en el archivo de configuración del servidor proxy y correlacionarlo con un visor. Por ejemplo, text/html.
RESPONSE_CONTENT_LENGTH
Es de sólo lectura. Cuando se envía esta información con el método de POST, esta variable contiene el número de caracteres de datos. Los servidores no suelen enviar un distintivo de final de archivo cuando reenvían la información mediante la entrada estándar. Si es necesario, puede utilizar el valor de CONTENT_LENGTH para determinar el final de la serie de entrada. Por ejemplo, 7034.
RULE_FILE_PATH
Es de sólo lectura. Contiene la vía de acceso al sistema de archivos plenamente cualificada y el nombre del archivo de configuración.
SSL_SESSIONID
Es de sólo lectura. Devuelve el ID de sesión de SSL si la solicitud actual se ha recibido en una conexión SSL. Devuelve NULL si la solicitud actual no se ha recibido en una conexión SSL.
SCRIPT_NAME
Contiene el URL de la solicitud.
SERVER_ADDR
Es de sólo lectura. Contiene la dirección IP local del servidor proxy.
SERVER_NAME
Es de sólo lectura. Contiene el nombre de sistema principal del servidor proxy o dirección IP del servidor de contenido para esta solicitud. Por ejemplo, www.ibm.com.
SERVER_PORT
Es de sólo lectura. Contiene el número de puerto del servidor proxy al que se ha enviado la solicitud de cliente. Por ejemplo, 80.
SERVER_PROTOCOL
Es de sólo lectura. Contiene el nombre y la versión del protocolo que se ha utilizado para realizar la solicitud. Por ejemplo, HTTP/1.1.
SERVER_ROOT
Es de sólo lectura. Contiene el directorio donde está instalado el programa del servidor proxy.
SERVER_SOFTWARE
Es de sólo lectura. Contiene el nombre y la versión del servidor proxy.
STATUS
Contiene el código de respuesta HTTP y la serie de respuesta. Por ejemplo, 200 OK.
TRACE
Determina cuánta información se rastreará. Los valores que se devuelven son:
URI
Lectura/escritura. Es igual que DOCUMENT_URL.
URI_PATH
Es de sólo lectura. Devuelve sólo la parte de vía de acceso de un URL.
URL
Lectura/escritura. Es igual que DOCUMENT_URL.
URL_MD4
Es de sólo lectura. Devuelve el nombre del archivo posible de memoria caché para la solicitud actual.
USE_PROXY
Identifica el proxy con el que se debe asociar para la petición actual. Especifique el URL. Por ejemplo, http://myproxy:8080.
USERID
Es igual que REMOTE_USER.
USERNAME
Es igual que REMOTE_USER.

Autenticación y autorización

En primer lugar, revisemos brevemente la terminología:

Authentication
Verificación de las señales de seguridad asociadas con esta solicitud a fin de determinar la identidad del solicitante.
Authorization
Proceso que utiliza las señales de seguridad para determinar si el solicitante tiene acceso al recurso.

Figura 3 ilustra el proceso de autenticación y autorización del servidor proxy.

Figura 3. Proceso de autenticación y autorización del servidor proxy
Diagrama de proceso de autorización y autenticación

Como se muestra en la Figura 3, el inicio del proceso de autorización es el primer paso del proceso de autorización y autenticación del servidor.

En Caching Proxy,la autenticación forma parte del proceso de autorización; sólo se produce cuando se exige una autorización.

Proceso de autenticación y autorización

El servidor proxy sigue estos pasos al procesar una solicitud que exige autorización.

  1. En primer lugar, el servidor proxy examina su archivo de configuración para determinar si hay o no una directiva de autorización.
  2. El servidor proxy inicia el proceso de autenticación comprobando si la cabecera HTTP_authenticate está en la solicitud del cliente.
  3. El servidor proxy comprueba si hay una directiva de autenticación en el archivo de configuración de proxy.

Si el plug-in de Caching Proxy proporciona su propio proceso de autorización, prevalece sobre la autorización y autenticación predeterminadas del servidor. Por lo tanto, si tiene directivas de autorización en el archivo de configuración, las funciones de plug-in asociadas con ellas deben gestionar también las autenticaciones necesarias. Se proporciona la función HTTPD_authenticate() predefinida para que la utilice.

Estos son los tres modos de proporcionar autenticación en los plug-ins de autorización:

Si el plug-in de Caching Proxy no proporciona su propio proceso de autorización, aún puede proporcionar una autenticación personalizada utilizando el método siguiente:

Cuando se ejecuta el paso Authorization, realiza la autorización de servidor predeterminada, que, por su parte, llama a la función de plug-in de autenticación.

Recuerde los puntos siguientes:

Almacenamiento de variantes en caché

Utilice el almacenamiento de variantes en memoria caché para guardar en memoria caché los datos que se hayan modificado del documento original (el URI). Caching Proxy gestiona las variantes generadas por la API. Las variantes son distintas versiones de un documento base.

Por lo general, cuando los servidores de origen envían variantes, no pueden identificarse como tales. Caching Proxy sólo da soporte a las variantes creadas por plug-ins (por ejemplo, la conversión de páginas de códigos). Si un plug-in crea una variante según criterios que no están en la cabecera HTTP, debe incluir una función de paso PreExit o PostAuthorization para crear una seudocabecera, de modo que el Caching Proxy pueda identificar correctamente la variante existente.

Por ejemplo, utilice el programa de la API de Transmogrifier para modificar los datos que los usuarios soliciten según el valor de la cabecera User-Agent que el navegador envíe. En la función close, guarde el contenido modificado en un archivo o especifique un longitud de almacenamiento intermedio y pase el almacenamiento intermedio como argumento de datos. A continuación, utilice las funciones de almacenamiento de variantes en memoria caché httpd_variant_insert() y httpd_variant_lookup() para colocar el contenido en la memoria caché.

Ejemplos de API

Para ayudarle a iniciarse en sus propias funciones de API de Caching Proxy, observe los programas de ejemplo proporcionados en el directorio samples del CD-ROM de la instalación de Edge Components. Hay información adicional disponible en el sitio web de WebSphere Application Server, www.ibm.com/software/webservers/appserv/.