Documentation de référence sur les conditions

Vous consultez la documentation d'Apigee X.
Consultez la documentation d'Apigee Edge.

Les conditions permettent aux proxys d'API d'agir de manière dynamique lors de l'exécution. Les conditions définissent des opérations sur les variables, qui sont évaluées par le pipeline de traitement Apigee. Les instructions conditionnelles sont des valeurs booléennes, et correspondent toujours à true ou false.

Présentation des conditions

Cette section décrit comment et dans quels cas utiliser les instructions conditionnelles avec Apigee. En outre, les sections suivantes décrivent la syntaxe :

Structure des instructions conditionnelles

La structure de base d'une instruction conditionnelle est la suivante :

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

Exemple :

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

Vous pouvez combiner des conditions avec AND pour appliquer plusieurs conditions à la fois. Par exemple, les conditions suivantes ne renvoient true que si l'URI de la requête correspond à /statuses et si le verbe HTTP de la requête est GET :

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

Cas d'utilisation des instructions conditionnelles

Les conditions vous permettent de contrôler le comportement des éléments suivants :

Exécution d'une règle

Vous pouvez contrôler l'application des règles à l'aide d'instructions conditionnelles. Un cas d'utilisation courant consiste à transformer de manière conditionnelle les messages de réponses en fonction de l'en-tête HTTP ou du contenu du message.

L'exemple suivant transforme de manière conditionnelle le code XML en JSON en fonction de l'en-tête Accept :

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

Exécution d'un flux

Vous pouvez contrôler l'exécution des flux nommés dans ProxyEndpoints et TargetEndpoints à l'aide d'instructions conditionnelles. Notez que seuls les flux nommés peuvent être exécutés de manière conditionnelle. Les flux Preflow et Postflow (requête et réponse) dans ProxyEndpoints et TargetEndpoints s'exécutent pour chaque transaction, et fournissent ainsi des fonctionnalités de sécurité intégrée inconditionnelles.

Par exemple, pour exécuter un flux de requête conditionnel basé sur le verbe HTTP du message de requête et un flux de réponse conditionnel basé sur un code d'état HTTP (potentiel) représentant une erreur, saisissez le code suivant :

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

Sélection de la route d'un point de terminaison cible

Vous pouvez contrôler le point de terminaison cible appelé par la configuration du point de terminaison du proxy à l'aide d'instructions conditionnelles. Une règle de routage transfère une requête vers un point de terminaison cible particulier. Lorsque plusieurs points de terminaison cibles sont disponibles, la règle de routage est évaluée pour sa condition et, si la valeur est "true", la requête est transmise au point de terminaison cible nommé.

Par exemple, pour acheminer de manière conditionnelle les messages vers les points de terminaison cibles en fonction de Content-Type, procédez comme suit :

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

Pour en savoir plus, consultez la page Variables de flux et conditions.

Expressions de chemin d'accès

Les expressions de chemin d'accès permettent d'établir une correspondance avec les chemins d'URI, en utilisant * pour représenter un seul élément de chemin et ** pour représenter plusieurs niveaux d'URI.

Exemple :

Format Exemples de chemins d'URI correspondants
/*/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

% est traité comme un caractère d'échappement. Le modèle %{user%} correspond à {user}, mais pas à user.

Variables

Vous pouvez utiliser des variables de flux intégrées et des variables personnalisées dans les instructions conditionnelles. Pour en savoir plus, consultez les pages suivantes :

Opérateurs

Lorsque vous utilisez des opérateurs, respectez les restrictions suivantes :

  • Les opérateurs ne peuvent pas être utilisés comme noms de variables.
  • Un espace est requis avant et après un opérateur.
  • Pour inclure un opérateur dans une variable, le nom de cette variable doit être placé entre guillemets simples. Par exemple, 'request.header.help!me'.
  • Les opérateurs arithmétiques (+ * - / %) ne sont pas acceptés.
  • La priorité Java est utilisée pour les opérateurs.
  • Apigee s'appuie sur des expressions régulières telles qu'elles sont décrites dans java.util.regex.

Le tableau suivant répertorie les opérateurs acceptés. Vous pouvez utiliser le symbole ou le mot dans vos expressions :

Symbole Éléments textuels Description
! Not, not Opérateur unaire (une seule entrée)
= Equals, Is Égal à (sensible à la casse)
!= NotEquals, IsNot Différent de (sensible à la casse)
:= EqualsCaseInsensitive Égal à, mais non sensible à la casse
> ou &gt; GreaterThan Supérieur à Si vous utilisez le signe ">" lors de la définition de la condition dans l'interface utilisateur d'Apigee, il est converti en &gt;.
>= ou &gt;= GreaterThanOrEquals Supérieur ou égal à Si vous utilisez le symbole ">=" lors de la définition de la condition dans l'interface utilisateur d'Apigee, il est converti en &gt;=.
&lt; LesserThan Inférieur à. L'interface utilisateur d'Apigee n'accepte pas le littéral <.
&lt;= LesserThanOrEquals Inférieur ou égal à. L'interface utilisateur d'Apigee n'accepte pas le littéral <=.
&& And and Et
|| Or Ou
() Regroupe une expression. ( ouvre l'expression et ) la ferme.
~~ JavaRegex

Correspond à une expression régulière conforme à javax.util.regex. La correspondance est sensible à la casse. Pour obtenir des exemples, consultez la page Mise en correspondance de modèles.

~ Matches, Like Met en correspondance un modèle de style glob à l'aide du caractère générique *. La correspondance est sensible à la casse. Pour obtenir des exemples, consultez la page Mise en correspondance de modèles.
~/ MatchesPath, LikePath Correspond à une expression de chemin d'accès. La correspondance est sensible à la casse. Pour obtenir des exemples, consultez la page Mise en correspondance de modèles.
=| StartsWith Correspond aux premiers caractères d'une chaîne. La correspondance est sensible à la casse.

Opérandes

Apigee adapte les opérandes à un type de données courant avant de les comparer. Par exemple, si le code d'état de la réponse est 404, les expressions response.status.code = "400" et response.status.code = 400 sont équivalentes.

Pour les opérandes numériques, le type de données est interprété comme un entier, sauf si la valeur se termine comme suit :

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

Dans ces cas, le système effectue les adaptations répertoriées dans le tableau suivant (dans lequel RHS désigne la partie droite de l'équation et LHS la partie gauche) :

RHS LHS Booléen Entier Long Float Double Chaîne Comparable Objet
Booléen Booléen Entier Long Float Double Chaîne -
Entier Entier Entier Long Float Double Chaîne Comparable -
Long Long Long Long Float Double Chaîne Comparable -
Float Float Float Float Float Double Chaîne Comparable -
Double Double Double Double Double Double Chaîne Comparable -
Chaîne Chaîne Chaîne Chaîne Chaîne Chaîne Chaîne Comparable -
Comparable Comparable Comparable Comparable Comparable Comparable Comparable Comparable -
Objet - - - - - - - -

Opérandes nuls

Le tableau suivant indique si les conditions renvoient true ou false lorsque des valeurs sont nulles sur le côté gauche (LSH) et/ou sur le côté droit (RHS) de l'opérande affiché :

Opérateur LHS nul RHS nul LHS et RHS nuls
=, ==, := false false vrai
=| false false false
!= vrai vrai false
> ou &gt; vrai false false
>= ou &gt;= false vrai vrai
&lt; vrai false false
&lt;= vrai false vrai
~ false N/A false
~~ false N/A false
!~ vrai false false
~/ false N/A false

Littéraux

En plus des littéraux de chaîne et numériques, vous pouvez utiliser les littéraux suivants dans les instructions conditionnelles :

  • null
  • true
  • false

Exemple :

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

Exemples

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