Questa pagina è stata tradotta dall'API Cloud Translation.

Criterio RaiseFault

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

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.

Questa policy è una policy standard e può essere implementata in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per ogni tipo di ambiente, consulta Tipi di criteri.

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

Esempi

Restituisci FaultResponse

Nell'utilizzo più comune, RaiseFault viene utilizzato per restituire una risposta di errore personalizzata all'app richiedente. Ad esempio, questo criterio restituirà un codice di stato 404 senza payload:

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

Restituisci il payload FaultResponse

Un esempio più complesso prevede la restituzione di un payload di risposta di errore personalizzato, insieme alle intestazioni HTTP e a un codice di stato HTTP. Nell'esempio seguente, la risposta di errore viene compilata con un messaggio XML contenente il codice di stato HTTP ricevuto da Apigee dal servizio di 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 popolamento dinamico dei messaggi FaultResponse, consulta il riferimento alle variabili.

Gestire gli errori di callout del servizio

Informazioni sul criterio RaiseFault

Apigee ti consente di eseguire la gestione personalizzata delle eccezioni 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 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 agli sviluppatori di app e agli utenti finali delle app rispetto a messaggi di errore generici o codici di risposta HTTP.

Quando viene eseguita, la norma 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 norme. 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, devi allegare 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/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <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:

Attributo	Descrizione	Predefinito	Presence
`name`	Il nome interno del criterio. Il valore dell'attributo `name` può 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 su `false` per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su `true` per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente	falso	Facoltativo
`enabled`	Imposta su `true` per applicare il criterio. Imposta su `false` per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.	true	Facoltativo
`async`	Questo attributo è stato ritirato.	falso	Deprecato

Elemento <DisplayName>

Da utilizzare insieme 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>

Predefinito

Predefinito	N/D Se ometti questo elemento, viene utilizzato il valore dell'attributo `name` del criterio.
Presence	Facoltativo
Tipo	Stringa

N/D

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.

Presence Facoltativo

Tipo Stringa

Elemento <IgnoreUnresolvedVariables>

(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 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 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>
</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.

L'elemento <Header> supporta la funzionalità di sostituzione dinamica delle stringhe chiamata modelli di messaggi.

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

Predefinito:	N/D
Presenza:	Facoltativo
Tipo:	Stringa

<FaultResponse><Copy> element

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

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

Predefinito:	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 la policy si trova nel flusso di richieste, l'origine viene impostata per impostazione predefinita sull'oggetto richiesta. Se il criterio è nel flusso di risposta, il valore predefinito è 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 come {request.header.user-agent}. Se la variabile di origine non può essere risolta o viene risolta in un tipo non di messaggio, <Copy> non riesce a rispondere.	Facoltativo	Stringa

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 la policy si trova nel flusso di richieste, l'origine viene impostata per impostazione predefinita sull'oggetto richiesta. Se il criterio è nel flusso di risposta, il valore predefinito è 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 come {request.header.user-agent}.
Se la variabile di origine non può essere risolta o viene risolta in un tipo non di messaggio, <Copy> non riesce a rispondere.

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

Predefinito:	N/D
Presenza:	Facoltativo
Tipo:	Stringa

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

Predefinito:	falso
Presenza:	Facoltativo
Tipo:	Stringa

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.

Predefinito:	N/D
Presenza:	Facoltativo
Tipo:	Stringa

<FaultResponse><Set> element

Imposta le informazioni nel messaggio di errore.

Gli elementi secondari di <Set> supportano la funzionalità di sostituzione dinamica delle stringhe chiamata modelli di messaggi.

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

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

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

Predefinito:
Presenza:	Facoltativo
Tipo:	Stringa

Attributi

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

Attributo	Descrizione	Presenza	Tipo
contentType	Se viene specificato contentType, il relativo valore viene assegnato all'intestazione `Content-Type`.	Facoltativo	Stringa
variablePrefix	Specifica facoltativamente il delimitatore iniziale di una variabile di flusso perché i payload JSON non possono utilizzare il carattere "{" predefinito.	Facoltativo	Char
variableSuffix	Specifica facoltativamente il delimitatore finale di una variabile di flusso perché i payload JSON non possono utilizzare il carattere "}" predefinito.	Facoltativo	Char

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

Imposta il codice di stato della risposta.

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

Predefinito:	falso
Presenza:	Facoltativo
Tipo:	Booleano

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

Predefinito:	falso
Presenza:	Facoltativo
Tipo:	Booleano

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 dei messaggi 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.

Variabile	Tipo	Autorizzazione	Descrizione
fault.name	Stringa	Sola lettura	Quando viene eseguito il criterio RaiseFault, questa variabile viene sempre impostata sulla stringa `RaiseFault`.
fault.type	Stringa	Sola lettura	Restituisce il tipo di errore nell'errore 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 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 il contenuto di 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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
`steps.raisefault.RaiseFault`	`500`	See fault string.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name = "RaiseFault"`
`raisefault.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`raisefault.RF-ThrowError.failed = true`

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Criterio RaiseFault Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Cosa

Esempi

Restituisci FaultResponse

Restituisci il payload FaultResponse

Gestire gli errori di callout del servizio

Informazioni sul criterio RaiseFault

Riferimento elemento

Attributi <RaiseFault>

Elemento <DisplayName>

Elemento <IgnoreUnresolvedVariables>

Elemento <FaultResponse>

Elemento <FaultResponse><AssignVariable>

Elemento <FaultResponse><Add>/<Headers>

<FaultResponse><Copy> element

Attributi

Elemento <FaultResponse><Copy>/<Headers>

<FaultResponse><Copy>/<StatusCode> element

Elemento <FaultResponse><Remove>/<Headers>

<FaultResponse><Set> element

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

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

Attributi

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

Elemento <ShortFaultReason>

Variabili di flusso

Esempio di utilizzo di RaiseFault

Messaggi di errore

Runtime errors

Deployment errors

Fault variables

Example error response

Schema

Argomenti correlati

Criterio RaiseFault