Gestione degli errori

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Possono verificarsi molte condizioni di errore mentre i proxy API gestiscono le richieste dalle app. 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 personalizzata degli errori in Apigee.

La gestione personalizzata degli errori consente inoltre 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 capire come si verificano gli errori e come reagiscono i proxy API.

Video

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

Video Descrizione
Introduzione alla gestione e ai flussi di errore degli 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.
Segnala errori personalizzati utilizzando il criterio AlzaFault 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.
Informazioni sull'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 regola di errore predefinita Definisci la regola di errore predefinita per gestire gli errori generici nella tua API.

Come si verificano gli errori

Innanzitutto ci occuperemo semplicemente di come si verificano gli errori. Sapere come si verificano gli errori ti aiuta a pianificare le diverse situazioni in cui vuoi implementare una 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 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 del 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 a un servizio di destinazione non disponibile.
  • Si è verificato un errore a livello di sistema, ad esempio un'eccezione per esaurimento della memoria.

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

Errori personalizzati

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

Puoi aggiungere un criterio AlzaFault a un flusso 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 AlzaFault 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 serve solo per mostrarti che puoi generare errori personalizzati. Analizziamo più in dettaglio il criterio AlzaFault nella sezione Confronto tra le regole di errore e il criterio AlzaFault.

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

Che cosa fanno i proxy API quando si verificano errori

Ecco cosa succede quando un proxy genera un errore.

Esci dalla pipeline proxy

Quando un proxy API 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ò ripristinare l'elaborazione alla 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 a uno stato di errore. I criteri per quota e da JSON a XML non vengono eseguiti, il proxy non procede verso TargetEndpoint e viene restituito un messaggio di errore all'app client.

Verifica la presenza di regole di errore

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

  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.
    • Non viene eseguito alcun <FaultRules> esistente.
    • L'elemento <AlwaysEnforce> è impostato su true.

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

Esempio di semplice gestione degli errori

Iniziamo con un semplice esempio, in cui una chiamata a un proxy API non contiene una chiave API obbligatoria. Per impostazione predefinita, la risposta che viene 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 comprendere il messaggio di errore, ma non è possibile. Inoltre, molti errori predefiniti sono più lievi e difficili da decifrare.

In qualità di sviluppatore di API, spetta a te modificare questo messaggio per soddisfare le esigenze di chiunque riceva il messaggio di errore, che si tratti di uno sviluppatore di app per iOS o di un gruppo di test interno con requisiti specifici 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 definisca il messaggio personalizzato e 2) una FaultRule che esegua il criterio quando il proxy entra in stato di errore.

1. Crea un criterio che definisca il messaggio personalizzato

Innanzitutto, crea un criterio che definisca il messaggio di errore personalizzato. Puoi utilizzare qualsiasi tipo di criterio, ad esempio il criterioAssignMessage, per impostare un payload e intestazioni HTTP facoltative come il codice di stato e la frase di motivazione. A questo scopo, 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; è sufficiente crearlo, come descritto in Creare il criterio.

Di seguito è riportato un esempio di criterioAssignMessage che:

  • Restituisce un messaggio JSON.
  • Imposta un codice di stato HTTP (911, che è un codice di stato ovvio inesistente semplicemente per illustrare la flessibilità di cui disponi). Il codice di stato viene visualizzato nell'intestazione HTTP.
  • Consente di impostare una frase di motivazione HTTP per sostituire la frase predefinita Unauthorized per questo errore di chiave API mancante. La frase di motivazione 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 viene eseguito questo criterio, 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' sciocca, 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 ricerca.

Ma come viene eseguito questo criterio? La sezione successiva è a tua disposizione.

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

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

Inoltre, devi aggiungere un <DefaultFaultRule> per fornire un messaggio di errore generale personalizzato se non viene eseguita nessuna delle tue 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 in ProxyEndpoint. Questo è importante. Scoprirai di più sull'inserimento di FaultRules in ProxyEndpoint rispetto a TargetEndpoint in un secondo momento.
  • <Name>: il nome del criterio da eseguire. Il nome proviene dall'attributo name del criterio nell'elemento principale, come mostrato nell'esempio del criterio precedente.

  • <Condition>: Apigee valuta la condizione ed esegue il criterio solo se la condizione è true. Se sono presenti più FaultRules che restituiscono true, Apigee esegue la prima che risulta true. (Importante: l'ordine in cui vengono valutate le FaultRules, dall'alto verso il basso o dal basso verso l'alto, è diverso da TargetEndpoint e ProxyEndpoint, come descritto nella sezione Più FaultRules e logica di esecuzione). Se non includi una condizione, la FaultRule viene impostata automaticamente su true. Ma non è una best practice. Ogni FaultRule deve avere la 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 lo includerai, perché vuoi che venga eseguito indipendentemente da quale sia l'ultima risorsa.

    La regola predefinitaFaultRule viene generalmente utilizzata per restituire un messaggio di errore generico in caso di errori imprevisti. Un esempio potrebbe essere un messaggio contenente i dati di contatto per l'assistenza tecnica. Questa risposta predefinita ha il duplice scopo di fornire informazioni ottimizzate per gli sviluppatori e, al contempo, di offuscare 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 semplice degli errori, è stato utilizzato un semplice esempio di una regola FaultRule e di una condizione. In un progetto API reale, con tutti i possibili errori che possono verificarsi, è probabile che siano presenti più FaultRules e una RegolaFaultRule sia in <ProxyEndpoint> che in <TargetEndpoint>. In ultima analisi, tuttavia, viene eseguita una sola FaultRule quando un proxy API entra in stato di errore.

Questa sezione descrive la logica utilizzata da Apigee per gestire FaultRules, dal modo in cui arriva a una singola FaultRule per l'esecuzione a come vengono gestite le condizioni dei passaggi inner quando viene attivata la relativa FaultRule. Questa sezione fornisce anche indicazioni su quando definire FaultRules in <ProxyEndpoint> rispetto a <TargetEndpoint> e descrive la relazione tra FaultRules e il criterio AlzaFault.

Esecuzione di FaultRules

In breve, ecco la logica utilizzata da Apigee quando un proxy API entra in stato di errore. Tieni presente che esiste una leggera differenza tra la valutazione di FaultRules in ProxyEndpoint e in TargetEndpoint.

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

    • Se viene eseguita una FaultRule, ma non viene eseguito alcun passaggio nella FaultRule (perché le relative condizioni vengono valutate in base a 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 FaultRule.

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

Di seguito sono riportati alcuni esempi con commenti incorporati.

Esecuzione di ProxyEndpoint

La valutazione di ProxyEndpoint FaultRules si trova dal basso verso l'alto, quindi inizia a leggere l'ultima FaultRule nell'esempio seguente e continua a leggere. Osserva l'ultima regola predefinita.

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

La valutazione di TargetEndpoint FaultRules è dall'alto verso il basso, quindi inizia a leggere dalla prima FaultRule nell'esempio seguente e procedi fino in fondo. Osserva l'ultima regola predefinita.

<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 FaultRules è importante a seconda che l'errore si verifichi in ProxyEndpoint o in TargetEndpoint.

Ad esempio:

Ordine ProxyEndpoint Ordine TargetEndpoint

Nell'esempio seguente, poiché la valutazione si trova dal basso verso l'alto, viene eseguita FaultRule 3, il che significa che FaultRules 2 e 1 non vengono valutate.

5. Regola di errore 1: FALSO

4. Regola di errore 2: VERO

3. Regola di 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 FaultRule 2, il che significa che le FaultRules 3, 4 e 5 non vengono valutate.

1. Regola di errore 1: FALSO

2. Regola di errore 2: VERO

3. Regola di errore 3: TRUE

4. Regola di errore 4: FALSO

5. Regola di errore 5: FALSO

Norme da includere

È possibile eseguire qualsiasi criterio da una FaultRule inserendolo nei passaggi. Ad esempio, puoi eseguire un criterio AssegnaMessage per formattare una risposta all'app client e poi 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 stato di errore (informazioni su continueOnError)

È possibile che l'intestazione si ripeta, ma c'è una particolare sfumatura da considerare in merito a un errore del proxy che causa l'ingresso di un proxy API in uno stato di errore o, meglio, di non 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 ha valore true, non verrà attivata se il proxy non è in stato di errore.

Tuttavia, di seguito è riportato un esempio di errore in cui il proxy non entra in uno stato di errore. In qualsiasi criterio, puoi impostare un attributo sull'elemento principale chiamato continueOnError. Questo attributo è molto importante per la gestione dei guasti, perché determina se il proxy entra in uno stato di errore in caso di esito negativo del criterio. Nella maggior parte dei casi, è consigliabile mantenere il valore predefinito continueOnError="false", che mette il proxy in uno stato di errore se il criterio non funziona e viene attivata la gestione personalizzata degli errori. Tuttavia, se continueOnError="true" (ad esempio, se non vuoi che un callout di servizio non interrompa l'esecuzione del proxy), il proxy non entra in stato di errore se questo criterio non viene applicato e il proxy non esaminerà le tue regole di errore.

Per informazioni sulla registrazione degli errori quando continueOnError="true", consulta Gestione degli errori dei criteri nel flusso attuale.

Dove definire FaultRules: ProxyEndpoint o TargetEndpoint

Quando si verifica un errore relativo a un proxy API, l'errore si verifica in <ProxyEndpoint> (richiesta o risposta all'app client) o in <TargetEndpoint> (richiesta o risposta dal servizio di destinazione). Ovunque si verifichi l'errore, Apigee cerca le regole di errore.

Ad esempio, se non è disponibile un server di destinazione (codice di stato HTTP 503), il proxy API passerà in stato di errore nella risposta <TargetEndpoint> e il normale flusso del proxy API non continuerà a utilizzare <ProxyEndpoint>. Se hai definito FaultRules solo in <ProxyEndpoint>, questo errore non verrà gestito.

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

FaultRules e criterio AlzaFault

Le regole di errore e il criterio AlzaFault all'apparenza sembrano essere metodi alternativi per eseguire la gestione dei guasti, e in qualche modo è vero. Ma funzionano anche insieme. Questa sezione spiega la relazione tra i due. Comprendere questa relazione dovrebbe aiutarti a progettare la gestione dei guasti, 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 mettere un proxy API in stato di errore quando un altro errore non si sarebbe verificato.

    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 AlzaFault al flusso di risposta. L'aspetto sarebbe 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 AlzaFault invia anche un messaggio di errore all'app client.

Cosa succede quando un criterio AlzaFault attiva un errore, che mette il proxy in uno stato di errore, che potenzialmente esegue una FaultRule? In questi casi, le cose possono diventare un po' complicate. Se il criterio AlzaFault restituisce un messaggio di errore e viene attivata una regola FaultRule che restituisce un messaggio di errore, cosa viene restituito all'app client?

  • Poiché la regola FaultRule o predefinitaFaultRule viene eseguita dopo il criterio AlzaFault, i dati della risposta FaultRule prevale.
  • I dati di risposta del criterio AlzaFault (codice di stato, frase di motivazione o payload del messaggio) vengono utilizzati se questi dati non sono impostati da FaultRule o predefinitaFaultRule.
  • Se sia il criterio AlzaFault sia FaultRule aggiungono intestazioni HTTP personalizzate, vengono incluse entrambe nella risposta. I nomi di intestazione duplicati creano un'intestazione con più valori.

Ecco un esempio di cosa viene impostato da un criterio AlzaFault e da un criterio FaultRule e da cosa viene restituito all'app client. Gli esempi sono progettati per brevità, non per best practice.

Cosa viene impostato da un criterio RaiseFault e da una FaultRule.

L'app client riceve:


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

<- Il criterio delle regole di errore consente di impostare quanto segue:


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

<- Il criterio RaiseFault imposta quanto segue:


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

Condizioni degli edifici

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

Per contestualizzare il resto di questa sezione, ecco una regola di errore di esempio con una condizione FaultRule esterna e una condizione Step interna.

<FaultRule name="invalid_key_rule">
    <Step>
        <Name>invalid-key-message</Name>
        <Condition>oauthV2.Verify-API-Key-1.failed = true</Condition>
    </Step>
    <Condition>fault.name = "FailedToResolveAPIKey"</Condition>
</FaultRule>

Variabili specifiche per gli errori dei criteri

Le variabili fault.name e {policy_namespace}.{policy_name}.failed sono disponibili quando un criterio genera un errore.

fault.name

Quando un criterio ha esito negativo, 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, quanto segue, 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"}}}

Quindi la condizione sarebbe simile alla seguente:

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

Per un elenco degli errori relativi alle norme, consulta la Guida di riferimento agli errori delle norme.

{policy_namespace}.{policy_name}.failed

La variabile *.failed è disponibile in caso di esito negativo di un criterio. Di seguito sono riportati alcuni esempi di variabili *.failed per criteri diversi. Per gli spazi dei nomi dei criteri, consulta le variabili di flusso in ogni argomento di riferimento alle norme.

Altre variabili disponibili

Quando un proxy API entra in stato di errore, le uniche variabili disponibili per l'utilizzo in condizioni sono:

  • Le variabili del criterio che hanno avuto esito negativo.
  • Le variabili del messaggio HTTP esistenti al momento dell'errore. Ad esempio, se viene generato un errore nella risposta, una FaultRule 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 funziona, 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.

Informazioni dettagliate

Best practice per la gestione dei guasti

La gestione dei guasti è un'attività di progettazione dell'architettura molto importante per lo sviluppo di proxy API. È importante capire come e quando gestire gli errori, determinare quali messaggi di errore verranno visualizzati e progettare i formati dei messaggi di errore. Dopo (o come) aver compreso questi aspetti, utilizza queste best practice per l'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 pattern più comune è l'utilizzo del criterioAssignMessage per impostare elementi specifici nella risposta di errore in attesa. Puoi anche utilizzare AttributionMessage 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 FlowHook. 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 passaggi all'interno di una FaultRule. È preferibile utilizzare i criteri di AssegnaMessage per impostare o modificare gli elementi del messaggio, inclusi payload, intestazioni o codice di stato.
  • Per ogni FaultRule o per tutte le FaultRule tranne l'ultima valutata, fornisci un <Condition> esterno associato come elemento secondario dell'elemento <FaultRule>. La condizione di esecuzione per una FaultRule senza una 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 FaultRule restituisce true o false. Le condizioni dei passaggi vengono valutate solo dopo che Apigee ha eseguito la regola FaultRule che le contiene. In una regola FaultRule, è comune avere più criteri Steps conAssignMessage (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 FaultRule per ogni errore del criterio che potresti ricevere, quindi fai una distinzione tra errori separati con condizioni allegate ai passaggi. Ad esempio, crea una FaultRule per gestire un errore nei criteri per le quote, come QuotaViolation, e una FaultRule separata per InvalidApiKey. Per informazioni su questi errori, consulta la documentazione di riferimento sugli errori dei criteri. Man mano che scopri altri errori che devono essere gestiti, puoi tornare indietro in un secondo momento e aggiungerli alle tue regole di errore. Va bene essere iterativi, anche se richiedono un nuovo deployment del proxy). Questo approccio ti consente di rilevare lo stesso tipo di errore indipendentemente dal criterio, il che rende efficiente il tuo file XML FaultRules.

    Le condizioni di passaggio interne offrono 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 esterno in modo che venga attivata all'errore QuotaViolation (che in entrambi i casi viene generato quando la quota viene superata). Quindi imposta 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 sviluppatore o 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, prendi in considerazione una singola regola di errore che viene eseguita quando un determinato criterio non viene eseguito e includi più passaggi per mappare 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 passaggi diversi per il criterioAssignMessage vengano eseguiti in condizioni diverse, come segue:

    <FaultRule name="raise-fault-3">
  <!-- This condition catches *any* error in the Verify-API-Key-1 policy. -->
  <Condition>oauthV2.Verify-API-Key-1.failed = "true"</Condition>
  <!-- This first step always executes, which handles errors you haven't mapped with inner conditions. -->
  <Step>
    <Name>AM-Generic-Key-Fault</Name>
  </Step>
  <Step>
    <Name>AM-API-Key-NotFound</Name>
    <Condition>fault.name = "FailedToResolveAPIKey"</Condition>
  </Step>
  <Step>
    <Name>AM-API-Key-Invalid</Name>
    <Condition>fault.name = "InvalidApiKey"</Condition>
  </Step>
</FaultRule>
  • Aggiungi FaultRules in cui si verificano gli errori (lato client <ProxyEndpoint> o lato target <TargetEndpoint>). Includi FaultRules per ogni criterio visualizzato in ciascuna località.
  • Quando utilizzi i criteri AlzaFault in combinazione con FaultRules, coordina i dati di risposta che vengono rinviati quando sia il criterio AlzaFault sia un valore FaultRule restituisce dati. Ad esempio, se hai un criterio AlzaFault che imposta il codice di stato HTTP, non configurare anche un passaggio di AssegnaMessage all'interno di una regola FaultRule che reimposta il codice di stato. Il peggio che può capitare è che il codice di stato predefinito venga restituito all'app client.

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

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

    Puoi anche specificare un elemento <Condition> in un <DefaultFaultRule>. Potresti voler eseguire questa operazione 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 <DefaultFaultRule> con <AlwaysEnforce> impostato su true, se hai uno o più criteri che vuoi che il proxy esegua sempre, indipendentemente dal fatto che sia stata eseguita una FaultRule 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 che l'errore sia stato gestito o meno in precedenza. Successivamente, dovrai allegare un criterio di AssegnaMessage appropriato nella sezione <PostFlow>/<Response> e anche allegare lo stesso criterio in <DefaultFaultRule> con <AlwaysEnforce> impostato su true.

Pattern per una gestione dei guasti riutilizzabile e centralizzata

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

Creazione di FaultRules

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

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

Aggiunta di criteri a una FaultRule

Anche se puoi inserire qualsiasi criterio in FaultRule, in genere usi il criterioAssignMessage per generare un messaggio di risposta personalizzato per una condizione di errore. MigrateMessage consente di configurare una risposta HTTP con payload, codice di stato HTTP, intestazioni ed elementi della frase di motivazione.

L'esempio seguente mostra una configurazione tipica dei criteri AttributionMessage:

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

Tieni presente che non specifica un elemento <AssignTo>. Ciò significa che verrà assegnato al messaggio ambient, a seconda di dove è allegato il criterio.

Ora puoi utilizzare questo criterio in FaultRule. Osserva il modo in cui fai riferimento al criterio AttributionMessage per nome nella 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 eseguirà il criterio di AssegnaMessage denominato AM-Invalid-Key ogni volta che un'app presenta una chiave API non valida.

Puoi eseguire più criteri in una FaultRule, 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 ExtractVariables, il criterioAssignMessage o qualsiasi altro criterio nella regola FaultRule. Tieni presente che l'elaborazione della FaultRule si interrompe immediatamente se si verifica una di queste situazioni:

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

Definizione del messaggio di errore personalizzato restituito da una FaultRule

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

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 (vedi l'esempio FaultRules precedente).

<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 di motivazione, ovvero una breve descrizione dell'errore.

Creazione di una regola predefinitaFaultRule

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

Ad esempio, la configurazione TargetEndpoint di seguito definisce una RegolaFaultRule 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 utilizzata in genere per restituire un messaggio di errore generico in caso di errori imprevisti, ad esempio un messaggio contenente le informazioni di contatto per l'assistenza tecnica. Questa risposta predefinita ha il duplice scopo di fornire informazioni ottimizzate per gli sviluppatori e di offuscare gli URL di backend o altre informazioni che potrebbero essere utilizzate per compromettere il sistema.

Ad esempio, definisci il seguente criterio AssegnaMessage in modo che restituisca 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 FaultRule. La regola predefinitaFaultRule è sempre l'ultima FaultRule da eseguire:

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

Un uso della regola predefinitaFaultRule è determinare il tipo di errore che si verifica quando non è altrimenti possibile determinarlo. Ad esempio, se il proxy API non funziona a causa di un errore che non puoi determinare, puoi utilizzare la regola predefinitaFaultRule per richiamare il seguente criterio abuseMessage. Questo criterio scrive il valore fault.name in un'intestazione denominata Unhandled-Fault nella risposta:

<AssignMessage name="AM-Set-Fault-Header">
  <Set>
    <Headers>
      <Header name="Unhandled-Fault">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Puoi quindi visualizzare l'intestazione nello strumento di debug o nella risposta per vedere la causa dell'errore.

Aggiunta del logging dei messaggi a PostClientFlow

PostClientFlow è l'unico flusso che viene eseguito dopo che il proxy entra nello stato di errore. Solo il criterio MessageLogging può essere associato a questo flusso, che viene eseguito dopo che la risposta viene inviata nuovamente al client. Anche se collegare il criterio MessageLogging a questo flusso tecnicamente non è una soluzione per la gestione degli errori, puoi utilizzarlo per registrare le informazioni in caso di errore. Poiché viene eseguito a prescindere dal fatto che il proxy abbia esito positivo o negativo, puoi inserire i criteri di logging dei messaggi in PostClientFlow per avere la certezza che vengano sempre eseguiti.

Gestire gli errori delle norme nel flusso attuale

Gli esempi mostrati finora utilizzano tutti una regola FaultRule 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 è possibile ripristinare il controllo alla normale pipeline e in genere viene restituito un 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 della 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 criterio VerificationAPIKey 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 VerificationAPIKey imposta la variabile oauthV2.verify-api-key.failed su true, ma l'elaborazione continua nel flusso attuale.

Puoi quindi aggiungere il criterio VerificationAPIKey come passaggio nel pre-flusso di ProxyEndpoint:

<ProxyEndpoint name="default">
  ...
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>verify-api-key</Name>
      </Step>
      <Step>
        <Name>FaultInFlow</Name>
        <Condition>oauthV2.verify-api-key.failed = "true"</Condition>
      </Step>
    </Request>
    <Response/>
  </PreFlow>
</ProxyEndpoint>

Nota come il passaggio successivo nel preflusso utilizza una condizione per verificare l'esistenza di un errore. Se si è verificato un errore nel criterio VerificationAPIKey, viene eseguito il criterio denominato FaultInFlow. In caso contrario, il criterio FaultInFlow viene ignorato. Il criterio FaultInFlow può eseguire molte cose, ad esempio registrare l'errore, tentare di correggerlo o eseguire altre azioni.

Attivazione di un errore tramite il criterio AlzaFault

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

Il criterio RaiseFault viene utilizzato per testare una condizione specifica che potrebbe non essere rilevata da un altro criterio. Nell'esempio precedente, hai aggiunto un tag <Condition> a un tag PreFlow <Step> che ha causato l'esecuzione del criterio FaultInFlow se la condizione è soddisfatta. Se FaultInFlow è un criterio AlzaFault, 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 di errore.

Quando un criterio AlzaFault attiva un errore, puoi utilizzare la regola FaultRule e la condizione seguenti per elaborarlo:

<FaultRule name="raisefault_rule">
  <Step>
    <Name>POLICY-NAME-HERE</Name>
  </Step>
  <Condition>fault.name = "RaiseFault"</Condition>
</FaultRule>

Tieni presente che la condizione verifica un guasto denominato RaiseFault. Il criterio AlzaFault imposta sempre il valore di fault.name su RaiseFault. Puoi anche impostare variabili personalizzate all'interno di un criterio RaiseFault. Se lo fai, puoi testare queste variabili negli elementi Condition.

Gestione personalizzata dei codici di errore HTTP da parte del server di destinazione

Gli esempi mostrati nelle sezioni precedenti riguardano gli errori creati dai criteri. 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 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 quindi restituisce un messaggio di errore direttamente al client che ha inviato la richiesta.

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

Nell'esempio successivo, utilizzerai la proprietà success.codes per configurare TargetEndpoint in modo che i codici di risposta HTTP 400 e 500 vengano trattati correttamente, insieme ai codici HTTP predefiniti. Trattando questi codici come riusciti, TargetEndpoint assume l'elaborazione del messaggio di risposta, anziché richiamare lo stato di errore:

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <Properties>
          <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Come puoi vedere in questo esempio, puoi utilizzare i caratteri jolly per impostare la proprietà success.codes su un intervallo di valori.

L'impostazione della proprietà success.codes sovrascrive i valori predefiniti. Di conseguenza, se vuoi aggiungere il codice HTTP 400 all'elenco dei codici di operazione riuscita 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 un 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 al fine di restituire un messaggio di risposta personalizzato all'app che ha inviato la richiesta. TargetEndpoint utilizza il criterio denominato ReturnError per gestire i codici di risposta HTTP 400 e 500:

<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request/>
    <Response>
      <Step>
        <Name>ReturnError</Name>
        <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition>
      </Step>
    </Response>
  </PreFlow>

  <HTTPTargetConnection>
    <Properties>
      <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Questa configurazione TargetEndpoint fa sì che il criterio chiamato ReturnError gestisca la risposta ogni volta che TargetEndpoint rileva un codice di risposta HTTP di 400 O 500.

Tassonomia dei 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 tramite il criterio AlzaFault
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 a nessun BasePath per le configurazioni 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 la definizione di connessioni a livello di rete o trasporto
Richiedi convalide Lunghezza contenuto mancante, Intestazione host mancante Gli errori si verificano durante i controlli della semantica su ogni richiesta
Convalide delle risposte Gli errori si verificano durante i controlli della semantica su ogni risposta
Errori di IO SSLHandshakeError, ReadTimeout, ReadError, WriteTimeout, WriteError, ChunkError Errori di lettura/scrittura a endpoint client o di destinazione, timeout, errori TLS/SSL ed errori in blocchi
Sistema Errori di runtime non definiti
Memoria Memoria esaurita, GCOverLimit Errori relativi alla memoria
Thread RogueTaskTerminated Errori come l'interruzione di attività inesplorate
Norme Gli errori relativi a 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 segnala un guasto, viene compilato un insieme di attributi per facilitare la risoluzione dei problemi. Un guasto include le seguenti informazioni:

  • Motivo
  • Attributi personalizzati definiti dall'utente