RaiseFault-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Richtliniensymbol

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.

Diese Richtlinie ist eine Standardrichtlinie, die in jeder Umgebung bereitgestellt werden kann. Nicht alle Nutzer müssen Richtlinien- und Umgebungstypen kennen. Informationen zu Richtlinientypen und zur Verfügbarkeit bei jedem Umgebungstyp finden Sie unter Richtlinientypen.

Allgemeine Informationen zur Fehlerbehebung finden Sie unter Umgang mit Fehlern.

Beispiele

FaultResponse zurückgeben

In der häufigsten Verwendung wird RaiseFault verwendet, um eine benutzerdefinierte Fehlerantwort an die anfragende Anwendung zurückzugeben. Die Richtlinie gibt beispielsweise den Statuscode 404 ohne Nutzlast zurück:

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
   </Set>
 </FaultResponse>
</RaiseFault>

FaultResponse-Nutzlast zurückgeben

Ein komplexeres Beispiel umfasst die Rückgabe einer benutzerdefinierten Fehlerantwort, zusammen mit HTTP-Headern und einem HTTP-Statuscode. Im folgenden Beispiel wird die Fehlerantwort mit einer XML-Nachricht gefüllt, die den von dem Back-End-Dienst empfangenen HTTP-Statuscode und einen Header mit dem aufgetretenen Fehlertyp enthält:

<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>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

Eine Liste aller Variablen, die für das dynamische Einfügen von FaultResponse-Nachrichten verfügbar sind, finden Sie unter Variablenreferenz.

Fehler bei Service-Callouts verarbeiten

Informationen zur RaiseFault-Richtlinie

Mit Apigee können Sie benutzerdefinierte Ausnahmen mithilfe einer Richtlinie vom Typ "RaiseFault" ausführen. Mit der RaiseFault-Richtlinie, die der AssignMessage-Richtlinie ähnelt, können Sie eine benutzerdefinierte Fehlerantwort als Reaktion auf einen Fehler 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/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <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:

Attribut Beschreibung Standard Präsenz
name

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

 – Erforderlich
continueOnError

Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten.

Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Siehe auch:

 falsch Optional
enabled

Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen.

Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.

 true Optional
async

Dieses Attribut wurde verworfen.

 false Verworfen

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

–

Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.
Präsenz Optional
Typ String

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

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

<AssignVariable> in der AssignMessage-Richtlinie.

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

Standard:

 –

Präsenz:

 Optional

Typ:

 String

<FaultResponse><Copy>-Element

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

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

Standard:

–

Präsenz:

Optional

Typ:

String

Attribute

 <Copy source="response">
Attribut Beschreibung Präsenz Typ
Quelle

Gibt das Quellobjekt der Kopie an.

  • Wenn source nicht angegeben wird, wird sie als einfache Nachricht behandelt. Befindet sich die Richtlinie beispielsweise im Anfrageablauf, verwendet die Quelle standardmäßig das Objekt request. Wenn sich die Richtlinie im Antwortablauf befindet, wird standardmäßig das Objekt response verwendet. Wenn Sie source weglassen, können Sie eine absolute Referenz auf eine Ablaufvariable als Quelle der Kopie verwenden. Geben Sie beispielsweise den Wert als {request.header.user-agent} an.
  • Wenn die Quellvariable nicht aufgelöst werden kann oder in einen nicht-Nachrichtentyp aufgelöst wird, reagiert <Copy> nicht.
 Optional String

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

Standard:

–

Präsenz:

 Optional

Typ:

String

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

Standard:

 false

Präsenz:

 Optional

Typ:

 String

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

Standard:

 –

Präsenz:

 Optional

Typ:

 String

<FaultResponse><Set>-Element

Legt Informationen in der Fehlermeldung fest.

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

Standard:

 –

Präsenz:

 Optional

Typ:

 –

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

Standard:

 –

Präsenz:

 Optional

Typ:

 String

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

Standard:

Präsenz:

 Optional

Typ:

 String

Attribute

 <Payload contentType="content_type" variablePrefix="char" variableSuffix="char">
Attribut Beschreibung Präsenz Typ
contentType

Wenn "contentType" angegeben ist, wird ihr Wert dem Header Content-Type zugewiesen.

 Optional String
variablePrefix Gibt optional das führende Trennzeichen für eine Ablaufvariable an, da JSON-Nutzlasten nicht das Standardzeichen "{" verwenden können. Optional Char
variableSuffix Gibt optional das abschließende Trennzeichen für eine Ablaufvariable an, weil JSON-Nutzlasten nicht das Standardzeichen "}" verwenden können. Optional Char

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

Legt den Statuscode der Antwort fest.

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

Standard:

 false

Präsenz:

 Optional

Typ:

 Boolesch

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

Standard:

 false

Präsenz:

 Optional

Typ:

 Boolesch

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.

Variable Typ Berechtigung Beschreibung
fault.name String Schreibgeschützt: Wenn die RaiseFault-Richtlinie ausgeführt wird, wird diese Variable immer auf den String RaiseFault gesetzt.
fault.type String Schreibgeschützt: Gibt den Fehlertyp im Fehler zurück und, falls nicht verfügbar, einen leeren String.
fault.category String Schreibgeschützt: Gibt die Fehlerkategorie im Fehler und, falls nicht verfügbar, einen leeren String zurück.

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>
 Im Folgenden wird gezeigt, was in RaiseFault enthalten wäre: 
<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>

Fehlerreferenz

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die 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.

Fehlercode HTTP-Status Ursache
steps.raisefault.RaiseFault 500 Siehe Fehlerstring.

Bereitstellungsfehler

–

Fehlervariablen

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

Variablen Wo Beispiel
fault.name="fault_name" fault_name ist der Name des Fehlers, der in der obigen Tabelle Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name = "RaiseFault"
raisefault.policy_name.failed policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. raisefault.RF-ThrowError.failed = true

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.