Referência das condições

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

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

Visão geral das condições

Nesta seção, descrevemos como e onde usar instruções condicionais com o Edge. 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>

Você pode 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 as instruções condicionais, você pode controlar a execução de fluxos nomeados em ProxyEndpoints e TargetEndpoints. Observe que apenas fluxos "nomeados" podem ser executados condicionalmente. Os pré-fluxos e pós-fluxos, tanto a solicitação quanto a resposta, em ProxyEndpoints e TargetEndpoints são executados em cada transação e, portanto, fornecem recursos "failsafe" incondicionais.

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.
  • O Apigee Edge depende de expressões regulares implementadas no java.util.regex:

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

Symbol 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 interface do Edge, convertido para >.
>= ou &gt;= GreaterThanOrEquals Maior ou igual. Se você usar >= ao definir a condição na interface do Edge, ela é convertida em &gt;=.
&lt; LesserThan Menor que. A interface do Edge não é compatível com o "<" literal.
&lt;= LesserThanOrEquals Menor que ou igual a. A interface do Edge 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 ver exemplos, consulte Correspondência de padrões em instruções condicionais.
~ 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 com condicionais.
~/ 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 com condicionais.
=| StartsWith Corresponde aos primeiros caracteres de uma string. A correspondência diferencia maiúsculas de minúsculas.

Operandos

O Apigee Edge adapta 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" (flutuante, por exemplo, 3.142f, 91.1F)
  • "d" ou "D" (duplo, por exemplo, 3.142d, 100.123D)
  • "l" ou "L" (longo, 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 Booleanos Inteiro Longo Float Dobro String Comparável Objeto
Booleanos Booleanos Inteiro Longo Float Dobro String -
Inteiro Inteiro Inteiro Longo Float Dobro String Comparável -
Longo Longo Longo Longo Float Dobro String Comparável -
Float Float Float Float Float Dobro String Comparável -
Dobro Dobro Dobro Dobro Dobro Dobro 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>