RaiseFault-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

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. 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	Presence
`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: Fehlerregeln werden NUR im Fehlerzustand ausgelöst (über continueOnError) Umgang mit Fehlern im aktuellen Ablauf	false	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

Standard	– Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs `name` der Richtlinie verwendet.
Presence	Optional
Typ	String

–

Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.

Presence 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 RaiseFault-Richtlinie verwendet die gleiche Syntax wie das Element <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.

Das Element <Header> unterstützt die Funktion zur dynamischen Stringsubstitution mit dem Namen Nachrichtenvorlagen.

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

Attribut

Beschreibung

Presence

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.

Die Unterelemente von <Set> unterstützen die dynamische Stringsubstitution mit dem Namen Nachrichtenvorlagen.

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

Hinweis: Bei der Fehlerbehandlung besteht die Best Practice darin, den Teil errorcode der Fehlerantwort zu beachten. Verlassen Sie sich nicht auf den Text in faultstring. Er kann sich ändern.

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