Gestione degli errori

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Possono verificarsi molte condizioni di errore durante il servizio delle richieste delle app da parte dei 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 persino arricchirli con elementi come intestazioni HTTP aggiuntive, devi configurare la gestione degli errori personalizzati in Apigee.

La gestione degli errori personalizzata 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 degli errori personalizzata nei proxy API, è utile comprendere come si verificano gli errori e come reagiscono i proxy API.

Video

Guarda i seguenti video per scoprire di più sulla gestione degli errori.

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.
Gestire gli errori utilizzando le regole di errore Scopri come gestire gli errori utilizzando le regole di errore.
Generare errori personalizzati utilizzando il criterio RaiseFault Genera errori personalizzati durante il runtime dell'API utilizzando il criterio RaiseFault.
Definire le regole di errore nei proxy API e negli endpoint di destinazione Definisci le regole di errore nel proxy API e negli endpoint di destinazione e comprendi le differenze.
Informazioni sull'ordine di esecuzione delle regole di errore Comprendi l'ordine di esecuzione delle regole di errore negli endpoint del proxy API e del target.
Definire la regola di errore predefinita Definisci la regola di errore predefinita per gestire gli errori generici nell'API.

Come si verificano gli errori

Per prima cosa, spiegheremo semplicemente come si verificano gli errori. Sapere come si verificano gli errori ti aiuta a pianificare le diverse situazioni in cui vuoi implementare la gestione degli errori personalizzata.

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 VerifyAPIKey genera automaticamente un errore oppure, se il numero di chiamate API supera un determinato limite, il criterio Quota o il criterio SpikeArrest genera un errore. Consulta il riferimento agli errori dei criteri per i tipi di errori che i criteri possono generare.
  • 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 a causa di 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 memoria insufficiente.

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

Errori personalizzati

Per le situazioni in cui non è presente un errore automatico, ti consigliamo di generare un errore personalizzato, ad esempio se una risposta contiene la parola unavailable o se il codice di stato HTTP è maggiore di 201. Aggiungi un criterio RaiseFault al posto appropriato in un flusso del proxy API.

Puoi aggiungere un criterio RaiseFault a un flusso di proxy API come faresti con qualsiasi altro criterio. Nel seguente esempio di configurazione del proxy, il criterio Raise-Fault-1 è associato alla risposta TargetEndpoint. Se la parola unavailable è presente 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>

Questo è solo per mostrarti che puoi generare errori personalizzati. Nella sezione FaultRules e il criterio RaiseFault approfondiremo il criterio RaiseFault.

Per altri esempi, consulta questi post della community di Apigee:

Azione dei proxy API in caso di 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ò restituire l'elaborazione alla pipeline di flusso normale.

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

  1. Verifica la chiave API
  2. Quota
  3. JSON to XML

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

Controlla la presenza di FaultRules

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

  1. Una sezione <FaultRules>, che contiene la logica per attivare messaggi di errore personalizzati (e altri criteri) in base a condizioni specifiche che hai definito.
  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 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 di gestione degli errori semplice

Iniziamo con un esempio semplice, in cui una chiamata a un proxy API non contiene una chiave API obbligatoria. 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, sta 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 dei messaggi di errore propri.

Ecco un esempio di base di come creare un messaggio di errore personalizzato per gestire questo errore. Per farlo, sono necessari 1) un criterio che definisce il messaggio personalizzato e 2) un criterio FaultRule che esegue il criterio quando il proxy entra in uno 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 norma, come una norma AssignMessage, che può impostare un payload e intestazioni HTTP facoltative come il codice di stato e la frase del motivo. Il criterio Assegna messaggio è ideale per questo. Ti consente di controllare il payload del messaggio, 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; basta crearlo, come descritto in Creare il criterio.

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.
  • Imposta una frase di motivo HTTP (per sostituire la frase di motivo Unauthorized predefinita per questo errore di 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 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 norma? La sezione successiva ti mostra come.

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

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

Devi anche aggiungere un <DefaultFaultRule> per fornire un messaggio di errore generale personalizzato se nessuno dei tuoi FaultRule viene eseguito.

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 regole di errore sono definite in ProxyEndpoint. Questo è importante. Maggiori informazioni su come inserire FaultRules in ProxyEndpoint rispetto a TargetEndpoint più avanti.
  • <Name>: il nome del criterio da eseguire. Il nome proviene dall'attributo name del criterio nell'elemento principale, come mostrato nell'esempio di criterio precedente.

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

  • <DefaultFaultRule>: se non viene eseguita alcuna regola FaultRule personalizzata, viene eseguita <DefaultFaultRule>, inviando un messaggio personalizzato più generico anziché il messaggio criptico predefinito generato da Apigee. Un <DefaultFaultRule> può avere anche un <Condition>, ma nella maggior parte dei casi non ne viene incluso uno, perché vuoi che venga eseguito in ogni caso 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 per l'assistenza tecnica. Questa risposta predefinita ha il duplice scopo di fornire informazioni utili per gli sviluppatori e allo stesso tempo di offuscare gli URL di backend o altre informazioni che potrebbero essere utilizzate per compromettere il sistema.

Più regole di errore e logica di esecuzione

Nella sezione Esempio di gestione degli errori semplici, abbiamo utilizzato un semplice esempio di una singola regola di errore e condizione. In un progetto API reale, con tutti i possibili errori che possono verificarsi, è probabile che tu abbia più FaultRule e un DefaultFaultRule sia in <ProxyEndpoint> che in <TargetEndpoint>. Tuttavia, alla fine viene eseguito solo un FaultRule quando un proxy API entra in uno stato di errore.

Questa sezione descrive la logica utilizzata da Apigee per gestire le regole di errore, da come arriva a un singolo FaultRule da eseguire a come vengono gestite le condizioni del passaggio interne quando viene attivato il relativo 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 esiste una leggera differenza tra la valutazione di FaultRules in ProxyEndpoint e in TargetEndpoint.

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

    • Se viene eseguita una regola di errore, ma non vengono eseguiti i passaggi al suo interno (perché le condizioni vengono valutate come 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 eseguito nessun FaultRule, Apigee esegue <DefaultFaultRule>, se presente.

Di seguito sono riportati alcuni esempi con commenti in linea.

Esecuzione di ProxyEndpoint

La valutazione dei FaultRule di ProxyEndpoint avviene dal basso verso l'alto, quindi inizia a leggere dall'ultimo FaultRule nel seguente esempio e procedi verso l'alto. Esamina per ultimo 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 regole di errore TargetEndpoint avviene dall'alto verso il basso, quindi inizia a leggere dalla prima regola di errore nell'esempio seguente e procedi verso il basso. Esamina per ultimo 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 errore

Come puoi vedere nell'esempio precedente, l'ordine in cui inserisci i FaultRule è importante a seconda che l'errore si verifichi in ProxyEndpoint o in TargetEndpoint.

Ad esempio:

Ordine di ProxyEndpoint Ordine di TargetEndpoint

Nell'esempio seguente, poiché la valutazione avviene dal basso verso l'alto, viene eseguita la regola di errore 3, il che significa che le regole di errore 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 la regola di errore 2, il che significa che le regole di errore 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 criterio da una regola di errore inserendoli in Passaggi. Ad esempio, puoi eseguire un criterio Assegna messaggio per formattare una risposta all'app client, quindi registrare un messaggio con il criterio di registrazione dei messaggi. 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 una ripetizione, ma c'è una sfumatura particolare da tenere presente in merito a un errore del proxy che causa l'ingresso di un proxy API in uno stato di errore, o meglio, non in uno stato di errore: l'attributo continueOnError in un criterio.

Per riepilogare: un proxy API valuta <FaultRules> e <DefaultFaultRule> solo se il proxy ha attivato 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, di seguito è riportato 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 denominato continueOnError. Questo attributo è molto importante per la gestione degli errori, perché determina se il proxy entra o meno in uno stato di errore se il criterio non va a buon fine. 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 va a buon fine e viene attivata la gestione degli errori personalizzata. Tuttavia, se continueOnError="true" (ad esempio, se non vuoi che l'errore di un callout del servizio interrompa l'esecuzione del proxy), il proxy non entrerà in uno stato di errore se il criterio non va a buon fine e non esaminerà le regole di errore.

Per informazioni su come registrare gli errori quando continueOnError="true", consulta Gestire gli errori delle norme all'interno del flusso corrente.

Dove definire FaultRules: ProxyEndpoint o TargetEndpoint

Quando si verifica un errore in un proxy API, l'errore si verifica in <ProxyEndpoint> (richiesta dall'app client o risposta all'app client) o in <TargetEndpoint> (richiesta al servizio target o risposta dal servizio target). Apigee cerca FaultRules ovunque si verifichi l'errore.

Ad esempio, se un server di destinazione non è disponibile (codice di stato HTTP 503), il proxy API entrerebbe in uno stato di errore nella risposta <TargetEndpoint> e il normale flusso del proxy API non continuerebbe a <ProxyEndpoint>. Se hai definito FaultRules solo nel file <ProxyEndpoint>, questi non gestiranno l'errore.

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

FaultRules e il criterio RaiseFault

A prima vista, le regole di errore e il criterio RaiseFault potrebbero sembrare modi alternativi per gestire gli errori e in qualche modo è vero. Ma funzionano anche insieme. Questa sezione spiega il rapporto tra i 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.

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

  • Poiché FaultRule o DefaultFaultRule viene eseguito dopo il criterio RaiseFault, i dati di risposta di FaultRule hanno la precedenza.
  • I dati di risposta del criterio RaiseFault (codice di stato, frase del motivo o payload del messaggio) vengono utilizzati se non sono impostati da FaultRule o DefaultFaultRule.
  • Se sia il criterio RaiseFault sia la regola FaultRule aggiungono intestazioni HTTP personalizzate, entrambe sono incluse nella risposta. I nomi delle intestazioni duplicate creano un'intestazione con più valori.

Ecco un esempio di ciò che viene impostato da un criterio RaiseFault e da una regola di errore e di ciò che viene restituito all'app client. I sample sono progettati per essere brevi, non per le best practice.

Che cosa viene impostato da un criterio RaiseFault e da una regola di errore.

L'app client riceve:

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

<- Il criterio delle regole di errore imposta:

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 fondamentali per l'esecuzione di FaultRule. Le condizioni FaultRule vengono create nello stesso modo delle altre condizioni in Apigee, ad esempio per i flussi condizionali o le condizioni RaiseFault.

Per contestualizzare il resto di questa sezione, di seguito è riportata 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 va a buon fine, rileva 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"}}}

La condizione sarà quindi la seguente:

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

Per un elenco degli errori relativi ai criteri, consulta la documentazione di riferimento relativa agli errori dei criteri.

{policy_namespace}.{policy_name}.failed

La variabile *.failed è disponibile quando un criterio non va a buon fine. 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 ogni argomento del riferimento ai criteri.

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 che non sono riuscite.
  • Le variabili dei messaggi HTTP esistenti nel punto di 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 di quota non è andato a buon fine, puoi utilizzare la variabile ratelimit.{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

Best practice per la gestione degli errori

La gestione degli errori è un'importante attività di progettazione dell'architettura per lo sviluppo di proxy API. È importante prendersi il tempo di capire come e quando gestire gli errori, stabilire il contenuto dei messaggi di errore e progettarne i formati. Dopo (o mentre) aver risolto questi problemi, utilizza queste best practice per aiutarti con l'implementazione della gestione degli errori.

Di seguito sono riportate 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 utilizzare AssignMessage anche per impostare le variabili utilizzate per altri scopi, ad esempio per le variabili a cui fanno riferimento i criteri di logging che vengono eseguiti in PostClientFlow o in FlowHooks. Valuta anche la possibilità di registrare un messaggio, ad esempio con il criterio di logging dei messaggi o il criterio di callout del servizio, se vuoi registrare errori specifici in condizioni di errore specifiche.
  • Non specificare i criteri RaiseFault come passaggi all'interno di una regola di errore. È preferibile utilizzare i criteri AssignMessage per impostare o modificare gli elementi del messaggio, inclusi il payload, le intestazioni o il codice di stato.
  • Per ogni FaultRule o per tutti tranne l'ultimo valutato, specifica un <Condition> esterno collegato come elemento secondario dell'elemento <FaultRule>. La condizione di esecuzione per una regola di errore senza condizione esplicita specificata verrà valutata implicitamente come true. Un elemento <Condition> collegato come elemento secondario di un elemento <Step> non viene utilizzato per determinare se la condizione di esecuzione per la regola di errore restituisce true o false. Le condizioni del passaggio vengono valutate solo dopo che Apigee esegue la regola di errore che le contiene. In una regola di errore, è comune avere più passaggi con criteri AssignMessage (o altri), ciascuno con una condizione di passaggio.

  • Per gestire gli errori in più criteri dello stesso tipo (ad esempio, più criteri di quota), crea una regola di errore per ogni errore del criterio che potresti ricevere e poi distingui gli errori separati con le condizioni associate ai passaggi. Ad esempio, crea una regola FaultRule per gestire un errore nei criteri di quota, come QuotaViolation, e una regola FaultRule separata per InvalidApiKey. Per gli errori relativi alle norme, consulta il riferimento agli errori delle norme. Man mano che scopri altri errori che devono essere gestiti, puoi tornare indietro in un secondo momento e aggiungerli a FaultRules. È consentito un approccio iterativo, anche se richiede il ricollocamento 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 tuo flusso di richieste, imposta la condizione FaultRule esterna in modo che venga attivata per l'errore QuotaViolation (che viene generato quando la quota viene superata in entrambi i casi). Poi imposta le condizioni del passaggio per valutare le variabili exceed.count specifiche in entrambi i criteri di quota. 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 relativi ai criteri.

  • Per gestire gli errori quando utilizzi un singolo criterio di un tipo, valuta una singola regola di errore che viene eseguita quando il criterio non va a buon fine e includi più passaggi che mappano a ogni possibile errore. In questo modo, il codice XML rimane più semplice utilizzando un singolo FaultRule anziché più FaultRule (uno per ogni tipo di errore). Ad esempio, puoi specificare che diversi passaggi del regolamento AssignMessage vengano eseguiti in condizioni diverse, ad esempio:

    <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 verificheranno gli errori (lato client <ProxyEndpoint> o lato target <TargetEndpoint>). Includi FaultRules per ogni criterio visualizzato in ogni posizione.
  • Quando utilizzi i criteri RaiseFault in combinazione con FaultRules, coordina i dati di risposta che vengono inviati quando sia il criterio RaiseFault sia un criterio 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 un criterio 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> integra l'elemento <FaultRules> per offrirti un maggiore controllo sulle norme eseguite dal proxy quando gestisce uno stato di errore. Se specifichi un <DefaultFaultRule>, questo verrà eseguito se una o entrambe le seguenti condizioni sono vere:

    • Nessun'altra regola di errore è stata eseguita. Un caso speciale è rappresentato dalla situazione in cui non è configurato alcun elemento <FaultRules>.
    • Se l'elemento secondario <AlwaysEnforce> di <DefaultFaultRule> è true.

    Puoi anche specificare un elemento <Condition> in un <DefaultFaultRule>. Questa operazione può essere utile per escluderne l'esecuzione in base a uno stato della richiesta o a un messaggio di errore in attesa, ad esempio se è presente o mancante un'intestazione specifica.

    Utilizza un <DefaultFaultRule> con <AlwaysEnforce> impostato su true se hai uno o più criteri che vuoi che il proxy esegua sempre, indipendentemente dall'esecuzione di una regola FaultRule precedente. Un possibile scenario: supponiamo che tu voglia iniettare un'intestazione nella risposta in tutti i casi, indipendentemente dal fatto che la richiesta del proxy abbia generato o meno un errore e che l'errore sia stato gestito in precedenza o meno. Poi, allega un criterio AssignMessage appropriato nella sezione <PostFlow>/<Response> e anche lo stesso criterio in <DefaultFaultRule> con <AlwaysEnforce> impostato su true.

Pattern per la gestione degli errori centralizzata e riutilizzabile

Un modello di gestione degli errori per i proxy Apigee descrive un modello per la gestione centralizzata degli errori senza duplicazione del codice.

Creazione di FaultRules

Per aggiungere una regola di errore, devi modificare la configurazione XML di ProxyEndpoint o TargetEndpoint. Puoi utilizzare l'interfaccia utente 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 FaultRule nell'interfaccia utente di Apigee, crea prima i criteri che vuoi eseguire, poi aggiungili alla configurazione di FaultRule. Se provi a salvare un FaultRule che fa riferimento a un criterio non ancora creato, verrà visualizzato un errore nell'interfaccia utente.

Aggiunta di criteri a FaultRule

Sebbene sia possibile inserire qualsiasi criterio in FaultRule, in genere si utilizza il criterio AssignMessage per generare un messaggio di risposta personalizzato per una condizione di errore. AssignMessage ti consente di configurare una risposta HTTP con elementi di payload, codice di stato HTTP, intestazioni e frase del motivo.

L'esempio seguente mostra una configurazione tipica del regolamento Assegna messaggio:

<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 è specificato 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 al criterio 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 eseguirà il criterio AssignMessage 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 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 il criterio di registrazione dei messaggi, il criterio di estrazione delle variabili, il criterio di assegnazione del messaggio o qualsiasi altro criterio in FaultRule. Tieni presente che l'elaborazione della regola di errore si interrompe immediatamente se si verifica una di queste situazioni:

  • Qualsiasi criterio in FaultRule causa un errore
  • Uno dei criteri in FaultRule è di tipo RaiseFault

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, offri ai tuoi clienti informazioni coerenti e utili.

Il seguente esempio di criterio AssignMessage utilizza i tag <Payload> e <StatusCode> per definire la risposta personalizzata all'errore 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.
  • La frase del motivo, che è una breve descrizione dell'errore.

Creazione di una regola DefaultFaultRule

Una regola DefaultFaultRule funge da gestore delle eccezioni per qualsiasi errore non gestito esplicitamente da un'altra regola FaultRule. Se le condizioni per tutte le regole FaultRules non corrispondono all'errore, la regola DefaultFaultRule gestisce l'errore. Attiva la gestione degli errori predefiniti aggiungendo il tag <DefaultFaultRule> come elemento secondario di un ProxyEndpoint o di un TargetEndpoint.

Ad esempio, la configurazione di TargetEndpoint riportata di seguito definisce una regola di errore predefinita 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 contenente i dati di contatto per l'assistenza tecnica. Questa risposta predefinita ha il duplice scopo di fornire informazioni utili per gli sviluppatori e allo stesso tempo 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 la regola DefaultFaultRule per ogni errore, anche se è già stata eseguita un'altra regola FaultRule. DefaultFaultRule è sempre l'ultima regola FaultRule eseguita:

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

Un utilizzo di DefaultFaultRule è determinare il tipo di errore che si verifica quando non puoi determinarlo. Ad esempio, se il proxy API non funziona a causa di un errore che non riesci a determinare, puoi utilizzare la regola DefaultFaultRule per richiamare la seguente norma 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 cosa ha causato l'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 associato solo il criterio di registrazione dei messaggi, che viene eseguito dopo che la risposta è stata inviata nuovamente al cliente. Anche se l'associazione del criterio di registrazione dei messaggi a questo flusso non è tecnicamente una gestione degli errori, puoi utilizzarlo per registrare le informazioni in caso di errore. Poiché viene eseguito indipendentemente dal fatto che il proxy sia riuscito o meno, puoi inserire i criteri di logging dei messaggi in PostClientFlow e avere la certezza che vengano sempre eseguiti.

Gestione degli errori dei criteri all'interno del flusso corrente

Gli esempi mostrati finora utilizzano tutti una regola di errore su ProxyEndpoint o TargetEndpoint per gestire eventuali errori dei criteri nell'ambito 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 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 della gestione dell'errore nel flusso corrente è che potresti avere un modo per recuperare dall'errore e completare l'elaborazione della richiesta.

Di seguito è riportato un criterio VerifyAPIKey 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 corrente.

Aggiungi quindi 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 del PreFlow utilizzi una condizione per verificare l'esistenza di un errore. Se si è verificato un errore nel criterio VerifyAPIKey, viene eseguito il criterio FaultInFlow. In caso contrario, il criterio FaultInFlow viene saltato. Il criterio FaultInFlow può fare molte cose, ad esempio registrare l'errore, tentare di correggerlo o eseguire un'altra azione.

Attivazione di un errore mediante il criterio RaiseFault

Puoi utilizzare il criterio RaiseFault in qualsiasi momento in un flusso per attivare un errore. Quando viene eseguito un criterio RaiseFault, il flusso corrente viene terminato e il controllo viene trasferito allo stato di errore.

Un utilizzo del criterio RaiseFault è verificare la presenza di 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, il controllo viene trasferito allo stato di errore. In alternativa, puoi inserire un criterio RaiseFault in un flusso per eseguire il debug e testare le regole di errore.

Quando un criterio RaiseFault attiva un errore, puoi utilizzare la seguente regola di errore 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 la presenza di 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 modo, puoi testare queste variabili all'interno degli elementi Condition.

Gestione personalizzata dei codici di errore HTTP dal server di destinazione

Gli esempi riportati 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 da un errore HTTP, configura un endpoint di destinazione per elaborare i codici di risposta HTTP.

Per impostazione predefinita, Apigee tratta i codici di risposta HTTP nell'intervallo 1xx-3xx come successo e i codici di risposta HTTP nell'intervallo 4xx-5xx come errore. Ciò significa che qualsiasi risposta del servizio di backend con un codice di risposta HTTP 4xx-5xx invoca automaticamente lo stato di errore, che poi restituisce un messaggio di errore direttamente al client richiedente.

Puoi creare gestori personalizzati per qualsiasi codice di risposta HTTP. Ad esempio, potresti non volere trattare tutti i codici di risposta HTTP nell'intervallo 4xx-5xx come "errore", ma solo 5xx, oppure potresti volere restituire messaggi di errore personalizzati per i codici di risposta HTTP 400 e 500.

Nell'esempio seguente, utilizzi la proprietà success.codes per configurare TargetEndpoint in modo da trattare i codici di risposta HTTP 400 e 500 come riusciti, insieme ai codici HTTP predefiniti. Trattando questi codici come un successo, TargetEndpoint assume il controllo dell'elaborazione del messaggio di risposta anziché invocare 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 esito 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 che effettua la richiesta. 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 in modo che il criterio denominato ReturnError gestisca la risposta ogni volta che TargetEndpoint rileva un codice di risposta HTTP 400 OPPURE 500.

Tassonomia degli errori

API Services organizza gli errori nelle seguenti categorie e sottocategorie.

Categoria Sottocategoria Nome del guasto Descrizione
Messaggistica Errori che si verificano durante il flusso di messaggi (esclusi gli errori relativi alle norme)
Errori 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 Impossibile selezionare un endpoint di destinazione denominato per una richiesta
Errori di classificazione NotFound Errori causati da un URI di richiesta che non corrisponde a nessun BasePath per nessuna configurazione di ProxyEndpoint (ovvero nessun proxy API corrisponde all'URL nella richiesta dell'app client)
Trasporti Errori a livello di trasporto HTTP
Connettività ConnectionRefused, ConnectionReset, ConnectionTimeout Si verificano errori durante l'instaurazione di connessioni a livello di rete o di trasporto
Convalide delle richieste ContentLengthMissing, HostHeaderMissing Si verificano errori durante i controlli di semantica su ogni richiesta
Convalide delle risposte Si verificano errori durante i controlli di semantica su ogni risposta
Errori I/O SSLHandshakeError, ReadTimeout, ReadError, WriteTimeout, WriteError, ChunkError Errori di lettura/scrittura negli endpoint client o target, timeout, errori TLS/SSL ed errori con suddivisione in blocchi
Sistema Errori di runtime non definiti
Memoria OutOfMemory, GCOverLimit Errori relativi alla memoria
Thread RogueTaskTerminated Errori come l'interruzione di attività inutilizzate
Norme I guasti per ogni tipo di criterio sono definiti nella sezione Riferimento ai criteri.

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

  • Motivo
  • Attributi personalizzati definiti dall'utente