Pedidos e respostas de streaming

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

O que vai aprender neste tópico

Depois de ler este tópico, vai saber o seguinte:

• O que é o streaming de pedidos e respostas no Apigee
• Quando usar o streaming de pedidos e respostas
• Como ativar o streaming de pedidos e respostas

Exemplo: se quiser aceder diretamente a um exemplo de código, consulte Exemplos de código relacionados para ver detalhes.

O que é o streaming de pedidos e respostas?

Por predefinição, o streaming HTTP está desativado e as cargas de resposta e de pedido HTTP são escritas num buffer na memória antes de serem processadas pelo pipeline do proxy de API. Pode alterar este comportamento ativando o streaming. Com o streaming ativado, os payloads de pedidos e respostas são transmitidos sem modificação para a app cliente (para respostas) e o ponto final de destino (para pedidos).

Quando devo ativar o streaming?

Se o seu proxy de API processar pedidos e/ou respostas muito grandes (para ver os limites de tamanho, consulte Que mais devo saber sobre o streaming), pode querer ativar o streaming.

Nota: se os seus pedidos de API enviarem ou devolverem uma grande quantidade de dados, pode ver este erro HTTP:

{"fault":"{\"detail\":{\"errorcode\":\"protocol.http.TooBigBody\"},\"faultstring\":\"Body buffer overflow\"}"}

Se vir este erro, recomendamos que ative o streaming. Se continuar a ver o erro depois de ativar o streaming, considere remover todas as políticas que exijam acesso ao payload de pedido ou resposta. Para mais informações, consulte o artigo Tamanho da carga útil da mensagem.

Que mais devo saber sobre o streaming?

O tamanho da carga útil da mensagem está restrito a 30 MB. Em pedidos e respostas não transmitidos, exceder esse tamanho resulta num erro protocol.http.TooBigBody.

Aviso: embora o streaming possa ajudar a contornar o limite de tamanho de pedido/resposta de 30 MB imposto pelo produto, o Apigee não recomenda exceder esse limite quando usa o streaming e não pode oferecer apoio técnico para problemas que surjam como resultado da ultrapassagem desse limite, como problemas de desempenho, limites de tempo, etc.

Para payloads superiores a 30 MB, o Apigee recomenda a utilização de um padrão de URLs assinados num JavaCallout do Apigee, ilustrado pelo exemplo Edge Callout: Signed URL Generator no GitHub.

Nota: com o streaming ativado, a Apigee recomenda vivamente que não anexe políticas que exijam acesso ao payload do pedido ou da resposta. Esses tipos de políticas causam erros ou acionam o armazenamento em buffer no proxy da API, o que limita o tamanho da carga útil aos números indicados acima e anula o objetivo de ativar o streaming para processar cargas úteis grandes. Pode anexar políticas que não interagem com o corpo do pedido/resposta, como políticas de autenticação ou de registo de mensagens.

Dados codificados

Quando o streaming está ativado, o Apigee não codifica nem descodifica os payloads de pedidos ou respostas antes de os enviar para o cliente que se liga ao Apigee ou a um servidor de destino de back-end. Consulte as linhas de request.streaming.enabled e response.streaming.enabled na tabela TargetEndpoint Transport Property Specification para mais informações.

Como ativar o streaming de pedidos e respostas

Para ativar o streaming de pedidos, tem de adicionar a propriedade request.streaming.enabled às definições de ProxyEndpoint e TargetEndpoint no pacote de proxy e defini-la como true. Da mesma forma, defina a propriedade response.streaming.enabled para ativar o streaming de respostas.

Pode localizar estes ficheiros de configuração na IU do Apigee na vista Develop para o seu proxy. Se estiver a desenvolver localmente, estes ficheiros de definição encontram-se em apiproxy/proxies e apiproxy/targets.

Este exemplo mostra como ativar o streaming de pedidos e respostas na definição TargetEndpoint.

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

Este exemplo mostra como ativar o streaming de respostas e pedidos na definição de ProxyEndpoint:

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

Para mais informações sobre a configuração de definições de pontos finais, consulte a referência de propriedades de pontos finais.

Exemplos de código relacionados

Os exemplos de proxy de API no GitHub são fáceis de transferir e usar.

Alguns exemplos de proxies que incluem streaming:

• streaming: demonstra um proxy de API configurado para streaming HTTP.
• Edge Callout: Signed URL Generator: ilustra a prática recomendada de gerar um URL assinado para aceder a ficheiros grandes em vez de tentar transmiti-los numa solicitação/resposta.