Gérer les pannes

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

De nombreuses conditions d'erreur peuvent survenir lorsque les proxys d'API traitent les requêtes en provenance d'applications. Par exemple, les proxys d'API peuvent rencontrer des problèmes réseau lors de la communication avec les services de backend, les applications peuvent présenter des identifiants ayant expiré, le format des messages de requête peut être incorrect, etc.

Lorsqu'une erreur se produit après l'appel d'un proxy d'API par une application cliente, un message d'erreur est renvoyé au client. Par défaut, le client reçoit un message d'erreur souvent difficile à déchiffrer, sans détails ni conseils. Toutefois, si vous souhaitez remplacer les messages d'erreur par défaut par des messages personnalisés plus utiles, et et même les enrichir avec des en-têtes HTTP supplémentaires, par exemple, vous devez configurer dans Edge.

La gestion personnalisée des erreurs vous permet également d'ajouter des fonctionnalités telles que la journalisation des messages chaque fois qu'une erreur se produit.

Avant d'aborder la mise en œuvre de la gestion des erreurs personnalisée dans vos proxys d'API, il est utile de comprendre comment les erreurs se produisent et comment les proxys d'API réagissent face à elles.

Vidéos

Regardez les vidéos suivantes pour en savoir plus sur la gestion des erreurs.

Vidéo Description
Présentation de la gestion des erreurs et des flux d'erreurs Découvrez la gestion des erreurs et ce qu'il se passe lorsqu'une erreur se produit dans un proxy d'API.
Gérez les erreurs à l'aide de règles d'erreur. Découvrez comment gérer les erreurs à l'aide de règles d'erreur.
Générez les erreurs personnalisées à l'aide de la stratégie RaiseFault Générez des erreurs personnalisées lors de l'exécution de l'API à l'aide de la stratégie RaiseFault.
Définissez des règles de défaillance sur le proxy d'API et sur les points de terminaison cibles Définissez les règles d'erreur dans le proxy d'API et les points de terminaison cibles et comprenez les différences.
Comprenez l'ordre d'exécution des règles de défaillance Comprenez l'ordre d'exécution des règles d'erreur dans le proxy d'API et les points de terminaison cibles.
Définissez une règle d'erreur par défaut Définissez une règle d'erreur par défaut pour gérer les erreurs génériques dans votre API.

Comment les erreurs se produisent-elles ?

Nous aborderons simplement la façon dont les erreurs se produisent. Déterminer la façon dont les erreurs se produisent aide à planifier les différentes situations dans lesquelles vous souhaitez mettre en œuvre une gestion des erreurs personnalisée.

Erreurs automatiques

Un proxy d'API génère automatiquement une erreur dans les situations suivantes :

  • Une stratégie génère une erreur. Par exemple, si un appel d'API envoie une clé ayant expiré, la stratégie VerifyAPIKey génère automatiquement une erreur. Si le nombre d'appels d'API dépasse une certaine limite, la stratégie de quota ou la stratégie SpikeArrest génèrent une erreur. (Consultez la Documentation de référence sur les erreurs de règles pour connaître les types d'erreurs de règles susceptibles d'être générés.)
  • Le flux de messages du proxy d'API présente un problème, par exemple une erreur de routage.
  • Une erreur de backend se produit, par exemple une erreur HTTP due à des échecs au niveau du protocole, des erreurs TLS/SSL ou un service cible indisponible.
  • Il y a une défaillance au niveau du système, telle qu'une exception de mémoire saturée.

Pour plus d'informations sur ces erreurs, consultez la section Classification des pannes de cette rubrique.

Erreurs personnalisées

Dans les cas où il n'y a pas d'erreur automatique, vous pouvez générer une erreur personnalisée, par exemple si une réponse contient le mot "unavailable" ou si le code d'état HTTP est supérieur à 201. Pour ce faire, ajoutez une règle RaiseFault à l'emplacement approprié dans un flux de proxy d'API.

Vous pouvez ajouter une règle RaiseFault à un flux de proxy d'API de la même manière que toute autre règle. Dans l'exemple de configuration de proxy suivant, la règle Raise-Fault-1 est associée à la réponse du TargetEndpoint. Si le mot "unavailable" figure dans la réponse du service cible, la règle RaiseFault est exécutée et génère une erreur.

<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>Raise-Fault-1</Name>
      <Condition>(message.content Like "*unavailable*")</Condition>
    </Step>
  </Response>

L'objectif ici est simplement de vous montrer que vous pouvez générer des erreurs personnalisées. Nous examinerons plus en détail la stratégie RaiseFault dans la section Règles d'erreur et stratégie RaiseFault.

Pour plus d'exemples, consultez les publications suivantes sur les forums communautaires d'Apigee :

Que font les proxys d'API en cas d'erreur ?

Voici ce qu'il se passe lorsqu'un proxy génère une erreur.

Quitter le pipeline de proxy

Lorsqu'un proxy d'API rencontre une erreur, quelle que soit la façon dont elle se produit, il ferme le pipeline de flux normal, passe à un état d'erreur et renvoie un message d'erreur à l'application cliente. Lorsque le proxy d'API passe à l'état d'erreur, il ne peut plus revenir au traitement normal du pipeline de flux normal.

Par exemple, supposons qu'un proxy d'API possède des stratégies dans l'ordre suivant dans la requête ProxyEndpoint :

  1. Vérifier la clé API
  2. Quota
  3. JSON vers XML

Si une erreur se produit lors de la validation de la clé API, le proxy d'API passe à un état d'erreur. Les règles "Quota" et "JSON vers XML" ne sont pas exécutées, le proxy ne poursuit pas l'acheminement vers le TargetEndpoint et un message d'erreur est renvoyé à l'application cliente.

Vérifier les règles d'erreur

Dans l'état d'erreur, les proxys d'API vérifient également la présence des éléments suivants (dans l'ordre) dans la configuration du proxy d'API avant de renvoyer un message d'erreur par défaut à l'application cliente :

  1. Une section <FaultRules>, qui contient la logique permettant de déclencher des messages d'erreur personnalisés (et d'autres stratégies) en fonction de conditions spécifiques que vous définissez.
  2. Une section <DefaultFaultRule> qui déclenche un message d'erreur par défaut dans les situations suivantes :
    • Aucune règle <FaultRules> n'est définie.
    • Aucune stratégie <FaultRules> existante n'est exécutée.
    • L'élément <AlwaysEnforce> est défini sur "true".

En substance, le proxy d'API vous donne la possibilité de renvoyer un message d'erreur personnalisé et de déclencher une autre logique. Si le proxy ne trouve aucune de ces sections ou qu'elles existent, mais pas de sections a été déclenchée, le proxy envoie son propre message par défaut généré par Edge.

Exemple simple de gestion des erreurs

Commençons par un exemple simple, où un appel à un proxy d'API ne contient pas une clé d'API requise. Par défaut, voici la réponse qui est renvoyée à l'application cliente :

HTTP/1.1 401 Unauthorized
Date: Wed, 20 Jul 2016 19:19:32 GMT
Content-Type: application/json
Content-Length: 150
Connection: keep-alive
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

Il est possible que les utilisateurs de votre API soient en mesure de déterminer le message d'erreur, mais ce n'est peut-être pas le cas. De nombreuses erreurs par défaut sont subtiles et difficiles à déchiffrer.

En tant que développeur d'API, vous devez modifier ce message pour répondre aux besoins de la personne qui le recevra, qu'il s'agisse d'un développeur d'application iOS ou d'un groupe de test interne ayant ses propres besoins en termes de format de message d'erreur.

Voici un exemple de la façon dont vous devez créer un message d'erreur personnalisé pour gérer cette erreur. Cela nécessite 1) une règle qui définit le message personnalisé, et 2) une règle FaultRule qui exécute la règle lorsque le proxy passe à un état d'erreur.

1. Créer une stratégie définissant le message personnalisé

Commencez par créer une règle qui définit le message d'erreur personnalisé. Vous pouvez utiliser n'importe quel type de règle, par exemple une règle AssignMessage, qui permet de définir une charge utile et des en-têtes HTTP facultatifs tels que le code d'état et l'expression de motif. Une règle d'attribution de message est idéale pour ce type d'opération. Elle vous permet de contrôler la charge utile des messages, de définir un code d'état HTTP différent, de définir une autre expression de motif HTTP et d'ajouter des en-têtes HTTP.

N'associez la règle à aucun flux dans le proxy d'API. Il suffit simplement qu'elle existe dans le groupe de proxys. Pour ce faire, dans l'éditeur de proxy de l'interface utilisateur de gestion, accédez à l'onglet "Développement", Volet de navigation, puis cliquez sur l'icône + dans la barre des règles.

Vous pouvez ainsi créer une stratégie sans l'associer à un flux du proxy d'API. Une stratégie qui n'est pas associée à un flux est signalée par l'icône de "détachement" dans la liste Stratégies, comme indiqué à côté de la stratégie de message de clé API présentée à la figure précédente.

Voici un exemple de stratégie AssignMessage qui :

  • Renvoie un message JSON.
  • Définit un code d'état HTTP (911, qui est un code d'état n'existant manifestement pas mais servant à illustrer la flexibilité dont vous disposez). Le code d'état s'affiche dans l'en-tête HTTP.
  • Définit une expression de motif HTTP (pour remplacer l'expression par défaut "Non autorisé" correspondant à cette erreur de clé API manquante). L'expression de motif indiquée s'affiche à côté du code d'état dans l'en-tête HTTP.
  • Crée et renseigne un nouvel en-tête HTTP appelé invalidKey.
<AssignMessage async="false" continueOnError="false" enabled="true" name="invalid-key-message">
    <DisplayName>Invalid key message</DisplayName>
    <Set>
        <Payload contentType="application/json">{"Citizen":"Where's your API key? I don't see it as a query parameter"}</Payload>
        <StatusCode>911</StatusCode>
        <ReasonPhrase>Rejected by API Key Emergency Services</ReasonPhrase>
    </Set>
    <Add>
        <Headers>
            <Header name="invalidKey">Invalid API key! Call the cops!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Lorsque cette règle est exécutée, la réponse à l'application cliente se présente comme suit. Comparez-la à la réponse par défaut indiquée précédemment.

HTTP/1.1 911 Rejected by API Key Emergency Services
Date: Wed, 20 Jul 2016 18:42:36 GMT
Content-Type: application/json
Content-Length: 35
Connection: keep-alive
invalidKey: Invalid API key! Call the cops!
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"Citizen":"Where's your API key? I don't see it as a query parameter."}

Oui, c'est un peu loufoque, mais cela montre les possibilités dont vous disposez. Au moins, le développeur qui reçoit le message sait maintenant qu'il a oublié d'inclure une clé API en tant que paramètre de requête.

Mais comment cette règle est-elle exécutée ? La section suivante vous explique comment.

2. Créer la règle <FaultRule> qui déclenchera la stratégie

Dans les sections <ProxyEndpoint> ou <TargetEndpoint> de la configuration du proxy, vous ajouterez un bloc XML <FaultRules> contenant une ou plusieurs sections <FaultRule> individuelles. Chaque règle d'erreur représente une erreur différente que vous souhaitez gérer. Dans cet exemple simple, nous utilisons une seule règle d'erreur pour vous montrer de quoi celle-ci est constituée.

Vous devez également ajouter un <DefaultFaultRule> pour fournir un message d'erreur général personnalisé si aucune de vos règles d'erreur n'est exécutée.

Exemple

<ProxyEndpoint name="default">
...
    <FaultRules>
       <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Points essentiels :

  • Les règles d'erreur sont définies dans ProxyEndpoint. C'est important. Obtenez plus d'informations sur l'insertion de règles d'erreur dans ProxyEndpoint et TargetEndpoint ultérieurement.
  • <Name> : nom de la stratégie à exécuter. Le nom provient de l'attribut name de la stratégie sur l'élément parent, comme indiqué précédemment dans l'exemple de stratégie.

  • <Condition> : Edge évalue la condition et exécute la stratégie uniquement si la condition est vraie. S'il existe plusieurs FaultRules évaluer sur true, Edge exécute la première qui est vraie. (Important : L'ordre d'évaluation des règles d'erreur, de haut en bas ou de bas en haut, diffère entre le TargetEndpoint et le ProxyEndpoint, comme décrit dans la section Règles FaultRules multiples et logique d'exécution.) Si vous n'incluez pas de condition, la règle FaultRule est automatiquement vraie. Ce n'est pas une bonne pratique. Chaque règle FaultRule doit avoir sa propre condition.

  • <DefaultFaultRule> - Si aucune règle FaultRule personnalisée n'est exécuté, <DefaultFaultRule> est exécuté, ce qui envoie une réponse plus générique message personnalisé au lieu du message énigmatique par défaut généré par Edge. Une <DefaultFaultRule> peut également avoir une <Condition>, mais dans la plupart des cas, vous n'en incluez pas, car vous souhaitez l'exécuter en dernier recours quoi qu'il en soit.

    La règle DefaultFaultRule sert généralement à renvoyer un message d'erreur générique pour toute erreur inattendue. Par exemple, il peut s'agir d'un message contenant des coordonnées de l'assistance technique. Cette réponse par défaut sert à la fois à fournir des informations conviviales aux développeurs tout en masquant les URL de backend ou d'autres informations susceptibles d'être utilisées pour compromettre le système.

Plusieurs règles d'erreur et logique d'exécution

Dans la section Exemple de gestion des erreurs simple, nous avons utilisé un exemple simple d'une règle d'erreur et d'une condition uniques. Dans un projet d'API réel contenant toutes les erreurs possibles, vous risquez de créer plusieurs règles d'erreur et une règle d'erreur par défaut dans <ProxyEndpoint> et <TargetEndpoint>. Au final toutefois, une seule règle d'erreur est exécutée lorsqu'un proxy d'API passe à l'état d'erreur.

Cette section décrit la logique qu'Edge utilise pour gérer FaultRules, de la façon dont il arrive à un une seule règle FaultRule pour s'exécuter selon la valeur "inner" ; Les conditions d'étape sont gérées lorsque leur règle FaultRule est déclenchée. Cette section indique également quand définir des règles d'erreur dans <ProxyEndpoint> par rapport à <TargetEndpoint>, et décrit la relation entre les règles d'erreur et la stratégie RaiseFault.

Exécution des règles d'erreur

En bref, voici la logique qu'Edge utilise lorsqu'un proxy d'API passe en état d'erreur. Notez qu'il existe une légère différence entre l'évaluation FaultRules dans le ProxyEndpoint et dans le TargetEndpoint.

  1. Edge évalue les FaultRules dans ProxyEndpoint ou TargetEndpoint, en fonction de où l'erreur s'est produite: <ph type="x-smartling-placeholder">
      </ph>
    • ProxyEndpoint - Edge commence par la bas <FaultRule> dans le fichier XML de configuration et remonte, en évaluant la <Condition> de chaque <FaultRule> (la valeur "externe" et non la condition "interne" <Step>).
    • TargetEndpoint : Edge commence par le top <FaultRule> dans le fichier XML de configuration, puis revient à la fin, en évaluant la <Condition> de chaque <FaultRule> (la valeur "externe" et non la condition "interne" <Step>).
  2. Exécute la première règle d'erreur dont la condition est vraie. Si une règle d'erreur n'a pas de condition, sa valeur est "true" par défaut.
    • Lorsqu'une règle d'erreur est exécutée, toutes les étapes de la règle d'erreur sont évaluées dans l'ordre, de haut en bas dans le fichier XML de configuration. Les étapes sans condition sont automatiquement exécutées (les stratégies sont exécutées), et les étapes dont la <Condition> renvoie la valeur "true" sont exécutées (les conditions renvoyant la valeur "false" ne sont pas exécutées).

    • Si une règle FaultRule est exécutée, mais qu'aucun pas de cette règle n'est exécuté (car son conditions évaluées sur "false"), le message d'erreur par défaut généré par Edge est renvoyé à l'application cliente. Le <DefaultFaultRule> n'est pas exécuté, car Edge a déjà exécuté sa seule FaultRule.

  3. Si aucune règle FaultRule n'est exécutée, Edge exécute la règle <DefaultFaultRule>, si à l'heure actuelle.

Voici des exemples de commentaires intégrés.

Exécution du proxyEndpoint

L'évaluation des règles d'erreur ProxyEndpoint se faisant de bas en haut, commencez donc à lire à la dernière règle d'erreur dans l'exemple suivant et avancez vers le haut. Examinez la dernière règle d'erreur par défaut en dernier.

<ProxyEndpoint name="default">
...
    <FaultRules>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just below this got
     executed (bottom-to-top evaluation in a ProxyEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
<FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 1. Because this is the ProxyEndpoint, Edge looks at this FaultRule
     first. But let's say this FaultRule is FALSE. A policy did not 
     throw a FailedToResolveAPIKey error. Edge moves UP to check
     the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Exécution de TargetEndpoint

L'évaluation des règles d'erreur TargetEndpoint se faisant de haut en bas, commencez donc à lire à la première règle d'erreur dans l'exemple suivant et avancez vers le bas. Examinez la dernière règle d'erreur par défaut en dernier.

<TargetEndpoint name="default">
...
    <FaultRules>
<!-- 1. Because this is the TargetEndpoint, Edge looks at this FaultRule
     first. Let's say this FaultRule is FALSE. 
     A policy did not throw a FailedToResolveAPIKey error. 
     Edge moves down to the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
        <FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just above this got
     executed (top-to-bottom evaluation in a TargetEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Ordre des règles d'erreur

Comme vous pouvez le voir dans l'exemple précédent, l'ordre dans lequel vous placez vos règles d'erreur est important, selon que l'erreur se produit dans ProxyEndpoint ou dans TargetEndpoint.

Exemple :

Ordre dans ProxyEndpoint Ordre dans TargetEndpoint

Dans l'exemple suivant, étant donné que l'évaluation se fait de bas en haut, la règle d'erreur 3 est exécutée, ce qui signifie que les règles d'erreur 2 et 1 ne sont pas évaluées.

5. Règle d'erreur 1 : FALSE

4. Règle d'erreur 2 : TRUE

3. Règle d'erreur 3 : TRUE

2. Règle d'erreur 4 : FALSE

1. Règle d'erreur 5 : FALSE

Dans l'exemple suivant, étant donné que l'évaluation se fait de haut en bas, la règle d'erreur 2 est exécutée, ce qui signifie que les règles d'erreur 3, 4 et 5 ne sont pas évaluées.

1. Règle d'erreur 1 : FALSE

2. Règle d'erreur 2 : TRUE

3. Règle d'erreur 3 : TRUE

4. Règle d'erreur 4 : FALSE

5. Règle d'erreur 5 : FALSE

Règles à inclure

Vous pouvez exécuter toutes les règles d'une règle FaultRule en les plaçant dans des étapes. Par exemple, vous pouvez exécuter une règle AssignMessage pour mettre en forme une réponse destinée à l'application cliente, puis consigner un message avec la règle MessageLogging. Les règles sont exécutées dans l'ordre dans lequel vous les avez placées (de haut en bas dans le fichier XML).

Les règles d'erreur sont déclenchées UNIQUEMENT à l'état d'erreur (au niveau de continueOnError)

L'en-tête peut donner l'impression que nous nous répétons, mais il existe une nuance particulière à prendre en compte concernant une erreur de proxy entraînant le passage d'une API à un état d'erreur, ou plutôt son non passage à un état d'erreur : l'attribut continueOnError sur une stratégie.

En résumé : un proxy d'API évalue <FaultRules> et <DefaultFaultRule> uniquement si le proxy est passé à un état d'erreur. Cela signifie que même si une condition de règle d'erreur renvoie la valeur "true", elle ne sera pas déclenchée si le proxy n'est pas dans un état d'erreur.

Toutefois, voici un exemple d'erreur se produisant et de proxy ne passant pas à un état d'erreur. Sur n'importe quelle stratégie, vous pouvez définir un attribut sur l'élément parent appelé continueOnError. Cet attribut est très important pour la gestion des erreurs, car il détermine si le proxy passe ou non à un état d'erreur en cas d'échec de la stratégie. Dans la plupart des cas, vous devez conserver la valeur par défaut continueOnError="false", qui place le proxy dans un état d'erreur si la stratégie échoue et la gestion d'erreur personnalisée est déclenchée. Toutefois, si continueOnError="true" (par exemple, si vous ne souhaitez pas que l'échec d'un appel de service arrête l'exécution du proxy), le proxy ne passe pas à un état d'erreur en cas d'échec de cette stratégie et le proxy n'examine pas vos règles d'erreur.

Pour plus d'informations sur la journalisation des erreurs lorsque continueOnError="true", consultez la section Gérer les erreurs de règles dans le flux actuel.

Où définir les règles d'errur : ProxyEndpoint ou TargetEndpoint

Lorsqu'un proxy d'API rencontre une erreur, celle-ci se produit dans <ProxyEndpoint> (requête de ou réponse à l'application cliente) ou dans <TargetEndpoint> (requête à ou réponse du service cible). Partout est l'endroit où Edge recherche FaultRules.

Par exemple, si aucun serveur cible n'est disponible (code d'état HTTP 503), le proxy d'API passe à un état d'erreur dans la réponse <TargetEndpoint> et le flux de proxy d'API normal ne continue pas vers <ProxyEndpoint>. Si des règles d'erreur sont définies uniquement dans le <ProxyEndpoint>, elles ne traitent pas cette erreur.

Voici un autre exemple. Si une stratégie RaiseFault sur la réponse <ProxyEndpoint> déclenche une erreur, une règle d'erreur dans <TargetEndpoint> ne sera pas exécutée.

Stratégie FaultRules ou RaiseFault

Les règles d'erreur et la règle RaiseFault peuvent donner l'impression qu'il s'agit de deux solutions équivalentes pour gérer les défaillances, et de certaines manières, c'est le cas. Mais elles fonctionnent aussi en synergie. Cette section explique la relation entre les deux. Comprendre cette relation devrait vous aider à concevoir votre gestion des défaillances, en particulier si vous souhaitez utiliser ces deux règles.

En bref :

  • Les règles d'erreur sont toujours évaluées lorsqu'un proxy d'API passe à un état d'erreur.

  • La stratégie RaiseFault permet de placer un proxy d'API dans un état d'erreur lorsqu'une erreur ne se serait autrement pas produite.

    Par exemple, si vous souhaitez générer une erreur lorsque le code d'état HTTP de la réponse du service cible est supérieur à 200, vous devez ajouter une règle RaiseFault dans votre flux de réponse. Celle-ci se présente alors sous la forme suivante :

    <TargetEndpoint name="default">
    <PreFlow name="PreFlow">
...
        <Response>
            <Step>
                <Name>Raise-Fault-1</Name>
<!-- If the condition is true, the Raise-Fault-1 policy gets executed -->
                <Condition>(response.status.code GreaterThan "200")</Condition>
            </Step>
        </Response>

    La stratégie RaiseFault envoie également un message d'erreur à l'application cliente.

Que se passe-t-il lorsqu'une règle RaiseFault déclenche une erreur, ce qui place alors le proxy dans un état d'erreur, ce qui à son tour déclenche potentiellement l'exécution d'une règle FaultRule ? C'est là que les choses deviennent un peu délicates. Si la règle RaiseFault renvoie un message d'erreur et une règle FaultRule se déclenche et renvoie un message d'erreur, qu'est-ce qui est renvoyé à l'application cliente ?

  • Étant donné que la règle d'erreur ou règle d'erreur par défaut est exécutée après la stratégie RaiseFault, les données de réponse de règle d'erreur l'emportent.
  • Les données de réponse de la stratégie RaiseFault (code d'état, expression de motif ou charge utile du message) sont utilisées si elles ne sont pas définies par la règle d'erreur ou règle d'erreur par défaut.
  • Si les règles RaiseFault et FaultRule ajoutent toutes deux des en-têtes HTTP personnalisés, les données des deux sont incluses dans la réponse. Des noms d'en-têtes en double créent un en-tête comportant plusieurs valeurs.

Voici un exemple de ce qui est défini par une stratégie RaiseFault et une règle d'erreur, ainsi que les éléments renvoyés à l'application cliente. Les exemples sont conçus pour des raisons de concision, et non pour les bonnes pratiques.

L'application cliente reçoit :

Status Code: 468
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: woops,gremlins

<- La stratégie de règles d'erreur définit les éléments suivants :

Status Code: [none] 
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: gremlins

<- La stratégie RaiseFault définit les éléments suivants :

Status Code: 468
Reason Phrase: Can't do that
Payload: {"DOH!":"Try again."}
Header: 
  errorNote: woops

Conditions de construction

Les conditions sont la clé de l'exécution des règles d'erreur. Vous créez des conditions FaultRule de la même manière que vous faites pour d'autres conditions dans Edge, telles que pour les flux conditionnels ou les conditions RaiseFault.

Pour mettre en contexte le reste de cette section, voici un exemple de règle d'erreur qui présente une condition de règle d'erreur externe et une condition d'étape interne.

<FaultRule name="invalid_key_rule">
    <Step>
        <Name>invalid-key-message</Name>
        <Condition>(oauthV2.Verify-API-Key-1.failed = true)</Condition>
    </Step>
    <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
</FaultRule>

Variables spécifiques aux erreurs liées aux stratégies

Les variables fault.name et {policy_namespace}.{policy_name}.failed sont disponibles lorsqu'une règle génère une erreur.

fault.name

Lorsqu'une stratégie échoue, interceptez l'erreur dans une condition à l'aide de la variable fault.name. Exemple :

<Condition>(fault.name = "policy_error_name")</Condition>

Le nom de l'erreur s'affiche dans le message d'erreur par défaut. Par exemple, dans le code suivant, le nom de l'erreur est FailedToResolveAPIKey. Dans ce cas, une variable de flux appelée fault.name est définie sur la valeur FailedToResolveAPIKey.

{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

Ainsi, la condition se présentera comme suit :

<Condition>(fault.name = "FailedToResolveAPIKey")</Condition>

Pour obtenir la liste des erreurs de règles, consultez la documentation de référence sur les erreurs de règles.

{policy_namespace}.{policy_name}.failed

La variable *.failed est disponible lorsqu'une règle échoue. Vous trouverez ci-dessous des exemples de variables *.failed pour différentes règles. Pour les espaces de noms de règles, consultez les variables de flux dans la documentation de référence sur les règles.

Autres variables disponibles

Lorsqu'un proxy d'API passe à l'état d'erreur, les seules variables disponibles à utiliser dans les conditions sont les suivantes :

  • Variables de la stratégie qui a échoué.
  • Variables de message HTTP qui existent au point de défaillance. Par exemple, si une erreur est générée dans la réponse, une règle FaultRule du <TargetEndpoint> peut utiliser les données HTTP response.status.code, message.content, error.content, etc. Si une règle de quota a échoué, vous pouvez utiliser la variable ratelimit.{quota_policy_name}.exceed.count. Utiliser l'outil Trace et la règle consultez les rubriques de référence qui vous aideront à identifier les variables et les données HTTP disponibles.

En savoir plus

Bonnes pratiques pour la gestion des erreurs

La gestion des erreurs est une tâche de conception architecturale majeure pour le développement de proxys d'API. Il est important de prendre le temps de comprendre comment et quand vous allez gérer des erreurs, de déterminer ce que diront les messages d'erreur et de concevoir les formats des messages d'erreur. Une fois que vous avez clarifié ces aspects, utilisez ces bonnes pratiques pour vous aider à mettre en œuvre la gestion des erreurs.

Voici quelques bonnes pratiques à suivre pour concevoir et créer une gestion des erreurs :

  • Pour chaque règle FaultRule, fournissez une <Condition> externe (associée à l'élément <Step>). Les règles FaultRule sans condition externe renvoient automatiquement la valeur "true" (vrai). Les conditions Step "internes" ne sont pas utilisées pour déterminer si une règle FaultRule est vraie ou fausse. Les conditions de pas ne sont évaluées qu'après qu'Edge a exécuté la règle FaultRule qui les contient. Dans une règle FaultRule, il est courant d'avoir plusieurs étapes avec des règles d'attribution de messages (ou d'autres règles), chacune ayant une condition Step.

  • Pour gérer les erreurs dans plusieurs règles du même type (par exemple, plusieurs règles de quota), créez une règle FaultRule par erreur de règle que vous êtes susceptible de recevoir. Par exemple, créez une règle FaultRule pour chaque erreur probable dans les règles de quota, telles que QuotaViolation, InvalidMessageWeight ou StartTimeNotSupported. (Consultez la documentation de référence sur les erreurs liées aux règles pour connaître les erreurs de règles.) Au fur et à mesure que vous découvrez d'autres erreurs à traiter, vous pouvez revenir et les ajouter à vos règles FaultRules. Un fonctionnement itératif est tout à fait acceptable, même si cela nécessite un redéploiement du proxy.) Cette approche vous permet d'identifier le même type d'erreur quelle que soit la règles qui génère l'erreur et de rendre le XML de vos règles FaultRules plus efficace.

    Utilisez ensuite les conditions d'étape internes si vous avez besoin d'un contrôle plus précis des erreurs. Par exemple, si vous appliquez à la fois un quota de développeur individuel et un quota global avec deux stratégies dans votre flux de requêtes, définissez votre condition de règle d'erreur "externe" à déclencher au niveau de l'erreur QuotaViolation (générée lorsque le quota est dépassé dans un cas ou un autre). Définissez ensuite les conditions d'étape pour évaluer les variables exceed.count dans vos deux stratégies de quota. Seule l'erreur pertinente est envoyée au client (dépassement du quota de développeur ou du quota global). Voici un exemple de cette configuration :

    <FaultRule name="over_quota">
<!-- This condition catches a QuotaViolation in *any* Quota policy -->
  <Condition>(fault.name = "QuotaViolation")</Condition>
  <Step>
    <Name>developer-over-quota-fault</Name>
    <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
  </Step>
  <Step>
    <Name>global-over-quota-fault</Name>
    <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
  </Step>
</FaultRule>

    Pour un autre exemple, reportez-vous à ce thread de la communauté Apigee.

  • Pour gérer les erreurs lorsque vous utilisez une seule stratégie d'un type, considérez une règle d'erreur unique qui est exécutée en cas d'échec de cette stratégie, et incluez plusieurs étapes correspondant à chaque erreur possible. Cela maintient votre fichier XML efficace en utilisant une seule règle d'erreur plutôt que plusieurs (une pour chaque type d'erreur). Exemple :

    <FaultRule name="raise-fault-3">
<!-- This condition catches *any* error in the Verify-API-Key-1 policy. -->
  <Condition>(oauthV2.Verify-API-Key-1.failed = "true")</Condition>
  <!-- This first step always executes, which handles errors you haven't mapped with inner conditions. -->
  <Step>
    <Name>Generic-Key-Fault</Name>
  </Step>
  <Step>
    <Name>Assign-Message-Raise-Fault-1</Name>
    <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
  </Step>
  <Step>
    <Name>Assign-Message-Raise-Fault-2</Name>
    <Condition>(fault.name = "InvalidApiKey")</Condition>
  </Step>
</FaultRule>
  • Ajouter les règles d'erreur où les erreurs se produiront (côté client <ProxyEndpoint> ou côté cible <TargetEndpoint>). Incluez des règles d'erreur pour chaque stratégie qui s'affiche à chaque emplacement.
  • Dans les règles FaultRules, vous pouvez exécuter n'importe quel type de règle capable de renvoyer un message à l'application cliente. La règle AssignMessage est idéale pour cette opération. Envisagez également de consigner un message à l'aide de la règle MessageLogging si vous souhaitez effectuer le suivi des erreurs.
  • Lorsque vous utilisez des stratégies RaiseFault conjointement avec des règles d'erreur, coordonnez les données de réponse renvoyées lorsque la stratégie RaiseFault et une règle d'erreur renvoient des données. Par exemple, si votre stratégie RaiseFault réinitialise le code d'état HTTP, ne faites pas réinitialiser le code d'état par une règle d'erreur. Le pire pouvant se produire est que le code d'état par défaut soit renvoyé à l'application cliente.
  • Exécution de <DefaultFaultRule> :
    • Si vous souhaitez qu'une <DefaultFaultRule> s'exécute toujours lorsqu'aucune autre règle d'erreur ne s'exécute, n'incluez pas de <Condition>.
    • Si vous souhaitez qu'une <DefaultFaultRule> s'exécute en permanence, même lorsqu'une autre règle d'erreur a été exécutée, ajoutez l'élément enfant <AlwaysEnforce>true</AlwaysEnforce>.

Schéma de gestion centralisée et réutilisable des erreurs

La publication suivante destiné à la communauté Apigee décrit un schéma de gestion centralisée des erreurs sans duplication de code :

https://community.apigee.com/articles/23724/an-error-handling-pattern-for-apigee-proxies.html

Créer des règles d'erreur

Pour ajouter une règle d'erreur, vous devez modifier la configuration XML de ProxyEndpoint ou TargetEndpoint. Vous pouvez utiliser l'interface utilisateur Edge pour effectuer cette modification dans le volet Code de la Develop (Développer) pour un proxy d'API ou modifier le fichier XML qui définit le point de terminaison ProxyEndpoint ou Point de terminaison cible.

Si vous créez FaultRules dans l'interface utilisateur de gestion, commencez par créer les stratégies à exécuter, puis les ajouter à la configuration FaultRule. (Une erreur s'affiche dans l'interface utilisateur si vous essayez d'enregistrer une règle d'erreur faisant référence à une stratégie qui n'a pas encore été créée.)

Ajout de stratégies à une FaultRule

Bien que vous puissiez placer n'importe quelle stratégie dans la règle d'erreur, vous utilisez généralement la stratégie AssignMessage pour générer un message de réponse personnalisé pour une condition d'erreur. La stratégie AssignMessage vous permet de configurer une réponse HTTP avec des éléments de charge utile, de code d'état HTTP, d'en-têtes et d'expression de motif.

L'exemple ci-dessous présente une configuration de stratégie AssignMessage type :

<AssignMessage name="fault_invalidkey">
  <Set>
      <Payload contentType="text/plain">Contact support at support@mycompany.com.</Payload>
      <StatusCode>401</StatusCode>
      <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Vous pouvez maintenant utiliser cette stratégie dans votre règle d'erreur. Notez la façon dont vous référencez la stratégie AssignMessage par nom dans la règle d'erreur :

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>fault_invalidkey</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

Lorsque vous déployez la configuration ci-dessus, le proxy d'API exécute la règle AssignMessage appelée fault_invalidkey chaque fois qu'une application présente une clé API non valide.

Vous pouvez exécuter plusieurs stratégies dans une règle d'erreur, comme illustré dans l'exemple suivant :

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>policy1</Name>
      </Step>
      <Step>
        <Name>policy2</Name>
      </Step>
      <Step>
        <Name>policy3</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

Les stratégies s'exécutent dans l'ordre défini. Par exemple, vous pouvez utiliser la stratégie MessageLogging, la stratégie ExtractVariables, la stratégie AssignMessage ou toute autre stratégie dans la règle d'erreur. Notez que le traitement de la règle d'erreur s'arrête immédiatement si l'une des situations suivantes se produit :

  • Une stratégie de la règle d'erreur entraîne une erreur.
  • Une stratégie de la règle d'erreur est de type RaiseFault.

Définir le message d'erreur personnalisé renvoyé par une règle d'erreur

Il est recommandé de définir des réponses d'erreur claires en provenance de vos API. Vous fournissez ainsi des informations cohérentes et utiles à vos clients.

L'exemple de stratégie AssignMessage suivant utilise les tags <Payload>, <StatusCode> et <ReasonPhase> pour définir la réponse d'erreur personnalisée renvoyée au client au niveau d'une erreur InvalidApiKey (voir l'exemple de règle d'erreur précédent).

<AssignMessage name="fault_invalidkey">
  <Set>
    <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization. 
       Contact support at support@mycompany.com.</Payload>
    <StatusCode>401</StatusCode>
    <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Cette réponse inclut les éléments suivants :

  • Charge utile contenant le message d'erreur ainsi qu'une adresse e-mail permettant de contacter l'assistance.
  • Le code d'état HTTP renvoyé dans la réponse.
  • L'expression du motif, qui est une brève description de l'erreur.

Créer une règle d'erreur par défaut

Une règle d'erreur par défaut agit comme un gestionnaire d'exceptions pour toute erreur qui n'est pas explicitement gérée par une autre règle d'erreur. Si les conditions de toutes les règles d'erreur ne correspondent pas à l'erreur, la règle d'erreur par défaut gère l'erreur. Activez la gestion des erreurs par défaut en ajoutant le tag <DefaultFaultRule> en tant qu'élément enfant d'un ProxyEndpoint ou d'un TargetEndpoint.

Par exemple, la configuration TargetEndpoint ci-dessous définit une règle d'erreur par défaut qui appelle une stratégie nommée ReturnGenericError :

<TargetEndpoint name="default">
  ...
  <FaultRules>
    ...
  </FaultRules>

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
  </DefaultFaultRule>

  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

La règle d'erreur par défaut est généralement utilisée pour renvoyer un message d'erreur générique pour toute erreur inattendue, tel qu'un message contenant les coordonnées de l'assistance technique. Cette réponse par défaut sert à la fois à fournir des informations conviviales aux développeurs tout en masquant les URL de backend ou d'autres informations susceptibles d'être utilisées pour compromettre le système.

Par exemple, vous définissez la stratégie AssignMessage suivante pour renvoyer une erreur générique :

<AssignMessage name="ReturnGenericError">
  <Set>
    <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload>
  </Set>
</AssignMessage>

Incluez l'élément <AlwaysEnforce> dans le tag <DefaultFaultRule> pour exécuter la règle d'erreur par défaut pour chaque erreur, même si une autre règle d'erreur a déjà été exécutée. La règle d'erreur par défaut est toujours la dernière règle d'erreur à s'exécuter :

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

L'une des utilisateurs de la règle DefaultFaultRule consiste à déterminer le type d'erreur qui se produit lorsque vous ne pouvez pas l'identifier autrement. Par exemple, votre proxy d'API échoue pour une erreur que vous ne parvenez pas à déterminer. Utilisez la règle DefaultFaultRule pour appeler la règle AssignMessage suivante. Cette règle écrit la valeur fault.name dans un en-tête nommé DefaultFaultHeader dans la réponse :

<AssignMessage async="false" continueOnError="false" enabled="true" name="DefaultFaultRule">
  <DisplayName>DefaultFaultRule</DisplayName>
  <Set>
    <Headers>
      <Header name="DefaultFaultHeader">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Vous pouvez ensuite afficher l'en-tête dans l'outil de trace périphérique ou dans la réponse pour voir la cause .

Ajout de la journalisation des messages à PostClientFlow

PostClientFlow est le seul flux qui s'exécute une fois que le proxy passe l'état d'erreur. Seule la règle MessageLogging peut être associée à ce flux. Elle est exécutée une fois la réponse renvoyée au client. Bien que l'association de la règle MessageLogging à ce flux ne relève techniquement pas du traitement des erreurs, vous pouvez l'utiliser pour consigner des informations en cas d'erreur. Comme il est exécuté, que le proxy ait réussi ou échoué, vous pouvez placer les règles MessageLogging dans PostClientFlow et être sûr qu'elles s'exécutent toujours.

Gérer les erreurs de stratégie dans le flux actuel

Les exemples présentés jusqu'à présent utilisent tous une règle d'erreur sur ProxyEndpoint ou TargetEndpoint pour gérer les erreurs de stratégie dans le cadre de l'état d'erreur. En effet, la valeur par défaut de l'élément continueOnError d'une stratégie est false, ce qui signifie que lorsqu'une erreur se produit dans une stratégie, le contrôle est dirigé vers l'état d'erreur. Une fois dans l'état de serreur, vous ne pouvez pas retourner le contrôle au pipeline normal et vous renvoyez généralement une forme de message d'erreur à l'application appelante.

Toutefois, si vous définissez l'élément continueOnError sur true pour une stratégie, le contrôle reste dans le flux en cours et la stratégie suivante du pipeline s'exécute une fois que la stratégie a provoqué l'erreur. L'avantage de gérer l'erreur dans le flux actuel est que vous avez peut-être un moyen de vous remettre de l'erreur pour terminer le traitement de la requête.

Voici, ci-dessous, une stratégie VerifyAPIKey nommée verify-api-key, avec l'élément continueOnError défini sur true:

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

Si la clé API est manquante ou non valide, la règle VerifyAPIKey définit la variable oauthV2.verify-api-key.failed sur true, mais le traitement se poursuit dans le flux en cours.

Vous ajoutez ensuite la stratégie VerifyAPIKey en tant qu'étape dans le pré-flux de ProxyEndpoint :

<ProxyEndpoint name="default">
  ...
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>verify-api-key</Name>
      </Step>
      <Step>
        <Name>FaultInFlow</Name>
        <Condition>(oauthV2.verify-api-key.failed = "true")</Condition>
      </Step>
    </Request>
    <Response/>
  </PreFlow>      
</ProxyEndpoint>

Notez que l'étape suivante de PreFlow utilise une condition servant à tester l'existence d'une erreur. Si une erreur s'est produite dans la règle VerifAPIKey, la règle nommée FaultInFlow s'exécute. Sinon, la règle FaultInFlow est ignorée. La règle FaultInFlow peut effectuer de nombreuses actions, telles que consigner l'erreur, tenter de la corriger ou effectuer toute autre action.

Déclencher une erreur à l'aide de la règle RaiseFault

Vous pouvez utiliser la règle RaiseFault à tout moment dans un flux pour déclencher une erreur. Lorsqu'une règle RaiseFault s'exécute, elle interrompt le flux en cours et transfère le contrôle à l'état d'erreur.

L'une des utilisateurs de la règle RaiseFault consiste à tester une condition spécifique qu'une autre règle pourrait ne pas détecter. Dans l'exemple ci-dessus, vous avez ajouté un tag <Condition> à un tag PreFlow <Step>, ce qui a entraîné l'exécution de la règle FaultInFlow si la condition est remplie. Si FaultInFlow est une règle RaiseFault, vous pouvez contrôler le transfert vers l'état d'erreur. Vous pouvez également insérer une règle RaiseFault dans un flux afin de déboguer et tester vos règles FaultRules.

Lorsqu'une stratégie RaiseFault déclenche une erreur, vous pouvez utiliser la règle d'erreur et la condition suivantes pour la traiter :

<FaultRule name="raisefault_rule">
  <Step>
    <Name>{policy_name}</Name>
  </Step>
  <Condition>(fault.name = "RaiseFault")</Condition>
</FaultRule>

Notez que la condition teste une erreur nommée RaiseFault. La règle RaiseFault définit toujours la valeur de fault.name sur RaiseFault.

Gestion personnalisée des codes d'erreur HTTP du serveur cible

Les exemples présentés dans les sections précédentes s'appliquent aux erreurs créées par les règles. Toutefois, vous pouvez également créer une réponse personnalisée pour les erreurs de niveau transport, ce qui signifie que les erreurs HTTP sont renvoyées par le serveur cible. Pour contrôler la réponse à partir d'une erreur HTTP, configurez un TargetEndpoint pour traiter les codes de réponse HTTP.

Par défaut, Edge traite les codes de réponse HTTP de la plage 1xx-3xx comme « succès » et HTTP codes de réponse compris dans la plage 4xx-5xx comme « échec ». Cela signifie que toute réponse du service de backend ayant un code de réponse HTTP 4xx-5xx appelle automatiquement l'état d'erreur, qui renvoie alors un message d'erreur directement au client demandeur.

Vous pouvez créer des gestionnaires personnalisés pour tous les codes de réponse HTTP. Par exemple, vous pouvez souhaiter traiter seulement les codes de réponse HTTP 5xx comme des erreurs, et non la totalité de la plage 4xx-5xx. Vous pouvez aussi renvoyer des messages d'erreur personnalisés pour les codes de réponse HTTP 400 et 500.

Dans l'exemple suivant, vous utilisez la propriété success.codes afin de configurer le TargetEndpoint pour qu'il traite les codes de réponse HTTP 400 et 500 en tant que réussite, comme les codes HTTP par défaut. En traitant ces codes comme une réussite, le TargetEndpoint prend le relais du traitement du message de réponse, au lieu d'appeler l'état d'erreur :

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <Properties>
          <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Comme vous pouvez le voir dans cet exemple, vous pouvez utiliser des caractères génériques pour définir la propriété success.codes sur une plage de valeurs.

La définition de la propriété success.codes écrase les valeurs par défaut. Par conséquent, si vous souhaitez ajouter le code HTTP 400 à la liste des codes de réussite par défaut, définissez cette propriété comme suit :

<Property name="success.codes">1xx,2xx,3xx,400</Property>

Toutefois, si vous souhaitez uniquement que le code HTTP 400 soit traité comme un code de réussite, définissez la propriété comme suit :

<Property name="success.codes">400</Property>

Vous pouvez maintenant définir des gestionnaires personnalisés pour les codes de réponse HTTP 400 et 500 afin de renvoyer un message de réponse personnalisé à l'application à l'origine de la requête. Le TargetEndpoint suivant utilise la stratégie ReturnError pour gérer les codes de réponse HTTP 400 et 500 :

<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request/>
    <Response>
      <Step>
        <Name>ReturnError</Name>
        <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition>
      </Step>
    </Response>
  </PreFlow>

  <HTTPTargetConnection>
    <Properties>
      <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Cette configuration TargetEndpoint amène la stratégie appelée ReturnError à gérer la réponse chaque fois que le TargetEndpoint rencontre un code de réponse HTTP de 400 ou 500.

Classification des défaillances

Les services d'API regroupent les erreurs dans les catégories et sous-catégories suivantes.

Category Sous-catégorie Nom de l'erreur Description
Messaging Échecs qui se produisent pendant le flux de messages (échec de stratégie non inclus)
Erreurs personnalisées {fault_name} Toutes les erreurs explicitement gérées par le proxy d'API à l'aide de la stratégie RaiseFault
Codes de réponse InternalServerError, NotFound Codes d'erreur HTTP 5xx, 4xx
Échecs de routage NoRoutesMatched Échec de la sélection d'un TargetEndpoint nommé pour une requête
Échecs de classification NotFound Échecs provoqués par un URI de requête qui ne correspond à aucun BasePath pour des configurations ProxyEndpoint (c'est-à-dire qu'aucun proxy d'API ne correspond à l'URL dans la requête de l'application cliente)
Transport Erreurs au niveau du transport HTTP
Connectivité ConnectionRefused, ConnectionReset, ConnectionTimeout Échecs lors de l'établissement de connexions au niveau du réseau ou du transport
Validations des requêtes ContentLengthMissing, HostHeaderMissing Des erreurs se produisent lors des vérifications sémantiques de chaque requête
Validations des réponses Des erreurs se produisent lors des vérifications sémantiques de chaque réponse
Erreurs d'E/S SSLHandshakeError, ReadTimeout, ReadError, WriteTimeout, WriteError, ChunkError Erreurs de lecture/écriture sur les points de terminaison client ou cibles, les délais avant expiration, les erreurs TLS/SSL et les erreurs fragmentées
Système Erreurs d'exécution non définies
Mémoire OutOfMemory, GCOverLimit Défaillances liées à la mémoire
Thread RogueTaskTerminated Échecs tels que l'arrêt de tâches sur lesquelles le contrôle est perdu
Règle Les erreurs pour chaque type de stratégie sont définies dans la documentation de référence sur les stratégies.

Une erreur est toujours accompagnée d'une description textuelle du motif de l'échec. Lorsque le système génère une erreur, un ensemble d'attributs sont renseignés pour vous aider au dépannage. Un échec inclut les informations suivantes :

  • Motif
  • Attributs personnalisés définis par l'utilisateur