Gestione degli errori nei criteri di Gestione APIError handling in API Management policies

Gestione API di Azure consente agli autori di rispondere alle condizioni di errore che possono verificarsi durante l'elaborazione delle richieste al proxy fornendo un oggetto ProxyError.Azure API Management allows publishers to respond to error conditions that may occur during the processing of requests to the proxy by providing a ProxyError object. È possibile accedere all'oggetto ProxyError tramite la proprietà context.LastError. I criteri possono utilizzarlo nella sezione dei criteri on-error.The ProxyError object is accessed through the context.LastError property and can be used by policies in the on-error policy section. In questo argomento vengono indicati dei riferimenti per le funzionalità di gestione degli errori in Gestione API di Azure.This topic provides a reference for the error handling capabilities in Azure API Management.

Gestione degli errori in Gestione APIError handling in API Management

I criteri in Gestione API di Azure sono divisi nelle sezioni inbound, backend, outbound e on-error come mostrato nell'esempio seguente.Policies in Azure API Management are divided into inbound, backend, outbound, and on-error sections as shown in the following example.

<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.During the processing of a request, built-in steps are executed along with any policies that are in scope for the request. Se si verifica un errore, l'elaborazione passa immediatamente alla sezione di criteri on-error.If an error occurs, processing immediately jumps to the on-error policy section. È possibile usare la sezione di criteri on-error 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.The on-error policy section can be used at any scope, and API publishers can configure custom behavior such as logging the error to event hubs or creating a new response to return to the caller.

Nota

Per impostazione predefinita, la sezione on-error non è presente nei criteri.The on-error section is not present in policies by default. Per aggiungere la sezione on-error a un criterio, selezionare il criterio desiderato nell'editor dei criteri e aggiungerlo.To add the on-error section to a policy, browse to the desired policy in the policy editor and add it. Per ulteriori informazioni sulla configurazione dei criteri, vedere Criteri di Gestione API.For more information about configuring policies, see Policies in API Management.

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.If there is no on-error section, callers will receive 400 or 500 HTTP response messages if an error condition occurs.

Criteri consentiti in on-errorPolicies allowed in on-error

È possibile usare i seguenti criteri nella sezione di criteri on-error.The following policies can be used in the on-error policy section.

LastErrorLastError

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 e dotata delle seguenti proprietà.When an error occurs and control jumps to the on-error policy section, the error is stored in context.LastError property which can be accessed by policies in the on-error section and has the following properties.

NomeName TipoType DescrizioneDescription ObbligatorioRequired
SorgenteSource stringstring Indica l'elemento in cui si è verificato l'errore.Names the element where the error occurred. Può trattarsi di un criterio o di un nome di passaggio predefinito nella pipeline.Could be either policy or a built-in pipeline step name. Yes
MotivoReason stringstring Codice errore leggibile tramite computer, da utilizzare se necessario nella gestione degli errori.Machine-friendly error code, which could be used in error handling. NoNo
MessageMessage stringstring Descrizione dell'errore leggibile dall'utente.Human-readable error description. Yes
ScopeScope stringstring Nome dell'ambito in cui si è verificato l'errore. Può essere "global", "product", "api" o "operation"Name of the scope where the error occurred and could be one of "global", "product", "api", or "operation" NoNo
SezioneSection stringstring Nome della sezione in cui si è verificato l'errore. Può essere "inbound", "backend", "outbound" o "on-error".Section name where error occurred and could one of "inbound", "backend", "outbound", or "on-error". NoNo
PathPath stringstring Specifica i criteri annidati, ad esempio "choose[3]/when[2]".Specifies nested policy, e.g. "choose[3]/when[2]". NoNo
PolicyIdPolicyId stringstring Valore dell'attributo id, se specificato dal cliente, nel criterio in cui si è verificato l'erroreValue of the id attribute, if specified by the customer, on the policy where error occurred NoNo

Nota

Tutti i criteri dispongono di un attributo id facoltativo che è possibile aggiungere al loro elemento radice.All policies have an optional id attribute that can be added to the root element of the policy. 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.If this attribute is present in a policy when an error condition occurs, the value of the attribute can be retrieved using the context.LastError.PolicyId property.

Errori predefiniti per i passaggi predefinitiPredefined errors for built-in steps

Gli errori seguenti sono predefiniti per le condizioni di errore che possono verificarsi durante la valutazione dei passaggi di elaborazione predefiniti.The following errors are predefined for error conditions that can occur during the evaluation of built-in processing steps.

SorgenteSource CondizioneCondition MotivoReason MessageMessage
configurazioneconfiguration L'URI non corrisponde a un'API o a un'operazioneUri doesn't match to any Api or Operation OperationNotFoundOperationNotFound Impossibile associare la richiesta in ingresso a un'operazione.Unable to match incoming request to an operation.
autorizzazioneauthorization Chiave di sottoscrizione non fornitaSubscription key not supplied SubscriptionKeyNotFoundSubscriptionKeyNotFound Accesso negato, chiave di sottoscrizione mancante.Access denied due to missing subscription key. Assicurarsi di includere la chiave di sottoscrizione quando si effettuano richieste a questa API.Make sure to include subscription key when making requests to this API.
autorizzazioneauthorization Il valore della chiave di sottoscrizione non è validoSubscription key value is invalid SubscriptionKeyInvalidSubscriptionKeyInvalid Accesso negato, la chiave di sottoscrizione non è valida.Access denied due to invalid subscription key. Assicurarsi di fornire la chiave valida di una sottoscrizione attiva.Make sure to provide a valid key for an active subscription.

Errori predefiniti per i criteriPredefined errors for policies

Gli errori seguenti sono predefiniti per le condizioni di errore che possono verificarsi durante la valutazione dei criteri.The following errors are predefined for error conditions that can occur during policy evaluation.

SorgenteSource CondizioneCondition MotivoReason MessageMessage
rate-limitrate-limit Limite di velocità superatoRate limit exceeded RateLimitExceededRateLimitExceeded Il limite di velocità è stato superatoRate limit is exceeded
quotaquota La quota è stata superataQuota exceeded QuotaExceededQuotaExceeded La quota del volume di chiamate è esaurita.Out of call volume quota. La quota verrà ripristinata in xx:xx:xx.Quota will be replenished in xx:xx:xx. -oppure- La quota della larghezza di banda è esaurita.-or- Out of bandwidth quota. La quota verrà ripristinata in xx:xx:xx.Quota will be replenished in xx:xx:xx.
jsonpjsonp Il valore del parametro callback non è valido (contiene caratteri errati)Callback parameter value is invalid (contains wrong characters) CallbackParameterInvalidCallbackParameterInvalid Il valore del parametro callback {callback-parameter-name} non è un identificatore JavaScrpit valido.Value of callback parameter {callback-parameter-name} is not a valid JavaScript identifier.
ip-filterip-filter Impossibile analizzare l'IP del chiamante dalla richiestaFailed to parse caller IP from request FailedToParseCallerIPFailedToParseCallerIP Impossibile stabilire l'indirizzo IP per il chiamante.Failed to establish IP address for the caller. Accesso negato.Access denied.
ip-filterip-filter L'IP del chiamante non è presente nell'elenco degli IP consentitiCaller IP is not in allowed list CallerIpNotAllowedCallerIpNotAllowed L'indirizzo IP del chiamante {ip-address} non è consentito.Caller IP address {ip-address} is not allowed. Accesso negato.Access denied.
ip-filterip-filter L'IP del chiamante è presente nell'elenco degli IP bloccatiCaller IP is in blocked list CallerIpBlockedCallerIpBlocked L'indirizzo IP del chiamante è bloccato.Caller IP address is blocked. Accesso negato.Access denied.
check-headercheck-header Intestazione richiesta non presentata o valore mancanteRequired header not presented or value is missing HeaderNotFoundHeaderNotFound Impossibile trovare l'intestazione {header-name} nella richiesta.Header {header-name} was not found in the request. Accesso negato.Access denied.
check-headercheck-header Intestazione richiesta non presentata o valore mancanteRequired header not presented or value is missing HeaderValueNotAllowedHeaderValueNotAllowed Il valore {header-value} dell'intestazione {header-name} non è consentito.Header {header-name} value of {header-value} is not allowed. Accesso negato.Access denied.
validate-jwtvalidate-jwt La richiesta non contiene il token JWTJwt token is missing in request TokenNotFoundTokenNotFound JWT non trovato nella richiesta.JWT not found in the request. Accesso negato.Access denied.
validate-jwtvalidate-jwt Convalida della firma non riuscitaSignature validation failed TokenSignatureInvalidTokenSignatureInvalid <messaggio dalla libreria JWT>.<message from jwt library>. Accesso negato.Access denied.
validate-jwtvalidate-jwt Destinatari non validiInvalid audience TokenAudienceNotAllowedTokenAudienceNotAllowed <messaggio dalla libreria JWT>.<message from jwt library>. Accesso negato.Access denied.
validate-jwtvalidate-jwt Autorità di certificazione non validaInvalid issuer TokenIssuerNotAllowedTokenIssuerNotAllowed <messaggio dalla libreria JWT>.<message from jwt library>. Accesso negato.Access denied.
validate-jwtvalidate-jwt Token scadutoToken expired TokenExpiredTokenExpired <messaggio dalla libreria JWT>.<message from jwt library>. Accesso negato.Access denied.
validate-jwtvalidate-jwt La chiave della firma non è stata risolta dall'IDSignature key was not resolved by id TokenSignatureKeyNotFoundTokenSignatureKeyNotFound <messaggio dalla libreria JWT>.<message from jwt library>. Accesso negato.Access denied.
validate-jwtvalidate-jwt Attestazioni necessarie non presenti nel tokenRequired claims are missing from token TokenClaimNotFoundTokenClaimNotFound Il token JWT non contiene le attestazioni seguenti: <c1>, <c2>, …JWT token is missing the following claims: <c1>, <c2>, … Accesso negato.Access denied.
validate-jwtvalidate-jwt I valori di attestazione non corrispondonoClaim values mismatch TokenClaimValueNotAllowedTokenClaimValueNotAllowed Il valore {claim-value} dell'attestazione {claim-name} non è consentito.Claim {claim-name} value of {claim-value} is not allowed. Accesso negato.Access denied.
validate-jwtvalidate-jwt Altri errori di convalidaOther validation failures JwtInvalidJwtInvalid <messaggio dalla libreria JWT><message from jwt library>

Passaggi successiviNext steps

Per altre informazioni sull'uso di questi criteri, vedere:For more information working with policies, see: