Condividi tramite

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 agli autori di rispondere alle condizioni di errore che possono verificarsi durante l'elaborazione delle richieste. È possibile accedere all'oggetto ProxyError tramite la proprietà context.LastError. I criteri possono utilizzarlo nella sezione dei criteri on-error. 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 che rientrano nell'ambito per la 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 comportamenti personalizzati come la registrazione degli errori nell'hub eventi o la creazione di una nuova risposta da restituire al chiamante.

Nota

Per impostazione predefinita, la sezione on-error non è presente nei criteri. 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 la sezione on-error non è presente, il chiamante riceverà dei messaggi di risposta 400 o 500 HTTP in caso di una condizione di errore.

Criteri consentiti in on-error

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

UltimoErrore

Quando si verifica un errore e il controllo passa alla sezione di criteri on-error, l'errore viene conservato nella proprietà context.LastError, accessibile dai criteri nella sezione on-error. LastError ha le seguenti proprietà.

Nome Tipo Descrizione Richiesto
Source corda Indica l'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: "in ingresso", "back-end", "in uscita" o "in on error". NO
Path corda Specifica la gerarchia dei criteri annidata, ad esempio "choose[3]\when[2]". Più istanze di un criterio annidato vengono indicizzate 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, il valore dell'attributo può essere recuperato tramite la proprietà context.LastError.PolicyId.

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 a un'API o a un'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.
multipli La connessione downstream (da un client a un gateway di Gestione API) è stata interrotta dal client mentre la richiesta era in sospeso ErroreDiConnessioneDelClient multipli
multipli La connessione upstream (da un gateway di Gestione API a un servizio back-end) non è stata stabilita o interrotta dal back-end Errore di Connessione al Backend multipli
multipli Si è verificata un'eccezione di runtime durante la valutazione di un'espressione specifica ExpressionValueEvaluationFailure multipli

Errori predefiniti per i criteri

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'IP del chiamante non è presente nell'elenco degli IP consentiti CallerIpNotAllowed L'indirizzo IP del chiamante {ip-address} non è consentito. Accesso negato.
filtro IP L'IP del chiamante è presente nell'elenco degli IP bloccati CallerIpBlocked L'indirizzo IP del chiamante è bloccato. Accesso negato.
check-header Intestazione richiesta non presentata o valore mancante HeaderNotFound Impossibile trovare l'intestazione {header-name} nella richiesta. Accesso negato.
check-header Intestazione richiesta non presentata o valore mancante HeaderValueNotAllowed Il valore {header-value} dell'intestazione {header-name} non è consentito. Accesso negato.
validate-jwt JWT non è presente nella richiesta TokenNotPresent JWT non presente.
validate-jwt Convalida della firma non riuscita TokenSignatureInvalid <messaggio dalla libreria JWT>. Accesso negato.
validate-jwt Destinatari non validi TokenAudienceNotAllowed <messaggio dalla libreria JWT>. Accesso negato.
validate-jwt Autorità di certificazione non valida TokenIssuerNotAllowed <messaggio dalla libreria JWT>. Accesso negato.
validate-jwt Token scaduto Token Scaduto <messaggio dalla libreria JWT>. Accesso negato.
validate-jwt La chiave della firma non è stata risolta dall'ID TokenSignatureKeyNotFound <messaggio dalla libreria JWT>. Accesso negato.
validate-jwt Attestazioni necessarie non presenti nel token TokenClaimNotFound JWT manca le attestazioni seguenti: <c1>, <c2>, ... Accesso negato.
validate-jwt I valori di attestazione non corrispondono TokenClaimValueNotAllowed 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>
forward-request o send-request 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

L'impostazione di un criterio di API in:

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

e l'invio di una richiesta non autorizzata determineranno la risposta seguente:

Risposta di errore non autorizzata

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere:

  • Last updated on