Referência de propriedades do endpoint

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Este tópico descreve as propriedades de transporte que podem ser definidas nas configurações de TargetEndpoint e ProxyEndpoint para controlar as mensagens e o comportamento de conexão. Para ver a cobertura completa das opções de configuração TargetEndpoint e ProxyEndpoint, consulte a referência da configuração do proxy de API.

Propriedades de transporte TargetEndpoint

O elemento HTTPTargetConnection nas configurações de TargetEndpoint define um conjunto de propriedades de transporte HTTP. Use essas propriedades para definir configurações no nível de transporte.

As propriedades são definidas em elementos TargetEndpoint HTTPTargetConnection, conforme esta configuração de exemplo:

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <Properties>
      <Property name="request.retain.headers">User-Agent,Referer,Accept-Language</Property>
      <Property name="retain.queryparams">apikey</Property>
    </Properties>
  </HTTPTargetConnection>
</TargetEndpoint>

Especificação da propriedade de transporte TargetEndpoint

Nome da propriedade Valor padrão Descrição
allow.post.without.content.length false Permite enviar solicitações POST sem conteúdo no corpo.
allow.put.without.content.length false Permite enviar solicitações PUT sem conteúdo no corpo.
allow.tls.session.resumption true Se os clientes true (padrão) reutilizarem sessões TLS ao fazer novas conexões com o destino. Defina como false se não quiser reutilizar a sessão TLS. A reutilização de sessão geralmente significa tempos de conexão mais curtos, mas alguns destinos podem não suportar a reutilização de sessão ou ter dificuldade com isso.
keepalive.timeout.millis 60.000 Tempo limite de inatividade para a conexão de destino no pool de conexões. Se a conexão no pool ficar inativa além do limite especificado, ela será fechada.
connect.timeout.millis

3000

Tempo limite da conexão de destino. A Apigee retornará um código de status HTTP 503 se ocorrer um tempo limite de conexão. Em alguns casos, um código de status HTTP 504 pode ser retornado quando LoadBalancer é usado na definição do servidor de destino, e o tempo limite é atingido.
ignore.allow.header.for.405

true

Permite passar o código de status 405 de volta para o cliente. Ao ativar a sinalização, a Apigee retornará o código de status 405 em vez de 502.
io.timeout.millis 55000

Se não houver dados a serem lidos pelo número de milissegundos especificado ou se o soquete não estiver pronto para gravar dados pelo número especificado de milissegundos, a transação será tratada como tempo limite.

  • Se um tempo limite ocorrer durante a leitura da solicitação HTTP da entrada, 408 Request Timeout será reajustado. 408 Request Timeout não será retornado se ocorrer um tempo limite durante a gravação de uma solicitação para o destino.
  • Se ocorrer um tempo limite durante a gravação da solicitação HTTP ou a leitura da resposta HTTP, 504 Gateway Timeout será retornado.

Consulte Como configurar io.timeout.millis e api.timeout.
supports.http11 true Se for true e o cliente enviar uma solicitação 1.1, o destino também receber uma solicitação 1.1. Caso contrário, a solicitação 1.0 é enviada para o destino.
use.proxy true

Essa propriedade se aplica somente à Apigee híbrida.

Se o arquivo de modificações híbridas da Apigee contiver a configuração HTTP_PROXY, conforme descrito em Configurar o encaminhamento de proxy para proxies de API, use essa propriedade para gerenciar/controlar quais proxies não devem usar a configuração de proxy.

Se definido como false, o proxy de API pulará as configurações de proxy HTTP especificadas no arquivo de modificações do híbrido da Apigee para conexões de destino definidas no proxy.

use.proxy.tunneling true

Essa propriedade se aplica somente à Apigee híbrida.

Se esse valor estiver definido como "true" e as configurações de proxy forem especificadas no arquivo de modificação da Apigee híbrida, conforme descrito em Configurar proxy de encaminhamento para proxies de API, as conexões de destino serão definidas para usar o túnel especificado. Se o destino usar TLS/SSL, essa propriedade será ignorada e a mensagem será sempre enviada usando um túnel.

request.streaming.enabled false

Por padrão (false), os payloads da solicitação HTTP são lidos em um buffer, e as políticas que podem operar no payload funcionarão conforme o esperado. Nos casos em que os payloads são maiores que o tamanho do buffer (10 MB na Apigee), é possível definir esse atributo como true. Quando true, os payloads da solicitação HTTP não são lidos em um buffer, mas são transmitidos por streaming como estão para o endpoint de destino. Nesse caso, todas as políticas que operam no payload no fluxo de solicitação TargetEndpoint são ignoradas. Consulte também Solicitações e respostas de streaming.
response.streaming.enabled false

Por padrão (falso), os payloads da resposta HTTP são lidos em um buffer, e as políticas que podem operar no payload funcionam conforme o esperado. Nos casos em que os payloads são maiores que o tamanho do buffer (10 MB na Apigee), você pode definir esse atributo como verdadeiro. Quando verdadeiro, os payloads da resposta HTTP não são lidos em um buffer, mas são transmitidos por streaming como estão para o fluxo de resposta de ProxyEndpoint. Nesse caso, todas as políticas que operam no payload no fluxo de resposta de TargetEndpoint são ignoradas. Consulte também Solicitações e respostas de streaming.
success.codes N/A

Por padrão, a Apigee trata o código HTTP 4XX ou 5XX como erros e trata os códigos HTTP 1XX, 2XX, 3XX como bem-sucedidos. Essa propriedade permite a definição explícita de códigos de sucesso, por exemplo, 2XX, 1XX, 505 trata os códigos de resposta HTTP 100, 200 e 505 como bem-sucedidos.

A definição dessa propriedade substitui os valores padrão. Portanto, se você quiser adicionar o código HTTP 400 à lista de códigos bem-sucedidos padrão, defina esta propriedade como:

<Property name="success.codes">1xx,2xx,3xx,400</Property>

Se você quiser que apenas o código HTTP 400 seja tratado como um código de sucesso, defina a propriedade como:

<Property name="success.codes">400</Property>

Ao definir o código HTTP 400 como o único código de sucesso, os códigos 1xx, 2xx e 3xx serão tratados como códigos de falha.
compression.algorithm N/A Por padrão, a Apigee respeita o tipo de compactação definido (gzip, deflate ou nenhum) para mensagens recebidas. Se a solicitação for recebida do cliente usando, por exemplo, a compactação gzip, o Apigee Edge encaminhará a solicitação para o destino usando a compactação gzip. Se a resposta recebida do destino usar deflate, o Apigee Edge encaminhará a resposta ao cliente usando deflate. Os valores aceitos são:
  • gzip: sempre enviar mensagens usando a compactação gzip.
  • deflate: sempre enviar mensagens usando a compactação deflate.
  • nenhum: sempre enviar mensagens sem compactação.

Consulte também: A Apigee é compatível com compactação/descompactação com compactação GZIP/deflate? (em inglês).
request.retain.headers.
enabled		 true Por padrão, o Apigee Edge sempre mantém todos os cabeçalhos HTTP nas mensagens de saída. Quando definido como true, todos os cabeçalhos HTTP presentes na solicitação de entrada são definidos na solicitação de saída.
request.retain.headers N/A Define cabeçalhos HTTP específicos da solicitação que devem ser definidos na solicitação de saída para o serviço de destino. Por exemplo, para passar pelo cabeçalho User-Agent, defina o valor de request.retain.headers como User-Agent. Vários cabeçalhos HTTP são especificados como uma lista separada por vírgulas. Por exemplo, User-Agent,Referer,Accept-Language. Esta propriedade substitui request.retain.headers.enabled. Se request.retain.headers.enabled for definido como false, todos os cabeçalhos especificados na propriedade request.retain.headers ainda serão definidos na mensagem de saída.
response.retain.headers.
enabled		 true Por padrão, o Apigee Edge sempre mantém todos os cabeçalhos HTTP nas mensagens de saída. Quando definido como true, todos os cabeçalhos HTTP presentes na resposta de entrada do serviço de destino são definidos na resposta de saída antes de serem transmitidos para o ProxyEndpoint.
response.retain.headers N/A Define cabeçalhos HTTP específicos da resposta que precisam ser definidos na resposta de saída antes de irem para o ProxyEndpoint. Por exemplo, para passar pelo cabeçalho Expires, defina o valor de response.retain.headers como Expires. Vários cabeçalhos HTTP são especificados como uma lista separada por vírgulas. Por exemplo, Expires,Set-Cookie. Esta propriedade substitui response.retain.headers.enabled. Se response.retain.headers.enabled for definido como false, todos os cabeçalhos especificados na propriedade response.retain.headers ainda serão definidos na mensagem de saída.
retain.queryparams.
enabled		 true Por padrão, o Apigee Edge sempre mantém todos os parâmetros de consulta nas solicitações de saída. Quando definido como true, todos os parâmetros de consulta presentes na solicitação de entrada são definidos na solicitação de saída para o serviço de destino.
retain.queryparams N/A Define parâmetros de consulta específicos a serem definidos na solicitação de saída. Por exemplo, para incluir o parâmetro de consulta apikey da mensagem de solicitação, defina retain.queryparams como apikey. Vários parâmetros de consulta são especificados como uma lista separada por vírgulas, por exemplo, apikey,environment. Esta propriedade modifica retain.queryparams.enabled.

Propriedades de transporte ProxyEndpoint

Os elementos ProxyEndpoint HTTPTargetConnection definem um conjunto de propriedades de transporte HTTP. Essas propriedades podem ser usadas para definir configurações no nível de transporte.

As propriedades são definidas em elementos ProxyEndpoint HTTPProxyConnection, conforme esta configuração de exemplo:

<ProxyEndpoint name="default">
  <HTTPProxyConnection>
    <BasePath>/v1/weather</BasePath>
    <Properties>
      <Property name="request.streaming.enabled">true</Property>
    </Properties>
  </HTTPProxyConnection>
</ProxyEndpoint>

Cabeçalhos de solicitação

Uma solicitação HTTP recebida inclui os cabeçalhos HTTP enviados pelo cliente. Os cabeçalhos com nomes que correspondem ao padrão X-Apigee-* são removidos das solicitações recebidas se um cliente as enviar. Esse padrão de nome é reservado para a Apigee.

Especificação da propriedade de transporte ProxyEndpoint

Nome da propriedade Valor padrão Descrição
X-Forwarded-For false Quando definido como verdadeiro, o endereço IP do host virtual é adicionado à solicitação de saída como o valor do cabeçalho HTTP X-Forwarded-For.
request.streaming.
enabled		 false Por padrão (false), os payloads da solicitação HTTP são lidos em um buffer, e as políticas que podem operar no payload funcionam conforme o esperado. Nos casos em que os payloads são maiores que o tamanho do buffer (10 MB na Apigee), é possível definir esse atributo como true. Quando true, os payloads da solicitação HTTP não são lidos em um buffer, mas são transmitidos por streaming como estão para o fluxo de solicitação de TargetEndpoint. Nesse caso, todas as políticas que operam no payload no fluxo de solicitação de ProxyEndpoint são ignoradas. Consulte também Solicitações e respostas de streaming.
response.streaming.
enabled		 false Por padrão (falso), os payloads da resposta HTTP são lidos em um buffer, e as políticas que podem operar no payload funcionam conforme o esperado. Nos casos em que os payloads são maiores que o tamanho do buffer (10 MB na Apigee), é possível definir esse atributo como true. Quando true, os payloads da resposta HTTP não são lidos em um buffer, mas são transmitidos por streaming como estão para o cliente. Nesse caso, todas as políticas que operam no payload no fluxo de resposta de ProxyEndpoint são ignoradas. Consulte também Solicitações e respostas de streaming.
compression.algorithm N/A

Por padrão, a Apigee respeita o tipo de compactação definido (gzip, deflate ou nenhum) para mensagens recebidas. Por exemplo, quando um cliente envia uma solicitação que usa a compactação gzip, a Apigee encaminha a solicitação ao destino usando a compactação gzip. É possível configurar algoritmos de compactação para serem explicitamente aplicados definindo essa propriedade em TargetEndpoint ou ProxyEndpoint. Os valores aceitos são:

  • gzip: sempre enviar mensagens usando a compactação gzip.
  • deflate: sempre enviar mensagens usando a compactação deflate.
  • nenhum: sempre enviar mensagens sem compactação.

Consulte também: A Apigee é compatível com compactação/descompactação com compactação GZIP/deflate? (em inglês).
api.timeout N/A

Configurar o tempo limite para proxies de API individuais (em milissegundos)

É possível configurar proxies de API, mesmo aqueles com streaming ativado, para expirar após um tempo especificado com um status 504 Gateway Timeout.

Por exemplo, para configurar um proxy para expirar após 180.000 milissegundos (três minutos), adicione a seguinte propriedade a HTTPProxyConnection: 

<Property name="api.timeout">180000</Property>

Não é possível definir essa propriedade com uma variável.

Consulte Como configurar io.timeout.millis e api.timeout.
HTTPHeader.allowDuplicates N/A

Use essa configuração para permitir cabeçalhos duplicados (para cabeçalhos específicos).

<HTTPProxyConnection>
  <Properties>
     <Property name="HTTPHeader.allowDuplicates">Content-Type,Authorization</Property>
  </Properties>
</HTTPProxyConnection>
HTTPHeader.multiValued N/A

Use essa configuração para permitir cabeçalhos duplicados (para cabeçalhos específicos).

<HTTPProxyConnection>
  <Properties>
    <Property name="HTTPHeader.multiValued">Content-Type,Authorization</Property>
  </Properties>
</HTTPProxyConnection>

Como configurar io.timeout.millis e api.timeout

A operação de io.timeout.millis e de api.timeout estão relacionadas. Em todas as solicitações a um proxy de API:

  1. A Entrada (também conhecida como balanceador de carga interno) envia o valor de tempo limite para o processador de mensagens. Esse valor de tempo limite é de 300 segundos por padrão e não é configurável.
  2. O processador de mensagens define api.timeout:
    1. Se api.timeout não for definido no nível do proxy, use o tempo limite definido pela Entrada.
    2. Se api.timeout estiver definido no nível do proxy, defina ele no processador de mensagens como o menor tempo limite da Entrada ou como o valor de api.timeout.

  3. O valor de api.timeout especifica a quantidade máxima de tempo que um proxy de API precisa para executar da solicitação de API para a resposta.

    Depois que cada política no proxy de API for executada ou antes que o processador de mensagens envie a solicitação ao endpoint de destino, o processador de mensagens fará o cálculo de api.timeout menos o tempo decorrido desde o início da solicitação.

    Se o valor for menor que zero, quer dizer a quantidade máxima de tempo para processar a solicitação expirou e o processador de mensagens retornará um 504 Gateway Timeout.

  4. O valor de io.timeout.millis especifica o tempo máximo que o endpoint de destino tem para responder.

    Antes de se conectar a um endpoint de destino, o processador de mensagens determina o menor entre api.timeout menos o tempo decorrido desde o início da solicitação e io.timeout.millis. Em seguida, ele define io.timeout.millis como esse valor.

    Se ocorrer um tempo limite durante a gravação da solicitação HTTP ou a leitura da resposta HTTP, 504 Gateway Timeout será retornado.