Règle FlowCallout

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Utilisez la règle FlowCallout pour appeler un flux partagé à partir d'un proxy d'API ou d'un autre flux partagé.

Dans un flux partagé, vous créez une séquence d'étapes que vous pouvez réutiliser au moment de l'exécution à partir de plusieurs emplacements. Ces étapes sont mises en œuvre en tant que règles, comme dans un proxy d'API. La stratégie FlowCallout vous permet d'appeler le flux partagé à partir des proxys d'API et d'autres flux partagés. Elle fonctionne comme un appel de fonction dans un langage de programmation classique.

• Par exemple, imaginez que vous avez créé un flux partagé avec des fonctionnalités de sécurité telles que la validation de clés API, la validation de jetons OAuth et la protection des expressions régulières. Ce flux partagé représente votre convention de vérification des requêtes entrantes. Les règles FlowCallout vous permettent d'appeler ce flux partagé à partir de plusieurs proxys d'API.
• Vous pouvez appeler un flux partagé à partir d'un autre flux en mettant en œuvre une règle FlowCallout depuis un flux partagé.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Remarque : Pour en savoir plus sur les flux partagés, consultez la section Flux partagés réutilisables. Vous pouvez également appeler un flux partagé à partir d'un code de proxy d'API extérieur pour appliquer le prétraitement des requêtes ou le post-traitement des réponses pour tous les proxys d'API déployés dans un environnement. Pour en savoir plus, consultez la section Associer un flux partagé à l'aide de hooks de flux.

Exemples

Valider la clé API dans un flux partagé

Dans cet exemple, un flux partagé est utilisé pour effectuer des tâches courantes liées à la sécurité. Ici, le flux partagé valide une clé API. Les proxys d'API et d'autres flux partagés peuvent utiliser la règle FlowCallout pour effectuer des appels dans ce flux partagé.

La définition de flux partagé suivante inclut une règle Verify-API-Key qui s'exécute lorsque le flux partagé est appelé à partir d'une règle FlowCallout dans un proxy d'API.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="default">
    <Step>
        <Name>Verify-API-Key</Name>
    </Step>
</SharedFlow>

La règle VerifyAPIKey dans le flux partagé précédent récupère la valeur de la clé et la vérifie.

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

La règle FlowCallout suivante, utilisée dans un proxy d'API, appelle le flux partagé précédent pour vérifier la clé API. Le groupe de flux partagés verify-apikey-shared (non illustré ici) configure le flux partagé de la même manière qu'un groupe APIProxy configure un proxy.

<FlowCallout async="false" continueOnError="false" enabled="true" name="Auth-Flow-Callout">
    <DisplayName>Auth Flow Callout</DisplayName>
    <SharedFlowBundle>verify-apikey-shared</SharedFlowBundle>
</FlowCallout>

Transmettre des paramètres à un flux partagé

Cet exemple montre comment transmettre des paramètres d'une règle FlowCallout à un flux partagé. Ici, une règle FlowCallout appelle un flux partagé conçu pour effectuer des fonctions courantes de traitement de chaînes. Le flux partagé inclut du code JavaScript qui concatène les entrées, ou ne prend pas en compte les entrées. La règle FlowCallout définit les paramètres qui spécifient l'entrée de chaîne, la sortie de chaîne et le traitement qu'il convient d'appliquer à l'entrée.

1. La règle String-Handler FlowCallout appelle le flux partagé, en transmettant des paramètres qui spécifient la variable afin de stocker la sortie du flux partagé, l'opération de flux partagé et l'entrée à utiliser (ici, un littéral de chaîne, mais Il peut également s'agir d'une variable de flux). Les éléments Parameter spécifient les noms et les valeurs des variables pour créer l'environnement d'exécution. Le flux partagé peut récupérer ces variables pour les utiliser dans son propre code.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
     <DisplayName>String Handler</DisplayName>
     <Parameters>
       <Parameter name="input">Gladys Kravitz</Parameter>
       <Parameter name="operations">concatenate tolowercase</Parameter>
       <Parameter name="outputVariable">string.handler.output</Parameter>
     </Parameters>
     <SharedFlowBundle>StringHandler</SharedFlowBundle>
   </FlowCallout>

2. Le flux partagé default suivant inclut une stratégie JavaScript SharedStringFunctions qui s'exécute lorsque le flux partagé est appelé à partir d'une règle FlowCallout.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <SharedFlow name="default">
     <Step>
       <Name>SharedStringFunctions</Name>
     </Step>
   </SharedFlow>

3. Dans le flux partagé, la règle JavaScript SharedStringFunctions suivante spécifie le fichier JavaScript SharedStringFunctions.js avec le code à exécuter.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="SharedStringFunctions">
     <DisplayName>SharedStringFunctions</DisplayName> <Properties/>
     <ResourceURL>jsc://SharedStringFunctions.js</ResourceURL>
   </Javascript>

4. Le code JavaScript suivant, SharedStringFunctions.js, s'exécute à partir de la règle JavaScript SharedStringFunctions. Ce script récupère les valeurs des variables créées à partir des éléments Parameter de la règle FlowCallout.

   // Input value from the calling API proxy.
   var handledString = context.getVariable("input");
   // Variable to use for output from this script.
   var outputVariable = context.getVariable("outputVariable");
   // A space-separated list of things to do to the input string.
   // Convert to lower case to handle unintentional capitals in configuration.
   var operation = context.getVariable("operations").toLowerCase();
   
   // If "lowercase" was given as an operation, convert the input to lowercase.
   if (operation.includes("tolowercase")) {
       handledString = handledString.toLowerCase();
   }
   
   // If "concatenate" was given as an operation, concatenate the input.
   if (operation.includes("concatenate")) {
       handledString = handledString.replace(/\s+/g, '');
   }
   // Assign the resulting string to the output variable specified by
   // the calling API proxy.
   context.setVariable(outputVariable, handledString);

5. L'exécution est renvoyée à partir de la règle JavaScript vers le flux partagé, puis à la règle FlowCallout dans le proxy d'API d'origine.

Documentation de référence des éléments

Voici les éléments et les attributs que vous pouvez configurer sur cette règle :

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <SharedFlowBundle>thereferencedsharedflowbundle</SharedFlowBundle>
</FlowCallout>

Attributs <FlowCallout>

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Attribut	Description	Par défaut	Presence
name	Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.	N/A	Obligatoire
continueOnError	Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir également : Les règles d'erreur sont déclenchées UNIQUEMENT en état d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel	false	Facultatif
enabled	Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.	true	Facultatif
async	Cet attribut est obsolète.	false	Obsolète

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>

Par défaut	N/A Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.
Presence	Facultatif
Type	Chaîne

Élément <SharedFlowBundle>

Spécifie le nom du flux partagé à appeler. La valeur de cet élément doit être identique à celle de l'attribut de nom de l'élément <SharedFlowBundle> cible.

<SharedFlowBundle/>

Dans l'exemple le plus simple, vous indiquez le nom du flux partagé appelé en tant que valeur pour cet élément. Autrement dit, la valeur de cet élément doit être identique à celle de l'attribut name du flux partagé.

<SharedFlowBundle>Shared-Flow-Name</SharedFlowBundle>

Par défaut	N/A
Presence	Obligatoire
Type	N/A

Attributs

Aucune.

Élément <Parameter>

Spécifie un paramètre et une valeur (ou une source de valeur) à transmettre en tant que variable dans le flux partagé appelé par cette règle.

Avec un paramètre, vous pouvez spécifier une valeur (ou une variable contenant une valeur) à transmettre au flux partagé appelé par la règle. Le concept de cette action est semblable à la spécification d'un paramètre dans un appel de fonction. Comme pour un paramètre de fonction, la valeur d'un paramètre FlowCallout peut varier en fonction du contexte de l'appel de flux partagé.

Les paramètres FlowCallout ne sont visibles que lors de l'exécution du flux partagé.

Syntaxe

Vous pouvez utiliser cet élément avec l'une des formes de syntaxe suivantes. Notez que lorsque vous spécifiez une valeur littérale, le format de la valeur que vous spécifiez dépend du code qui l'utilise.

<!- A literal value in an attribute. --/>
<Parameter name="parameter-name" value='parameter-value' />
<!- A reference to a variable in an attribute. --/>
<Parameter name="parameter-name" ref='source-variable-name' />
<!- A literal value in the element content. --/>
<Parameter name="parameter-name">parameter-value</Parameter>
<!- An reference to an attribute in the element content. --/>
<Parameter name="parameter-name">{source-variable-name}</Parameter>

Exemple

La règle String-Handler FlowCallout transmet des paramètres qui spécifient où stocker le résultat du flux partagé et l'entrée à utiliser. Les éléments Parameter spécifient les noms et les valeurs des variables pour créer l'environnement d'exécution. Le flux partagé peut récupérer ces variables pour les utiliser dans leur propre code.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
  <DisplayName>String Handler</DisplayName>
  <Parameters>
    <Parameter name="input">Gladys Kravitz</Parameter>
    <Parameter name="outputVariable">string.handler.output</Parameter>
  </Parameters>
  <SharedFlowBundle>StringHandler</SharedFlowBundle>
</FlowCallout>

Par défaut	N/A
Presence	Obligatoire
Type	N/A

Attributs

Attribut	Description	Par défaut	Presence	Type
name	Nom de la variable d'exécution à créer avec ce paramètre.	Aucun	Obligatoire	Chaîne
ref	Variable contenant la valeur à utiliser lors de l'exécution. Ignorez cet attribut si vous spécifiez une valeur littérale à utiliser.	Aucun	Facultatif	Chaîne
value	Valeur à utiliser dans la variable d'exécution créée avec ce paramètre. Ignorez cet attribut si vous spécifiez le nom d'une variable qui doit être la source de la valeur.	Aucun	Facultatif	Chaîne

Élément <Parameters>

Spécifie l'ensemble des éléments <Parameter> à transmettre en tant que variables dans le flux partagé appelé par cette règle.

Syntaxe

<Parameters>
  <Parameter name="parameter-name" value='parameter-value' />
</Parameters>

Par défaut	N/A
Presence	Facultatif
Type	N/A

Attributs

Aucune.

Schémas

Exemple : consultez les exemples de dépôt GitHub pour visualiser les schémas les plus récents.

Variables de flux

Les variables de flux permettent un comportement dynamique des règles et des flux lors de l'exécution, en fonction des en-têtes HTTP, du contenu des messages ou du contexte du flux. Pour en savoir plus sur les variables de flux, consultez la documentation de référence sur les variables.

Variable	Description
apigee.edge.sharedflow.name	Champ d'application : lors de l'exécution du flux partagé Type : chaîne Autorisation : lecture Valeur de l'attribut name du flux partagé.
apigee.edge.flowhook.name	Champ d'application : lors de l'exécution du flux partagé associé au hook de flux. Type : Chaîne Autorisation : Lecture Nom du hook de flux.

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Conseil : Vous avez besoin d'aide pour résoudre une erreur ? Cliquez sur dans la colonne "Corriger" pour obtenir des informations de dépannage détaillées.

Utilisez API Monitoring pour examiner des codes d'erreur et diagnostiquer les problèmes plus rapidement.

Code d'erreur	État HTTP	Cause	Corriger
flow.SharedFlowNotFound	500	Soit le flux partagé n'existe pas, soit il existe, mais n'est pas déployé.

Erreurs de déploiement

ND

Articles associés

• Créer des flux partagés : Flux partagés réutilisables
• Exécuter des flux partagés sur plusieurs proxy : Associer un flux partagé à l'aide d'un hook de flux