Cette page s'applique à Apigee et à Apigee hybrid.
Consultez la documentation d'Apigee Edge.
Cette rubrique décrit la structure des erreurs liées aux règles et les types de variables de flux définis lors d'une erreur liée aux règles. Ces informations sont essentielles si vous concevez et mettez en œuvre la gestion des pannes pour vos proxys.
Cet article suppose que vous avez des connaissances générales sur le fonctionnement de la gestion des erreurs dans Apigee et que vous savez ce que sont les règles de défaillance. Si vous avez besoin de revenir sur ces points, consultez la section Gérer les pannes. Les informations fournies ici vous aideront également à utiliser la documentation de référence sur les erreurs liées aux règles.
À propos de la réponse par défaut concernant les erreurs liées aux règles
Lorsqu'une règle génère une erreur, Apigee saisit immédiatement le flux d'erreur et génère un message d'erreur. Ce message généré par le système est un objet JSON qui comprend deux informations : un errorcode et un faultstring.
Exemple :
{
"fault":{
"detail":{
"errorcode":"steps.extractvariables.SourceMessageNotAvailable"
},
"faultstring":"mymessage message is not available for ExtractVariable: ParseJsonResponse"
}
}
Décomposons rapidement ce message d'erreur :
L'élément errorcode est composé d'un prefix et d'un error
name, comme suit : [prefix].[error_name]. Dans l'exemple ci-dessus, "steps.extractvariables" est le préfixe et SourceMessageNotAvailable est le nom de l'erreur. Le préfixe vous indique quel type de règle a généré l'erreur. Dans l'exemple ci-dessus, vous pouvez constater qu'une règle Extract Variables a généré l'erreur et que le nom de l'erreur est SourceMessageNotAvailable.
L'attribut faultstring contient une description de l'erreur. La chaîne d'erreur comprend généralement des indices pour vous aider à identifier le problème spécifique à l'origine de l'erreur, tels que le nom de la règle, le nom d'une variable non résolue ou tout ce qui a contribué à l'erreur. Par exemple, dans le message d'erreur ci-dessus, mymessage est le nom d'une variable de message non résolue référencée dans la règle, et ParseJsonResponse est le nom de la règle qui a déclenché l'erreur.
Variables spécifiques aux erreurs liées aux règles
Lorsqu'une erreur de règle est déclenchée, certaines variables de flux spécifiques à l'erreur sont renseignées. Ces variables sont très utiles dans la gestion des pannes. Comme expliqué sur la page consacrée à la gestion des erreurs, il est courant de capturer les erreurs de règle générées par le système et d'effectuer une action ultérieure, comme créer une réponse d'erreur personnalisée. Par exemple, pour des raisons de sécurité, vous pouvez empêcher les clients de voir les erreurs et les codes d'état réellement renvoyés par Apigee.
Variable fault.name
Lorsqu'une règle génère une erreur, elle définit la variable de flux fault.name sur la partie error_name de l'attribut errorcode (comme décrit dans la section précédente). Il est très courant d'évaluer cette variable pour exécuter des règles de défaillance de manière conditionnelle.
Voici un exemple de règle de défaillance qui teste la valeur de fault.name :
<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="Source Message Not Available Fault">
<Step>
<Name>AM-CustomErrorMessage</Name>
<Condition>(fault.name Matches "SourceMessageNotAvailable") </Condition>
</Step>
</FaultRule>
Gardez à l'esprit que lorsqu'une règle déclenche une erreur, la variable fault.name est toujours définie sur le nom de l'erreur.
La variable [prefix].[policy_name].failed
Outre fault.name, une autre variable couramment utilisée par les développeurs est l'option [prefix].[policy_name].failed, qui est définie sur "true" ou "false" lorsqu'une règle est exécutée. Dans les règles de défaillance, vous devrez vérifier si elle est définie sur true, autrement dit vérifier si une erreur s'est produite. Voici comment créer une condition qui vérifie l'option [prefix].[policy_name].failed. Pour vérifier correctement cette variable, vous devez savoir deux choses :
- Le nom de la règle que vous vérifiez. Il s'agit de la valeur de l'attribut de nom de la règle, et non du nom à afficher. Cet attribut est toujours inclus dans le fichier XML de définition de la règle.
- Un préfixe spécifique au type de règle que vous vérifiez. (nous vous expliquerons comment trouver le préfixe ci-dessous).
Pour illustrer cela, voici un autre exemple de règle de défaillance. Remarquez la façon dont le nom de la variable [prefix].[policy_name].failed est formé dans la condition externe. Dans ce cas, le préfixe est extractvariables et le nom de la règle est ParseJsonResponse. Dans ce cas, la règle de défaillance ne s'exécute que si cette variable est "true". Enfin, voici une astuce : les règles de défaillance pouvant contenir plusieurs étapes, ce modèle permet d'organiser les règles de défaillance en blocs.
<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="Extract Variable Faults">
<Step>
<Name>AM-CustomErrorMessage</Name>
<Condition>(fault.name Matches "SourceMessageNotAvailable") </Condition>
</Step>
<Condition>(extractvariables.ParseJsonResponse.failed = true) </Condition>
</FaultRule>
À propos des variables error et message
La variable error n'est disponible que dans le flux d'erreur d'un proxy. Vous pouvez obtenir des informations utiles à partir de la variable error, telles que le message d'erreur, le code d'état, la phrase de motif, etc. Le format de la variable d'erreur est le suivant :
error.ERROR_COMPONENT = VALUE
Exemple :
error.message = "request message is not available for ExtractVariable: ParseJsonResponse"
et
error.status.code = "500"
La variable message est également disponible dans le flux d'erreur et peut être utilisée à des fins similaires à la variable error. La variable de message est spéciale, car elle est contextuelle. Dans un flux de requête, elle se comporte comme une variable de requête. Dans un flux de réponse, elle peut être utilisée pour obtenir/définir des valeurs de réponse.
Reportez-vous à la documentation de référence sur les variables de flux pour plus d'informations sur toutes les variables Apigee, y compris error et message.