RaiseFault-Richtlinie

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

Was

Generiert eine benutzerdefinierte Nachricht als Reaktion auf eine Fehlerbedingung. Verwenden Sie RaiseFault, um eine Fehlerantwort zu definieren, die an die anfragende Anwendung zurückgegeben wird, wenn eine bestimmte Bedingung auftritt.

Allgemeine Informationen zum Umgang mit Fehlern finden Sie unter Fehlerbehandlung.

Samples

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

Informationen zur RaiseFault-Richtlinie

Apigee Edge bietet Ihnen die Möglichkeit, eine benutzerdefinierte Ausnahmebehandlung mithilfe einer Richtlinie vom Typ IncreaseFault durchzuführen. Mit der Richtlinie IncreaseFault, die der AssignMessage-Richtlinie ähnelt, können Sie eine benutzerdefinierte Fehlerantwort als Reaktion auf eine Fehlerbedingung generieren.

Mit der RaiseFault-Richtlinie definieren Sie eine Fehlerantwort, die an die anfragende Anwendung zurückgegeben wird, wenn eine bestimmte Fehlerbedingung auftritt. Die Fehlerantwort kann aus HTTP-Headern, Abfrageparameter und einer Nachrichtennutzlast bestehen. Eine benutzerdefinierte Fehlerantwort kann für Anwendungsentwickler und Endnutzer von Anwendungen hilfreicher sein als allgemeine Fehlermeldungen oder HTTP-Antwortcodes.

Bei der Ausführung überträgt die RaiseFault-Richtlinie die Steuerung vom aktuellen Ablauf an den Fehlerablauf, der dann die festgelegte Fehlerantwort an die anfragende Clientanwendung zurückgibt. Wenn der Nachrichtenablauf zum Fehlerablauf wechselt, erfolgt keine weitere Richtlinienverarbeitung. Alle verbleibenden Verarbeitungsschritte werden umgangen und die Fehlerantwort wird direkt an die anfordernde Anwendung zurückgegeben.

Sie können RaiseFault in einem ProxyEndpoint oder TargetEndpoint verwenden. Normalerweise hängen Sie eine Bedingung an die RaiseFault-Richtlinie an. Nach dem Ausführen von RaiseFault führt Apigee eine normale Fehlerverarbeitung sowie eine Auswertung von FaultRules aus. Wenn keine Fehlerregeln definiert sind, wird die Verarbeitung der Anfrage beendet.

Elementverweis

Die Elementreferenz beschreibt die Elemente und Attribute der RaiseFault-Richtlinie.

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

<RaiseFault>-Attribute

<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">

In der folgenden Tabelle werden Attribute beschrieben, die für alle übergeordneten Richtlinienelemente gelten:

<DisplayName>-Element

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

<DisplayName>Policy Display Name</DisplayName>

<IgnoreUnresolvedVariables>-Element

(Optional) Ignorieren Sie eventuelle nicht behobene Variablenfehler im Ablauf. Gültige Werte: true/false. Standard true.

<FaultResponse>-Element

(Optional) Definiert die Antwortnachricht, die an den anfordernden Client zurückgegeben wird. FaultResponse verwendet die gleichen Einstellungen wie die AssignMessage-Richtlinie (nicht in Apigee Edge für Private Cloud verfügbar).

<FaultResponse><AssignVariable>-Element

Weist einer Zielablaufvariable einen Wert zu. Wenn die Ablaufvariable nicht vorhanden ist, wird sie von AssignVariable erstellt.

Verwenden Sie beispielsweise den folgenden Code, um die Variable myFaultVar in der RaiseFault-Richtlinie festzulegen:

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

Sie können auf diese Variable dann später in Nachrichtenvorlagen in der RaiseFault-Richtlinie verweisen. Außerdem kann eine an eine FaultRule angehängte Richtlinie dann auf die Variable zugreifen. Die folgende AssignMessage-Richtlinie verwendet beispielsweise die in RaiseFault festgelegte Variable, um einen Header in der Fehlerantwort festzulegen:

<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> in der RaiseFault-Richtlinie verwendet die gleiche Syntax wie das Element <AssignVariable> in der AssignMessage-Richtlinie. Beachten Sie, dass diese Funktionalität derzeit in Apigee Edge für Private Cloud nicht verfügbar ist.

Element <FaultResponse><Add>/<Headers>

Fügt HTTP-Header zur Fehlermeldung hinzu. Der leere Header <Add><Headers/></Add> fügt keinen Header hinzu. In diesem Beispiel wird der Wert der Ablaufvariable request.user.agent in den Header kopiert.

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

<FaultResponse><Copy>-Element

Kopiert Informationen von der durch das Attribut source angegebenen Nachricht an die Fehlermeldung.

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

Attribute

 <Copy source="response">

Element <FaultResponse><Copy>/<Headers>

Kopiert den angegebenen HTTP-Header aus der Quelle in die Fehlermeldung. Geben Sie <Copy><Headers/></Copy>. zum Kopieren aller Header an.

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

Wenn es mehrere Header mit demselben Namen gibt, verwenden Sie die folgende Syntax:

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

In diesem Beispiel werden "h1", "h2" und der zweite Wert von "h3" kopiert. Wenn "h3" nur einen Wert hat, wird dieser nicht kopiert.

Element <FaultResponse><Copy>/<StatusCode>

Der HTTP-Statuscode zum Kopieren aus dem vom Quellattribut angegebenen Objekt in die Fehlermeldung.

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

Element <FaultResponse><Copy>/<ReasonPhrase>

Der Grund für den Kopiervorgang aus dem durch das Quellattribut angegebenen Objekt in die Fehlermeldung.

<Copy source='response'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>     
</Copy>

Element <FaultResponse><Remove>/<Headers>

Entfernt angegebene HTTP-Header aus der Fehlermeldung. Wenn Sie alle Header entfernen möchten, geben Sie <Remove><Headers/></Remove> an. In diesem Beispiel wird der Header user-agent aus der Nachricht entfernt.

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

Wenn es mehrere Header mit demselben Namen gibt, verwenden Sie die folgende Syntax:

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

In diesem Beispiel werden "h1", "h2" und der zweite Wert von "h3" entfernt. Wenn "h3" nur einen Wert hat, wird er nicht entfernt.

<FaultResponse><Set>-Element

Legt Informationen in der Fehlermeldung fest.

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

Element <FaultResponse>/<Set>/<Headers>

Legt HTTP-Header in der Fehlermeldung fest oder überschreibt diese. Beachten Sie, dass der leere Header <Set><Headers/></Set> keinen Header festlegt. In diesem Beispiel wird der Header user-agent auf die Nachrichtenvariable gesetzt, die mit dem Element <AssignTo> angegeben wird.

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

<FaultResponse>/<Set>/<Payload>-Element

Legt die Nutzlast der Fehlermeldung fest.

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

Legen Sie eine JSON-Nutzlast fest:

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

In einer JSON-Nutzlast können Sie mithilfe der Attribute variablePrefix und variableSuffix Variablen mit Trennzeichen einfügen, wie im folgenden Beispiel gezeigt.

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

Ab Cloud Release Version 16.08.17 können Sie auch geschweifte Klammern verwenden, um Variablen einzufügen:

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

Legen Sie eine gemischte Nutzlast in XML fest:

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

Attribute

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

Element <FaultResponse>/<Set>/<StatusCode>

Legt den Statuscode der Antwort fest.

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

Element <FaultResponse>/<Set>/<ReasonPhrase>

Legt die Grundphrase für die Antwort fest.

<Set source='request'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</Set>

<ShortFaultReason>-Element

Gibt an, dass eine kurze Fehlerursache in der Antwort angezeigt werden soll:

<ShortFaultReason>true|false</ShortFaultReason>

Der Fehlergrund in der Antwort der Richtlinie ist standardmäßig:

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

Für eine bessere Lesbarkeit der Nachricht können Sie das Element <ShortFaultReason> auf "true" setzen, um faultstring auf den Richtliniennamen zu kürzen:

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

Gültige Werte: true/false(default).

Ablaufvariablen

Ablaufvariablen ermöglichen ein dynamisches Verhalten von Richtlinien und Abläufen zur Laufzeit, basierend auf HTTP-Headern, Nachrichteninhalten oder dem Ablaufkontext. Die folgenden vordefinierten Ablaufvariablen sind verfügbar, nachdem eine RaiseFault-Richtlinie ausgeführt wurde. Weitere Informationen zu Ablaufvariablen finden Sie in der Variablenreferenz.

Beispiel für die Verwendung von RaiseFault

Im folgenden Beispiel wird eine Bedingung verwendet, um das Vorhandensein eines queryparam mit dem Namen zipcode in der eingehenden Anfrage zu erzwingen. Wenn queryparam nicht vorhanden ist, löst der Ablauf einen Fehler über RaiseFault aus:

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

Fehlerreferenz

In diesem Abschnitt werden die Fehlercodes und Fehlermeldungen beschrieben, die zurückgegeben werden, sowie die Fehlervariablen, die von Edge festgelegt werden, wenn diese Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Bereitstellungsfehler

–

Fehlervariablen

Diese Variablen werden bei Laufzeitfehlern festgelegt. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Beispiel für eine Fehlerantwort

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

Schema

Jeder Richtlinientyp wird durch ein XML-Schema (.xsd) definiert. Zu Referenzzwecken sind Richtlinienschemas auf GitHub verfügbar.

Weitere Informationen

Siehe Umgang mit Fehlern.