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:

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

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:

Padrão Exemplos de caminhos de URI correspondentes
/*/a/ /x/a/ ou /y/a/
/*/a/* /x/a/b ou /y/a/foo
/*/a/** /x/a/b/c/d
/*/a/*/feed/ /x/a/b/feed/ ou /y/a/foo/feed/
/a/**/feed/** /a/b/feed/rss/1234

% é 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:

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:

Símbolo Word Descrição
! Not, not Operador unário (usa uma única entrada)
= Equals, Is Igual a (diferencia maiúsculas de minúsculas)
!= NotEquals, IsNot Diferente de (diferencia maiúsculas de minúsculas)
:= EqualsCaseInsensitive Igual a, mas não diferencia maiúsculas de minúsculas
> ou &gt; GreaterThan Maior que Se você usar > ao definir a condição na IU da Apigee, ele será convertido em &gt;.
>= ou &gt;= GreaterThanOrEquals Maior que ou igual a Se você usar >= ao definir a condição na IU da Apigee, ele será convertido em &gt;=.
&lt; LesserThan Menor que. A IU da Apigee não é compatível com o literal <.
&lt;= LesserThanOrEquals Menor que ou igual a. A IU da Apigee não é compatível com o literal <=.
&& And, and E
|| Or O operador Ou não diferencia maiúsculas de minúsculas. Por exemplo, OR, Or e or são válidos.
() Agrupa uma expressão. O ( abre a expressão e o ) a fecha.
~~ JavaRegex

Corresponde a uma expressão regular compatível com javax.util.regex. A correspondência diferencia maiúsculas de minúsculas. Para exemplos, consulte Correspondência de padrões.
~ Matches, Like Corresponde a um padrão de estilo glob usando o caractere curinga *. A correspondência diferencia maiúsculas de minúsculas. Para exemplos, consulte Correspondência de padrões.
~/ MatchesPath, LikePath Corresponde a uma expressão de caminho. A correspondência diferencia maiúsculas de minúsculas. Para exemplos, consulte Correspondência de padrões.
=| StartsWith Corresponde aos primeiros caracteres de uma string. A correspondência diferencia maiúsculas de minúsculas.

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:

RHS LHS Booleano Número inteiro Longo Ponto flutuante Duplo String Comparável Objeto
Booleano Booleano Número inteiro Longo Ponto flutuante Duplo String -
Número inteiro Número inteiro Número inteiro Longo Ponto flutuante Duplo String Comparável -
Longo Longo Longo Longo Ponto flutuante Duplo String Comparável -
Ponto flutuante Ponto flutuante Ponto flutuante Ponto flutuante Ponto flutuante Duplo String Comparável -
Duplo Duplo Duplo Duplo Duplo Duplo String Comparável -
String String String String String String String Comparável -
Comparável Comparável Comparável Comparável Comparável Comparável Comparável Comparável -
Objeto - - - - - - - -

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:

Operador LHS nulo RHS nulo LHS e RHS nulos
=, ==, := false false true
=| false false false
!= true true false
> ou &gt; true false false
>= ou &gt;= false true true
&lt; true false false
&lt;= true false true
~ false N/A false
~~ false N/A false
!~ true false false
~/ false N/A false

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>