Variáveis de solicitação e resposta

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

Confira a documentação da Apigee Edge.

Ao fazer uma solicitação a um proxy de API, você pode passar qualquer uma ou todas as informações a seguir, dependendo da configuração do proxy da API:

• Cabeçalhos de solicitação
• Parâmetros de consulta
• Dados do formulário
• Payloads XML ou JSON
• URIs de recurso

Por padrão, todos os dados em uma solicitação inalterada são transmitidos do ProxyEndpoint para o TargetEndpoint. Portanto, quando o TargetEndpoint faz a solicitação ao servidor de back-end, todas as informações na solicitação original são passadas para o serviço de back-end.

O mesmo acontece com a resposta recebida pelo serviço de back-end pela Apigee. Por padrão, todos os dados recebidos na resposta são passados inalterados para o aplicativo que originou a solicitação.

Como os dados da solicitação são transmitidos para o servidor de back-end?

A imagem a seguir mostra uma definição de proxy da API:

Para este proxy de API:

• Host virtual de proxy da API: default
• Domínio definido pelos nomes de host no grupo de ambiente: http://www.example.com
• Caminho base de proxy: /v1/weather
• TargetEndpoint especificado pela regra de rota: default
• URL de destino: http://weather.yahooapis.com

Um app cliente faz uma solicitação GET ao proxy da API usando o seguinte comando curl:

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

Essa solicitação contém o recurso forecastrss e um parâmetro de consulta, w. A Apigee analisa a solicitação conforme mostrado abaixo e atribui partes da solicitação às 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

Observação: há muitas variáveis de fluxo diferentes criadas durante o processamento de uma solicitação e uma resposta. Consulte Referência de variáveis de fluxo para mais informações.

O TargetEndpoint faz uma solicitação ao serviço de back-end usando informações da solicitação:

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

Observe como os parâmetros de recurso e consulta especificados na solicitação são incluídos automaticamente na solicitação para o servidor de back-end. A partir da definição do TargetEndpoint, a solicitação tem o formulário:

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

Assim como os parâmetros de consulta, todos os cabeçalhos ou parâmetros de formulário incluídos na solicitação ao proxy da API são transmitidos ao servidor de back-end. Por exemplo, você faz a solicitação abaixo que inclui um cabeçalho:

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

Ou solicite uma solicitação no formulário abaixo para incluir um cabeçalho e dados de formulários:

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

Nos dois exemplos, os cabeçalhos e os dados do formulário são transmitidos inalterados ao 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 de formulário são representados por variáveis de fluxo, como request.formparam.count e request.formparam.names.

Como os dados de resposta são retornados?

Por padrão, todos os dados recebidos da Apigee a partir do serviço de back-end na resposta são passados inalterados para o aplicativo que originou a solicitação. Conforme descrito acima para a solicitação, os dados retornados na resposta podem ser acessados por meio de variáveis de fluxo na Apigee. Para mais informações, consulte a referência das variáveis de fluxo.

Acessar dados de solicitação e resposta em um proxy de API

Há muitas vezes em que você quer modificar os dados da solicitação antes de enviá-los ao servidor de back-end. Exemplo:

• Para remover informações de segurança usadas pela Apigee para validar solicitações. Essas informações não são exigidas pelo serviço de back-end.
• Para adicionar dados enviados ao serviço de back-end, por exemplo, para rastrear usuários ou coletar análises.
• Para processar a solicitação condicionalmente com base nos dados da solicitação. Por exemplo, um proxy de API pode ter vários TargetEndpoints. O TargetEndpoint usado pela solicitação é determinado pelos dados da solicitação. Em seguida, você remove esses dados da solicitação antes de enviá-los ao serviço de back-end.

O mesmo vale para os dados na resposta. Como parte do processamento da resposta, o proxy da API pode querer modificar os dados antes de retorná-los ao aplicativo solicitante.

Acessar mensagens de solicitação

Você pode usar políticas para acessar e alterar partes de uma mensagem de solicitação. Essas partes incluem:

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

Em um fluxo normal, depois que a solicitação é processada, o proxy envia a solicitação transformada para o destino.

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

Dica: é possível usar variáveis para reconstruir o URL de solicitação de entrada. Por exemplo, o código a seguir em uma política JavaScript monta o URL da solicitação das 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 ser semelhante ao seguinte:

https://www.example.com/sample

Acessar mensagens de resposta

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

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

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

Políticas comuns para acessar variáveis de fluxo

A Apigee define várias políticas que podem ser usadas para processar os dados de solicitação e resposta. As políticas incluem o seguinte:

• Política AssignMessage: cria ou modifica mensagens de solicitação ou resposta HTTP durante um fluxo de proxy da 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 uso em uma instrução de condição. A política aplica um padrão de texto ao conteúdo da mensagem e, ao encontrar uma correspondência, define uma variável designada.
• Política JSONtoXML e política XMLtoJSON: converte mensagens do JavaScript Object Notation (JSON) no formato de linguagem de marcação extensível (XML) ou vice-versa.
• Política JavaCallout, política JavaScript, PythonScript, Política RegularExpressionProtection: essas políticas permitem escrever um script. para acessar variáveis de fluxo que contêm dados de solicitação e resposta.