Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di
Apigee Edge.
Durante l'elaborazione delle richieste dalle app, possono verificarsi molte condizioni di errore nei proxy API. Ad esempio, i proxy API potrebbero riscontrare problemi di rete durante la comunicazione con i servizi di backend, le app potrebbero presentare credenziali scadute, i messaggi di richiesta potrebbero essere formattati in modo errato e così via.
Quando si verifica un errore dopo che un'app client chiama un proxy API, al client viene restituito un messaggio di errore. Per impostazione predefinita, il client riceve un messaggio di errore spesso criptico senza dettagli o indicazioni. Tuttavia, se vuoi sostituire i messaggi di errore predefiniti con messaggi personalizzati più utili e arricchirli con elementi come intestazioni HTTP aggiuntive, devi configurare la gestione degli errori personalizzata in Apigee.
La gestione personalizzata degli errori ti consente anche di aggiungere funzionalità come la registrazione dei messaggi ogni volta che si verifica un errore.
Prima di parlare dell'implementazione della gestione personalizzata degli errori nei proxy API, è utile capire come si verificano gli errori e come reagiscono i proxy API.
Video
Guarda i seguenti video per saperne di più sulla gestione dei guasti.
Video | Descrizione |
---|---|
Introduzione alla gestione degli errori e ai flussi di errore | Scopri di più sulla gestione degli errori e su cosa succede quando si verifica un errore in un proxy API. |
Gestire gli errori utilizzando le regole di errore | Scopri come gestire i guasti utilizzando le regole di guasto. |
Generare errori personalizzati utilizzando il criterio RaiseFault | Genera errori personalizzati durante il runtime dell'API utilizzando il criterio RaiseFault. |
Definisci regole di errore nel proxy API e negli endpoint di destinazione | Definisci le regole di errore nel proxy API e negli endpoint di destinazione e comprendi le differenze. |
Comprendere l'ordine di esecuzione delle regole di errore | Comprendere l'ordine di esecuzione delle regole di errore nel proxy API e negli endpoint di destinazione. |
Definisci la regola predefinita | Definisci la regola di errore predefinita per gestire gli errori generici nella tua API. |
Come si verificano gli errori
Per prima cosa, vedremo come si verificano gli errori. Sapere come si verificano gli errori ti aiuta a pianificare le diverse situazioni in cui vuoi implementare la gestione personalizzata degli errori.
Errori automatici
Un proxy API genera automaticamente un errore nelle seguenti situazioni:
- Una policy genera un errore. Ad esempio, se una chiamata API invia una chiave scaduta, i criteri VerifyAPIKey generano automaticamente un errore; oppure se il numero di chiamate API supera un determinato limite, i criteri Quota o SpikeArrest generano un errore. Per i tipi di errori che possono generare i criteri, consulta il riferimento agli errori dei criteri.
- Si è verificato un problema nel flusso di messaggi del proxy API, ad esempio un errore di routing.
- Si è verificato un errore di backend, ad esempio un errore HTTP dovuto a errori a livello di protocollo, errori TLS/SSL o un servizio di destinazione non disponibile.
- Si è verificato un errore a livello di sistema, ad esempio un'eccezione di esaurimento della memoria.
Per saperne di più su questi errori, consulta Tassonomia dei guasti in questo argomento.
Errori personalizzati
Per le situazioni in cui non si verifica un errore automatico, potresti voler generare un errore personalizzato, ad esempio se una risposta contiene la parola unavailable
o se il codice di stato HTTP è maggiore di 201
. Per farlo, aggiungi un criterio RaiseFault al punto
appropriato in un flusso di proxy API.
Puoi aggiungere una norma RaiseFault a un flusso proxy API come faresti con qualsiasi altra norma. Nel
seguente esempio di configurazione del proxy, la policy Raise-Fault-1
è collegata
alla risposta TargetEndpoint. Se nella risposta del servizio di destinazione è presente la parola unavailable
, viene eseguita la norma RaiseFault e viene generato un errore.
<TargetEndpoint name="default"> ... <Response> <Step> <Name>Raise-Fault-1</Name> <Condition>message.content Like "*unavailable*"</Condition> </Step> </Response>
Questo serve solo a dimostrare che puoi generare errori personalizzati. Nella sezione FaultRules e RaiseFault forniamo maggiori dettagli sul criterio RaiseFault.
Per altri esempi, consulta questi post della community di Apigee:
Cosa fanno i proxy API quando si verificano errori
Ecco cosa succede quando un proxy genera un errore.
Esci dalla pipeline proxy
Quando un proxy API rileva un errore, indipendentemente da come si verifica, esce dalla pipeline di flusso normale, entra in uno stato di errore e restituisce un messaggio di errore all'app client. Una volta che il proxy API entra nello stato di errore, non può riprendere l'elaborazione nella pipeline di flusso normale.
Ad esempio, supponiamo che un proxy API abbia criteri nel seguente ordine nella richiesta ProxyEndpoint:
- Verifica chiave API
- Quota
- JSON to XML
Se si verifica un errore durante la verifica della chiave API, il proxy API passa allo stato di errore. Le norme relative a quota e JSON in XML non vengono eseguite, il proxy non procede a TargetEndpoint e viene restituito un messaggio di errore all'app client.
Controlla FaultRules
Nello stato di errore, i proxy API verificano anche la presenza di quanto segue (in ordine) nella configurazione del proxy API prima di restituire un messaggio di errore predefinito all'app client:
- Una sezione
<FaultRules>
, che contiene la logica per attivare messaggi di errore personalizzati (e altre norme) in base a condizioni specifiche che definisci. - Una sezione
<DefaultFaultRule>
, che attiva un messaggio di errore predefinito nelle seguenti situazioni:- Nessun
<FaultRules>
definito. - Nessun
<FaultRules>
esistente viene eseguito. - L'elemento
<AlwaysEnforce>
è impostato su true.
- Nessun
In sostanza, il proxy API ti offre l'opportunità di restituire un messaggio di errore personalizzato e attivare un'altra logica. Se il proxy non trova nessuna di queste sezioni o se esistono ma non è stato attivato alcun errore personalizzato, il proxy invia il proprio messaggio predefinito generato da Apigee.
Esempio semplice di gestione degli errori
Iniziamo con un esempio semplice, in cui una chiamata a un proxy API non contiene una chiave API richiesta. Per impostazione predefinita, la risposta restituita all'app client è la seguente:
HTTP/1.1 401 Unauthorized Date: Wed, 20 Jul 2016 19:19:32 GMT Content-Type: application/json Content-Length: 150 Connection: keep-alive Server: Apigee Router * Connection #0 to host myorg-test.apigee.net left intact {"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
Gli utenti dell'API potrebbero essere in grado di capire il messaggio di errore, ma non è detto. Inoltre, molti errori predefiniti sono più sottili e difficili da decifrare.
In qualità di sviluppatore di API, spetta a te modificare questo messaggio per soddisfare le esigenze di chi lo riceverà, che si tratti di uno sviluppatore di app per iOS o di un gruppo di test interno con requisiti di formato specifici per i messaggi di errore.
Ecco un esempio di base di come creare un messaggio di errore personalizzato per gestire questo errore. Ciò richiede 1) un criterio che definisca il messaggio personalizzato e 2) una FaultRule che esegua il criterio quando il proxy entra in uno stato di errore.
1. Crea una norma che definisca il messaggio personalizzato
Innanzitutto, crea una norma che definisca il messaggio di errore personalizzato. Puoi utilizzare qualsiasi tipo di criterio, ad esempio un criterio AssignMessage, che può impostare un payload e intestazioni HTTP facoltative come il codice di stato. Il criterio AssignMessage è ideale per questo scopo. Consente di controllare il payload del messaggio, impostare un codice di stato HTTP diverso e aggiungere intestazioni HTTP.
Non è necessario collegare la norma a un flusso, ma è sufficiente crearla, come descritto in Creare la norma.
Di seguito è riportato un esempio di criterio AssignMessage che:
- Restituisce un messaggio JSON.
- Imposta un codice di stato HTTP (
911
, un codice di stato ovviamente inesistente solo per illustrare la flessibilità a tua disposizione). Il codice di stato viene visualizzato nell'intestazione HTTP. - Crea e compila una nuova intestazione HTTP denominata
invalidKey
.
<AssignMessage async="false" continueOnError="false" enabled="true" name="invalid-key-message"> <DisplayName>Invalid key message</DisplayName> <Set> <Payload contentType="application/json">{"Citizen":"Where's your API key? I don't see it as a query parameter"}</Payload> <StatusCode>911</StatusCode> </Set> <Add> <Headers> <Header name="invalidKey">Invalid API key!</Header> </Headers> </Add> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
Quando questo criterio viene eseguito, la risposta all'app client sarà simile alla seguente. Confrontalo con la risposta predefinita mostrata in precedenza.
HTTP/1.1 911 Rejected by API Key Emergency Services Date: Wed, 20 Jul 2016 18:42:36 GMT Content-Type: application/json Content-Length: 35 Connection: keep-alive invalidKey: Invalid API key! Server: Apigee Router * Connection #0 to host myorg-test.apigee.net left intact {"Citizen":"Where's your API key? I don't see it as a query parameter."}
Sì, è un po' sciocco, ma ti mostra cosa è possibile fare. Almeno ora lo sviluppatore che riceve il messaggio sa di aver dimenticato di includere una chiave API come parametro di query.
Ma come viene eseguita questa policy? La sezione successiva ti mostra come fare.
2. Crea l'<FaultRule> che attiverà la policy
Nelle sezioni <ProxyEndpoint>
o <TargetEndpoint>
della
configurazione del proxy, aggiungerai un blocco XML <FaultRules>
che contiene una
o più sezioni <FaultRule>
individuali. Ogni FaultRule rappresenta un errore diverso che vuoi gestire. In questo semplice esempio, utilizzeremo una sola FaultRule per mostrarti di cosa è composta.
Devi anche aggiungere un <DefaultFaultRule>
per fornire un messaggio di errore generale personalizzato se non viene eseguita nessuna delle tue FaultRule.
Esempio
<ProxyEndpoint name="default"> ... <FaultRules> <FaultRule name="invalid_key_rule"> <Step> <Name>invalid-key-message</Name> </Step> <Condition>(fault.name = "FailedToResolveAPIKey")</Condition> </FaultRule> </FaultRules> <DefaultFaultRule name="default-fault"> <Step> <Name>Default-message</Name> </Step> </DefaultFaultRule>
Punti chiave:
- Le FaultRules sono definite in ProxyEndpoint. Questo è importante. Scopri di più sull'inserimento di FaultRules in ProxyEndpoint e TargetEndpoint più avanti.
<Name>
: il nome della policy da eseguire. Il nome deriva dall'attributoname
della norma nell'elemento principale, come mostrato nell'esempio di norma precedente.-
<Condition>
: Apigee valuta la condizione ed esegue il criterio solo se la condizione è vera. Se sono presenti più FaultRule che restituiscono true, Apigee esegue la prima che restituisce true. (Importante: l'ordine in cui vengono valutate le FaultRule, dall'alto verso il basso o dal basso verso l'alto, varia tra TargetEndpoint e ProxyEndpoint, come descritto nella sezione Più FaultRule e logica di esecuzione.) Se non includi una condizione, FaultRule è automaticamente true. Ma non è una best practice. Ogni FaultRule deve avere la propria condizione. -
<DefaultFaultRule>
: se non viene eseguita alcuna FaultRule personalizzata, viene eseguito<DefaultFaultRule>
, che invia un messaggio personalizzato più generico anziché il messaggio predefinito criptico generato da Apigee. Un<DefaultFaultRule>
può anche avere un<Condition>
, ma nella maggior parte dei casi non ne includerai uno, perché vuoi che venga eseguito a prescindere come ultima risorsa.La regola DefaultFaultRule viene in genere utilizzata per restituire un messaggio di errore generico per qualsiasi errore imprevisto. Un esempio è un messaggio che contiene i dati di contatto dell'assistenza tecnica. Questa risposta predefinita ha il duplice scopo di fornire informazioni utili agli sviluppatori e di offuscare gli URL di backend o altre informazioni che potrebbero essere utilizzate per compromettere il sistema.
Più FaultRule e logica di esecuzione
Nella sezione Esempio di gestione semplice degli errori, abbiamo utilizzato un esempio semplice
di una singola FaultRule e condizione. In un progetto API reale, con tutti i possibili errori
che possono verificarsi, è probabile che tu abbia più FaultRule e una DefaultFaultRule sia in <ProxyEndpoint>
che in <TargetEndpoint>
. In definitiva, però,
viene eseguita una sola FaultRule quando un proxy API entra in uno stato di errore.
Questa sezione descrive la logica utilizzata da Apigee nella gestione di FaultRules, da come si arriva a una singola FaultRule da eseguire a come vengono gestite le condizioni dei passaggi interni quando viene attivata la FaultRule. Questa sezione fornisce anche indicazioni su quando definire FaultRules in
<ProxyEndpoint>
rispetto a <TargetEndpoint>
e descrive la
relazione tra FaultRules e il criterio RaiseFault.
Esecuzione di FaultRules
In breve, ecco la logica utilizzata da Apigee quando un proxy API entra in uno stato di errore. Tieni presente che l'evaluazione di FaultRules in ProxyEndpoint è leggermente diversa rispetto a TargetEndpoint.
- Apigee valuta FaultRules in ProxyEndpoint o TargetEndpoint, a seconda di
dove si è verificato l'errore:
- ProxyEndpoint: Apigee inizia con l'elemento inferiore
<FaultRule>
nel file XML di configurazione e procede verso l'alto, valutando l'elemento<Condition>
di ogni<FaultRule>
(la condizione esterna, non le condizioni<Step>
interne). - TargetEndpoint: Apigee inizia con il primo
<FaultRule>
nel file XML di configurazione e procede verso il basso, valutando il<Condition>
di ogni<FaultRule>
(la condizione esterna, non le condizioni<Step>
interne).
- ProxyEndpoint: Apigee inizia con l'elemento inferiore
- Esegue la prima FaultRule la cui condizione è true. Se una FaultRule non ha
alcuna condizione, è vera per impostazione predefinita.
- Quando viene eseguita una FaultRule, tutti gli Step al suo interno vengono valutati in ordine,
dall'alto verso il basso nella configurazione XML. I passaggi senza condizioni vengono eseguiti automaticamente
(vengono eseguite le norme) e i passaggi con un
<Condition>
che restituisce vengono eseguiti (le condizioni che restituisconocode
non vengono eseguite). -
Se viene eseguita una FaultRule, ma non vengono eseguiti passaggi nella FaultRule (perché le relative condizioni restituiscono
code
), all'app client viene restituito il messaggio di errore predefinito generato da Apigee. L'elemento<DefaultFaultRule>
non viene eseguito, perché Apigee ha già eseguito la sua FaultRule.
- Quando viene eseguita una FaultRule, tutti gli Step al suo interno vengono valutati in ordine,
dall'alto verso il basso nella configurazione XML. I passaggi senza condizioni vengono eseguiti automaticamente
(vengono eseguite le norme) e i passaggi con un
- Se non viene eseguita alcuna FaultRule, Apigee esegue
<DefaultFaultRule>
, se presente.
Di seguito sono riportati alcuni esempi con commenti in linea.
Esecuzione di ProxyEndpoint
La valutazione delle FaultRule di ProxyEndpoint avviene dal basso verso l'alto, quindi inizia a leggere dall'ultima FaultRule nell'esempio seguente e procedi verso l'alto. Esamina per ultima la regola DefaultFaultRule.
<ProxyEndpoint name="default"> ... <FaultRules> <!-- 3. This FaultRule is automatically TRUE, because there's no outer condition. But because the FaultRule just below this got executed (bottom-to-top evaluation in a ProxyEndpoint), Apigee doesn't even evaluate this FaultRule. Note that it's not a best practice to have a FaultRule without an outer condition, which automatically makes the FaultRule true. --> <FaultRule name="random-error-message"> <Step> <Name>Random-fault</Name> </Step> </FaultRule> <!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation error. This is the first FaultRule to be TRUE, so it's executed. Now the Steps are evaluated, and for the ones whose conditions evaluate to TRUE, their policies are executed. Steps without conditions are automatically true. --> <FaultRule name="over_quota"> <Step> <Name>developer-over-quota-fault</Name> <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition> </Step> <Step> <Name>global-over-quota-fault</Name> <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition> </Step> <Step> <Name>log-error-message</Name> </Step> <Condition>(fault.name = "QuotaViolation")</Condition> </FaultRule> <!-- 1. Because this is the ProxyEndpoint, Apigee looks at this FaultRule first. But let's say this FaultRule is FALSE. A policy did not throw a FailedToResolveAPIKey error. Apigee moves UP to check the next FaultRule. --> <FaultRule name="invalid_key_rule"> <Step> <Name>invalid-key-message</Name> </Step> <Condition>(fault.name = "FailedToResolveAPIKey")</Condition> </FaultRule> </FaultRules> <!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. If a FaultRule is executed, but none of its Steps are executed, The DefaultFaultRule is not executed (because Apigee has already executed its one FaultRule). --> <DefaultFaultRule name="default-fault"> <Step> <Name>Default-message</Name> </Step> </DefaultFaultRule>
Esecuzione di TargetEndpoint
La valutazione delle FaultRules di TargetEndpoint avviene dall'alto verso il basso, quindi inizia a leggere dalla prima FaultRule nell'esempio seguente e procedi verso il basso. Esamina per ultima la regola DefaultFaultRule.
<TargetEndpoint name="default"> ... <FaultRules> <!-- 1. Because this is the TargetEndpoint, Apigee looks at this FaultRule first. Let's say this FaultRule is FALSE. A policy did not throw a FailedToResolveAPIKey error. Apigee moves down to the next FaultRule. --> <FaultRule name="invalid_key_rule"> <Step> <Name>invalid-key-message</Name> </Step> <Condition>(fault.name = "FailedToResolveAPIKey")</Condition> </FaultRule> <!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation error. This is the first FaultRule to be TRUE, so it's executed. Now the Steps are evaluated, and for the ones whose conditions evaluate to TRUE, their policies are executed. Steps without conditions are automatically true. --> <FaultRule name="over_quota"> <Step> <Name>developer-over-quota-fault</Name> <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition> </Step> <Step> <Name>global-over-quota-fault</Name> <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition> </Step> <Step> <Name>log-error-message</Name> </Step> <Condition>(fault.name = "QuotaViolation")</Condition> </FaultRule> <!-- 3. This FaultRule is automatically TRUE, because there's no outer condition. But because the FaultRule just above this got executed (top-to-bottom evaluation in a TargetEndpoint), Apigee doesn't even evaluate this FaultRule. Note that it's not a best practice to have a FaultRule without an outer condition, which automatically makes the FaultRule true. --> <FaultRule name="random-error-message"> <Step> <Name>Random-fault</Name> </Step> </FaultRule> </FaultRules> <!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. If a FaultRule is executed, but none of its Steps are executed, The DefaultFaultRule is not executed (because Apigee has already executed its one FaultRule). --> <DefaultFaultRule name="default-fault"> <Step> <Name>Default-message</Name> </Step> </DefaultFaultRule>
Ordine delle regole di guasto
Come puoi vedere nell'esempio precedente, l'ordine in cui inserisci le FaultRule è importante a seconda che l'errore si verifichi in ProxyEndpoint o in TargetEndpoint.
Ad esempio:
Ordine ProxyEndpoint | Ordine TargetEndpoint |
---|---|
Nell'esempio seguente, poiché la valutazione avviene dal basso verso l'alto, viene eseguita FaultRule 3, il che significa che FaultRule 2 e 1 non vengono valutate. 5. FaultRule 1: FALSE 4. FaultRule 2: TRUE 3. FaultRule 3: TRUE 2. FaultRule 4: FALSE 1. FaultRule 5: FALSE |
Nell'esempio seguente, poiché la valutazione avviene dall'alto verso il basso, viene eseguita FaultRule 2, il che significa che FaultRule 3, 4 e 5 non vengono valutate. 1. FaultRule 1: FALSE 2. FaultRule 2: TRUE 3. FaultRule 3: TRUE 4. FaultRule 4: FALSE 5. FaultRule 5: FALSE |
Norme da includere
Puoi eseguire qualsiasi policy da una FaultRule inserendola in Steps. Ad esempio, puoi eseguire un criterio AssignMessage per formattare una risposta all'app client, quindi registrare un messaggio con il criterio MessageLogging. I criteri vengono eseguiti nell'ordine in cui li inserisci (dall'alto verso il basso nel file XML).
Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError)
Il titolo potrebbe sembrare ripetitivo, ma c'è una sfumatura particolare da
tenere presente in merito a un errore proxy che causa l'inserimento di un proxy API in uno stato di errore o,
meglio, non l'inserimento in uno stato di errore: l'attributo continueOnError
in un criterio.
Ricapitolando: un proxy API valuta <FaultRules>
e
<DefaultFaultRule>
solo se il proxy è entrato in uno stato di errore. Ciò
significa che anche se una condizione FaultRule restituisce true, non viene attivata se il proxy
non è in uno stato di errore.
Tuttavia, ecco un esempio di errore che si verifica e il proxy non entra in uno stato di errore. In
qualsiasi criterio, puoi impostare un attributo sull'elemento principale chiamato continueOnError
.
Questo attributo è molto importante per la gestione degli errori, perché determina se
il proxy entra o meno in uno stato di errore in caso di errore del criterio. Nella maggior parte dei casi, ti consigliamo di mantenere il valore predefinito continueOnError="false"
, che imposta il proxy in uno stato di errore se il criterio non viene rispettato e viene attivata la gestione degli errori personalizzata. Tuttavia, se
continueOnError="true"
(ad esempio, se non vuoi che l'errore di un callout di servizio
interrompa l'esecuzione del proxy), il proxy non entrerà in uno stato di errore se
queste norme non vengono rispettate e non esaminerà FaultRules.
Per informazioni sulla registrazione degli errori durante continueOnError="true"
, consulta Gestione degli errori delle norme nel flusso corrente.
Dove definire FaultRules: ProxyEndpoint o TargetEndpoint
Quando un proxy API rileva un errore, l'errore si verifica in <ProxyEndpoint>
(richiesta da o risposta all'app client) o in <TargetEndpoint>
(richiesta a o risposta dal servizio di destinazione). Apigee cerca FaultRules nel punto in cui si verifica l'errore.
Ad esempio, se un server di destinazione non è disponibile (codice di stato HTTP 503
), il proxy API entra
in uno stato di errore nella risposta <TargetEndpoint>
e il normale flusso del proxy API
non continua fino a <ProxyEndpoint>
. Se hai definito FaultRules
solo in <ProxyEndpoint>
, non gestiranno l'errore.
Ecco un altro esempio. Se un criterio RaiseFault nella risposta <ProxyEndpoint>
attiva un errore, una FaultRule in <TargetEndpoint>
non verrà
eseguita.
FaultRules e il criterio RaiseFault
Le regole di errore e la norma RaiseFault possono sembrare modi alternativi per gestire gli errori e in alcuni casi è vero. ma collaborano anche. Questa sezione spiega il rapporto tra le due. Comprendere questa relazione dovrebbe aiutarti a progettare la gestione degli errori, soprattutto se vuoi utilizzarli entrambi.
In breve:
- Le regole di errore vengono sempre valutate quando un proxy API entra in uno stato di errore.
-
La policy RaiseFault è un modo per impostare un proxy API in uno stato di errore quando altrimenti non si sarebbe verificato un errore.
Ad esempio, se vuoi generare un errore se il codice di stato HTTP nella risposta del servizio di destinazione è maggiore di
200
, aggiungi un criterio RaiseFault nel flusso di risposta. L'aspetto sarà simile al seguente:<TargetEndpoint name="default"> <PreFlow name="PreFlow"> ... <Response> <Step> <Name>Raise-Fault-1</Name> <!-- If the condition is true, the Raise-Fault-1 policy gets executed --> <Condition>(response.status.code GreaterThan "200")</Condition> </Step> </Response>
Il criterio RaiseFault invia anche un messaggio di errore all'app client.
Cosa succede quando una norma RaiseFault attiva un errore, che mette il proxy in uno stato di errore, che potenzialmente esegue una FaultRule? A questo punto le cose possono diventare un po' complicate. Se il criterio RaiseFault restituisce un messaggio di errore e viene attivata una FaultRule che restituisce un messaggio di errore, cosa viene restituito all'app client?
- Poiché FaultRule o DefaultFaultRule viene eseguita dopo la norma RaiseFault, i dati di risposta di FaultRule hanno la precedenza.
- I dati di risposta del criterio RaiseFault (codice di stato o payload del messaggio) vengono utilizzati se non sono impostati da FaultRule o DefaultFaultRule.
- Se sia il criterio RaiseFault che FaultRule aggiungono intestazioni HTTP personalizzate, entrambe vengono incluse nella risposta. I nomi delle intestazioni duplicati creano un'intestazione con più valori.
Ecco un esempio di ciò che viene impostato da un criterio RaiseFault e da una FaultRule e di ciò che viene restituito all'app client. Gli esempi sono pensati per essere brevi, non per le best practice.
L'app client riceve: Status Code: 468 Payload: {"Whoa":"Sorry."} Header: errorNote: woops,gremlins |
<- Fault rules policy sets this: Status Code: [none] Payload: {"Whoa":"Sorry."} Header: errorNote: gremlins |
<- RaiseFault policy sets this: Status Code: 468 Payload: {"DOH!":"Try again."} Header: errorNote: woops |
Condizioni di costruzione
Le condizioni sono fondamentali per l'esecuzione di FaultRule. Crea le condizioni FaultRule nello stesso modo in cui crei altre condizioni in Apigee, ad esempio per i flussi condizionali o le condizioni RaiseFault.
Per contestualizzare il resto di questa sezione, ecco una regola di errore di esempio con una condizione FaultRule esterna e una condizione Step interna.
<FaultRule name="invalid_key_rule"> <Step> <Name>invalid-key-message</Name> <Condition>oauthV2.Verify-API-Key-1.failed = true</Condition> </Step> <Condition>fault.name = "FailedToResolveAPIKey"</Condition> </FaultRule>
Variabili specifiche per gli errori dei criteri
Le variabili fault.name
e {policy_namespace}.{policy_name}.failed
sono disponibili quando un criterio genera un errore.
fault.name
Quando un criterio non viene applicato, intercetta l'errore in una condizione utilizzando la variabile fault.name
. Ad esempio:
<Condition>fault.name = "policy_error_name"</Condition>
Il nome dell'errore viene visualizzato nel messaggio di errore predefinito. Ad esempio, nel seguente, il nome del guasto è FailedToResolveAPIKey
. In questo caso, una variabile di flusso chiamata
fault.name
è impostata sul valore FailedToResolveAPIKey
.
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
Quindi la condizione sarà simile a questa:
<Condition>fault.name = "FailedToResolveAPIKey"</Condition>
Per un elenco degli errori relativi alle norme, consulta la guida di riferimento agli errori relativi alle norme.
{policy_namespace}.{policy_name}.failed
La variabile *.failed
è disponibile quando un criterio non viene rispettato. Di seguito sono riportati
esempi di variabili *.failed
per criteri diversi.
Per gli spazi dei nomi dei criteri, consulta le variabili di flusso in ogni argomento di riferimento ai criteri.
- Criterio RaiseFault:
raisefault.failed
(lo stesso per tutti i criteri RaiseFault) - Criterio VerifyAPIKey:
oauthV2.{policy_name}.failed
, ad esempiooauthV2.Verify-API-Key-1.failed
- Criteri per le quote e criteri SpikeArrest:
ratelimit.{policy_name}.failed
, ad esempio,ratelimit.Quota-1.failed
Altre variabili disponibili
Quando un proxy API entra in uno stato di errore, le uniche variabili disponibili per l'utilizzo nelle condizioni sono:
- Le variabili del criterio non riuscito.
- Le variabili dei messaggi HTTP esistenti al momento dell'errore. Ad esempio, se viene
generato un errore nella risposta, una FaultRule in
<TargetEndpoint>
potrebbe utilizzare dati HTTPresponse.status.code
,message.content
,error.content
e così via. Se un criterio di quota non è andato a buon fine, puoi utilizzare la variabileratelimit.{quota_policy_name}.exceed.count
. Utilizza lo strumento di debug e il riferimento alle norme per capire quali variabili e dati HTTP sono disponibili.
Ulteriori informazioni
-
Condizioni: Riferimento alle condizioni e Variabili e condizioni del flusso
- Errori: Riferimento all'errore relativo alle norme
- Variabili: riferimento alle variabili di flusso e consulta le singole pagine di riferimento alle norme per le variabili disponibili con ogni norma.
Best practice per la gestione degli errori
La gestione degli errori è un'attività di progettazione architettonica importante per lo sviluppo di proxy API. È importante dedicare del tempo a capire come e quando gestire gli errori, determinare il contenuto dei messaggi di errore e progettare i formati dei messaggi di errore. Dopo (o mentre) capisci queste cose, utilizza queste best practice per aiutarti con l'implementazione della gestione degli errori.
Ecco alcune best practice per la progettazione e la creazione della gestione degli errori:
- In FaultRules, puoi specificare qualsiasi tipo di criterio. Il pattern più comune è utilizzare il criterio AssignMessage per impostare elementi specifici nella risposta di errore in attesa. Puoi anche utilizzare AssignMessage per impostare variabili utilizzate per altri scopi, ad esempio per le variabili a cui fanno riferimento le norme di logging eseguite in PostClientFlow o in FlowHooks. Valuta anche la possibilità di registrare un messaggio, ad esempio con il criterio MessageLogging o con il criterio ServiceCallout, se vuoi registrare errori specifici in condizioni di errore specifiche.
- Non specificare i criteri RaiseFault come passaggi all'interno di una FaultRule. È meglio utilizzare i criteri AssignMessage per impostare o modificare gli elementi del messaggio, inclusi payload, intestazioni o codice di stato.
- Per ogni FaultRule o per tutte le FaultRule tranne l'ultima valutata,
fornisci un outer
<Condition>
allegato come elemento secondario dell'elemento<FaultRule>
. La condizione di esecuzione per una FaultRule senza una condizione esplicita specificata verrà valutata implicitamente cometrue
. Un elemento<Condition>
allegato come elemento secondario di un elemento<Step>
non viene utilizzato per determinare se la condizione di esecuzione per FaultRule restituiscetrue
ofalse
. Le condizioni del passaggio vengono valutate solo dopo che Apigee esegue la FaultRule che le contiene. In una FaultRule, è comune avere più passaggi con criteri AssignMessage (o altri), ognuno con una condizione di passaggio. -
Per gestire gli errori in più criteri dello stesso tipo (ad esempio, più criteri Quota), crea una FaultRule per ogni errore dei criteri che probabilmente riceverai, quindi distingui tra errori separati con le condizioni associate ai passaggi. Ad esempio, crea una FaultRule per gestire un errore nei criteri di quota, ad esempio
QuotaViolation
e una FaultRule separata perInvalidApiKey
. Per gli errori relativi alle norme, consulta il riferimento agli errori relativi alle norme. Man mano che scopri altri errori da gestire, puoi tornare indietro in un secondo momento e aggiungerli a FaultRules. È possibile procedere in modo iterativo, anche se è necessario il redeployment del proxy. Questo approccio ti consente di rilevare lo stesso tipo di errore indipendentemente dal criterio che lo genera, il che rende efficiente il file XML FaultRules.Le condizioni del passaggio interno ti offrono un controllo più granulare. Ad esempio, se applichi sia la quota per sviluppatore individuale sia la quota globale con due criteri nel flusso di richiesta, imposta la condizione esterna FaultRule in modo che venga attivata in caso di errore
QuotaViolation
(che viene generato quando la quota viene superata in entrambi i casi). Poi imposta le condizioni del passaggio per valutare le variabiliexceed.count
specifiche in entrambe le tue norme relative alle quote. Al client viene inviato solo l'errore pertinente (superamento della quota dello sviluppatore o superamento della quota globale). Ecco un esempio di questa configurazione:<FaultRule name="over_quota"> <!-- This condition catches a QuotaViolation in *any* Quota policy --> <Condition>fault.name = "QuotaViolation"</Condition> <Step> <Name>AM-developer-over-quota-fault</Name> <Condition>ratelimit.developer-quota-policy.exceed.count GreaterThan 0</Condition> </Step> <Step> <Name>AM-global-over-quota-fault</Name> <Condition>ratelimit.global-quota-policy.exceed.count GreaterThan 0</Condition> </Step> </FaultRule>
Per un altro esempio, consulta questa discussione sulla gestione degli errori delle norme.
-
Per gestire gli errori quando utilizzi un singolo criterio di un tipo, valuta la possibilità di utilizzare una singola regola di errore che viene eseguita quando il criterio non va a buon fine e includi più passaggi che corrispondono a ogni possibile errore. In questo modo, il file XML rimane più semplice perché utilizza una sola FaultRule anziché più FaultRule (una per ogni tipo di errore). Ad esempio, puoi specificare che diversi passaggi della norma AssignMessage vengano eseguiti in condizioni diverse, come segue:
<FaultRule name="raise-fault-3"> <!-- This condition catches *any* error in the Verify-API-Key-1 policy. --> <Condition>oauthV2.Verify-API-Key-1.failed = "true"</Condition> <!-- This first step always executes, which handles errors you haven't mapped with inner conditions. --> <Step> <Name>AM-Generic-Key-Fault</Name> </Step> <Step> <Name>AM-API-Key-NotFound</Name> <Condition>fault.name = "FailedToResolveAPIKey"</Condition> </Step> <Step> <Name>AM-API-Key-Invalid</Name> <Condition>fault.name = "InvalidApiKey"</Condition> </Step> </FaultRule>
- Aggiungi FaultRules in cui si verificheranno gli errori (lato client
<ProxyEndpoint>
o lato target<TargetEndpoint>
). Includi FaultRules per ogni norma visualizzata in ogni posizione. - Quando utilizzi i criteri RaiseFault insieme a FaultRules, coordina i dati di risposta che vengono restituiti quando sia il criterio RaiseFault sia una FaultRule restituiscono dati. Ad esempio, se hai un criterio RaiseFault che imposta il codice di stato HTTP, non configurare anche un passaggio AssignMessage all'interno di una FaultRule che reimposta il codice di stato. Il peggio che può capitare è che il codice di stato predefinito venga restituito all'app client.
-
L'elemento
<DefaultFaultRule>
integra l'elemento<FaultRules>
per offrirti un maggiore controllo sulle norme che il proxy esegue quando gestisce uno stato di errore. Se specifichi un<DefaultFaultRule>
, questo verrà eseguito se una o entrambe le seguenti condizioni sono vere:- Nessun'altra FaultRule è stata eseguita. Un caso speciale è quando non è configurato alcun elemento
<FaultRules>
. - Se l'elemento secondario
<AlwaysEnforce>
di<DefaultFaultRule>
è true.
Puoi anche specificare un elemento
<Condition>
in un elemento<DefaultFaultRule>
. Potresti volerlo fare per escluderne l'esecuzione in base a un determinato stato della richiesta o a un messaggio di errore in attesa, ad esempio se un'intestazione specifica è presente o mancante.Utilizza un
<DefaultFaultRule>
con<AlwaysEnforce>
impostato sutrue
, se hai una o più policy che vuoi che il proxy esegua sempre, indipendentemente dal fatto che sia stata eseguita una FaultRule precedente. Uno scenario possibile: supponiamo che tu voglia inserire un'intestazione nella risposta in tutti i casi, indipendentemente dal fatto che la richiesta proxy abbia generato un errore o meno e indipendentemente dal fatto che l'errore sia stato gestito in precedenza. Poi devi allegare un criterio AssignMessage appropriato nella sezione<PostFlow>
/<Response>
e allegare lo stesso criterio anche in<DefaultFaultRule>
con<AlwaysEnforce>
impostato sutrue
. - Nessun'altra FaultRule è stata eseguita. Un caso speciale è quando non è configurato alcun elemento
Pattern per la gestione centralizzata e riutilizzabile degli errori
Un pattern di gestione degli errori per i proxy Apigee descrive un pattern per la gestione centralizzata degli errori senza duplicazione del codice.
Creazione di FaultRules
Per aggiungere una FaultRule, devi modificare la configurazione XML di ProxyEndpoint o TargetEndpoint. Puoi utilizzare la UI di Apigee per apportare questa modifica nel riquadro Codice della visualizzazione Sviluppa per un proxy API oppure modificare il file XML che definisce ProxyEndpoint o TargetEndpoint.
Se crei FaultRules nella UI di Apigee, crea prima i criteri che vuoi eseguire, poi aggiungili alla configurazione di FaultRule. Se provi a salvare una FaultRule che fa riferimento a un criterio non ancora creato, nell'interfaccia utente viene visualizzato un errore.
Aggiunta di policy a una FaultRule
Anche se puoi inserire qualsiasi policy in FaultRule, in genere utilizzi la policy AssignMessage per generare un messaggio di risposta personalizzato per una condizione di errore. AssignMessage consente di configurare una risposta HTTP con payload, codice di stato HTTP e intestazioni.
L'esempio seguente mostra una configurazione tipica del criterio AssignMessage:
<AssignMessage name="AM-Invalid-Key"> <Set> <Payload contentType="text/plain">That is an error.</Payload> <StatusCode>401</StatusCode> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </AssignMessage>
Tieni presente che non specifica un elemento <AssignTo>
. Ciò significa che
verrà assegnato al messaggio ambientale, a seconda di dove è allegato il criterio.
Ora puoi utilizzare questo criterio in FaultRule. Nota come fai riferimento alla norma AssignMessage per nome in FaultRule:
<ProxyEndpoint name="default"> ... <FaultRules> <FaultRule name="invalid_key_rule"> <Step> <Name>AM-Invalid-Key</Name> </Step> <Condition>fault.name = "InvalidApiKey"</Condition> </FaultRule> </FaultRules> </ProxyEndpoint>
Quando esegui il deployment della configurazione precedente, il proxy API esegue il criterio AssignMessage
chiamato AM-Invalid-Key
ogni volta che un'app presenta una chiave API non valida.
Puoi eseguire più criteri in una FaultRule, come mostrato nell'esempio seguente:
<ProxyEndpoint name="default"> ... <FaultRules> <FaultRule name="invalid_key_rule"> <Step> <Name>AM-Invalid-Key</Name> </Step> <Step> <Name>policy2</Name> </Step> <Step> <Name>policy3</Name> </Step> <Condition>fault.name = "InvalidApiKey"</Condition> </FaultRule> </FaultRules> </ProxyEndpoint>
I criteri vengono eseguiti nell'ordine definito. Ad esempio, puoi utilizzare la policy MessageLogging, la policy ExtractVariables, la policy AssignMessage o qualsiasi altra policy in FaultRule. Tieni presente che l'elaborazione di FaultRule si interrompe immediatamente se si verifica una di queste situazioni:
- Qualsiasi norma in FaultRule causa un errore
- Una qualsiasi delle norme in FaultRule è di tipo RaiseFault
Definizione del messaggio di errore personalizzato restituito da una FaultRule
Come best practice, devi definire risposte di errore chiare dalle tue API. In questo modo, fornisci informazioni coerenti e utili ai tuoi clienti.
Il seguente esempio di norma AssignMessage utilizza i tag <Payload>
e
<StatusCode>
per definire la risposta di errore personalizzata
inviata al client in caso di errore InvalidApiKey (vedi l'esempio precedente di FaultRules).
<AssignMessage name="AM-Invalid-Key"> <Set> <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization. Contact support at support@mycompany.com.</Payload> <StatusCode>401</StatusCode> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </AssignMessage>
Questa risposta include:
- Il payload contenente il messaggio di errore e un indirizzo email per contattare l'assistenza.
- Il codice di stato HTTP restituito nella risposta.
Creazione di una DefaultFaultRule
Una DefaultFaultRule funge da gestore delle eccezioni per qualsiasi errore non gestito esplicitamente da
un'altra FaultRule. Se le condizioni di tutte le FaultRule non corrispondono all'errore, quest'ultimo viene gestito da DefaultFaultRule. Attiva la gestione degli errori predefinita aggiungendo il tag <DefaultFaultRule>
come elemento secondario di un ProxyEndpoint o un TargetEndpoint.
Ad esempio, la configurazione TargetEndpoint riportata di seguito definisce una DefaultFaultRule che richiama una norma denominata AM-Return-Generic-Error
:
<TargetEndpoint name="default"> ... <FaultRules> ... </FaultRules> <DefaultFaultRule name="fault-rule"> <Step> <Name>AM-Return-Generic-Error</Name> </Step> </DefaultFaultRule> <HTTPTargetConnection> <URL>https://mytarget.example.net</URL> </HTTPTargetConnection> </TargetEndpoint>
La regola DefaultFaultRule viene in genere utilizzata per restituire un messaggio di errore generico per qualsiasi errore imprevisto, ad esempio un messaggio che contiene i dati di contatto dell'assistenza tecnica. Questa risposta predefinita ha il duplice scopo di fornire informazioni utili agli sviluppatori e di offuscare gli URL di backend o altre informazioni che potrebbero essere utilizzate per compromettere il sistema.
Ad esempio, definisci il seguente criterio AssignMessage per restituire un errore generico:
<AssignMessage name="AM-Return-Generic-Error"> <Set> <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload> </Set> </AssignMessage>
Includi l'elemento <AlwaysEnforce>
nel tag <DefaultFaultRule>
per eseguire DefaultFaultRule per ogni errore, anche se è già stata eseguita un'altra FaultRule. La regola DefaultFaultRule è sempre l'ultima FaultRule
da eseguire:
<DefaultFaultRule name="fault-rule"> <Step> <Name>AM-Return-Generic-Error</Name> </Step> <AlwaysEnforce>true</AlwaysEnforce> </DefaultFaultRule>
Un utilizzo di DefaultFaultRule è quello di determinare il tipo di errore che si verifica quando
altrimenti non è possibile determinarlo. Ad esempio, se il proxy API non funziona a causa di un errore che
non riesci a determinare, puoi utilizzare DefaultFaultRule per richiamare la seguente policy AssignMessage. Questo
criterio scrive il valore fault.name
in un'intestazione denominata Unhandled-Fault
nella risposta:
<AssignMessage name="AM-Set-Fault-Header"> <Set> <Headers> <Header name="Unhandled-Fault">{fault.name}</Header> </Headers> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </AssignMessage>
Puoi quindi visualizzare l'intestazione nello strumento di debug o nella risposta per vedere la causa dell'errore.
Aggiunta della registrazione dei messaggi a PostClientFlow
PostClientFlow è l'unico flusso che viene eseguito dopo che il proxy entra nello stato di errore. A questo flusso può essere allegata solo la norma MessageLogging, che viene eseguita dopo l'invio della risposta al client. Sebbene l'allegato del criterio MessageLogging a questo flusso non sia tecnicamente la gestione degli errori, puoi utilizzarlo per registrare informazioni in caso di errore. Poiché viene eseguito indipendentemente dall'esito positivo o negativo del proxy, puoi inserire i criteri di logging dei messaggi in PostClientFlow e avere la garanzia che vengano sempre eseguiti.
Gestione degli errori dei criteri all'interno del flusso corrente
Gli esempi mostrati finora utilizzano tutti una FaultRule su ProxyEndpoint o TargetEndpoint per gestire
eventuali errori dei criteri come parte dello stato di errore. Questo perché il valore predefinito dell'elemento
continueOnError
di un criterio è false
, il che significa che quando si verifica un
errore in un criterio, il controllo viene indirizzato allo stato di errore. Una volta nello stato di errore, non puoi restituire il controllo alla pipeline normale e in genere restituisci una qualche forma di messaggio di errore all'app chiamante.
Tuttavia, se imposti l'elemento continueOnError
su true
per un criterio, il controllo rimane nel flusso corrente e il criterio successivo nella pipeline viene eseguito dopo il criterio che ha causato l'errore. Il vantaggio di gestire l'errore nel flusso corrente è che
potresti avere un modo per recuperare dall'errore e completare l'elaborazione della richiesta.
Di seguito è riportata una policy VerifyAPIKey denominata verify-api-key
con l'elemento
continueOnError
impostato su true:
<VerifyAPIKey continueOnError="true" name="verify-api-key"> <DisplayName>Verify API Key</DisplayName> <APIKey ref="request.queryparam.apikey"/> </VerifyAPIKey>
Se la chiave API è mancante o non valida, il criterio VerifyAPIKey imposta la variabile
oauthV2.verify-api-key.failed
su true
, ma l'elaborazione
continua nel flusso corrente.
A questo punto, aggiungi il criterio VerifyAPIKey come passaggio nel PreFlow di ProxyEndpoint:
<ProxyEndpoint name="default"> ... <PreFlow name="PreFlow"> <Request> <Step> <Name>verify-api-key</Name> </Step> <Step> <Name>FaultInFlow</Name> <Condition>oauthV2.verify-api-key.failed = "true"</Condition> </Step> </Request> <Response/> </PreFlow> </ProxyEndpoint>
Nota come il passaggio successivo nel PreFlow utilizzi una condizione per verificare l'esistenza di un errore. Se si è verificato un errore nel criterio VerifyAPIKey, viene eseguito il criterio denominato
FaultInFlow
. In caso contrario, il criterio FaultInFlow
viene
ignorato. Le norme FaultInFlow
possono fare molte cose, ad esempio registrare l'errore,
tentare di correggerlo o eseguire un'altra azione.
Attivazione di un errore utilizzando il criterio RaiseFault
Puoi utilizzare il criterio RaiseFault in qualsiasi momento di un flusso per attivare un errore. Quando viene eseguito un criterio RaiseFault, il flusso corrente viene interrotto e il controllo viene trasferito allo stato di errore.
Un utilizzo del criterio RaiseFault è quello di testare una condizione specifica che un altro criterio
potrebbe non rilevare. Nell'esempio precedente, hai aggiunto un tag <Condition>
a un tag
PreFlow <Step>
che ha causato l'esecuzione della policy FaultInFlow
se la condizione è soddisfatta. Se FaultInFlow
è un criterio RaiseFault, il controllo
viene trasferito allo stato di errore. In alternativa, puoi inserire una norma RaiseFault in un flusso per eseguire il debug e
testare le FaultRules.
Quando un criterio RaiseFault attiva un errore, puoi utilizzare la seguente FaultRule e condizione per elaborarlo:
<FaultRule name="raisefault_rule"> <Step> <Name>POLICY-NAME-HERE</Name> </Step> <Condition>fault.name = "RaiseFault"</Condition> </FaultRule>
Tieni presente che la condizione verifica un errore denominato RaiseFault
. Il criterio RaiseFault
imposta sempre il valore di fault.name
su RaiseFault
. Puoi anche
impostare variabili personalizzate all'interno di una norma RaiseFault. In questo modo, puoi testare queste variabili
all'interno degli elementi Condizione.
Gestione personalizzata dei codici di errore HTTP dal server di destinazione
Gli esempi mostrati nelle sezioni precedenti si applicano agli errori creati dalle norme. Tuttavia, puoi anche creare una risposta personalizzata per gli errori a livello di trasporto, ovvero gli errori HTTP restituiti dal server di destinazione. Per controllare la risposta a un errore HTTP, configura un TargetEndpoint per elaborare i codici di risposta HTTP.
Per impostazione predefinita, Apigee considera i codici di risposta HTTP nell'intervallo 1xx-3xx
come
riusciti e i codici di risposta HTTP nell'intervallo 4xx-5xx
come non riusciti. Ciò significa che qualsiasi risposta dal servizio di backend
con un codice di risposta HTTP 4xx-5xx
richiama automaticamente lo stato di errore, che a sua volta
restituisce un messaggio di errore direttamente al client richiedente.
Puoi creare gestori personalizzati per qualsiasi codice di risposta HTTP. Ad esempio, potresti non voler
trattare tutti i codici di risposta HTTP nell'intervallo 4xx-5xx
come "errore", ma solo
5xx
oppure potresti voler
restituire messaggi di errore personalizzati per i codici di risposta HTTP 400
e 500
.
Nell'esempio successivo, utilizzi la proprietà success.codes
per configurare
TargetEndpoint in modo che tratti i codici di risposta HTTP 400
e 500
come riusciti,
insieme ai codici HTTP predefiniti. Trattando questi codici come riusciti, TargetEndpoint assume l'elaborazione del
messaggio di risposta, anziché richiamare lo stato di errore:
<TargetEndpoint name="default"> ... <HTTPTargetConnection> <Properties> <Property name="success.codes">1xx,2xx,3xx,400,500</Property> </Properties> <URL>http://weather.yahooapis.com</URL> </HTTPTargetConnection> </TargetEndpoint>
Come puoi vedere in questo esempio, puoi utilizzare i caratteri jolly per impostare la proprietà success.codes su un intervallo di valori.
L'impostazione della proprietà success.codes
sovrascrive
i valori predefiniti. Pertanto, se vuoi aggiungere il codice HTTP 400
all'elenco dei codici di successo predefiniti, imposta questa proprietà come:
<Property name="success.codes">1xx,2xx,3xx,400</Property>
Tuttavia, se vuoi che solo il codice HTTP 400
venga considerato come codice di successo, imposta la proprietà come segue:
<Property name="success.codes">400</Property>
Ora puoi definire gestori personalizzati per i codici di risposta HTTP 400
e 500
per restituire un messaggio di risposta personalizzato
all'app richiedente. Il seguente TargetEndpoint utilizza il criterio denominato
ReturnError
per gestire i codici di risposta HTTP 400
e 500
:
<TargetEndpoint name="default"> <PreFlow name="PreFlow"> <Request/> <Response> <Step> <Name>ReturnError</Name> <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition> </Step> </Response> </PreFlow> <HTTPTargetConnection> <Properties> <Property name="success.codes">1xx,2xx,3xx,400,500</Property> </Properties> <URL>http://weather.yahooapis.com</URL> </HTTPTargetConnection> </TargetEndpoint>
Questa configurazione TargetEndpoint fa sì che il criterio denominato ReturnError
gestisca la risposta ogni volta che TargetEndpoint rileva un codice di risposta HTTP 400
O 500
.
Tassonomia dei guasti
API Services organizza gli errori nelle seguenti categorie e sottocategorie.
Categoria | Sottocategoria | Nome guasto | Descrizione |
---|---|---|---|
Messaggistica | Errori che si verificano durante il flusso dei messaggi (esclusi gli errori relativi alle norme) | ||
Guasti personalizzati | {fault_name} | Eventuali errori gestiti esplicitamente dal proxy API utilizzando il criterio RaiseFault | |
Codici di risposta | InternalServerError, NotFound | Codici di errore HTTP 5xx , 4xx |
|
Errori di routing | NoRoutesMatched | Errore durante la selezione di un TargetEndpoint denominato per una richiesta | |
Errori di classificazione | NotFound | Errori causati da un URI di richiesta che non corrisponde a nessun BasePath per nessuna configurazione ProxyEndpoint (ovvero nessun proxy API corrisponde all'URL nella richiesta dell'app client) | |
Trasporto | Errori a livello di trasporto HTTP | ||
Connettività | ConnectionRefused, ConnectionReset, ConnectionTimeout | Si verificano errori durante la creazione di connessioni a livello di rete o di trasporto | |
Convalide delle richieste | ContentLengthMissing, HostHeaderMissing | Si verificano errori durante i controlli semantici su ogni richiesta | |
Convalide delle risposte | Si verificano errori durante i controlli semantici su ogni risposta | ||
Errori I/O | SSLHandshakeError, ReadTimeout, ReadError, WriteTimeout, WriteError, ChunkError | Errori di lettura/scrittura negli endpoint client o di destinazione, timeout, errori TLS/SSL ed errori chunked | |
Sistema | Errori di runtime non definiti | ||
Memoria | OutOfMemory, GCOverLimit | Errori relativi alla memoria | |
Thread | RogueTaskTerminated | Errori come la terminazione di attività non controllate | |
Norme | I difetti per ogni tipo di norma sono definiti nel Riferimento alle norme. |
Un errore è sempre accompagnato da una descrizione testuale del motivo del problema. Quando il sistema rileva un errore, viene compilato un insieme di attributi per facilitare la risoluzione dei problemi. Un guasto include le seguenti informazioni:
- Motivo
- Attributi personalizzati definiti dall'utente