Informações de Referência da API do Caching Proxy

Variáveis

Ao gravar programas de API, é possível usar variáveis do Caching Proxy que fornecem informações sobre o cliente remoto e o sistema do servidor.

Notas:

Definições de Variáveis

Nota:
Variáveis de cabeçalho que não começam com prefixos HTTP_ ou PROXY_ são ambíguas. Para evitar a ambiguidade, use sempre o prefixo HTTP_ ou PROXY_ com nomes de variáveis para cabeçalhos.
ACCEPT_RANGES
Contém o valor do cabeçalho de resposta Accept-Ranges, que especifica se o servidor de conteúdo pode responder a pedidos de intervalo. Use o PROXY_ACCEPT_RANGES para extrair o valor do cabeçalho que é enviado pelo servidor de conteúdo para o proxy. Use HTTP_ACCEPT_RANGES para configurar o valor do cabeçalho que é enviado do proxy para o cliente.
Nota:
ACCEPT_RANGES é ambíguo. Para eliminar a ambiguidade, use HTTP_ACCEPT_RANGES e PROXY_ACCEPT_RANGES.
ALL_VARIABLES
Somente leitura. Contém todas as variáveis de CGI. Por exemplo:
     ACCEPT_RANGES BYTES
     CLIENT_ADDR 9.67.84.3
AUTH_STRING
Somente leitura. Se o servidor suportar autenticação de cliente, essa cadeia conterá as credenciais não decodificadas a serem usadas para autenticar o cliente.
AUTH_TYPE
Somente leitura. Se o servidor suportar autenticação de cliente e o script estiver protegido, essa variável conterá o método usado para autenticar o cliente. Por exemplo, Básico.
CACHE_HIT
Somente leitura. Identifica se o pedido de proxy foi ou não localizado no cache. Os valores retornados incluem os seguintes:
CACHE_MISS
Somente gravação. Usado para forçar uma perda de acerto no cache. Os valores válidos são os seguintes:
CACHE_TASK
Somente leitura. Identifica se o cache foi usado. Os valores retornados incluem os seguintes:

Essa variável pode ser usada nas etapas PostAuthorization, PostExit, ProxyAdvisor ou Log.

CACHE_UPDATE
Somente leitura. Identifica se o pedido de proxy atualizou ou não o cache. Os valores retornados incluem os seguintes:
CLIENT_ADDR ou CLIENTADDR
O mesmo que REMOTE_ADDR.
CLIENTMETHOD
O mesmo que REQUEST_METHOD.
CLIENT_NAME ou CLIENTNAME
O mesmo que REMOTE_HOST.
CLIENT_PROTOCOL ou CLIENTPROTOCOL
Contém o nome e a versão do protocolo que o cliente está usando para fazer o pedido. Por exemplo, HTTP/1.1.
CLIENT_RESPONSE_HEADERS
Somente leitura. Retorna um buffer que contém os cabeçalhos que o servidor envia ao cliente.
CONNECTIONS
Somente leitura. Contém o número de conexões sendo atendidas ou o número de pedidos ativos. Por exemplo, 15.
CONTENT_CHARSET
Conjunto de caracteres da resposta para text/*, por exemplo, US ASCII. Extrair essa variável se aplica ao cabeçalho content-charset do cliente. Configurá-la afeta o cabeçalho content-charset no pedido para o servidor de conteúdo.
CONTENT_ENCODING
Especifica a codificação usada no documento, por exemplo x-gzip. Extrair essa variável se aplica ao cabeçalho content-encoding do cliente cliente. Configurá-lo afeta o cabeçalho content-encoding na solicitação para o servidor de conteúdo.
CONTENT_LENGTH
Extrair essa variável se aplica ao cabeçalho do pedido do cliente. Configurá-la afeta o valor do cabeçalho no pedido para o servidor de conteúdo.

Nota:
CONTENT_LENGTH é ambíguo. Para eliminar ambiguidade, use HTTP_CONTENT_LENGTH e PROXY_CONTENT_LENGTH.
CONTENT_TYPE
Extrair essa variável se aplica ao cabeçalho do pedido do cliente. Configurá-la afeta o valor do cabeçalho no pedido para o servidor de conteúdo.

Nota:
CONTENT_TYPE é ambíguo. Para eliminar a ambiguidade, use HTTP_CONTENT_TYPE e PROXY_CONTENT_TYPE.
CONTENT_TYPE_PARAMETERS
Contém outros atributos MIME, mas não o conjunto de caracteres. Extrair essa variável se aplica ao cabeçalho do pedido do cliente. Configurá-la afeta o valor do cabeçalho no pedido para o servidor de conteúdo.
DOCUMENT_URL
Contém a Uniform Request Locator (URL). Por exemplo:
http://www.anynet.com/~userk/main.htm
DOCUMENT_URI
O mesmo que DOCUMENT_URL.
DOCUMENT_ROOT
Somente leitura. Contém o caminho-raiz do documento, conforme definido por regras de passagem.
ERRORINFO
Especifica o código de erro para determinar a página de erro. Por exemplo, bloqueado.
EXPIRES
Define quando documentos armazenados em um cache de proxy expira. Extrair essa variável se aplica ao cabeçalho do pedido do cliente. Configurá-la afeta o valor do cabeçalho no pedido para o servidor de conteúdo. Por exemplo:
Segunda-feira, 1 de março de 2002 19:41:17 GMT
GATEWAY_INTERFACE
Somente leitura. Contém a versão da API que o servidor está usando. Por exemplo, ICSAPI/2.0.
GC_BIAS
Somente gravação. Esse valor de vírgula flutuante influencia a decisão de coleta de lixo do arquivo sendo considerado para coleta de lixo. O valor inserido é multiplicado pela configuração de qualidade do Caching Proxy para esse tipo de arquivo, para determinar a classificação. As configurações de qualidade variam de 0,0 a 0,1 e são definidas pelas diretivas AddType no arquivo de configuração de proxy (ibmproxy.conf).
GC_EVALUATION
Somente gravação. Esse valor de vírgula flutuante determina remover (0,0) ou manter (1,0) o arquivo sendo considerado para a coleta de lixo. Os valores entre 0,0 e 1,0 são organizados por classificação, ou seja, um arquivo com o valor GC_EVALUATION 0,1 tem mais probabilidade de ser removido do que com o valor GC_EVALUATION 0,9.
GC_EXPIRES
Somente leitura. Identifica quantos segundos restam até que o arquivo sob consideração expire no cache. Essa variável pode ser extraída somente por um plug-in do GC Advisor.
GC_FILENAME
Somente leitura. Identifica o arquivo sendo considerado para coleta de lixo. Essa variável pode ser extraída somente por um plug-in do GC Advisor.
GC_FILESIZE
Somente leitura. Identifica o tamanho do arquivo sendo considerado para coleta de lixo. Essa variável pode ser extraída somente por um plug-in do GC Advisor.
GC_LAST_ACCESS
Somente leitura. Identifica quando o arquivo foi acessado pela última vez. Essa variável pode ser extraída somente por um plug-in do GC Advisor.
GC_LAST_CHECKED
Somente leitura. Identifica quando os arquivos foram verificados pela última vez. Essa variável pode ser extraída somente por um plug-in do GC Advisor.
GC_LOAD_DELAY
Somente leitura. Identifica o tempo que levou para recuperar o arquivo. Essa variável pode ser extraída somente por um plug-in do GC Advisor.
HTTP_COOKIE
Quando lida, essa variável contém o valor do cabeçalho Set-Cookie configurado pelo cliente. Ele também pode ser usado para configurar um novo cookie no fluxo de resposta (entre o proxy e o cliente). Configurar essa variável faz com que a criação de um novo cabeçalho Set-Cookie no fluxo de pedido do documento, independente de o cabeçalho duplicado existir ou não.
HTTP_HEADERS
Somente leitura. Usada para extrair todos os cabeçalhos de pedido do cliente.
HTTP_REASON
Configurar essa variável afeta a cadeia de motivos na resposta de HTTP. Configurá-la também afeta a cadeia de motivos na resposta de proxy para o cliente. Extrair essa variável retorna a cadeia de motivos na resposta do servidor de conteúdo para o proxy.
HTTP_RESPONSE
Configurar essa variável afeta o código de resposta na resposta de HTTP. Configurá-la também afeta o código de status na resposta de proxy para o cliente. Extrair essa variável retorna o código de status na resposta do servidor de conteúdo para o proxy.
HTTP_STATUS
Contém o código de resposta de HTTP e a cadeia de motivos. Por exemplo, 200 OK.
HTTP_USER_AGENT
Contém o valor do cabeçalho do pedido User-Agent, que é o nome do navegador da Web do cliente, por exemplo, Netscape Navigator / V2.02. Configurar essa variável afeta o cabeçalho na resposta de proxy para o cliente. Extraí-la se aplica ao cabeçalho do pedido do cliente.
INIT_STRING
Somente leitura. A diretiva ServerInit define essa cadeia. Essa variável só pode ser lida durante a etapa Inicialização do Servidor.
LAST_MODIFIED
Extrair essa variável se aplica ao cabeçalho do pedido do cliente. Configurá-la afeta o valor do cabeçalho no pedido para o servidor de conteúdo. Por exemplo:
Segunda-feira, 1 de março de 1998 19:41:17 GMT
LOCAL_VARIABLES
Somente leitura. Todas as variáveis definidas pelo usuário.
MAXACTIVETHREADS
Somente leitura. O número máximo de encadeamentos ativos.
NOTMODIFIED_TO_OK
Força uma resposta integral para o cliente. Válido nas etapas PreExit e ProxyAdvisor.
ORIGINAL_HOST
Somente leitura. Retorna o nome do host ou o endereço IP de destino de um pedido.
ORIGINAL_URL
Somente leitura. Retorna a URL original enviada no pedido do cliente.
OVERRIDE_HTTP_NOTRANSFORM
Permite a modificação de dados na presença de um Cache-Control: cabeçalho no-transform. Configurar essa variável afeta o cabeçalho de resposta para o cliente.
OVERRIDE_PROXY_NOTRANSFORM
Permite a modificação de dados na presença de um Cache-Control: cabeçalho no-transform. Configurar essa variável afeta o pedido para o servidor de conteúdo.
PASSWORD
Para a autenticação básica, contém a senha decodificada. Por exemplo, password.
PATH
Contém o caminho completamente convertido.
PATH_INFO
Contém informações de caminho adicionais conforme enviadas pelo navegador da Web. Por exemplo, /foo.
PATH_TRANSLATED
Contém a versão decodificada ou convertida das informações do caminho contidas em PATH_INFO. Por exemplo:
d:\wwwhome\foo
/wwwhome/foo
PPATH
Contém o caminho convertido parcialmente. Use isso na etapa Conversão de Nome.
PROXIED_CONTENT_LENGTH
Somente leitura. Retorna o comprimento dos dados de resposta realmente transferido por meio do servidor proxy.
PROXY_ACCESS
Define se o pedido é ou não um pedido de proxy. Por exemplo, NO.
PROXY_CONTENT_TYPE
Contém o cabeçalho Content-Type do pedido de proxy feito por meio de HTTPD_proxy(). Quando as informações são enviadas com o método de POST, essa variável contém o tipo de dado incluído. É possível criar seu próprio tipo de conteúdo no arquivo de configuração do servidor proxy e mapeá-lo para um visualizador. Extrair essa variável se aplica ao valor do cabeçalho da resposta do servidor de conteúdo. Configurá-la afeta o cabeçalho do pedido para o servidor de conteúdo. Por exemplo:
application/x-www-form-urlencoded
PROXY_CONTENT_LENGTH
O cabeçalho Content-Length do pedido de proxy feito por meio de HTTPD_proxy(). Quando as informações são enviadas com o método de POST, essa variável contém o número de caracteres de dados. Os servidores normalmente não enviam um sinalizador de fim de arquivo ao encaminhar as informações usando a entrada padrão. Se necessário, é possível usar o valor CONTENT_LENGTH para determinar o fim da cadeia de entrada. Extrair essa variável se aplica ao valor do cabeçalho da resposta do servidor de conteúdo. Configurá-la afeta o cabeçalho do pedido para o servidor de conteúdo. Por exemplo:
7034
PROXY_COOKIE
Quando lida, essa variável contém o valor do cabeçalho Set-Cookie configurado pelo servidor de origem. Ela também pode ser usada para configurar um novo cookie no fluxo de pedido. Configurar essa variável faz com que a criação de um novo cabeçalho Set-Cookie no fluxo de pedido do documento, independente de o cabeçalho duplicado existir ou não.
PROXY_HEADERS
Somente leitura. Usado para extrair os cabeçalhos Proxy.
PROXY_METHOD
Método para o pedido feito por meio do HTTPD_proxy(). Extrair essa variável se aplica ao valor do cabeçalho da resposta do servidor de conteúdo. Configurá-la afeta o cabeçalho do pedido para o servidor de conteúdo.
QUERY_STRING
Quando informações são enviadas usando um método de GET, essa variável contém as informações que vem seguida de um ponto de interrogação (?) em uma consulta. Essas informações devem ser decodificadas pelo programa de CGI. Por exemplo:
NAME=Eugene+T%2E+Fox&ADDR=etfox%7Cibm.net&INTEREST=xyz
RCA_OWNER
Somente leitura. Retorna um valor numérico, fornecendo ao nó que era proprietário do objeto solicitado. Essa variável pode ser usada nas etapas PostExit, ProxyAdvisor ou Log e é significativa somente quando o servidor faz parte de uma matriz de cache que usa remote cache access (RCA).
RCA_TIMEOUTS
Somente leitura. Retorna um valor numérico que contém o número total (agregado) de tempos limite em pedidos RCA para todos os peers. É possível usar essa variável em cada etapa.
REDIRECT_*
Somente leitura. Contém uma cadeia de redirecionamento para o código de erro que corresponde ao nome da variável (por exemplo, REDIRECT_URL). Uma lista de variáveis REDIRECT_ possíveis pode ser localizada na documentação para o servidor Apache da Web em http://httpd.apache.org/docs-2.0/custom-error.html.
REFERRER_URL
Somente leitura. Contém o local da última URL do navegador. Ela permite que o cliente especifique, em benefício do servidor, o endereço (URL) do recurso a partir do qual o Request-URL foi obtido. Por exemplo:
http://www.company.com/homepage
REMOTE_ADDR
Contém o endereço IP do navegador da Web, se disponível. Por exemplo, 45.23.06.8.
REMOTE_HOST
Contém o nome do host do navegador da Web, se disponível. Por exemplo, www.raleigh.ibm.com.
REMOTE_USER
Se o servidor suportar autenticação de cliente e o script estiver protegido, essa variável conterá o nome de usuário passado para autenticação. Por exemplo, joeuser.
REQHDR
Somente leitura. Contém uma lista dos cabeçalhos enviados pelo cliente.
REQUEST_CONTENT_TYPE
Somente leitura. Retorna o tipo de conteúdo do corpo do pedido. Por exemplo:
application/x-www-form-urlencoded
REQUEST_CONTENT_LENGTH
Somente leitura. Quando as informações são enviadas com o método de POST, essa variável contém o número de caracteres de dados. Os servidores normalmente não enviam um sinalizador de fim de arquivo ao encaminhar as informações usando a entrada padrão. Se necessário, é possível usar o valor CONTENT_LENGTH para determinar o fim da cadeia de entrada. Por exemplo, 7034.
REQUEST_METHOD
Somente leitura. Contém o método (conforme especificado com o atributo METHOD em um formulário de HTML) usado para enviar o pedido. Por exemplo, GET ou POST.
REQUEST_PORT
Somente leitura. Retorna o número da porta especificado na URL ou uma porta padrão baseada no protocolo.
RESPONSE_CONTENT_TYPE
Somente leitura. Quando as informações são enviadas com o método de POST, essa variável contém o tipo de dado incluído. É possível criar seu próprio tipo de conteúdo no arquivo de configuração do servidor proxy e mapeá-lo para um visualizador. Por exemplo, text/html.
RESPONSE_CONTENT_LENGTH
Somente leitura. Quando as informações são enviadas com o método de POST, essa variável contém o número de caracteres de dados. Os servidores normalmente não enviam um sinalizador de fim de arquivo ao encaminhar as informações usando a entrada padrão. Se necessário, é possível usar o valor CONTENT_LENGTH para determinar o fim da cadeia de entrada. Por exemplo, 7034.
RULE_FILE_PATH
Somente leitura. Contém o caminho completo do sistema de arquivos e o nome do arquivo do arquivo de configuração.
SSL_SESSIONID
Somente leitura. Retorna o ID da sessão SSL se o pedido atual for recebido em uma conexão de SSL. Retorna NULL se o pedido atual não for recebido em uma conexão de SSL.
SCRIPT_NAME
Contém a URL do pedido.
SERVER_ADDR
Somente leitura. Contém o endereço do IP local do servidor proxy.
SERVER_NAME
Somente leitura. Contém o nome do host do servidor proxy ou o endereço IP do servidor de conteúdo desse pedido. Por exemplo, www.ibm.com.
SERVER_PORT
Somente leitura. Contém o número da porta do servidor proxy para a qual o pedido do cliente foi enviado. Por exemplo, 80.
SERVER_PROTOCOL
Somente leitura. Contém o nome e a versão do protocolo usado para fazer o pedido. Por exemplo, HTTP/1.1.
SERVER_ROOT
Somente leitura. Contém o diretório no qual o programa do servidor proxy é instalado.
SERVER_SOFTWARE
Somente leitura. Contém o nome e a versão do servidor proxy.
STATUS
Contém o código de resposta de HTTP e a cadeia de motivos. Por exemplo, 200 OK.
TRACE
Determina a quantidade de informações que será rastreada. Os valores retornados incluem:
URI
Ler/Gravar. O mesmo que DOCUMENT_URL.
URI_PATH
Somente leitura. Retorna a parte do caminho somente para a URL.
URL
Ler/Gravar. O mesmo que DOCUMENT_URL.
URL_MD4
Somente leitura. Retorna o nome do arquivo do arquivo de cache potencial para o pedido atual.
USE_PROXY
Identifica o proxy com o qual associar a solicitação atual. Especifique a URL. Por exemplo, http://myproxy:8080.
USERID
O mesmo que REMOTE_USER.
USERNAME
O mesmo que REMOTE_USER.

Autenticação e Autorização

Primeiro, uma revisão rápida da terminologia:

Autenticação
A verificação dos tokens de segurança associados a esse pedido, a fim de verificar a identidade do solicitante.
Autorização
Um processo que usa tokens de segurança para determinar se o solicitante tem acesso ao recurso.

Figura 3 descreve o processo de autenticação e de autorização do Servidor Proxy.

Figura 3. Processo de autenticação e autorização do servidor proxy
Diagrama do processo de autorização e autenticação

Conforme demonstrado em Figura 3, a iniciação do processo de autorização é a primeira etapa no processo de autorização e autenticação do servidor.

No Caching Proxy, a autenticação faz parte do processo de autorização; ela ocorre somente quando a autorização é necessária.

Processo de Autenticação e Autorização

O Servidor Proxy segue estas etapas ao processar um pedido que requeira autorização.

  1. Primeiro, o Servidor Proxy examina o arquivo de configuração para determinar se há ou não uma diretiva de autorização.
  2. O Servidor Proxy começa o processo de autenticação ao verificar para confirmar se o cabeçalho HTTP_authenticate está presente no pedido do cliente.
  3. O Servidor Proxy verifica para confirmar se há uma diretiva de autenticação presente no arquivo de configuração de proxy.

Se o plug-in do Caching Proxy fornecer seu próprio processo de autorização, ele substituirá a autorização e a autenticação do servidor padrão. Portanto, se tiver diretivas de autorização no arquivo de configuração, as funções de plug-in associadas a elas também deverão tratar qualquer autenticação necessária. A função HTTPD_authenticate() predefinida é fornecida para ser usada.

Há três formas de fornecer uma autenticação nos plug-in de autorização:

Se o plug-in do Caching Proxy não fornecer seu próprio processo de autorização, ainda será possível fornecer autenticação customizada ao usar o seguinte método:

Quando a etapa Autorização é executada, ela executa a autorização do servidor padrão, a qual, por sua vez, chama a função de plug-in de autenticação.

Lembre-se dos seguintes pontos:

Armazenamento em Cache da Variante

Use o armazenamento em cache da variante para dados em cache, que é uma forma modificada do documento original (a URI). O Caching Proxy trata variantes geradas pela API. Variantes são versões diferentes de um documento base.

Em geral, quando servidores de origem enviam variantes, eles falham ao identificá-las como tal. O Caching Proxy suporta somente variantes criadas por plug-ins (por exemplo, conversão de página de código). Se um plug-in cria uma variante baseada em critérios que não estão no cabeçalho HTTP, ele deve conter uma função de etapa PreExit ou PostAuthorization para criar um pseudocabeçalho para que o Caching Proxy possa identificar corretamente a variante existente.

Por exemplo, use um programa de API do Transformador para modificar os dados que os usuários solicitam com base no valor do cabeçalho Usuário-Agente enviado pelo navegador. Na função close, salve o conteúdo modificado em um arquivo ou especifique um comprimento de buffer e passe o buffer como o argumento de dados. Em seguida, use as funções httpd_variant_insert() e httpd_variant_lookup() de armazenamento em cache da variante para colocar o conteúdo no cache.

Exemplos de API

Para ajudá-lo a começar com suas próprias funções de API do Caching Proxy, consulte os programas de amostra fornecidos no diretório samples do CD-ROM de instalação da Edge Components. Informações adicionais estão disponíveis no Web site do WebSphere Application Server, www.ibm.com/software/webservers/appserv/.