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

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

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.

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

Samples

Renvoie FaultResponse

Dans l'utilisation la plus courante, GenerateFault est utilisée pour renvoyer une réponse d'erreur personnalisée à l'application à l'origine de la requête. Par exemple, cette stratégie renverra un code d'état 404 sans charge utile:

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
     <ReasonPhrase>The resource requested was not found</ReasonPhrase>
   </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 d'un message XML contenant le code d'état HTTP reçu par Edge du service de backend et d'un en-tête contenant le type d'erreur survenue:

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact support@company.com</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
     <ReasonPhrase>Server error</ReasonPhrase>
   </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


À propos de la règle RaiseFault

Apigee Edge vous permet d'effectuer un traitement personnalisé des exceptions à l'aide d'une règle de type AugmenteFault. La stratégie ResolveFault, semblable à la règleAssignMessage, 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/>
            <ReasonPhrase/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <ReasonPhrase/>
            <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 Présence
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.

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.

Présence 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ègleAssignMessage (non disponible dans Apigee Edge pour Cloud privé).

É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>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

<AssignVariable> dans la règle RaiseFault utilise la même syntaxe que l'élément <AssignVariable> de la règle AssignMessage. Notez que cette fonctionnalité n'est actuellement pas disponible dans Apigee Edge for Private Cloud.

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

<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/>
        <ReasonPhrase/>
    </Copy>

Valeur par défaut :

N/A

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 :

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><Copy>/<ReasonPhrase>

Description du motif à copier depuis l'objet spécifié par l'attribut source dans le message d'erreur.

<Copy source='response'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>     
</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.

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

Valeur par défaut :

N/A

Présence :

Facultatif

Type :

N/A

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

false

Présence :

Facultatif

Type :

Booléen

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

Définit l'expression de motif sur la réponse.

<Set source='request'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</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 Augmente Fault :
<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>
      <ReasonPhrase>Bad Request</ReasonPhrase>
    </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, ainsi que les variables d'erreur définies par Edge lorsque cette stratégie 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 Où : 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 stratégie qui a généré l'erreur. raisefault.RF-ThrowError.failed = true

Exemple de réponse d'erreur

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