Criterio RaiseFault

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza documentazione di Apigee Edge.

icona norme

Cosa

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

Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per ciascun tipo di ambiente, consulta Tipi di criteri.

Per informazioni generali sulla gestione dei guasti, consulta Gestire i guasti.

Esempi

Restituzione FaultResponse

Nell'uso più comune, RaiseFault viene utilizzato per restituire una risposta di errore personalizzata al che richiede l'app. Ad esempio, questo criterio restituirà il codice di stato 404 con nessun payload:

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

Payload FaultResponse di reso

Un esempio più complesso prevede la restituzione di un payload di risposta all'errore personalizzato, insieme alle intestazioni HTTP e a un codice di stato HTTP. Nell'esempio seguente, la risposta all'errore viene compilata. con un messaggio XML contenente il codice di stato HTTP ricevuto da Apigee dal backend e un'intestazione contenente il tipo di errore che si è verificato:

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

Per un elenco di tutte le variabili disponibili per il completamento dinamico di FaultResponse vedi Variabili riferimento

Gestire gli errori di callout del servizio

Informazioni sul criterio RaiseFault

Apigee ti consente di eseguire la gestione delle eccezioni personalizzate utilizzando un criterio di tipo RaiseFault. Il criterio RaiseFault, simile al criterio AssignMessage, 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 all'errore può essere composta da intestazioni HTTP, parametri di query e un payload del messaggio. 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.

Quando viene eseguito, il criterio RaiseFault trasferisce il controllo dal flusso corrente al flusso Error, che restituisce la risposta all'errore designata all'app client richiedente. Quando il flusso di messaggi passa al flusso Error, non viene eseguita ulteriore elaborazione dei criteri. Tutti i passaggi di elaborazione rimanenti vengono ignorati e la risposta all'errore viene restituita direttamente all'app richiedente.

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 degli errori, valutando FaultRules oppure, se non sono definiti criteri 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/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

&lt;RaiseFault&gt; attributi

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

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

Attributo Descrizione Predefinito Presenza
name

Il nome interno del criterio. Il valore dell'attributo name può Deve contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

 N/D Obbligatorio
continueOnError

Imposta il valore su false per restituire un errore quando un criterio non funziona. Si tratta di un comportamento previsto comportamento per la maggior parte dei criteri.

Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche:

 falso Facoltativo
enabled

Imposta su true per applicare il criterio.

Imposta false per disattivare il criterio. Il criterio non verrà applicata anche se rimane collegata a un flusso.

 true Facoltativo
async

Questo attributo è stato ritirato.

 falso Ritirato

&lt;DisplayName&gt; 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>
Predefinito

N/D

Se ometti questo elemento, il valore dell'attributo name del criterio è in uso.
Presenza Facoltativo
Tipo Stringa

Elemento <IgnoreUnresolvedVariables>

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

Elemento <FaultResponse>

(Facoltativo) Definisce il messaggio di risposta restituito al client richiedente. FaultResponse utilizza le stesse impostazioni del regolamento AssignMessage.

Elemento <FaultResponse><AssignVariable>

Assegna un valore a una variabile di 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>
</AssignMessage>

<AssignVariable> nel criterio RaiseFault utilizza la stessa sintassi dell'elemento <AssignVariable> nel criterio AssignMessage.

Elemento <FaultResponse><Add>/<Headers>

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

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

Predefinita:

 N/D

Presenza:

 Facoltativo

Tipo:

 Stringa

Elemento <FaultResponse><Copy>

Copia le informazioni dal messaggio specificato dall'attributo source al messaggio di errore.

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

Predefinita:

N/D

Presenza:

Facoltativo

Tipo:

Stringa

Attributi

 <Copy source="response">
Attributo Descrizione Presenza Tipo
origine

Specifica l'oggetto di origine della copia.

  • Se source non è specificato, viene trattato come un semplice messaggio. Ad esempio, se il criterio si trova nel nel flusso di richieste, l'origine usa per impostazione predefinita l'oggetto request. Se il criterio è in flusso di risposta, per impostazione predefinita viene utilizzato l'oggetto response. Se ometti source, puoi utilizzare un riferimento assoluto a una variabile di flusso come origine della copia. Ad esempio, specifica il valore {request.header.user-agent}.
  • Se la variabile di origine non può essere risolta o si risolve in un tipo diverso da messaggio, <Copia> non risponde.
 Facoltativo Stringa

Elemento <FaultResponse><Copy>/<Headers>

Copia l'intestazione HTTP specificata dall'origine al 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>

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

Predefinita:

N/D

Presenza:

 Facoltativo

Tipo:

Stringa

Elemento <FaultResponse><Copy>/<StatusCode>

Il codice di stato HTTP da copiare dall'oggetto specificato dall'attributo di origine al messaggio di errore.

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

Valore predefinito:

 falso

Presenza:

 Facoltativo

Tipo:

 Stringa

&lt;FaultResponse&gt;&lt;Remove&gt;/&lt;Headers&gt; 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.

Predefinita:

 N/D

Presenza:

 Facoltativo

Tipo:

 Stringa

&lt;FaultResponse&gt;&lt;Set&gt; elemento

Imposta le informazioni nel messaggio di errore.

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

Predefinita:

 N/D

Presenza:

 Facoltativo

Tipo:

 N/D

Elemento <FaultResponse>/<Set>/<Headers>

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>

Valore predefinito:

 N/D

Presenza:

 Facoltativo

Tipo:

 Stringa

Elemento <FaultResponse>/<Set>/<Payload>

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 variabili utilizzando gli attributi variablePrefix e variableSuffix con caratteri delimitatori, come mostrato nell'esempio seguente.

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

In alternativa, a partire dalla release cloud del 16/08/17, puoi anche utilizzare le 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>

Predefinita:

Presenza:

 Facoltativo

Tipo:

 Stringa

Attributi

 <Payload contentType="content_type" variablePrefix="char" variableSuffix="char">
Attributo Descrizione Presenza Tipo
contentType

Se contentType è specificato, il relativo valore viene assegnato all'intestazione Content-Type.

 Facoltativo Stringa
variablePrefix Facoltativamente, specifica il delimitatore iniziale su una variabile di flusso poiché i payload JSON non possono utilizzare il valore predefinito "{" . Facoltativo Char
variableSuffix Facoltativamente, specifica il delimitatore finale di un flusso perché i payload JSON non possono utilizzare il valore predefinito "}" . Facoltativo Char

Elemento <FaultResponse>/<Set>/<StatusCode>

Imposta il codice di stato della risposta.

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

Predefinita:

 falso

Presenza:

 Facoltativo

Tipo:

 Booleano

Elemento <ShortFaultReason>

Specifica di visualizzare un motivo di errore breve nella risposta:

<ShortFaultReason>true|false</ShortFaultReason>

Per impostazione predefinita, il motivo dell'errore nella risposta del 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).

Predefinita:

 falso

Presenza:

 Facoltativo

Tipo:

 Booleano

Variabili di flusso

Le variabili di flusso consentono il comportamento dinamico dei criteri e dei flussi in fase di esecuzione, in base agli intestazioni HTTP, ai contenuti dei messaggi o al contesto del flusso. 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.

Variabile Tipo Autorizzazione Descrizione
fault.name Stringa Sola lettura Quando viene eseguito il criterio RaiseFault, questa variabile è sempre impostata sulla stringa RaiseFault.
fault.type Stringa Sola lettura Restituisce il tipo di errore presente e, se non disponibile, una stringa vuota.
fault.category Stringa Sola lettura Restituisce la categoria di errore nell'errore e, se non disponibile, una stringa vuota.

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>
 Di seguito è illustrato cosa si trova in RaiseFault: 
<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>

Messaggi di errore

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

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto Stato HTTP Causa
steps.raisefault.RaiseFault 500 Vedi stringa errore.

Errori di deployment

Nessuno.

Variabili di errore

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

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'errore. fault.name = "RaiseFault"
raisefault.policy_name.failed policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. raisefault.RF-ThrowError.failed = true

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.