Ce que vous devez savoir sur les erreurs liées aux règles

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X.
en savoir plus

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.

Dans cette rubrique, nous partons du principe que vous avez une compréhension générale du fonctionnement de la gestion des pannes dans Edge et que vous savez ce que sont les règles d'erreur. 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 stratégie génère une erreur, Edge entre immédiatement dans 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 inclut deux informations : un errorcode (code d'erreur) et une faultstring (chaîne d'erreur).

Exemple :

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"foo message is not available for ExtractVariable: ParseJsonResponse"
   }
}

Décomposons rapidement ce message d'erreur :

L'attribut errorcode comprend un préfixe et un nom d'erreur, 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 à trouver un problème spécifique qui a provoqué l'erreur, comme le nom de la règle, le nom d'une variable non résolue ou tout élément ayant contribué à cette erreur. Par exemple, dans le message d'erreur ci-dessus, "foo" 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é dans l'article Gérer les erreurs, il est courant de piéger les erreurs de stratégie générées par le système et d'effectuer une action ultérieure, par exemple pour 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 de statut réels renvoyés par Edge.

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.

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 d'erreur, telles que le message d'erreur, le code d'état, l'expression de motif, etc. Le modèle de mise en forme 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. Pour en savoir plus, consultez la section Cas d'utilisation des variables de message.

Reportez-vous à la documentation de référence sur les variables pour plus d'informations sur toutes les variables Edge, y compris error et message.