Referência de condições

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

Veja a documentação do Apigee Edge.

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

Vista geral das condições

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

Estrutura das declarações condicionais

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

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

Por exemplo:

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

Pode combinar condições com AND para aplicar mais do que uma de cada vez. Por exemplo, as seguintes condições são avaliadas como true apenas se o URI do pedido corresponder a /statuses e o verbo HTTP do pedido for GET:

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

Onde pode usar declarações condicionais

Pode usar condições para controlar o comportamento no seguinte:

Execução de políticas

Ao usar declarações condicionais, pode controlar a aplicação de políticas. Um exemplo de utilização comum é a transformação condicional de mensagens de resposta, com base no cabeçalho HTTP ou no conteúdo da mensagem.

O exemplo seguinte transforma condicionalmente XML em JSON com base no cabeçalho Accept:

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

Execução do fluxo

Através de declarações condicionais, pode controlar a execução de fluxos com nome em ProxyEndpoints e TargetEndpoints. Tenha em atenção que só é possível executar condicionalmente fluxos denominados. Os preflows e os postflows (tanto o pedido como a resposta) em ProxyEndpoints e TargetEndpoints são executados para todas as transações e, por isso, oferecem capacidades de segurança incondicionais.

Por exemplo, para executar um fluxo de pedidos condicional com base no verbo HTTP da mensagem de pedido e um fluxo de respostas condicional com base num (potencial) código de estado HTTP que represente 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 trajeto do ponto final de destino

Através de declarações condicionais, pode controlar o ponto final de destino invocado pela configuração do ponto final do proxy. Uma regra de encaminhamento encaminha um pedido para um ponto final de destino específico. Quando estiver disponível mais do que um ponto final de destino, a regra de encaminhamento é avaliada quanto à respetiva condição e, se for verdadeira, o pedido é encaminhado para o ponto final de destino com o nome indicado.

Por exemplo, para encaminhar condicionalmente mensagens para pontos finais 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 as variáveis de fluxo e as condições para mais informações.

Expressões de caminho

As expressões de caminho são usadas para fazer corresponder caminhos de URI, usando * para representar um único elemento de caminho e ** para representar vários níveis de URI. As chavetas {name} também podem ser usadas para corresponder a um único elemento do caminho e dar clareza ao leitor. A variável name só é usada para esclarecimento e não preenche o valor correspondente numa variável de fluxo.

Por 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/{reader}/feed/ /x/a/b/feed/ ou /y/a/foo/feed/
/a/**/feed/** /a/b/feed/rss/1234

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

Variáveis

Pode usar variáveis de fluxo integradas e variáveis personalizadas em declarações condicionais. Para mais informações, consulte:

Operadores

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

  • Não é possível usar operadores como nomes de variáveis.
  • É necessário um espaço antes e depois de um operador.
  • Para incluir um operador numa variável, o nome da variável tem de estar entre aspas simples. Por exemplo, 'request.header.help!me'.
  • Os operadores aritméticos (+ * - / %) não são suportados.
  • A precedência do Java é usada para operadores.
  • O Apigee baseia-se em expressões regulares implementadas em java.util.regex.

A tabela seguinte indica os operadores suportados. Pode usar o símbolo ou a palavra nas suas expressões:

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

Corresponde a uma expressão regular compatível com javax.util.regex. A correspondência é sensível a maiúsculas e minúsculas. Para ver exemplos, consulte Correspondência de padrões.
~ Matches, Like Corresponde a um padrão de estilo glob que usa o caráter universal *. A correspondência é sensível a maiúsculas e minúsculas. Para ver exemplos, consulte Correspondência de padrões.
~/ MatchesPath, LikePath Corresponde a uma expressão de caminho. A correspondência é sensível a maiúsculas e minúsculas. Para ver exemplos, consulte Correspondência de padrões.
=| StartsWith Corresponde aos primeiros carateres de uma string. A correspondência é sensível a maiúsculas e minúsculas.

Operandos

O Apigee adapta os operandos a um tipo de dados comum antes de os comparar. Por exemplo, se o código de estado da resposta for 404, a expressão response.status.code = "400" e o response.status.code = 400 são equivalentes.

Para operandos numéricos, o tipo de dados é interpretado como número inteiro, a menos que o valor termine 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)

Nestes casos, o sistema faz adaptações apresentadas na tabela seguinte (em que RHS se refere ao lado direito da equação e LHS é o lado esquerdo):

RHS LHS Booleano Número inteiro Longo Flutuante Duplo String Comparável Objeto
Booleano Booleano Número inteiro Longo Flutuante Duplo String -
Número inteiro Número inteiro Número inteiro Longo Flutuante Duplo String Comparável -
Longo Longo Longo Longo Flutuante Duplo String Comparável -
Flutuante Flutuante Flutuante Flutuante 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 seguinte 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 apresentado:

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

Literals

Além de literais de strings e numéricos, pode usar os seguintes literais em declarações condicionais:

  • null
  • true
  • false

Por 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>