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

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

Consultez la documentation d'Apigee Edge.

Événement

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. Tous les utilisateurs n'ont pas besoin de connaître les types de règles et d'environnements. 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">

The following table describes attributes that are common to all policy parent elements:

Attribute	Description	Default	Presence
name	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
continueOnError	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	false	Optional
enabled	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
async	This attribute is deprecated.	false	Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Default	N/A If you omit this element, the value of the policy's name attribute is used.
Presence	Optional
Type	String

É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>

<AssignVariable> dans 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 :	ND
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 :	ND
Présence :	Facultatif
Type :	Chaîne

Attributs

 <Copy source="response">

Attribut	Description	Présence	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 :	ND
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 :	faux
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 :	ND
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 :	ND
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 :	ND
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	Présence	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 :	faux
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 :	faux
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	Permission	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.
type de défaillance	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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
steps.raisefault.RaiseFault	500	See fault string.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name = "RaiseFault"
raisefault.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	raisefault.RF-ThrowError.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
   "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.