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. Observação: em alguns casos, a Apigee tenta se conectar automaticamente até três vezes. Como resultado, o tempo total de nova tentativa pode exceder o que está configurado para o `connect.timeout.millis`.
`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. Observação: se você estiver usando conexões WebSocket, defina um tempo limite acima do valor padrão de 5.500. Se a conexão WebSocket estiver inativa, essa propriedade não será válida. A conexão será encerrada após 55 segundos. 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`. Importante: o tempo limite especificado precisa ser menor que o tempo limite padrão do processador de mensagens de 300 segundos. 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:

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.
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.
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.
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.