Cette page s'applique à Apigee et à Apigee hybrid.
Consultez la documentation d'Apigee Edge.
Les flux sont les composants de base des proxys d'API. Les flux vous permettent de programmer le comportement d'une API en vous permettant de configurer la séquence dans laquelle les stratégies et le code sont exécutés par un proxy d'API.
Les flux sont des étapes séquentielles le long du chemin de traitement des requêtes API. Lorsque vous ajoutez une logique de proxy, telle que pour valider une clé API, vous l'ajoutez en tant qu'étape dans la séquence spécifiée par un flux. Lorsque vous définissez une condition pour indiquer si et quand une logique est exécutée, vous ajoutez la condition à un flux.
L'exemple de configuration de flux suivant définit un flux dans lequel la stratégie VerifyAPIKey s'exécute si le chemin de la requête entrante se termine par / et que le verbe HTTP de la requête est GET.
<Flow name="Get Food Carts">
<Description>Get Food Carts</Description>
<Request>
<Step>
<Name>Verify-API-Key</Name>
</Step>
</Request>
<Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>
La valeur Verify-API-Key dans l'élément <Name> du flux permet d'inclure une stratégie configurée ailleurs dans le proxy avec XML, comme suit :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
<DisplayName>Verify API Key</DisplayName>
<Properties/>
<APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>
Concevoir une séquence d'exécution de flux
En structurant les flux, vous pouvez exécuter la logique dans l'ordre approprié le long du chemin de traitement.
Lorsque vous décidez où ajouter la logique, vous devez d'abord choisir de l'ajouter à un point de terminaison de proxy ou à un point de terminaison cible. Un proxy d'API divise son code entre le code qui interagit avec le client du proxy (point de terminaison du proxy) et le code facultatif qui interagit avec la cible backend du proxy, le cas échéant (point de terminaison cible).
Les deux points de terminaison contiennent des flux, comme décrit ici :
| Type de point de terminaison | Description | Flux compatibles |
|---|---|---|
| ProxyEndpoint | Contient les flux de proxy d'API les plus proches du client. Elle fournit des emplacements pour lesquels la logique agit en premier lieu sur la requête du client, puis en dernier à la réponse au client. | PreFlow, conditional flows, PostFlow, PostClientFlow |
| TargetEndpoint | Il contient les flux de proxy d'API les plus proches de la ressource backend. Fournit des emplacements pour la logique afin de préparer une requête, puis pour traiter la réponse d'une ressource backend. | PreFlow, conditional flows, PostFlow |
Vous configurez un flux avec XML qui spécifie ce qui doit se passer et dans quel ordre. L'illustration suivante montre comment les flux sont organisés de manière séquentielle dans un point de terminaison de proxy et un point de terminaison cible :
Le point de terminaison de proxy et le point de terminaison cible contiennent chacun des flux que vous pouvez organiser dans l'ordre suivant :
| Poste | Type de flux | Description |
|---|---|---|
| 1 | PreFlow |
Utile lorsque vous devez vous assurer qu'un code spécifique s'exécute avant tout autre événement. Si le flux PreFlow se trouve dans un point de terminaison cible, il s'exécute après le flux PostFlow du point de terminaison de proxy. |
| 2 | Flux conditionnel |
L'emplacement de la logique conditionnelle. S'exécute après le pré-flux et avant le postFlow. Un seul flux conditionnel est exécuté par segment : le premier flux dont la condition renvoie la valeur "true". Cela signifie que vous pouvez exécuter un flux conditionnel dans chacun des éléments suivants :
|
| 3 | PostFlow |
Il s'agit d'un bon emplacement pour enregistrer des données, envoyer une notification indiquant un événement survenu lors du traitement de la requête, etc. S'exécute après des flux conditionnels et un PreFlow. Si le flux PostFlow se trouve dans un point de terminaison de proxy et qu'il existe un point de terminaison cible, le point de terminaison de proxy s'exécute avant le flux PreFlow du point de terminaison cible. |
| 4 | PostClientFlow (flux proxy uniquement) | Flux de journalisation des messages après le renvoi d'une réponse au client. |
Exécution du code en premier avec un PreFlow
Un flux PreFlow est utile lorsque vous devez vous assurer qu'un code spécifique s'exécute avant tout autre événement.
Dans un point de terminaison de proxy, un flux PreFlow est un excellent emplacement pour le code qui authentifie un client et limite le trafic des clients. Dans un point de terminaison cible, qui commence à préparer l'envoi d'une requête à une cible de backend, un flux PreFlow convient pour les premières étapes de la préparation de l'envoi de la requête.
Par exemple, vous n'avez généralement pas besoin de servir un client qui a dépassé son quota. Pour répondre à ces exigences, vous allez placer des règles de sécurité et de quotas dans le segment PreFlow. Ainsi, vous n'avez pas à vous soucier d'une condition qui ne sera pas évaluée dans un flux conditionnel ultérieur. Les règles de ce flux sont toujours exécutées avant tout autre processus.
Dans l'exemple suivant, les règles SpikeArrest et de Quota s'exécutent avant le traitement des flux conditionnels.
<PreFlow name="MyPreFlow">
<Request>
<Step>
<Name>Spike-Arrest</Name>
</Step>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Response/>
</PreFlow>
Exécution du code de manière conditionnelle avec un flux conditionnel
Entre un PreFlow et un PostFlow, vous disposez de flux qui s'exécutent de manière conditionnelle. Cela vous donne la possibilité de configurer plusieurs séquences de logique, mais une seule exécution est basée sur l'état de votre proxy. Un flux conditionnel est facultatif si vous pouvez exécuter toutes les logiques dans PreFlow ou PostFlow, et si aucune condition n'est requise (en d'autres termes, un seul chemin d'accès via le point de terminaison est compatible).
Chaque flux spécifie une condition qui teste différentes valeurs d'état. Cela permet une exécution efficace en fonction des conditions. Par exemple, vous souhaiterez peut-être ne pouvoir convertir un fichier XML au format JSON que lorsque l'application à l'origine de la requête s'exécute sur un appareil mobile.
Ici, les contraintes de quota ne sont appliquées que si la requête est une requête GET dotée d'un format d'URI /issue/** (/issue/ avec une valeur de l'URI après la dernière barre oblique).
<Flow name="MyFlow">
<Description/>
<Request>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Response/>
<Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>
Vous devez utiliser des variables de flux pour spécifier des conditions. Pour en savoir plus sur l'utilisation de variables dans les conditions, consultez la page Conditions avec variables de flux.
Pour voir des exemples d'utilisation de la correspondance de modèles dans des conditions, consultez la section Correspondance de modèles.
Exécuter du code après une logique de base avec un PostFlow
Un flux PostFlow est un excellent emplacement pour effectuer des actions après la logique de base de votre point de terminaison et avant la fin du traitement du point de terminaison. Un flux PostFlow s'exécute après les flux conditionnels et PreFlow.
Un flux PostFlow est un bon emplacement pour enregistrer certaines données, envoyer une notification en cas de problème, transformer le format du message de réponse, etc.
Dans l'exemple suivant, une stratégie AssignMessage appelée SetResponseHeaders définit les en-têtes du message de réponse avant qu'Apigee renvoie la réponse au client.
<PostFlow>
<Response>
<Step>
<Name>SetResponseHeaders</Name>
</Step>
</Response>
</PostFlow>
Exécuter du code après que le client a reçu votre réponse de proxy avec un PostClientFlow
Un PostClientFlow ne peut inclure que les règles suivantes. Aucune autre règle ne peut être utilisée dans un PostClientFlow :
* La règle FlowCallout ne peut appeler que des flux partagés qui répondent eux-mêmes aux critères permettant d'être dans PostClientFlow (par exemple, ne contenir que des stratégies compatibles).
Si vous en incluez une, le flux PostClientFlow serait le dernier flux à exécuter, après l'envoi d'une réponse au client.
Un PostClientFlow convient pour la journalisation finale. Vous pouvez également consigner les horodatages de début et de fin du message de réponse.
Voici un exemple de flux PostClientFlow avec une stratégie MessageLogging.
<ProxyEndpoint name="endpoint1">
...
<PostFlow name="PostFlow">
<Request/>
<Response/>
</PostFlow>
<PostClientFlow>
<Response>
<Step>
<Name>Message-Logging-1</Name>
</Step>
</Response>
</PostClientFlow>
...
</ProxyEndpoint>
Pour plus d'informations, consultez la documentation de référence sur la configuration des proxys d'API.
Ajouter une logique aux flux
Lorsque vous ajoutez une logique à votre proxy, vous le faites en ajoutant des stratégies aux flux de votre proxy. Comme les flux s'exécutent dans une séquence (PreFlow, Flow puis PostFlow, comme décrit dans cette rubrique), le contenu d'un flux s'exécute dans une séquence.
L'exemple de configuration de flux suivant fait référence à trois stratégies (configurées ailleurs dans leurs propres fichiers XML). La stratégie référencée par Verify-API-Key s'exécute avant la stratégie référencée par Assign-Message. Elles sont toutes deux suivies de la stratégie représentée par Quota.
<Flow name="Get Food Cart Menus">
<Description>Get Food Cart Menus</Description>
<Request>
<Step>
<Name>Verify-API-Key</Name>
</Step>
<Step>
<Name>Assign-Message</Name>
</Step>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>
Flux de débogage
L'outil Debug fournit un moyen graphique de voir comment la logique de votre proxy d'API s'exécute suite à une requête. Cet outil illustre le traitement entre les requêtes et les réponses. Elle n'illustre pas précisément la séparation entre PreFlow, les flux conditionnels et PostFlow.
Pour en savoir plus sur le débogage des proxys, consultez la page Utiliser l'outil Debug.
Gérer les erreurs dans les flux
Vous pouvez générer des pannes à partir de différentes sources dans un proxy d'API, y compris à partir de flux.
L'exemple suivant est le stanza de la réponse d'un flux PreFlow dans un point de terminaison cible. En d'autres termes, il s'agit du code qui s'exécute immédiatement après réception de la réponse d'une cible de backend.
Dans cet exemple, une erreur est générée si la réponse de la cible n'est pas 200 (succès).
<PreFlow name="PreFlow">
<Response>
<Step>
<Name>RaiseFault</Name>
<Condition>(response.status.code GreaterThan "200")</Condition>
</Step>
</Response>
</PreFlow>
Pour en savoir plus sur la gestion des erreurs, consultez la page Gérer les pannes.