criterio RaiseFault

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Cosa

Genera un messaggio personalizzato in risposta a una condizione di errore. Utilizzare RaiseFault per definire un'istanza risposta di errore che viene restituita all'app richiedente quando si verifica una condizione specifica.

Per informazioni generali sulla gestione degli errori, consulta la sezione Gestione degli errori.

Esempi

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

Informazioni sul criterio RaiseFault

Apigee Edge consente di eseguire una gestione personalizzata delle eccezioni utilizzando un criterio di tipo RaiseFault. Il criterio RaiseFault, simile al criterio RaiseFault, è simile al CriterioAssignMessage, consente di generare una risposta di errore personalizzata in risposta a una condizione di errore.

Utilizza il criterio RaiseFault per definire una risposta di errore che viene restituita all'app richiedente. quando si verifica una specifica condizione di errore. La risposta di errore può essere composta da intestazioni HTTP, query e un payload per i messaggi. Una risposta agli errori personalizzata può essere più utile per gli sviluppatori di app e per gli utenti finali delle app rispetto ai messaggi di errore generici o ai codici di risposta HTTP.

Se eseguito, il criterio RaiseFault trasferisce il controllo dal flusso attuale all'errore che restituisce la risposta di errore designata all'app client richiedente. Quando Il flusso di messaggi passa al flusso di errore, non viene eseguita alcuna ulteriore elaborazione dei criteri. Tutti i restanti I passaggi di elaborazione vengono bypassati e la risposta di errore viene restituita direttamente al prompt dell'app.

Puoi utilizzare RaiseFault in un ProxyEndpoint o in un TargetEndpoint. Generalmente, alleghi Condition alla Criterio RaiseFault. Dopo l'esecuzione di RaiseFault, Apigee eseguirà la normale elaborazione dei guasti, la valutazione FaultRules o se non sono definite regole di errore, termina l'elaborazione della richiesta.

Riferimento elemento

Il riferimento all'elemento descrive gli elementi e gli attributi del criterio 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>

<RaiseFault> attributi

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

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali del criterio:

<DisplayName> elemento

Da utilizzare in aggiunta all'attributo name per etichettare il criterio in editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

<IgnoreUnresolvedVariables> elemento

(Facoltativo) Ignora qualsiasi errore di variabile non risolto nel flusso. Valori validi: true/false. Valore predefinito: true.

<FaultResponse> elemento

(Facoltativo) Definisce il messaggio di risposta restituito al client richiedente. FaultResponse utilizza Le stesse impostazioni del criterioAssignMessage (non disponibile in Apigee Edge per il cloud privato).

<FaultResponse><AssignVariable> elemento

Assegna un valore a una variabile del flusso di destinazione. Se la variabile di flusso non esiste, AssignVariable la crea.

Ad esempio, utilizza il seguente codice per impostare la variabile denominata myFaultVar nel criterio RaiseFault:

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

Puoi quindi fare riferimento a questa variabile nei modelli di messaggio in un secondo momento nel criterio RaiseFault. Inoltre, un criterio associato a una regola di errore può quindi accedere alla variabile. Ad esempio, Il criterioAssignMessage utilizza la variabile impostata in RaiseFault per impostare un'intestazione nel campo risposta ai guasti:

<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> nel criterio RaiseFault utilizza la stessa sintassi del parametro Elemento <AssignVariable> nel criterioAssignMessage. Tieni presente che questa funzionalità non è attualmente disponibile in Apigee Edge per il cloud privato.

<FaultResponse><Add>/<Headers> elemento

Aggiunge intestazioni HTTP al messaggio di errore. Tieni presente che l'intestazione vuota <Add><Headers/></Add> non aggiunge nessuna intestazione. Questo esempio copia il valore della variabile di flusso request.user.agent nel intestazione.

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

<FaultResponse><Copy> elemento

Copia le informazioni dal messaggio specificato source al messaggio di errore.

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

Attributi

 <Copy source="response">

<FaultResponse><Copy>/<Headers> elemento

Copia l'intestazione HTTP specificata dall'origine nel messaggio di errore. Per copiare tutte le intestazioni, specifica <Copy><Headers/></Copy>.

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

Se esistono più intestazioni con lo stesso nome, utilizza la seguente sintassi:

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

In questo esempio vengono copiati "h1", "h2" e il secondo valore di "h3". Se "h3" ha un solo non viene copiato.

<FaultResponse><Copy>/<StatusCode> elemento

Il codice di stato HTTP da copiare dall'oggetto specificato dall'attributo source all'errore .

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

<FaultResponse><Copy>/<ReasonPhrase> elemento

La descrizione del motivo da copiare dall'oggetto specificato dall'attributo source all'errore .

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

<FaultResponse><Remove>/<Headers> elemento

Rimuove le intestazioni HTTP specificate dal messaggio di errore. Per rimuovere tutte le intestazioni, specifica <Remove><Headers/></Remove>. Questo esempio rimuove l'intestazione user-agent del messaggio.

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

Se esistono più intestazioni con lo stesso nome, utilizza la seguente sintassi:

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

Questo esempio rimuove "h1", "h2" e il secondo valore di "h3". Se "h3" ha un solo non viene rimosso.

<FaultResponse><Set> elemento

Imposta le informazioni nel messaggio di errore.

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

<FaultResponse>/<Set>/<Headers> elemento

Imposta o sovrascrive le intestazioni HTTP nel messaggio di errore. Tieni presente che l'intestazione vuota <Set><Headers/></Set> non imposta nessuna intestazione. Questo esempio imposta l'intestazione user-agent alla variabile del messaggio specificata con Elemento <AssignTo>.

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

<FaultResponse>/<Set>/<Payload> elemento

Imposta il payload del messaggio di errore.

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

Imposta un payload JSON:

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

In un payload JSON, puoi inserire le variabili utilizzando variablePrefix e Attributi variableSuffix con caratteri di delimitazione, come mostrato di seguito esempio.

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

oppure, a partire dalla release 16.08.17 di Cloud, puoi anche utilizzare parentesi graffe per inserire le variabili:

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

Imposta un payload misto in XML:

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

Attributi

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

<FaultResponse>/<Set>/<StatusCode> elemento

Imposta il codice di stato della risposta.

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

<FaultResponse>/<Set>/<ReasonPhrase> elemento

Imposta la frase relativa al motivo della risposta.

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

<ShortFaultReason> elemento

Specifica di visualizzare un motivo di errore breve nella risposta:

<ShortFaultReason>true|false</ShortFaultReason>

Per impostazione predefinita, il motivo dell'errore nella risposta al criterio è:

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

Per rendere il messaggio più leggibile, puoi impostare l'elemento <ShortFaultReason> su true per abbreviare faultstring in base al nome della norma:

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

Valori validi: true/false(valore predefinito).

Variabili di flusso

Le variabili di flusso consentono il comportamento dinamico di criteri e flussi in fase di runtime, in base a HTTP intestazioni, contenuti dei messaggi o contesto di Flow. Sono disponibili le seguenti variabili di flusso predefinite dopo l'esecuzione del criterio RaiseFault. Per ulteriori informazioni sulle variabili di flusso, consulta Riferimento per le variabili.

Esempio di utilizzo di RaiseFault

L'esempio seguente utilizza una condizione per imporre la presenza di un queryparam con il nome zipcode nella richiesta in entrata. Se che queryparam non è presente, il flusso genererà un errore tramite 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>

Messaggi di errore

Questa sezione descrive i codici e i messaggi di errore restituiti, nonché le variabili di errore. impostate da Edge quando questo criterio attiva un errore. È importante sapere se stai sviluppando regole di errore per per gestire gli errori. Per saperne di più, vedi Informazioni importanti sugli errori relativi alle norme Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Errori di deployment

Nessuno.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, vedi Cosa devi sapere sugli errori relativi alle norme.

Esempio di risposta di errore

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

Schema

Ogni tipo di criterio è definito da uno schema XML (.xsd). Come riferimento, consulta gli schemi dei criteri sono disponibili su GitHub.

Argomenti correlati

Consulta la sezione Gestione degli errori.