Variáveis de pedido e resposta

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

Veja a documentação do Apigee Edge.

Quando faz um pedido a um proxy de API, pode transmitir algumas ou todas as seguintes informações, consoante a forma como o proxy de API está configurado:

• Cabeçalhos do pedido
• Parâmetros de consulta
• Dados do formulário
• Payloads XML ou JSON
• URIs de recursos

Por predefinição, todos os dados num pedido são transmitidos inalterados do ProxyEndpoint para o TargetEndpoint. Por conseguinte, quando o TargetEndpoint faz o pedido ao servidor de back-end, todas as informações no pedido original são transmitidas ao serviço de back-end.

O mesmo se aplica à resposta recebida pelo Apigee do serviço de back-end. Por predefinição, todos os dados recebidos na resposta são transmitidos inalterados para a app que originou o pedido.

Como é que os dados de pedidos são transmitidos ao servidor de back-end?

A imagem seguinte mostra uma definição de proxy de API:

Para este proxy de API:

• Anfitrião virtual do proxy de API: default
• Domínio definido pelos nomes de anfitrião no grupo de ambientes: http://www.example.com
• Caminho base do proxy: /v1/weather
• TargetEndpoint especificado pela regra de encaminhamento: default
• URL de destino: http://weather.yahooapis.com

Uma app cliente faz um pedido GET ao proxy da API através do seguinte comando curl:

curl -X GET http://www.example.com/v1/weather/forecastrss?w=12797282

Repare que este pedido contém o recurso forecastrss e um parâmetro de consulta, w. O Apigee analisa o pedido conforme mostrado abaixo e atribui partes do pedido a variáveis de fluxo:

{request.verb} {proxy.basepath}/{proxy.pathsuffix}?{request.querystring}

As variáveis de fluxo são definidas com os seguintes valores:

• request.verb: GET
• proxy.basepath: /v1/weather
• proxy.pathsuffix: forecastrss
• request.querystring: w=12797282

Nota: existem muitas variáveis de fluxo diferentes criadas durante o processamento de um pedido e uma resposta. Para mais informações, consulte a referência de variáveis de fluxo.

Em seguida, o TargetEndpoint faz um pedido ao serviço de back-end através de informações do pedido:

{request.verb} {target.basepath}/{proxy.pathsuffix}?{request.querystring}

Repare como os parâmetros de recursos e de consulta especificados no pedido são incluídos automaticamente no pedido ao servidor de back-end. A partir da definição do TargetEndpoint, o pedido tem então o seguinte formato:

curl -X GET http://weather.yahooapis.com/forecastrss?w=12797282

Tal como os parâmetros de consulta, todos os cabeçalhos ou parâmetros de formulário que incluir no pedido ao proxy da API são transmitidos ao servidor de back-end. Por exemplo, faz o pedido abaixo que inclui um cabeçalho:

curl -X GET -H 'Content-type:application/xml' http://www.example.com/v1/weather/forecastrss?w=12797282

Ou um pedido no formulário abaixo para incluir um cabeçalho e dados do formulário:

curl -X POST -H "Content-type:application/json" -d \
  '{"email" : "[e-mail]",
    "firstName" : "Jane",
    "lastName" : "Tutorial",
    "userName" : "jtutorialxml"
  }' \
  http://www.example.com/v1/register/user

Em ambos os exemplos, os cabeçalhos e os dados do formulário são transmitidos inalterados para o serviço de back-end. Os cabeçalhos são representados por variáveis de fluxo, como request.headers.count e request.headers.names. Os dados do formulário são representados por variáveis de fluxo, como request.formparam.count e request.formparam.names.

Como são devolvidos os dados de respostas?

Por predefinição, todos os dados recebidos pelo Apigee do serviço de back-end na resposta são transmitidos inalterados para a app que originou o pedido. Conforme descrito acima para o pedido, os dados devolvidos na resposta são acessíveis através de variáveis de fluxo no Apigee. Para mais informações, consulte a referência de variáveis de fluxo.

Aceda aos dados de pedidos e respostas num proxy de API

Há muitas situações em que quer modificar os dados do pedido antes de os enviar para o servidor de back-end. Por exemplo:

• Para remover informações de segurança usadas pelo Apigee para validar pedidos. Essas informações não são exigidas pelo serviço de back-end.
• Para adicionar dados enviados para o serviço de back-end, por exemplo, para acompanhar os utilizadores ou recolher estatísticas.
• Para processar condicionalmente o pedido com base nos dados do pedido. Por exemplo, um proxy de API pode ter vários TargetEndpoints. O TargetEndpoint usado pelo pedido é determinado pelos dados do pedido. Em seguida, remove esses dados do pedido antes de o enviar para o serviço de back-end.

O mesmo se aplica aos dados na resposta. Como parte do processamento da resposta, o proxy da API pode querer modificar os dados antes de os devolver à app que fez o pedido.

Mensagens de pedido de acesso

Pode usar políticas para aceder e alterar partes de uma mensagem de pedido. Estas partes incluem:

• Cabeçalhos
• Parâmetros de consulta
• Parâmetros de formulário
• Endereço IP de origem
• Corpo da mensagem HTTP

Num fluxo normal, assim que o pedido é processado, o proxy envia o pedido transformado ao destino.

As políticas podem examinar as variáveis de pedido e, em seguida, transformar ou rejeitar o pedido com base no conteúdo dessas variáveis. As políticas transformam o pedido definindo as variáveis adequadas, por exemplo, variáveis correspondentes aos cabeçalhos dos pedidos.

Sugestão: Pode usar variáveis para reconstruir o URL do pedido recebido. Por exemplo, o código seguinte numa política de JavaScript monta o URL do pedido a partir das respetivas partes:

var req_verb = context.getVariable('request.verb');
var req_scheme = context.getVariable('client.scheme');
var req_host = context.getVariable('request.header.host');
var req_request_uri = context.getVariable('request.uri');
var req_url = req_scheme + "://" + req_host + req_request_uri;

O resultado da concatenação pode ter o seguinte aspeto:

https://www.example.com/sample

Aceda a mensagens de resposta

Usando as variáveis que se aplicam à mensagem de resposta, as políticas podem aceder aos componentes da mensagem, incluindo o cabeçalho, os parâmetros de consulta e os parâmetros do formulário, o endereço IP de origem, o corpo da mensagem HTTP, etc.

O proxy recebe uma mensagem de resposta e, em seguida, aplica-lhe uma série de políticas, com base em condições avaliadas na resposta, que podem modificar ou transformar a resposta.

As políticas podem examinar as variáveis de resposta e, em seguida, transformar ou rejeitar o pedido com base no conteúdo dessas variáveis. As políticas transformam a resposta definindo as variáveis adequadas, por exemplo, variáveis correspondentes aos cabeçalhos de resposta.

Políticas comuns para aceder a variáveis de fluxo

O Apigee define várias políticas que pode usar para processar os dados de pedidos e respostas. Estas políticas incluem:

• Política AssignMessage: cria ou modifica mensagens de pedidos ou respostas HTTP durante um fluxo de proxy de API. Também cria e preenche novas variáveis de fluxo.
• Política ExtractVariables: extrai conteúdo de mensagens, incluindo cabeçalhos, caminhos de URI, payloads e parâmetros de consulta, para utilização numa declaração de condição. Em seguida, a política aplica um padrão de texto ao conteúdo da mensagem e, quando encontra uma correspondência, define uma variável designada.
• Política JSONtoXML e Política XMLtoJSON: Converta mensagens do formato JavaScript Object Notation (JSON) para o formato extensible markup language (XML) ou vice-versa.
• Política JavaCallout, Política JavaScript, Política PythonScript, Política RegularExpressionProtection: estas políticas permitem-lhe escrever um script para aceder a variáveis de fluxo que contêm dados de pedidos e respostas.