Règle de génération d'erreur

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

Consultez la documentation d'Apigee Edge.

Quoi

Génère un message personnalisé en réponse à une condition d'erreur. Utilisez RaiseFault pour définir une réponse d'erreur renvoyée à l'application à l'origine de la requête lorsqu'une condition spécifique se produit.

Cette règle est une règle standard qui peut être déployée sur n'importe quel type d'environnement. Pour en savoir plus sur les types de règles et la disponibilité avec chaque type d'environnement, consultez la section Types de règles.

Pour obtenir des informations générales sur la gestion des pannes, consultez la page Gérer les défaillances.

Exemples

Renvoie FaultResponse

Dans l'utilisation la plus courante, RaiseFault est utilisée pour renvoyer une réponse d'erreur personnalisée à l'application à l'origine de la demande. Par exemple, cette règle renvoie un code d'état 404 sans charge utile :

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
   </Set>
 </FaultResponse>
</RaiseFault>

Renvoie la charge utile FaultResponse

Un exemple plus complexe consiste à renvoyer une charge utile de réponse d'erreur personnalisée, ainsi que des en-têtes HTTP et un code d'état HTTP. Dans l'exemple suivant, la réponse d'erreur est remplie avec un message XML contenant le code d'état HTTP reçu par Apigee du service de backend, et un en-tête contenant le type de défaillance qui s'est produit :

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact [e-mail]</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

Pour obtenir la liste de toutes les variables disponibles pour renseigner de manière dynamique les messages d'erreur FaultResponse, consultez la documentation de référence sur les variables.

Gérer les erreurs d'appel de service

Exemple : Apprenez par la pratique !
Cet exemple Découvrir Apigee vous montre comment vérifier le code HTTP dans une réponse à un appel de service et générer une exception personnalisée en fonction de la valeur du code. L'exemple renvoie un message d'erreur personnalisé lorsque le service cible renvoie un état 404. Il vous suffit de cloner le dépôt et de suivre les instructions de cet article. L'exemple illustre un modèle courant pour la gestion des erreurs d'appel de service. .

---

À propos de la règle RaiseFault

Apigee vous permet d'effectuer un traitement personnalisé des exceptions à l'aide d'une règle de type RaiseFault. La règle RaiseFault, semblable à la règle AssignMessage, vous permet de générer une réponse d'erreur personnalisée en réponse à une condition d'erreur.

Utilisez la règle RaiseFault pour définir une réponse d'erreur renvoyée à l'application à l'origine de la requête lorsqu'une condition d'erreur spécifique se produit. La réponse d'erreur peut être composée d'en-têtes HTTP, de paramètres de requête et d'une charge utile du message. Une réponse d'erreur personnalisée peut être plus utile pour les développeurs d'applications et pour les utilisateurs finaux que les messages d'erreur génériques ou les codes de réponse HTTP.

Lorsqu'elle est exécutée, la stratégie RaiseFault transfère le contrôle du flux actuel vers le flux Error, qui renvoie ensuite la réponse d'erreur désignée à l'application cliente à l'origine de la requête. Lorsque le flux de messages bascule vers le flux d'erreurs, aucun traitement supplémentaire de la stratégie n'est effectué. Toutes les étapes de traitement restantes sont ignorées, et la réponse d'erreur est directement renvoyée à l'application à l'origine de la requête.

Vous pouvez utiliser RaiseFault dans un ProxyEndpoint ou un TargetEndpoint. Vous associerez généralement une condition à la règle RaiseFault. Une fois la règle RaiseFault exécutée, Apigee effectue un traitement des erreurs standard en évaluant les règles d'erreur. Si aucune règle d'erreur n'est définie, Apigee arrête le traitement de la requête.

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

La référence d'élément décrit les éléments et les attributs de la règle RaiseFault.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">
    <DisplayName>RaiseFault 1</DisplayName>
    <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

Attributs <RaiseFault>

<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-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 <IgnoreUnresolvedVariables>

(Facultatif) Ignore toutes les erreurs de variable non résolues dans le flux. Valeurs valides : vrai/faux. Valeur par défaut : true.

Élément <FaultResponse>

(Facultatif) Définit le message de réponse renvoyé au client à l'origine de la requête. FaultResponse utilise les mêmes paramètres que la règle AssignMessage.

Élément <FaultResponse><AssignVariable>

Attribue une valeur à une variable de flux de destination. Si la variable de flux n'existe pas, AssignVariable la crée.

Par exemple, utilisez le code suivant pour définir la variable nommée myFaultVar dans la règle RaiseFault :

<FaultResponse>
  <AssignVariable>
    <Name>myFaultVar</Name>
    <Value>42</Value>
  </AssignVariable>
  ...
</FaultResponse>

Vous pouvez ensuite référencer ultérieurement cette variable dans les modèles de message dans la règle RaiseFault. En outre, une règle associée à une règle d'erreur peut ensuite accéder à la variable. Par exemple, la règle AssignMessage suivante utilise la variable définie dans RaiseFault pour définir un en-tête dans la réponse d'erreur :

<AssignMessage enabled="true" name="Assign-Message-1">
  <Add>
    <Headers>
      <Header name="newvar">{myFaultVar}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Le <AssignVariable> de la règle RaiseFault utilise la même syntaxe que l'élément <AssignVariable> de la règle AssignMessage.

Élément <FaultResponse><Add>/<Headers>

Ajoute des en-têtes HTTP au message d'erreur. Notez que l'en-tête vide <Add><Headers/></Add> n'ajoute aucun en-tête. Cet exemple copie la valeur de la variable de flux request.user.agent dans l'en-tête.

L'élément <Header> accepte la fonctionnalité de substitution de chaîne de variable appelée modélisation de message.

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

Valeur par défaut :	N/A
Présence :	Facultatif
Type :	Chaîne

Élément <FaultResponse><Copy>

Copie les informations depuis le message spécifié par l'attribut source vers le message d'erreur.

    <Copy source="request">
        <Headers/>
        <StatusCode/>
    </Copy>

Valeur par défaut :	N/A
Présence :	Facultatif
Type :	Chaîne

Attributs

 <Copy source="response">

Attribut	Description	Presence	Type
source	Spécifie l'objet source de la copie. Si la source n'est pas spécifiée, l'objet est traité comme un message simple. Par exemple, si la règle se trouve dans le flux de requête, la source est définie par défaut sur l'objet de requête. Si la règle se trouve dans le flux de réponse, elle utilise par défaut l'objet de réponse. Si vous omettez la source, vous pouvez utiliser une référence absolue à une variable de flux en tant que source de la copie. Par exemple, spécifiez la valeur en tant que {request.header.user-agent}. Si la variable source ne peut pas être résolue ou est associée à un type qui n'est pas un message, <Copy> ne répond pas.	Facultatif	Chaîne

Élément <FaultResponse><Copy>/<Headers>

Copie l'en-tête HTTP spécifié depuis la source vers le message d'erreur. Pour copier tous les en-têtes, spécifiez <Copy><Headers/></Copy>..

<Copy source='request'>
    <Headers>
        <Header name="headerName"/>
    </Headers>
</Copy>

Si plusieurs en-têtes portent le même nom, utilisez la syntaxe suivante :

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

Cet exemple copie "h1", "h2" et la deuxième valeur de "h3". Si "h3" n'a qu'une seule valeur, le paramètre n'est pas copié.

Valeur par défaut :	N/A
Présence :	Facultatif
Type :	Chaîne

Élément <FaultResponse><Copy>/<StatusCode>

Code d'état HTTP à copier depuis l'objet spécifié par l'attribut source vers le message d'erreur.

<Copy source='response'>
    <StatusCode>404</StatusCode>
</Copy>

Valeur par défaut :	false
Présence :	Facultatif
Type :	Chaîne

Élément <FaultResponse><Remove>/<Headers>

Supprime les en-têtes HTTP spécifiés du message d'erreur. Pour supprimer tous les en-têtes, spécifiez <Remove><Headers/></Remove>. Cet exemple supprime l'en-tête user-agent du message.

<Remove>
    <Headers>
        <Header name="user-agent"/>
    </Headers>
</Remove>

Si plusieurs en-têtes portent le même nom, utilisez la syntaxe suivante :

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

Cet exemple copie "h1", "h2" et la deuxième valeur de "h3". Si "h3" n'a qu'une seule valeur, le paramètre n'est pas supprimé.

Valeur par défaut :	N/A
Présence :	Facultatif
Type :	Chaîne

Élément <FaultResponse><Set>

Définit les informations dans le message d'erreur.

Les sous-éléments de <Set> sont compatibles avec la fonctionnalité de substitution de chaîne dynamique appelée modélisation de message.

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
    </Set>

Valeur par défaut :	N/A
Présence :	Facultatif
Type :	ND

Élément <FaultResponse>/<Set>/<Headers>

Définit ou remplace les en-têtes HTTP dans le message d'erreur. Notez que l'en-tête vide <Set><Headers/></Set> ne définit aucun en-tête. Cet exemple définit l'en-tête user-agent sur la variable de message spécifiée avec l'élément <AssignTo>.

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
</Set>

Valeur par défaut :	N/A
Présence :	Facultatif
Type :	Chaîne

Élément <FaultResponse>/<Set>/<Payload>

Définit la charge utile du message d'erreur.

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

Définissez une charge utile JSON :

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

Dans une charge utile JSON, vous pouvez insérer des variables à l'aide des attributs variablePrefix et variableSuffix avec des caractères délimiteurs, comme illustré dans l'exemple suivant.

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

À partir de la version 16.08.17, vous pouvez également les insérer entre des accolades :

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

Définissez une charge utile mixte en XML :

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

Valeur par défaut :
Présence :	Facultatif
Type :	Chaîne

Attributs

 <Payload contentType="content_type" variablePrefix="char" variableSuffix="char">

Attribut	Description	Presence	Type
contentType	Si contentType est spécifié, sa valeur est attribuée à l'en-tête Content-Type.	Facultatif	Chaîne
variablePrefix	Spécifie éventuellement le délimiteur de premier niveau sur une variable de flux, car les charges utiles JSON ne peuvent pas utiliser le caractère par défaut "{".	Facultatif	Caractère
variableSuffix	Spécifie éventuellement le délimiteur final sur une variable de flux, car les charges utiles JSON ne peuvent pas utiliser le caractère "}" par défaut.	Facultatif	Caractère

Élément <FaultResponse>/<Set>/<StatusCode>

Définit le code d'état sur la réponse.

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

Valeur par défaut :	false
Présence :	Facultatif
Type :	Booléen

Élément <ShortFaultReason>

Spécifie d'afficher un motif de défaillance court dans la réponse :

<ShortFaultReason>true|false</ShortFaultReason>

Par défaut, la raison de l'erreur dans la réponse de la stratégie est la suivante :

"fault":{"faultstring":"Raising fault. Fault name : Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

Pour rendre le message plus lisible, vous pouvez définir l'élément <ShortFaultReason> sur "true" pour raccourcir faultstring uniquement pour le nom de la stratégie :

"fault":{"faultstring":"Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

Valeurs valides : true/false(default).

Valeur par défaut :	false
Présence :	Facultatif
Type :	Booléen

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. Les variables de flux prédéfinies suivantes sont disponibles après l'exécution d'une règle RaiseFault. Pour en savoir plus sur les variables de flux, consultez la documentation de référence sur les variables.

Variable	Type	Autorisation	Description
fault.name	Chaîne	En lecture seule	Lorsque la règle RaiseFault s'exécute, cette variable est toujours définie sur la chaîne RaiseFault.
fault.type	Chaîne	En lecture seule	Renvoie le type de défaillance dans l'erreur et, s'il n'est pas disponible, une chaîne vide.
fault.category	Chaîne	En lecture seule	Renvoie le type de défaillance dans l'erreur et, s'il n'est pas disponible, une chaîne vide.

Exemple d'utilisation de RaiseFault

L'exemple suivant utilise une condition pour appliquer la présence d'un objet queryparam portant le nom zipcode à la requête entrante. Si queryparam n'est pas présent, le flux génère une erreur via RaiseFault :

<Flow name="flow-1">
  <Request>
    <Step>
        <Name>RF-Error-MissingQueryParam</Name>
        <Condition>request.queryparam.zipcode = null</Condition>
    </Step>
   ...
   </Request>
   ...
   <Condition>(proxy.pathsuffix MatchesPath "/locations") and (request.verb = "GET")</Condition>
</Flow>

Voici ce qui se trouve dans RaiseFault :

<RaiseFault name='RF-Error-MissingQueryParam'>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType='application/json'>{
  "error" : {
    "code" : 400.02,
    "message" : "invalid request. Pass a zipcode queryparam."
  }
}
</Payload>
      <StatusCode>400</StatusCode>
    </Set>
  </FaultResponse>
</RaiseFault>

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.

Code d'erreur	État HTTP	Cause
steps.raisefault.RaiseFault	500	Voir la chaîne d'erreur.

Erreurs de déploiement

Aucune.

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Variables	Lieu	Exemple
fault.name="fault_name"	fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur.	fault.name = "RaiseFault"
raisefault.policy_name.failed	policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur.	raisefault.RF-ThrowError.failed = true

Exemple de réponse d'erreur

Remarque : Pour le traitement des erreurs, la meilleure pratique consiste à intercepter la partie errorcode de la réponse. Ne vous fiez pas au texte dans faultstring, car il pourrait changer.

{
   "fault":{
      "detail":{
         "errorcode":"steps.raisefault.RaiseFault"
      },
      "faultstring":"Raising fault. Fault name: [name]"
   }
}

Schéma

Chaque type de règle est défini par un schéma XML (.xsd). Pour référence, des schémas de règles sont disponibles sur GitHub.

Articles associés

Consultez la page Gérer les erreurs.