Referência de propriedades do endpoint

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

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

Propriedades de transporte de TargetEndpoint

O elemento HTTPTargetConnection nas configurações 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 nos elementos TargetEndpoint e HTTPTargetConnection, conforme mostrado abaixo:

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

Especificação da propriedade de transporte de TargetEndpoint

Nome da propriedade Valor padrão Descrição
keepalive.timeout.millis 60000 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. O Edge retornará um código de status HTTP 503 se o tempo limite de conexão ocorrer.

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 ocorrer tempo limite durante a gravação da solicitação HTTP, 408, Request Timeout será retornado.
  • Se ocorrer tempo limite durante a leitura da resposta HTTP, 504, Gateway Timeout será retornado.

Este valor precisa ser sempre menor do que o valor da propriedade proxy_read_timeout do host virtual.

Esse valor precisa ser menor que o tempo limite usado pelo roteador para se comunicar com o processador de mensagens. Consulte Como configurar o tempo limite do roteador para mais informações.

Para saber mais, consulte Como definir io.timeout.millis e api.timeout para Edge.

supports.http10 true Se ele for true e o cliente enviar uma solicitação 1.0, o destino também receberá uma solicitação 1.0. Caso contrário, a solicitação 1.1 será enviada para o destino.
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 será enviada para o destino.
use.proxy true Se for definido como true, e as configurações de proxy forem especificadas em http.properties (apenas implantações locais), as conexões de destino serão definidas para usar o proxy especificado.
use.proxy.tunneling true Se for definido como true e as configurações de proxy forem especificadas em http.properties (apenas implantações locais), as conexões de destino serão configuradas para usar o túnel especificado. Se o destino usar TLS/SSL, essa propriedade será ignorada e a mensagem será sempre enviada por meio de um túnel.
enable.method.override false Para o método HTTP especificado, define um cabeçalho X-HTTP-Method-Override na solicitação de saída para o serviço de destino. Por exemplo, <Property name="GET.override.method">POST</Property>
*.override.method N/A Para o método HTTP especificado, define um cabeçalho X-HTTP-Method-Override na solicitação de saída. Por exemplo, <Property name="GET.override.method">POST</Property>
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), é possível definir esse atributo como true. Quando true, os payloads da solicitação HTTP não são lidos em um buffer. Eles são transmitidos no estado em que se encontram 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 (false), os payloads de 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), é possível definir esse atributo como true. Quando true, os payloads de resposta HTTP não são lidos em um buffer. Eles são transmitidos no estado em que se encontram para o fluxo de resposta de ProxyEndpoint. Nesse caso, todas as políticas que operam no payload no fluxo de resposta TargetEndpoint são ignoradas. Consulte também Solicitações e respostas de streaming.

success.codes N/A

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

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 são tratados como falhas.

compression.algorithm N/A Por padrão, o Apigee Edge encaminha solicitações para o destino usando o mesmo tipo de compactação da solicitação do cliente. 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 a compactação/descompactação com GZIP/deflate?

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 ir 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 ir para o ProxyEndpoint. Por exemplo, para transmitir o 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 estiver 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 de ProxyEndpoint

Os elementos ProxyEndpoint e 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 nos elementos ProxyEndpoint e HTTPProxyConnection da seguinte maneira:

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

Para saber mais sobre hosts virtuais, consulte Sobre hosts virtuais.

Especificação da propriedade de transporte de ProxyEndpoint

Nome da propriedade Valor padrão Descrição
X-Forwarded-For false Quando definido como true, o endereço IP do host virtual vai ser 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), é possível definir esse atributo como true. Quando true, os payloads da solicitação HTTP não são lidos em um buffer. Eles são transmitidos no estado em que se encontram para o fluxo de solicitação do TargetEndpoint. Nesse caso, todas as políticas que operam no payload no fluxo de solicitação ProxyEndpoint são ignoradas. Consulte também Solicitações e respostas de streaming.
response.streaming.
enabled
false Por padrão (false), os payloads de 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), é possível definir esse atributo como true. Quando true, os payloads de resposta HTTP não são lidos em um buffer. Eles são transmitidos no estado em que se encontram para o cliente. Nesse caso, todas as políticas que operam no payload no fluxo de resposta ProxyEndpoint são ignoradas. Consulte também Solicitações e respostas de streaming.
compression.algorithm N/A

Por padrão, o Apigee Edge respeita o tipo de compactação definido para qualquer mensagem recebida. Por exemplo, quando um cliente envia uma solicitação que usa a compactação gzip, o Apigee Edge encaminha a solicitação ao destino usando a compactação gzip. Configure os algoritmos de compactação para serem aplicados explicitamente definindo essa propriedade no TargetEndpoint ou no 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 a compactação/descompactação com GZIP/deflate?

api.timeout N/A

Configurar o tempo limite para proxies de API individuais

É possível configurar proxies de API, mesmo aqueles com streaming ativado, para expirar após um tempo especificado com um status 504 Gateway Timeout. O principal caso de uso é para clientes que têm proxies de API que levam mais tempo para serem executados. Por exemplo, digamos que você precise de proxies específicos para expirar em 3 minutos. Veja a seguir como usar api.timeout.

  1. Primeiro, configure o balanceador de carga, o roteador e o processador de mensagens para que eles expirem após três minutos.
  2. Em seguida, configure os proxies relevantes para expirar em três minutos. Especifique o valor em milissegundos. Por exemplo: <Property name="api.timeout">180000</Property>
  3. No entanto, aumentar os tempos limite do sistema pode causar problemas de desempenho, porque todos os proxies sem uma configuração api.timeout usam os novos tempos limite maiores do balanceador de carga, roteador e processador de mensagens. Assim, configure outros proxies de API que não exigem tempos limite mais longos para usar tempos limite mais baixos. Por exemplo, o comando a seguir define um proxy de API que expira depois de um minuto:
    <Property name="api.timeout">60000</Property>

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

Os clientes que não podem modificar os tempos limite do Edge também podem configurar um tempo limite do proxy de API, desde que ele seja menor que o tempo limite padrão do processador de mensagens Edge, de 57 segundos.

Para saber mais, consulte Como definir io.timeout.millis e api.timeout para Edge.

Como definir io.timeout.millis e api.timeout para o Edge

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

  1. O roteador envia seu valor de tempo limite para o processador de mensagens. O valor de tempo limite do roteador é o valor de proxy_read_timeout definido pelo host virtual que processa a solicitação ou o valor de tempo limite padrão de 57 segundos.
  2. Em seguida, o processador de mensagens define api.timeout:
    1. Se api.timeout não estiver definido no nível do proxy, defina-o como o tempo limite do roteador.
    2. Se api.timeout estiver definido no nível do proxy, defina-o no processador de mensagens como o menor tempo limite do roteador 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 executar da solicitação de API para a resposta.

    Depois que cada política no proxy de API é executada, ou antes que o processador de mensagens envie a solicitação para o endpoint de destino, o processador de mensagens calcula (api.timeout: tempo decorrido desde o início da solicitação). Se o valor for menor que zero, o tempo máximo para processar a solicitação vai expirar e o processador de mensagens retornará 504.

  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 de (api.timeout: 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 tempo limite durante a gravação da solicitação HTTP, 408, Request Timeout será retornado.
    • Se ocorrer tempo limite durante a leitura da resposta HTTP, 504, Gateway Timeout será retornado.

Sobre o ScriptTarget para aplicativos Node.js

O elemento ScriptTarget é usado para integrar um aplicativo Node.js ao seu proxy. Para informações sobre como usar Node.js e ScriptTarget, consulte:

Sobre os endpoints do HostedTarget

Uma tag <HostedTarget/> vazia instrui o Edge a usar como destino um aplicativo Node.js implantado no ambiente de Destinos hospedados. Para mais detalhes, consulte Visão geral de destinos hospedados.