Criterio RaiseFault

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Cosa

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

Per informazioni generali sulla gestione dei guasti, consulta Gestione dei guasti.

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 ti consente di eseguire la gestione personalizzata delle eccezioni utilizzando una policy 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 restituita all'app richiedente quando si verifica una condizione di errore specifica. La risposta di errore può essere costituita da intestazioni HTTP, parametri di query e un payload del messaggio. Una risposta di errore personalizzata può essere più utile per gli sviluppatori di app e per gli utenti finali delle app rispetto a messaggi di errore generici o codici di risposta HTTP.

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

Puoi utilizzare RaiseFault in un ProxyEndpoint o un TargetEndpoint. In genere, colleghi una condizione al criterio RaiseFault. Dopo l'esecuzione di RaiseFault, Apigee esegue la normale elaborazione degli errori, valutando 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>

Attributi <RaiseFault>

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

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

Elemento <IgnoreUnresolvedVariables>

(Facoltativo) Ignora eventuali errori di variabili non risolti nel flusso. Valori validi: true/false. Predefinito: true.

Elemento <FaultResponse>

(Facoltativo) Definisce il messaggio di risposta restituito al client richiedente. FaultResponse utilizza le stesse impostazioni del criterio AssignMessage (non disponibile in Apigee Edge for Private Cloud).

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 nei criteri RaiseFault. Inoltre, un criterio collegato a una FaultRule può accedere alla variabile. Ad esempio, la seguente policy AssignMessage utilizza la variabile impostata in RaiseFault per impostare un'intestazione nella risposta di errore:

<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 dell'elemento <AssignVariable> nel criterio AssignMessage. Tieni presente che questa funzionalità non è attualmente disponibile in Apigee Edge for Private Cloud.

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>

<FaultResponse><Copy> element

Copia le informazioni da il messaggio specificato dall'attributo source a il messaggio di errore.

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

Attributi

 <Copy source="response">

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 sono presenti 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 valore, non viene copiato.

<FaultResponse><Copy>/<StatusCode> element

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>

Elemento <FaultResponse><Copy>/<ReasonPhrase>

La descrizione del motivo da copiare dall'oggetto specificato dall'attributo di origine al messaggio di errore.

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

Elemento <FaultResponse><Remove>/<Headers>

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

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

Se sono presenti 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 valore, non viene rimosso.

<FaultResponse><Set> element

Imposta le informazioni nel messaggio di errore.

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

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 alcuna intestazione. Questo esempio imposta l'intestazione user-agent sulla variabile del messaggio specificata con l'elemento <AssignTo>.

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

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 nel seguente esempio.

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

o, a partire dalla release cloud 16.08.17, puoi utilizzare anche 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>

Attributi

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

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

Imposta il codice di stato della risposta.

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

Elemento <FaultResponse>/<Set>/<ReasonPhrase>

Imposta la frase del motivo della risposta.

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

Elemento <ShortFaultReason>

Specifica di visualizzare un breve motivo dell'errore nella risposta:

<ShortFaultReason>true|false</ShortFaultReason>

Per impostazione predefinita, il motivo del guasto nella risposta della policy è:

"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 al solo 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 alle intestazioni HTTP, al contenuto del messaggio o al contesto del flusso. Le seguenti variabili di flusso predefinite sono disponibili dopo l'esecuzione di un criterio RaiseFault. Per ulteriori informazioni sulle variabili di flusso, consulta Riferimento alle 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 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 policy è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle policy sono disponibili su GitHub.

Argomenti correlati

Consulta la sezione Gestione degli errori.