Gestione degli errori nei criteri di Gestione API

SI APPLICA A: Tutti i livelli di Gestione API

Fornendo un oggetto ProxyError, Gestione API di Azure consente ai server di pubblicazione di rispondere alle condizioni di errore, che possono verificarsi durante l'elaborazione delle richieste. L'oggetto ProxyError è accessibile tramite la proprietà contesto.LastError. Le politiche nella sezione on-error politica possono usare l'oggetto ProxyError. In questo articolo vengono indicati dei riferimenti per le funzionalità di gestione degli errori in Gestione API di Azure.

Gestione degli errori in Gestione API

I criteri in Gestione API di Azure sono divisi nelle sezioni inbound, backend, outbound e on-error come mostrato nell'esempio seguente.

<policies>
    <inbound>
        <!-- statements to be applied to the request go here -->
    </inbound>
    <backend>
        <!-- statements to be applied before the request is
             forwarded to the backend service go here -->
    </backend>
    <outbound>
        <!-- statements to be applied to the response go here -->
    </outbound>
    <on-error>
        <!-- statements to be applied if there is an error
             condition go here -->
    </on-error>
</policies>

Durante l'elaborazione di una richiesta, i passaggi predefiniti vengono eseguiti insieme a tutti i criteri inclusi nell'ambito della richiesta. Se si verifica un errore, l'elaborazione passa immediatamente alla sezione di criteri on-error.

La sezione dei criteri on-error può essere usata in qualsiasi ambito. Gli autori di API possono configurare un comportamento personalizzato, ad esempio la registrazione dell'errore per Hub eventi di Azure o la creazione di una nuova risposta per tornare al chiamante.

Nota

La on-error sezione non è presente nei criteri per impostazione predefinita. Per aggiungere la sezione on-error a un criterio, selezionare il criterio desiderato nell'editor dei criteri e aggiungerlo. Per ulteriori informazioni sulla configurazione dei criteri, vedere Criteri di Gestione API.

Se non è presente alcuna on-error sezione, i chiamanti ricevono 400 o 500 messaggi di risposta HTTP se si verifica una condizione di errore.

Politiche consentite in caso di errore

È possibile usare i seguenti criteri nella sezione di criteri on-error.

UltimoErrore

Quando si verifica un errore e il controllo passa alla on-error sezione dei criteri, l'errore viene archiviato nella proprietà contesto.LastError. Le politiche nella sezione on-error possono accedere a context.LastError. LastError ha le proprietà seguenti.

Nome Tipo Descrizione Richiesto
Source corda Nome dell'elemento in cui si è verificato l'errore. Può trattarsi di un criterio o di un nome di passaggio predefinito nella pipeline. Sì
Reason corda Codice errore leggibile tramite computer, da utilizzare se necessario nella gestione degli errori. NO
Message corda Descrizione dell'errore leggibile dall'utente. Sì
Scope corda Nome dell'ambito in cui si è verificato l'errore. NO
Section corda Nome della sezione in cui si è verificato l'errore. Valori possibili: inbound, backend, outboundo on-error. NO
Path corda Specifica la gerarchia dei criteri annidata, ad esempio choose[3]\\when[2]. Più elementi di un criterio annidato vengono indicizzati a partire da 1. NO
PolicyId corda Valore dell'attributo id, se specificato dal cliente, nel criterio in cui si è verificato l'errore NO

Suggerimento

È possibile accedere al codice di stato tramite context.Response.StatusCode.

Nota

Tutti i criteri dispongono di un attributo id facoltativo che è possibile aggiungere al loro elemento radice. Se questo attributo è presente in un criterio quando si verifica una condizione di errore, è possibile recuperare il valore dell'attributo usando la context.LastError.PolicyId proprietà .

Errori predefiniti per i passaggi predefiniti

Gli errori seguenti sono predefiniti per le condizioni di errore che possono verificarsi durante la valutazione dei passaggi di elaborazione predefiniti.

Origine Condizione Motivo Messaggio
configurazione L'URI non corrisponde ad alcuna API o operazione OperationNotFound Impossibile associare la richiesta in ingresso a un'operazione.
autorizzazione Chiave di sottoscrizione non fornita ChiaveDiSottoscrizioneNonTrovata Accesso negato, chiave di sottoscrizione mancante. Assicurarsi di includere la chiave di sottoscrizione quando si effettuano richieste a questa API.
autorizzazione Il valore della chiave di sottoscrizione non è valido ChiaveDiAbbonamentoNonValida Accesso negato, la chiave di sottoscrizione non è valida. Assicurarsi di fornire la chiave valida di una sottoscrizione attiva.
molteplici Il client ha interrotto una connessione downstream (da un client a un gateway di Gestione API) mentre la richiesta era in sospeso ErroreDiConnessioneDelClient molteplici
multiplo Il back-end è stato interrotto o non è stato in grado di stabilire una connessione upstream (da un gateway di Gestione API a un servizio back-end) Errore di Connessione al Backend molteplici / numerosi
multipli Eccezione di runtime durante la valutazione di un'espressione specifica ErroreDiValutazioneDelValoreDell'Espressione molteplici

Errori predefiniti per le politiche

Gli errori seguenti sono predefiniti per le condizioni di errore che possono verificarsi durante la valutazione dei criteri.

Origine Condizione Motivo Messaggio
limite di velocità Limite di velocità superato Limite di velocità superato Il limite di velocità è stato superato
limite La quota è stata superata Quota superata La quota del volume di chiamate è esaurita. La quota verrà ripristinata in xx:xx:xx. -oppure- La quota della larghezza di banda è esaurita. La quota verrà ripristinata in xx:xx:xx.
jsonp Il valore del parametro callback non è valido (contiene caratteri errati) CallbackParameterInvalid Il valore del parametro callback {callback-parameter-name} non è un identificatore JavaScrpit valido.
filtro IP Impossibile analizzare l'IP del chiamante dalla richiesta Impossibile interpretare l'IP del chiamante Impossibile stabilire l'indirizzo IP per il chiamante. Accesso negato.
filtro IP L'indirizzo IP del chiamante non è incluso nell'elenco consentito IndirizzoIpChiamanteNonConsentito L'indirizzo IP del chiamante {ip-address} non è consentito. Accesso negato.
filtro IP L'IP del chiamante è presente nell'elenco degli IP bloccati Indirizzo IP del chiamante bloccato L'indirizzo IP del chiamante è bloccato. Accesso negato.
check-header Intestazione richiesta non presentata o valore mancante IntestazioneNonTrovata Impossibile trovare l'intestazione {header-name} nella richiesta. Accesso negato.
check-header Intestazione richiesta non presentata o valore mancante ValoreIntestazioneNonConsentito Il valore {header-value} dell'intestazione {header-name} non è consentito. Accesso negato.
validate-jwt JSON Web Token (JWT) mancante nella richiesta TokenNotPresent JWT non presente.
validate-jwt Convalida della firma non riuscita FirmaDelTokenNonValida <messaggio dalla libreria JWT>. Accesso negato.
validate-jwt Destinatari non validi TokenAudienceNonConsentito <messaggio dalla libreria JWT>. Accesso negato.
validate-jwt Emittente non valido EmittenteTokenNonConsentito <messaggio dalla libreria JWT>. Accesso negato.
validate-jwt Token scaduto Token Scaduto <messaggio dalla libreria JWT>. Accesso negato.
validate-jwt La chiave di firma non è stata risolta in base all'ID TokenSignatureKeyNotFound <messaggio dalla libreria JWT>. Accesso negato.
validare-jwt Attestazioni necessarie non presenti nel token TokenClaimNotFound JWT manca le attestazioni seguenti: <c1>, <c2>, ... Accesso negato.
validate-jwt I valori delle richieste non corrispondono TokenClaimValueNonConsentito Il valore {claim-value} dell'attestazione {claim-name} non è consentito. Accesso negato.
validate-jwt Altri errori di convalida Jwt non valido <messaggio dalla libreria JWT>
inoltra-richiesta o invia-richiesta Il codice di stato e le intestazioni della risposta HTTP non sono stati ricevuti dal back-end entro il timeout configurato Interruzione temporanea multipli

Esempio

Impostare un criterio API sul valore seguente:

<policies>
    <inbound>
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <set-header name="ErrorSource" exists-action="override">
            <value>@(context.LastError.Source)</value>
        </set-header>
        <set-header name="ErrorReason" exists-action="override">
            <value>@(context.LastError.Reason)</value>
        </set-header>
        <set-header name="ErrorMessage" exists-action="override">
            <value>@(context.LastError.Message)</value>
        </set-header>
        <set-header name="ErrorScope" exists-action="override">
            <value>@(context.LastError.Scope)</value>
        </set-header>
        <set-header name="ErrorSection" exists-action="override">
            <value>@(context.LastError.Section)</value>
        </set-header>
        <set-header name="ErrorPath" exists-action="override">
            <value>@(context.LastError.Path)</value>
        </set-header>
        <set-header name="ErrorPolicyId" exists-action="override">
            <value>@(context.LastError.PolicyId)</value>
        </set-header>
        <set-header name="ErrorStatusCode" exists-action="override">
            <value>@(context.Response.StatusCode.ToString())</value>
        </set-header>
        <base />
    </on-error>
</policies>

L'invio di una richiesta non autorizzata restituisce la risposta seguente:

Lo screenshot mostra la risposta dell'esempio, che include un messaggio di errore.

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere:

  • Last updated on