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

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur 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.

Exemples

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
     <ReasonPhrase>The resource requested was not found</ReasonPhrase>
   </Set>
 </FaultResponse>
</RaiseFault>

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

À 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 RaiseFault. La stratégie RaiseFault, qui est 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/>
            <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 :

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

É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 (non disponible dans Apigee Edge pour Private Cloud).

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

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

Attributs

 <Copy source="response">

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

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

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

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

Élément <FaultResponse><Set>

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

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

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

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

Attributs

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

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

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

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

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

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

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.

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>

<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 qui sont définis par Edge 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.

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.

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.