Referência das condições

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

Confira a documentação da Apigee Edge.

As condições permitem que os proxies de API se comportem dinamicamente no ambiente de execução. As condições definem operações em variáveis, que são avaliadas pelo pipeline de processamento da Apigee. Instruções condicionais são booleanas e sempre são avaliadas como true ou false.

Visão geral das condições

Esta seção descreve como e onde usar as instruções condicionais com a Apigee. Além disso, as seguintes seções descrevem a sintaxe:

• Operadores
• Operandos
• Literais

Estrutura das instruções condicionais

A estrutura básica de uma instrução condicional é:

<Condition>variable.name operator "value"</Condition>

Exemplo:

<Condition>request.verb = "GET"</Condition>

É possível combinar condições com AND para aplicar mais de uma por vez. Por exemplo, as condições a seguir serão avaliadas como true somente se o URI da solicitação corresponder a /statuses e o verbo HTTP da solicitação for GET:

<Condition>(proxy.pathsuffix MatchesPath "/statuses") and (request.verb = "GET")</Condition>

Onde usar as instruções condicionais

Você pode usar condições para controlar o comportamento em:

• Execução de política
• Execução de fluxo
• Seleção de rota do endpoint de destino

Execução de política

Com as instruções condicionais, você pode controlar a aplicação das políticas. Um caso de uso comum é a transformação condicional de mensagens de resposta, com base no cabeçalho HTTP ou no conteúdo da mensagem.

O exemplo a seguir transforma o XML em JSON com base no cabeçalho Accept de maneira condicional:

<Step>
  <Condition>request.header.accept = "application/json"</Condition>
  <Name>XMLToJSON</Name>
</Step>

Execução de fluxo

Usando instruções condicionais, é possível controlar a execução de fluxos nomeados em ProxyEndpoints e TargetEndpoints. Observe que apenas fluxos nomeados podem ser executados condicionalmente. Pré-fluxos e pós-fluxos, tanto a solicitação quanto a resposta, em ProxyEndpoints e TargetEndpoints, são executados para cada transação e, assim, fornecem recursos failsafe com falha.

Por exemplo, para executar um fluxo de solicitação condicional com base no verbo HTTP da mensagem de solicitação e um fluxo de resposta condicional com base em um código de status HTTP (potencial) que representa um erro:

<Flow name="GetRequests">
  <Condition>request.verb = "GET"</Condition>
  <Request>
    <Step>
      <Condition>request.path MatchesPath "/statuses/**"</Condition>
      <Name>StatusesRequestPolicy</Name>
    </Step>
  </Request>
  <Response>
    <Step>
      <Condition>(response.status.code = 503) or (response.status.code = 400)</Condition>
      <Name>MaintenancePolicy</Name>
    </Step>
  </Response>
</Flow>

Seleção de rota do endpoint de destino

Com as instruções condicionais, você pode controlar o endpoint de destino invocado pela configuração do endpoint de proxy. Uma regra de rota encaminha uma solicitação para um endpoint de destino específico. Quando mais de um endpoint de destino está disponível, a regra de rota é avaliada para sua condição e, se for verdadeira, a solicitação será encaminhada para o endpoint de destino nomeado.

Por exemplo, para rotear condicionalmente as mensagens para endpoints de destino designados com base em Content-Type:

<RouteRule name="default">
 <!--this routing executes if the header indicates that this is an XML call. If true, the call is routed to the endpoint XMLTargetEndpoint-->
  <Condition>request.header.Content-Type = "text/xml"</Condition>
  <TargetEndpoint>XmlTargetEndpoint</TargetEndpoint>
</RouteRule>

Consulte Variáveis e condições de fluxo para mais informações.

Expressões de caminho

As expressões de caminho são usadas para corresponder caminhos de URI, usando * para representar um único elemento de caminho e ** para representar vários níveis de URI.

Exemplo:

% é tratado como um caractere de escape. O padrão %{user%} corresponde a {user}, mas não a user.

Variáveis

É possível usar ambas as variáveis de fluxo integradas e personalizadas nas instruções condicionais. Veja mais informações em:

• Referência das variáveis de fluxo: uma lista completa das variáveis integradas
• Política ExtractVariables: instruções sobre como definir variáveis personalizadas

Operadores

Ao usar operadores, observe as seguintes restrições:

• Não é possível usar os operadores como nomes de variáveis.
• Um caractere de espaço é necessário antes e depois de um operador.
• Para incluir um operador em uma variável, um nome de variável precisa ser colocado entre aspas simples. Por exemplo, 'request.header.help!me'
• Operadores aritméticos (+ * - / %) não são aceitos.
• A prioridade de Java é usada para operadores.
• A Apigee depende de expressões regulares conforme implementado em java.util.regex.

A tabela a seguir lista os operadores compatíveis. É possível usar o símbolo ou a palavra nas expressões:

Operandos

A Apigee adapta os operandos a um tipo de dados comum antes de compará-los. Por exemplo, se o código de status de resposta for 404, as expressões response.status.code = "400" e response.status.code = 400 serão equivalentes.

Para operandos numéricos, o tipo de dados é interpretado como inteiro, a menos que o valor seja encerrado da seguinte forma:

• f ou F (float, por exemplo, 3.142f, 91.1F)
• d ou D (double, por exemplo, 3.142d, 100.123D)
• l ou L (long, por exemplo, 12321421312L)

Nesses casos, o sistema realiza adaptações mostradas na tabela a seguir, em que o RHS se refere ao lado direito da equação e o LHS é o lado esquerdo:

Operandos nulos

A tabela a seguir mostra se as condições são avaliadas como true ou false quando os valores são nulos no lado esquerdo (LHS) e/ou no lado direito (RHS) do operando mostrado:

Literais

Além dos literais de string e numéricos, é possível usar os seguintes literais nas instruções condicionais:

• null
• true
• false

Exemplo:

• request.header.host is null
• flow.cachehit is true

Exemplos

<RouteRule name="default">
     <Condition>request.header.content-type = "text/xml"</Condition>
     <TargetEndpoint>XmlTargetEndpoint</TargetEndpoint>
</RouteRule>

<Step>
    <Condition>response.status.code = 503</Condition>
    <Name>MaintenancePolicy</Name>
</Step>

<Flow name="GetRequests">
    <Condition>response.verb="GET"</Condition>
    <Request>
        <Step>
            <Condition>request.path ~ "/statuses/**"</Condition>
            <Name>StatusesRequestPolicy</Name>
        </Step>
    </Request>
    <Response>
        <Step>
            <Condition>(response.status.code = 503) or (response.status.code = 400)</Condition>
            <Name>MaintenancePolicy</Name>
        </Step>
    </Response>
</Flow>