Criterio riseFault

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Cosa

Genera un messaggio personalizzato in risposta a una condizione di errore. Utilizza AlzaFault per definire una 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.

Samples

<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 una gestione personalizzata delle eccezioni utilizzando un criterio di tipo RaiseFault. Il criterio AlzaFault, simile al criterio AssignMessage, consente di generare una risposta di errore personalizzata in risposta a una condizione di errore.

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

Quando viene eseguito, il criterio AlzaFault trasferisce il controllo dal flusso attuale al flusso di errori, che poi restituisce la risposta di errore designata all'app client che ha inviato la richiesta. Quando il flusso del messaggio passa al flusso di errori, non viene eseguita un'ulteriore elaborazione del criterio. Tutti i restanti passaggi di elaborazione vengono ignorati e la risposta di errore viene restituita direttamente all'app richiedente.

Puoi utilizzare RaiseFault in un ProxyEndpoint o TargetEndpoint. In genere, è necessario collegare una condizione al criterio AlzaFault. Dopo l'esecuzione di AlzaFault, Apigee esegue la normale elaborazione degli errori, valutando FaultRules oppure, se non sono state definite regole di errore, termina l'elaborazione della richiesta.

Riferimento elemento

Il riferimento all'elemento descrive gli elementi e gli attributi del criterio AlzaFault.

<?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 dei criteri:

Elemento <DisplayName>

Utilizzalo in aggiunta all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

Elemento <IgnoraUnresolvedVariables>

(Facoltativo) Ignora eventuali errori di variabili non risolti 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 criterio AttributionMessage (non disponibile in Apigee Edge per il cloud privato).

Elemento <FaultResponse><AssignVariable>

Assegna un valore a una variabile di flusso di destinazione. Se la variabile di flusso non esiste, viene creata da AssignVariable.

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

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

Potrai quindi fare riferimento a quella variabile nei modelli di messaggi in un secondo momento nel criterio AlzaFault. Inoltre, un criterio associato a una FaultRule può accedere alla variabile. Ad esempio, il seguente criterio di AssegnaMessage utilizza la variabile impostata in AlzaFault 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 AlzaFault utilizza la stessa sintassi dell'elemento <AssignVariable> nel criterio AssignMessage. Tieni presente che questa funzionalità non è attualmente disponibile in Apigee Edge per il cloud privato.

Elemento <FaultResponse><Add>/<Headers>

Aggiunge intestazioni HTTP al messaggio di errore. Tieni presente che l'intestazione vuota <Add><Headers/></Add> non ne aggiunge altre. 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>

Elemento <FaultResponse><Copy>

Copia le informazioni dal messaggio specificato dall'attributo source in 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>

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

Elemento <FaultResponse><Copy>/<StatusCode>

Il codice di stato HTTP da copiare dall'oggetto specificato dall'attributo source 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.

Elemento <FaultResponse><Set>

Consente di impostare le informazioni nel messaggio di errore.

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

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

Consente di impostare o sovrascrivere 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 di delimitazione, come mostrato nell'esempio seguente.

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

oppure, a partire dalla release 16.08.17 del cloud, 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>

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 di motivazione 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 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 accorciare faultstring al solo nome del criterio:

"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 dei criteri e dei flussi in fase di runtime, in base alle intestazioni HTTP, ai contenuti dei messaggi o al contesto del flusso. Le seguenti variabili di flusso predefinite sono disponibili dopo l'esecuzione di un criterio AlzaFault. Per ulteriori informazioni sulle variabili di flusso, consulta le informazioni di riferimento sulle variabili.

Esempio di utilizzo di RaiseFault

L'esempio seguente utilizza una condizione per forzare la presenza di un elemento queryparam con il nome zipcode nella richiesta in entrata. Se queryparam non è presente, il flusso genererà un guasto tramite AlzaFault:

<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 e le variabili di errore impostate da Edge quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Errori di deployment

Nessuna.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.

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, gli schemi dei criteri sono disponibili su GitHub.

Argomenti correlati

Consulta la sezione Gestione degli errori