Gestione degli errori

Questa pagina si applica a Apigee e Apigee ibrido.

Visualizza la documentazione di Apigee Edge.

Quando i proxy API gestiscono le richieste delle app, possono verificarsi molte condizioni di errore. 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, viene restituito un messaggio di errore al client. 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 persino arricchirli con elementi come intestazioni HTTP aggiuntive, devi configurare una gestione degli errori personalizzata in Apigee.

La gestione personalizzata degli errori consente anche di aggiungere funzionalità come il logging 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 i proxy API reagiscono.

Video

Guarda i video che seguono per scoprire di più sulla gestione dei guasti.

Video Descrizione
Introduzione alla gestione degli errori e ai flussi di errori Scopri di più sulla gestione degli errori e su cosa succede quando si verifica un errore in un proxy API.
Gestisci gli errori utilizzando le regole di errore Scopri come gestire gli errori utilizzando le regole di errore.
Aumenta gli errori personalizzati utilizzando il criterio RaiseFault Genera errori personalizzati durante il runtime dell'API utilizzando il criterio RaiseFault.
Definisci le 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.
Comprendi l'ordine di esecuzione delle regole di errore Comprendi l'ordine di esecuzione delle regole di errore nel proxy API e negli endpoint di destinazione.
Definisci una regola di errore predefinita Definisci una regola di errore predefinita per gestire errori generici nell'API.

Come si verificano gli errori

Innanzitutto, vedremo semplicemente come si verificano gli errori. Sapere come si verificano gli errori ti aiuta a pianificare le diverse situazioni in cui vuoi implementare una gestione personalizzata degli errori.

Errori automatici

Un proxy API genera automaticamente un errore nelle seguenti situazioni:

  • Un criterio genera un errore. Ad esempio, se una chiamata API invia una chiave scaduta, il criterio VerificationAPIKey genera automaticamente un errore oppure, se il numero di chiamate API supera un determinato limite, il criterio per le quote o il criterio SpikeArrest genera un errore. (consulta la Guida di riferimento agli errori dei criteri per conoscere i tipi di errori che i criteri possono generare).
  • Si è verificato un problema nel flusso dei messaggi proxy API, ad esempio un errore di routing.
  • Si è verificato un errore del backend, ad esempio un errore HTTP dovuto a errori a livello di protocollo, errori TLS/SSL o un servizio di destinazione non disponibile.
  • Errore a livello di sistema, ad esempio eccezione di esaurimento memoria.

Per maggiori informazioni su questi errori, consulta la sezione Tassonomia degli errori in questo argomento.

Errori personalizzati

Per le situazioni in cui non si verifica un errore automatico, potresti 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 alla posizione appropriata in un flusso proxy API.

Puoi aggiungere un criterio RaiseFault a un flusso proxy API come faresti con qualsiasi altro criterio. Nel seguente esempio di configurazione del proxy, il criterio Raise-Fault-1 è collegato alla risposta TargetEndpoint. Se è presente la parola unavailable nella risposta del servizio di destinazione, il criterio RaiseFault viene eseguito e genera un errore.

<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>Raise-Fault-1</Name>
      <Condition>message.content Like "*unavailable*"</Condition>
    </Step>
  </Response>

Hai solo l'obiettivo di mostrarti che puoi generare errori personalizzati. Osserviamo più in dettaglio il criterio RaiseFault nella sezione FaultRules rispetto al criterio RaiseFault.

Per ulteriori esempi, leggi i seguenti post della community Apigee:

Che cosa fanno i proxy API quando si verificano errori

Ecco cosa succede quando un proxy restituisce un errore.

Esci dalla pipeline proxy

Quando un proxy API riscontra 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ò tornare all'elaborazione nella normale pipeline di flusso.

Ad esempio, supponiamo che un proxy API abbia criteri nel seguente ordine nella richiesta ProxyEndpoint:

  1. Verifica chiave API
  2. Quota
  3. Da JSON a XML

Se si verifica un errore durante la verifica della chiave API, il proxy API passa allo stato di errore. I criteri Quota e JSON a XML non vengono eseguiti, il proxy non procede al TargetEndpoint e viene restituito un messaggio di errore all'app client.

Controlla FaultRules

Nello stato di errore, i proxy API controllano anche la presenza dei seguenti elementi (in ordine) nella configurazione del proxy API prima di restituire un messaggio di errore predefinito all'app client:

  1. Una sezione <FaultRules> contenente la logica per attivare messaggi di errore personalizzati (e altri criteri) in base a condizioni specifiche da te definite.
  2. 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.

In sostanza, il proxy API ti offre la possibilità di restituire un messaggio di errore personalizzato e attivare altra logica. Se il proxy non trova nessuna di queste sezioni o esistono, ma non è stato attivato alcun errore personalizzato, invia il proprio messaggio predefinito generato da Apigee.

Esempio di gestione dei guasti semplice

Iniziamo con un semplice esempio, in cui una chiamata a un proxy API non contiene una chiave API obbligatoria. Per impostazione predefinita, la seguente è la risposta che viene restituita all'app client:

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

È possibile che i tuoi utenti dell'API siano in grado di capire il messaggio di errore, ma non è così. 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 chiunque lo riceva, che si tratti di uno sviluppatore di app per iOS o di un gruppo di test interno con requisiti propri per il formato dei messaggi di errore.

Ecco un esempio base di come creare un messaggio di errore personalizzato per gestire questo errore. Ciò richiede 1) un criterio che definisce il messaggio personalizzato e 2) una regola di errore che esegua il criterio quando il proxy passa in stato di errore.

1. Crea un criterio che definisce il messaggio personalizzato

Innanzitutto, crea un criterio che definisce il messaggio di errore personalizzato. Puoi utilizzare qualsiasi tipo di criterio, ad esempio un criterio AttributionMessage, che può impostare un payload e intestazioni HTTP facoltative come il codice di stato e la frase del motivo. Il criterioAssignMessage è l'ideale. Consente di controllare il payload dei messaggi, impostare un codice di stato HTTP diverso, impostare una frase di motivo HTTP diversa e aggiungere intestazioni HTTP.

Non è necessario collegare il criterio a un flusso, ma devi solo crearlo, come descritto in Creare il criterio.

Di seguito è riportato un esempio di criterio AttributionMessage che:

  • Restituisce un messaggio JSON.
  • Imposta un codice di stato HTTP (911, che è un evidente codice di stato inesistente semplicemente per illustrare la flessibilità di cui disponi). Il codice di stato viene visualizzato nell'intestazione HTTP.
  • Imposta una frase di motivo HTTP (per sostituire la frase predefinita del motivo Unauthorized per questo errore relativo alla chiave API mancante). La frase del motivo viene visualizzata accanto al codice di stato 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! Call the cops!</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à la seguente. Confrontala 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! Call the cops!
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 le possibilità. Almeno ora lo sviluppatore che riceve il messaggio sa di aver dimenticato di includere una chiave API come parametro di query.

Come viene applicata questa norma? Viene mostrata la sezione successiva.

2. Crea la regola <FaultRule> che attiverà il criterio

Nelle sezioni <ProxyEndpoint> o <TargetEndpoint> della configurazione del proxy, aggiungerai un blocco XML <FaultRules> contenente una o più sezioni <FaultRule> singole. Ogni FaultRule rappresenta un errore diverso che vuoi gestire. In questo semplice esempio, utilizzeremo una sola regola di errore per mostrarti di cosa è composta.

Devi anche aggiungere <DefaultFaultRule> per fornire un messaggio di errore generale personalizzato se non viene eseguita nessuna delle regole di errore.

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 nel ProxyEndpoint. Questo è importante. Ulteriori informazioni sull'impostazione di FaultRules nel ProxyEndpoint rispetto a TargetEndpoint in seguito.
  • <Name>: il nome del criterio da eseguire. Il nome proviene dall'attributo name del criterio nell'elemento padre, come mostrato nell'esempio di criterio in precedenza.

  • <Condition>: Apigee valuta la condizione ed esegue il criterio solo se la condizione è true. Se ci sono più FaultRules che valutano come true, Apigee esegue la prima che è vera. Importante: l'ordine in cui vengono valutate le regole di errore, dall'alto verso il basso o dal basso verso l'alto, è diverso tra TargetEndpoint e ProxyEndpoint, come descritto nella sezione Regole di errore multiple e logica di esecuzione. Se non includi una condizione, la regola di errore viene impostata automaticamente su true. Ma non è una best practice. Ogni FaultRule deve avere una propria condizione.

  • <DefaultFaultRule>: se non viene eseguita alcuna FaultRule personalizzata, viene eseguito <DefaultFaultRule>, inviando un messaggio personalizzato più generico anziché il messaggio criptico predefinito 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 dalla soluzione come ultima risorsa.

    La regola predefinitaFaultRule viene in genere utilizzata per restituire un messaggio di errore generico per qualsiasi errore imprevisto. Un esempio può essere un messaggio che contiene i dati di contatto per l'assistenza tecnica. Questa risposta predefinita ha il duplice scopo di fornire informazioni a misura di sviluppatore, offuscando al contempo gli URL di backend o altre informazioni che potrebbero essere utilizzate per compromettere il sistema.

Più FaultRules e logica di esecuzione

Nella sezione Esempio di gestione degli errori semplice, abbiamo utilizzato un semplice esempio di una singola regola e condizione di errore. In un progetto API reale, con tutti i possibili errori che possono verificarsi, è probabile che tu abbia più FaultRules e una DefaultFaultRule sia in <ProxyEndpoint> che in <TargetEndpoint>. Infine, tuttavia, viene eseguita una sola regola di errore quando un proxy API passa in stato di errore.

Questa sezione descrive la logica utilizzata da Apigee nella gestione delle regole di errore, dal modo in cui arriva a una singola regola di errore per l'esecuzione alla modalità di gestione delle condizioni di passaggio inner quando viene attivata la regola di errore. 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 passa in stato di errore. Tieni presente che esiste una leggera differenza tra la valutazione FaultRules nel ProxyEndpoint e nel TargetEndpoint.

  1. Apigee valuta le FaultRules nel ProxyEndpoint o nel TargetEndpoint, a seconda di dove si è verificato l'errore:
    • ProxyEndpoint: Apigee inizia con il <FaultRule> ProxyEndpoint nel file XML di configurazione e continua a funzionare, valutando <Condition> di ogni <FaultRule> (la condizione esterna, non le condizioni <Step> interne).
    • TargetEndpoint: Apigee inizia con il TargetEndpoint <FaultRule> nel file XML di configurazione e procede verso il basso, valutando <Condition> di ogni <FaultRule> (la condizione esterna, non le condizioni <Step> interne).
  2. Esegue la prima regola di errore la cui condizione è true. Se una regola di errore non ha una condizione, è true per impostazione predefinita.
    • Quando viene eseguita una regola di errore, tutti i passaggi all'interno di quest'ultima vengono valutati in ordine, dall'alto verso il basso nella configurazione XML. I passaggi senza condizioni vengono eseguiti automaticamente (i criteri vengono eseguiti) e quelli con <Condition> che viene valutato (le condizioni che restituiscono code non vengono eseguite).

    • Se viene eseguita una regola di errore, ma non viene eseguito alcun passaggio della regola di errore (perché le relative condizioni valutano code), il messaggio di errore predefinito generato da Apigee viene restituito all'app client. <DefaultFaultRule> non viene eseguito perché Apigee ha già eseguito la sua unica regola di errore.

  3. Se non viene eseguita alcuna FaultRule, Apigee esegue <DefaultFaultRule>, se presente.

Di seguito sono riportati alcuni esempi di commenti in linea.

Esecuzione proxyEndpoint

La valutazione di ProxyEndpoint FaultRules è dal basso verso l'alto, quindi inizia a leggere l'ultima FaultRule dell'esempio seguente e procedi fino in fondo. Guarda l'ultima regola predefinitaFault.

<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 Endpoint di destinazione

La valutazione delle regole di errore del punto di destinazione è dall'alto verso il basso, quindi inizia a leggere la prima regola di errore nell'esempio seguente e procedi verso il basso. Guarda l'ultima regola predefinitaFault.

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

Come puoi vedere nell'esempio precedente, l'ordine in cui inserisci le regole di errore è importante a seconda che l'errore si verifichi nel ProxyEndpoint o nel punto di destinazione.

Ad esempio:

Ordine ProxyEndpoint Ordine endpoint di destinazione

Nell'esempio seguente, poiché la valutazione è dal basso verso l'alto, viene eseguita la regola FaultRule 3, il che significa che le regole Fault 2 e 1 non vengono valutate.

5. Regola di errore 1: FALSE

4. Regola di errore 2: TRUE

3. Regola errore 3: TRUE

2. Regola di errore 4: FALSO

1. Regola di errore 5: FALSO

Nell'esempio seguente, poiché la valutazione è dall'alto verso il basso, viene eseguita la regola di errore 2, il che significa che le regole Fault 3, 4 e 5 non vengono valutate.

1. Regola di errore 1: FALSE

2. Regola di errore 2: TRUE

3. Regola errore 3: TRUE

4. Regola di errore 4: FALSO

5. Regola di errore 5: FALSO

Criteri da includere

Puoi eseguire qualsiasi criterio di una regola di errore inserendoli in passaggi. Ad esempio, puoi eseguire un criterioAssignMessage 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)

L'intestazione potrebbe sembrare ricorrente, ma c'è una particolare sfumatura da tenere presente in merito a un errore del proxy che causa l'attivazione di uno stato di errore del proxy API o, al contrario, il non inserimento di 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 verrà 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 nell'elemento principale chiamato continueOnError. Questo attributo è molto importante per la gestione degli errori, in quanto determina se il proxy entra in uno stato di errore in caso di errore del criterio. Nella maggior parte dei casi è consigliabile mantenere il valore continueOnError="false" predefinito, che attiva lo stato di errore del proxy se il criterio non funziona 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 ne interrompa l'esecuzione), il proxy non assumerà lo stato di errore se il criterio non funziona e il proxy non esaminerà le regole di errore.

Per informazioni sugli errori di logging quando continueOnError="true", consulta Gestione degli errori dei criteri nel flusso attuale.

Dove definire FaultRules: ProxyEndpoint o TargetEndpoint

Quando si verifica un errore di un proxy API, l'errore si verifica in <ProxyEndpoint> (richiesta da o risposta all'app client) o in <TargetEndpoint> (richiesta a o risposta dal servizio di destinazione). Ogni volta che si verifica l'errore, Apigee cerca FaultRules.

Ad esempio, se non è disponibile un server di destinazione (codice di stato HTTP 503), il proxy API entrerà in stato di errore nella risposta <TargetEndpoint> e il normale flusso del proxy API non sarebbe continuato con <ProxyEndpoint>. Se hai definito FaultRules solo in <ProxyEndpoint>, queste non gestiranno questo errore.

Ecco un altro esempio. Se un criterio RaiseFault nella risposta <ProxyEndpoint> attiva un errore, una FaultRule in <TargetEndpoint> non viene eseguita.

FaultRules e il criterio RaiseFault

In apparenza le regole di errore e il criterio RaiseFault potrebbero sembrare modi alternativi per eseguire la gestione degli errori; e in qualche modo è vero. ma interagiscono anche tra di loro. Questa sezione spiega la relazione tra i due. Comprendere questa relazione dovrebbe aiutarti a progettare la gestione dei guasti, soprattutto se vuoi utilizzare entrambi.

In breve:

  • Le regole di errore vengono sempre valutate quando un proxy API entra in uno stato di errore.

  • Il criterio RaiseFault consente di impostare un proxy API in uno stato di errore quando un errore non si sarebbe altrimenti verificato.

    Ad esempio, se vuoi generare un errore se il codice di stato HTTP nella risposta dal servizio di destinazione è maggiore di 200, aggiungi un criterio RaiseFault nel flusso di risposta. L'URL avrà il seguente aspetto:

    <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 un criterio RaiseFault attiva un errore, che mette il proxy in uno stato di errore ed esegue potenzialmente una regola di errore? È qui che le cose possono essere un po' complesse. Se il criterio RaiseFault restituisce un messaggio di errore e viene attivata una regola Fault e restituisce un messaggio di errore, cosa viene restituito all'app client?

  • Poiché la regola FaultRule o DefaultFaultRule viene eseguita dopo il criterio RaiseFault, i dati di risposta FaultRule prevalgono.
  • I dati di risposta del criterio RaiseFault (codice di stato, frase del motivo o payload del messaggio) vengono utilizzati se tali dati non sono impostati dalla regola FaultRule o nella regola predefinitaFault.
  • Se sia il criterio RaiseFault che FaultRule aggiungono intestazioni HTTP personalizzate, entrambi vengono inclusi nella risposta. I nomi delle intestazioni duplicati creano un'intestazione con più valori.

Di seguito è riportato un esempio di ciò che è impostato da un criterio RaiseFault e una FaultRule, e cosa viene restituito all'app client. Gli esempi sono progettati per brevità, non per best practice.

Valore impostato da un criterio RaiseFault e una FaultRule.

L'app cliente riceve:

Status Code: 468
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header:
  errorNote: woops,gremlins

<- Il criterio delle regole di errore imposta questo valore:

Status Code: [none] 
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header:
  errorNote: gremlins

<- Il criterio RaiseFault imposta questo:

Status Code: 468
Reason Phrase: Can't do that
Payload: {"DOH!":"Try again."}
Header: 
  errorNote: woops

Condizioni dell'edificio

Le condizioni sono la chiave per l'esecuzione di FaultRule. Puoi creare condizioni FaultRule come per altre condizioni in Apigee, ad esempio per i flussi condizionali o le condizioni RaiseFault.

Per contestualizzare il resto di questa sezione, ecco un esempio di regola di errore 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 degli 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 funziona, 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, di seguito, il nome dell'errore è FailedToResolveAPIKey. In questo caso, una variabile di flusso denominata fault.name è impostata sul valore FailedToResolveAPIKey.

{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

La condizione sarebbe quindi la seguente:

<Condition>fault.name = "FailedToResolveAPIKey"</Condition>

Per un elenco degli errori dei criteri, consulta la Guida di riferimento agli errori dei criteri.

{policy_namespace}.{policy_name}.failed

La variabile *.failed è disponibile quando un criterio non funziona. Di seguito sono riportati alcuni esempi di variabili *.failed per diversi criteri. Per gli spazi dei nomi dei criteri, consulta le variabili di flusso in ciascun argomento Riferimento ai criteri.

Altre variabili disponibili

Quando un proxy API passa in stato di errore, le uniche variabili disponibili da utilizzare nelle condizioni sono:

  • Le variabili del criterio per cui l'operazione non è riuscita.
  • Le variabili del messaggio HTTP esistenti al momento dell'errore. Ad esempio, se viene generato un errore nella risposta, una regola di errore in <TargetEndpoint> potrebbe utilizzare i dati HTTP response.status.code, message.content, error.content e così via. In alternativa, se un criterio per le quote non ha funzionato, puoi utilizzare la variabile ratelimit.{quota_policy_name}.exceed.count. Utilizza lo strumento di debug e la documentazione di riferimento alle norme per individuare le variabili e i dati HTTP disponibili.

Ulteriori informazioni

Best practice per la gestione dei guasti

La gestione dei guasti è una delle principali attività di progettazione dell'architettura per lo sviluppo di proxy API. È importante dedicare del tempo a capire come e quando gestire gli errori, determinare il tipo di messaggi visualizzati e progettare i relativi formati. Dopo (o come) hai capito come fare, utilizza queste best practice per aiutarti nell'implementazione della gestione dei guasti.

Di seguito sono riportate alcune best practice per la progettazione e la gestione dei guasti:

  • In FaultRules, puoi specificare qualsiasi tipo di criterio. Il metodo più comune consiste nell'utilizzare il criterioAssignMessage per impostare elementi specifici nella risposta di errore in attesa. Puoi anche utilizzareAssignMessage per impostare variabili utilizzate per altri scopi, ad esempio per le variabili a cui viene fatto riferimento dai criteri di logging eseguiti in PostClientFlow o in FlowHooks. Valuta anche la possibilità di registrare un messaggio, ad esempio con il criterio MessageLogging o il criterio ServiceCallout, se vuoi registrare errori specifici in condizioni di errore specifiche.
  • Non specificare i criteri RaiseFault come passi all'interno di una regola Fault. È preferibile utilizzare i criteriAssignMessage per impostare o modificare gli elementi dei messaggi, inclusi payload, intestazioni o codice di stato.
  • Per ogni FaultRule o per tutte le regole FaultRule tranne l'ultima valutata, fornisci un <Condition> esterno associato come figlio dell'elemento <FaultRule>. La condizione di esecuzione per una regola di errore senza Condizione esplicita specificata, verrà valutata implicitamente come true. Un elemento <Condition> associato come elemento secondario di un elemento <Step> non viene utilizzato per determinare se la condizione di esecuzione per FaultRule sia pari a true o false. Le condizioni dei passaggi vengono valutate solo dopo che Apigee ha eseguito la regola di errore che le contiene. In una regola Fault, è comune avere più passaggi con criteriAssignMessage (o altri), ciascuno con una condizione Step.

  • Per gestire gli errori in più criteri dello stesso tipo (ad esempio più criteri per le quote), crea una regola di errore per ogni errore del criterio che potresti ricevere, quindi distingui tra errori separati con condizioni associate ai passaggi. Ad esempio, crea una regola Fault per gestire un errore nei criteri per le quote, come QuotaViolation, e una regola FaultRule separata per InvalidApiKey. Consulta la documentazione di riferimento sugli errori dei criteri per gli errori relativi ai criteri. Man mano che scopri altri errori che devono essere gestiti, puoi tornare in un secondo momento e aggiungerli alle tue regole di errore. Va bene essere iterativi, anche se richiede il rideployment del proxy.) Questo approccio ti consente di rilevare lo stesso tipo di errore indipendentemente dal criterio che lo genera, rendendo efficiente il tuo XML FaultRules.

    Le condizioni interne dei passaggi ti consentono di avere un controllo più granulare. Ad esempio, se applichi sia la quota per singoli sviluppatori sia la quota globale con due criteri nel flusso di richieste, imposta la condizione FaultRule outer in modo che venga attivata in caso di errore QuotaViolation (che viene generato quando la quota supera in entrambi i casi). Imposta quindi le condizioni dei passaggi per valutare le variabili exceed.count specifiche in entrambi i criteri per le quote. Al client viene inviato solo l'errore pertinente (superamento della quota degli sviluppatori 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 relativi ai criteri.

  • Per gestire gli errori quando utilizzi un singolo criterio di un solo tipo, considera l'esecuzione di un'unica regola di errore che viene eseguita quando un criterio ha esito negativo e includi più passaggi mappati a ogni possibile errore. In questo modo il tuo XML è più semplice utilizzando una singola FaultRule anziché più FaultRules (una per ogni tipo di errore). Ad esempio, puoi specificare che i diversi passaggi del criterioAssignMessage vengano eseguiti in condizioni diverse, ad esempio in questo modo:

    <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 dove si verificano gli errori (lato client <ProxyEndpoint> o lato destinazione <TargetEndpoint>). Includi FaultRules per ogni criterio visualizzato in ciascuna località.
  • Quando utilizzi i criteri RaiseFault insieme a FaultRules, coordina i dati di risposta inviati quando sia il criterio RaiseFault che una FaultRule restituiscono dati. Ad esempio, se disponi di un criterio RaiseFault che imposta il codice di stato HTTP, non configurare anche un passaggioAssignMessage all'interno di una regola FaultRule che reimposta il codice di stato. Il peggio che può accadere è che il codice di stato predefinito venga restituito all'app client.

  • L'elemento <DefaultFaultRule> completa l'elemento <FaultRules> per darti maggiore controllo sui criteri eseguiti dal proxy quando gestisce uno stato di errore. Se specifichi un valore <DefaultFaultRule>, l'operazione verrà eseguita se una o entrambe le seguenti condizioni sono vere:

    • Non è stata eseguita nessun'altra regola FaultRule. Un caso speciale è quando non è configurato alcun elemento <FaultRules>.
    • Se l'elemento secondario <AlwaysEnforce> di <DefaultFaultRule> è true.

    Puoi anche specificare un elemento <Condition> su un <DefaultFaultRule>. Potresti volerne escludere l'esecuzione in base a uno stato della richiesta o al messaggio di errore in attesa, ad esempio se un'intestazione specifica è presente o mancante.

    Utilizza un valore <DefaultFaultRule> con <AlwaysEnforce> impostato su true se hai uno o più criteri che devono essere eseguiti sempre dal proxy, indipendentemente dall'esecuzione o meno di una regola di errore precedente. Uno scenario possibile: supponi di voler inserire un'intestazione nella risposta in tutti i casi, indipendentemente dal fatto che la richiesta proxy abbia generato o meno un errore e se l'errore sia stato gestito o meno in precedenza. Quindi, collega un criterio AssegnaMessage appropriato nella sezione <PostFlow>/<Response> e lo stesso criterio in <DefaultFaultRule> con <AlwaysEnforce> impostato su true.

Pattern per la gestione centralizzata e riutilizzabile dei guasti

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 regole di errore

Per aggiungere una FaultRule, devi modificare la configurazione XML di ProxyEndpoint o TargetEndpoint. Puoi utilizzare l'UI di Apigee per apportare questa modifica nel riquadro Codice della vista Sviluppo per un proxy API, oppure modificare il file XML che definisce il ProxyEndpoint o TargetEndpoint.

Se crei FaultRules nell'UI di Apigee, crea prima i criteri che vuoi eseguire, quindi aggiungile alla configurazione FaultRule. Se tenti di salvare una regola di errore che fa riferimento a un criterio che non è stato ancora creato, riceverai un errore nell'interfaccia utente.

Aggiunta di criteri a una regola di errore

Anche se puoi inserire qualsiasi criterio in FaultRule, in genere puoi usare il criterioAssignMessage per generare un messaggio di risposta personalizzato per una condizione di errore. AssegnaMessage ti consente di configurare una risposta HTTP con elementi payload, codice di stato HTTP, intestazioni e frase di motivo.

L'esempio seguente mostra una configurazione tipica del criterioAssignMessage:

<AssignMessage name="AM-Invalid-Key">
  <Set>
      <Payload contentType="text/plain">That is an error.</Payload>
      <StatusCode>401</StatusCode>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Nota che non è specificato alcun elemento <AssignTo>. Ciò significa che verrà assegnato al messaggio Ambient, a seconda di dove è collegato il criterio.

Ora puoi usare questo criterio nella regola Fault. Nota come fai riferimento al criterioAssignMessage 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 riportata sopra, il proxy API esegue il criterioAssignMessage chiamato AM-Invalid-Key ogni volta che un'app presenta una chiave API non valida.

Puoi eseguire più criteri in una regola di errore, come illustrato 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 il criterio MessageLogging, il criterio TakeoutVariables, il criterioAssignMessage o qualsiasi altro criterio nella regola Fault. Tieni presente che l'elaborazione della regola di errore si interrompe immediatamente se si verifica una delle seguenti situazioni:

  • Qualsiasi criterio in FaultRule causa un errore
  • Tutti i criteri in FaultRule sono di tipo RaiseFault

La definizione del messaggio di errore personalizzato restituito da una regola di errore

Come best practice, devi definire risposte di errore chiare dalle tue API. In questo modo, potrai fornire ai tuoi clienti informazioni coerenti e utili.

Il seguente esempio di criterioAssignMessage utilizza i tag <Payload> e <StatusCode> per definire la risposta di errore personalizzata inviata al client in caso di errore InvalidApiKey (consulta 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>

La 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.
  • La frase del motivo, che è una breve descrizione dell'errore.

Creazione di una regolaFaultDefault

Una regola predefinitaFaultRule agisce come gestore di eccezioni per qualsiasi errore non gestito esplicitamente da un'altra regola Fault. Se le condizioni per tutte le regole Fault non corrispondono all'errore, la regola di errore predefinita gestisce l'errore. Abilita la gestione predefinita degli errori aggiungendo il tag <DefaultFaultRule> come elemento secondario di un ProxyEndpoint o un TargetEndpoint.

Ad esempio, la configurazione TargetEndpoint seguente definisce una regola predefinitaFault che richiama un criterio denominato 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 predefinitaFaultRule 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 per l'assistenza tecnica. Questa risposta predefinita ha il duplice scopo di fornire informazioni a misura di sviluppatore, offuscando al contempo gli URL di backend o altre informazioni che potrebbero essere utilizzate per compromettere il sistema.

Ad esempio, definisci il seguente criterio AssegnaMessage 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 la regola predefinitaFaultRule per ogni errore, anche se è già stata eseguita un'altra regola FaultRule. La regola predefinitoFault è sempre l'ultima regola Fault da eseguire:

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>AM-Return-Generic-Error</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

La regola predefinitaFault consente di determinare il tipo di errore che si verifica quando non è possibile determinarlo. Ad esempio, se il proxy API non funziona a causa di un errore che non riesci a determinare, puoi utilizzare la regola predefinitaFault per richiamare il criterio AssegnaMessage seguente. 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 cosa ha causato l'errore.

Aggiunta del logging dei messaggi a PostClientFlow

PostClientFlow è l'unico flusso che viene eseguito dopo che il proxy entra nello stato di errore. È possibile collegare solo il criterio MessageLogging a questo flusso, che viene eseguito dopo che la risposta viene inviata al client. Sebbene il collegamento del criterio MessageLogging a questo flusso tecnicamente non sia la gestione degli errori, puoi utilizzarlo per registrare le 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 certezza che vengano sempre eseguiti.

Gestione degli errori dei criteri nel flusso attuale

Tutti gli esempi mostrati finora utilizzano una regola di errore 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. Nello stato di errore, non puoi restituire il controllo alla pipeline normale e in genere restituisci 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 attuale e il criterio successivo nella pipeline viene eseguito dopo il criterio che ha causato l'errore. Il vantaggio di gestire l'errore nel flusso attuale è che potresti avere un modo per recuperare l'errore e completare l'elaborazione della richiesta.

Di seguito è mostrato un criterioVerifyAPIKey denominato 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 non è presente o non è valida, il criterio VerifyAPIKey imposta la variabile oauthV2.verify-api-key.failed su true, ma l'elaborazione continua nel flusso attuale.

Quindi aggiungi il criterio VerifyAPIKey come passaggio nel PreFlow del 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 utilizza 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. Il criterio FaultInFlow può fare molte cose, ad esempio registrare l'errore, tentare di correggerlo o eseguire altre azioni.

Attivazione di un errore tramite il criterio RaiseFault

Puoi utilizzare il criterio RaiseFault in qualsiasi momento in un flusso per attivare un errore. Quando viene eseguito un criterio RaiseFault, termina il flusso attuale e trasferisce il controllo allo stato di errore.

Il criterio RaiseFault può essere utilizzato per testare una condizione specifica che un altro criterio potrebbe non rilevare. Nell'esempio precedente, hai aggiunto un tag <Condition> a un tag <Step> PreFlow che ha causato l'esecuzione del criterio FaultInFlow se la condizione è soddisfatta. Se FaultInFlow è un criterio RaiseFault, controlla i trasferimenti allo stato di errore. In alternativa, potresti inserire un criterio RaiseFault in un flusso per eseguire il debug e testare le regole Fault.

Quando un criterio RaiseFault attiva un errore, puoi utilizzare la seguente regola di errore e condizione per elaborarla:

<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 un criterio RaiseFault. In questo caso, puoi testare le variabili negli elementi Condition.

Gestione personalizzata dei codici di errore HTTP dal server di destinazione

Gli esempi mostrati nelle sezioni precedenti si applicano agli errori creati dai criteri. Tuttavia, puoi anche creare una risposta personalizzata per gli errori a livello di trasporto, ovvero errori HTTP restituiti dal server di destinazione. Per controllare la risposta da 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 riuscito e i codici di risposta HTTP nell'intervallo 4xx-5xx come errore. Ciò significa che qualsiasi risposta dal servizio di backend con un codice di risposta HTTP 4xx-5xx richiama automaticamente lo stato di errore, che 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.

Nel prossimo esempio, utilizzi la proprietà success.codes per configurare il TargetEndpoint in modo da trattare i codici di risposta HTTP 400 e 500 come operazione riuscita, insieme ai codici HTTP predefiniti. Trattando questi codici come operazioni riuscite, il TargetEndpoint prende in carico l'elaborazione del messaggio di risposta, invece di 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 vedi 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 operazione predefiniti, imposta questa proprietà come:

<Property name="success.codes">1xx,2xx,3xx,400</Property>

Tuttavia, se vuoi che il codice HTTP 400 venga trattato solo come codice di operazione riuscita, imposta la proprietà come:

<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 di TargetEndpoint fa sì che il criterio chiamato ReturnError gestisca la risposta ogni volta che TargetEndpoint rileva un codice di risposta HTTP 400 OR 500.

Tassonomia degli errori

I servizi API organizzano gli errori nelle seguenti categorie e sottocategorie.

Categoria Sottocategoria Nome errore Descrizione
Messaggistica Errori che si verificano durante il flusso dei messaggi (esclusi gli errori dei criteri)
Errori personalizzati {fault_name} Eventuali errori gestiti esplicitamente dal proxy API utilizzando il criterio RaiseFault
Codici di risposta Errore server interno, non trovato Codici di errore HTTP 5xx, 4xx
Errori di routing NoRoutesMatched Errore nella selezione di un TargetEndpoint denominato per una richiesta
Errori di classificazione NotFound Errori causati da un URI della richiesta che non corrisponde ad alcun BasePath per alcuna configurazione ProxyEndpoint (ovvero, nessun proxy API corrisponde all'URL nella richiesta dell'app client)
Trasporti Errori a livello di trasporto HTTP
Connettività ConnectionRefused, ConnectionReset, ConnectionTimeout Gli errori si verificano durante la creazione di connessioni a livello di rete o di trasporto
Richiedi convalide ContentLengthMancante, HostHeaderManca Gli errori si verificano durante i controlli della semantica su ogni richiesta
Convalide delle risposte Gli errori si verificano durante i controlli semantici su ogni risposta
Errori IO SSLHandshakeError, ReadTimeout, ReadError, writeTimeout, writeError, ChunkError Errori di lettura/scrittura negli endpoint client o di destinazione, timeout, errori TLS/SSL ed errori suddivisi in blocchi
Sistema Errori di runtime non definiti
Memoria OutOfMemory, GCOverLimit Errori relativi alla memoria
Thread RogueTaskTerminated Errori come la chiusura delle attività run-away
Norme Gli errori per ogni tipo di criterio sono definiti in Riferimento ai criteri.

Un errore è sempre accompagnato da una descrizione testuale del motivo dell'errore. Quando il sistema segnala un errore, viene compilato un set di attributi per facilitare la risoluzione dei problemi. Un guasto include le seguenti informazioni:

  • Motivo
  • Attributi personalizzati definiti dall'utente