RaiseFault-Richtlinie

<ph type="x-smartling-placeholder"></ph> Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie 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.

Beispiele

<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

Mit Apigee Edge können Sie eine benutzerdefinierte Ausnahmebehandlung mit einer Richtlinie vom Typ RaiseFault ausführen. Die RaiseFault-Richtlinie, die der Methode AssignMessage-Richtlinie, können Sie eine benutzerdefinierte Fehlerantwort als Antwort 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 verfügbar in Apigee Edge für Private Cloud).

<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 Funktion ist derzeit in Apigee Edge für Private Cloud nicht verfügbar.

<FaultResponse><Add>/<Headers>-Element

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

<FaultResponse><Copy>/<Headers>-Element

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.

<FaultResponse><Copy>/<StatusCode>-Element

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

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

<FaultResponse><Copy>/<ReasonPhrase>-Element

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>

<FaultResponse><Remove>/<Headers>-Element

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>

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

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

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

Legt den Statuscode der Antwort fest.

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

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

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

Dieser Abschnitt beschreibt die zurückgegebenen Fehlercodes und Fehlermeldungen 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.