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 che viene restituita all'app richiedente quando si verifica una condizione specifica.
Questo è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Non tutti gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità con ogni tipo di ambiente, consulta Tipi di criteri.
Per informazioni generali sulla gestione degli errori, consulta Gestione degli errori.
Esempi
Restituire FaultResponse
Nell'utilizzo più comune, RaiseFault viene utilizzato per restituire una risposta di errore personalizzata all'app che ha inviato la richiesta. 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>
Restituire il payload di FaultResponse
Un esempio più complesso prevede la restituzione di un payload di risposta di errore personalizzato, insieme a intestazioni HTTP e 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 completamento dinamico dei messaggi FaultResponse, consulta Riferimento alle variabili.
Gestire gli errori dei callout del servizio
Informazioni sul criterio RaiseFault
Apigee ti consente di eseguire una gestione delle eccezioni personalizzata utilizzando un criterio di tipo RaiseFault. Il criterio RaiseFault, simile al criterio AssegnaMessage, 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 condizione di errore specifica. La risposta di errore può consistere di intestazioni HTTP, parametri di query e un payload dei messaggi. Una risposta di errore personalizzata può essere più utile per gli sviluppatori di app e gli utenti finali delle app rispetto a messaggi di errore generici o codici di risposta HTTP.
Quando viene eseguito, il criterio RaiseFault trasferisce il controllo dal flusso attuale al flusso di errori, che restituisce quindi la risposta di errore designata all'app client che ha inviato la richiesta. Quando il flusso del messaggio passa al flusso degli 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. Di solito, è necessario collegare una Condition al criterio RaiseFault. Dopo l'esecuzione di RaiseFault, Apigee eseguirà la normale elaborazione dei errori, valutando FaultRules, oppure, se non sono state definite regole di errore, termina l'elaborazione della richiesta.
Riferimento elemento
Il riferimento agli elementi 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 | Presenza |
---|---|---|---|
name |
Il nome interno della norma. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
N/A | Obbligatorio |
continueOnError |
Impostalo su Imposta su |
false | Facoltativo |
enabled |
Imposta il criterio su Impostala su |
true | Facoltativo |
async |
Questo attributo è obsoleto. |
false | Deprecata |
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>
Predefinito |
N/A Se ometti questo elemento, viene utilizzato il valore dell'attributo |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
Elemento <IgnoraUnresolvedVariables>
(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 criterioAssignMessage.
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 RaiseFault:
<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 RaiseFault. Inoltre, un criterio associato a una FaultRule può accedere alla variabile. Ad esempio, il seguente criterio 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.
<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 nel 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.
|
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>
In questo esempio viene copiato "h1", "h2" e il secondo valore di "h3". Se "h3" ha un solo valore, 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 source al messaggio di errore.
<Copy source='response'> <StatusCode>404</StatusCode> </Copy>
Predefinita: |
false |
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>
. In questo esempio, l'intestazione user-agent
viene rimossa 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.
Predefinita: |
N/D |
Presenza: |
Facoltativo |
Tipo: |
Stringa |
Elemento <FaultResponse><Set>
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 alcuna intestazione. Questo esempio imposta
l'intestazione user-agent
sulla variabile messaggio specificata con l'elemento
<AssignTo>
.
<Set> <Headers> <Header name="user-agent">{request.header.user-agent}</Header> </Headers> </Set>
Predefinita: |
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 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, puoi anche usare 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 viene specificato contentType, il suo valore viene assegnato all'intestazione |
Facoltativo | Stringa |
variablePrefix | Facoltativamente, specifica il delimitatore iniziale su una variabile di flusso perché i payload JSON non possono utilizzare il carattere "{" predefinito. | Facoltativo | Carbone |
variableSuffix | Facoltativamente, specifica il delimitatore finale su una variabile di flusso perché i payload JSON non possono utilizzare il carattere "}" predefinito. | Facoltativo | Carbone |
Elemento <FaultResponse>/<Set>/<StatusCode>
Imposta il codice di stato della risposta.
<Set source='request'> <StatusCode>404</StatusCode> </Set>
Predefinita: |
false |
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 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
in modo che corrisponda solo al nome del criterio:
"fault":{"faultstring":"Raise-Fault-1","detail":{"errorcode":"errorCode"}}}
Valori validi: true/false(default).
Predefinita: |
false |
Presenza: |
Facoltativo |
Tipo: |
Booleano |
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 RaiseFault. Per ulteriori informazioni sulle variabili di flusso, consulta la sezione 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 applicare la presenza di un elemento
queryparam
con il nome zipcode
nella richiesta in entrata. Se
queryparam
non è presente, il flusso genererà un guasto 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 viene illustrato cosa potrebbe essere 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 e i messaggi di errore restituiti e le variabili di errore impostate da Apigee 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.
Codice di errore | Stato HTTP | Causa |
---|---|---|
steps.raisefault.RaiseFault |
500 |
Vedi stringa di errore. |
Errori di deployment
Nessuno.
Variabili di errore
Queste variabili vengono impostate quando si verifica un errore di runtime. Per maggiori informazioni, consulta la pagina Cosa devi sapere sugli errori relativi ai criteri.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome dell'errore è l'ultima parte del codice di 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
). Per riferimento, gli schemi dei criteri sono disponibili su GitHub.
Argomenti correlati
Consulta la sezione Gestione degli errori