Condividi tramite

Convalidare i parametri

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Il criterio validate-parameters convalida i parametri di intestazione, query o percorso nelle richieste rispetto allo schema dell'API.

Importante

Se è stata importata un'API usando una versione dell'API di gestione precedente a 2021-01-01-preview, il criterio validate-parameters potrebbe non funzionare. Potrebbe essere necessario reimportare l'API usando l'API di gestione versione 2021-01-01-preview o successiva.

Nota

La dimensione massima dello schema API che può essere usata da questo criterio di convalida è di 4 MB. Se lo schema supera questo limite, i criteri di convalida restituiranno errori in fase di esecuzione. Per aumentarlo, contattare l'assistenza.

Nota

Impostare gli elementi e gli elementi figlio del criterio nell'ordine specificato nell'istruzione del criterio. Per configurare questo criterio, il portale fornisce un editor guidato basato su moduli. Altre informazioni su come impostare o modificare i criteri di API Management.

Istruzione del criterio

<validate-parameters specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect" errors-variable-name="variable name"> 
    <headers specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </headers>
    <query specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </query>
    <path specified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </path>
</validate-parameters>

Attributi

Attributo Descrizione Richiesto Valore predefinito
specified-parameter-action Azione da eseguire per i parametri di richiesta specificati nello schema dell'API.

Se specificato in un elemento headers, queryo path, il valore sostituisce il valore di specified-parameter-action nell'elemento validate-parameters. Le espressioni di criteri sono consentite.		 Sì N/D
unspecified-parameter-action Azione da eseguire per i parametri di richiesta non specificati nello schema dell'API.

Se specificato in un elemento headers o query, il valore sostituisce il valore di unspecified-parameter-action nell'elemento validate-parameters. Le espressioni di criteri sono consentite.		 Sì N/D
errors-variable-name Nome della variabile in context.Variables in cui registrare gli errori di convalida. Le espressioni di criteri non sono consentite. No N/D

Elementi

Nome Descrizione Richiesto
intestazioni Aggiungere questo elemento e uno o più sotto-elementi parameter per eseguire l'override delle azioni di convalida predefinite per determinati parametri denominati nelle richieste. Se il parametro viene specificato nello schema dell'API, questo valore esegue l'override della configurazione specified-parameter-action di livello superiore. Se il parametro non viene specificato nello schema dell'API, questo valore esegue l'override della configurazione unspecified-parameter-action di livello superiore. No
query Aggiungere questo elemento e uno o più sotto-elementi parameter per eseguire l'override delle azioni di convalida predefinite per determinati parametri di query denominati nelle richieste. Se il parametro viene specificato nello schema dell'API, questo valore esegue l'override della configurazione specified-parameter-action di livello superiore. Se il parametro non viene specificato nello schema dell'API, questo valore esegue l'override della configurazione unspecified-parameter-action di livello superiore. No
path Aggiungere questo elemento e uno o più sotto-elementi parameter per eseguire l'override delle azioni di convalida predefinite per determinati parametri del percorso URL nelle richieste. Se il parametro viene specificato nello schema dell'API, questo valore esegue l'override della configurazione specified-parameter-action di livello superiore. Se il parametro non viene specificato nello schema dell'API, questo valore esegue l'override della configurazione unspecified-parameter-action di livello superiore. No

Azioni

I criteri di convalida del contenuto includono uno o più attributi che specificano un'azione eseguita da API Management quando si convalida un'entità in una richiesta API o una risposta rispetto allo schema API.

  • È possibile specificare un'azione per gli elementi rappresentati nello schema API e, a seconda dei criteri, per gli elementi che non sono rappresentati nello schema API.

  • Un'azione specificata nell'elemento figlio di un criterio esegue l'override di un'azione specificata per il relativo elemento padre.

Azioni disponibili:

Azione Descrizione
ignore Ignora convalida.
previeni Bloccare l'elaborazione della richiesta o della risposta, registrare l'errore di convalida dettagliato e restituire un errore. L'elaborazione viene interrotta quando viene rilevato il primo set di errori.
rilevare Errori di convalida del log, senza interrompere l'elaborazione della richiesta o della risposta.

Utilizzo

Note sull'utilizzo

  • Questo criterio può essere usato una sola volta in una sezione di criteri.

Registri

I dettagli sugli errori di convalida durante l'esecuzione dei criteri vengono registrati nella variabile context.Variables specificata nell'attributo errors-variable-name nell'elemento radice del criterio. Se configurato in un'azione prevent, un errore di convalida blocca ulteriormente l'elaborazione della richiesta o della risposta e viene propagato anche alla proprietà context.LastError.

Per analizzare gli errori, usare un criterio di traccia per registrare gli errori dalle variabili di contesto in Application Insights.

Implicazioni per le prestazioni

L'aggiunta di un criterio di convalida può influire sulla velocità effettiva dell'API. Sono comunque validi i principi generali seguenti:

  • Quanto maggiore sarà la dimensione dello schema dell'API, tanto minore sarà la velocità effettiva.
  • Quanto maggiore sarà il payload in una richiesta o una risposta, tanto minore sarà la velocità effettiva.
  • Le dimensioni dello schema dell'API hanno un impatto maggiore sulle prestazioni rispetto alle dimensioni del payload.
  • La convalida in base a uno schema API di dimensioni di vari megabyte può causare timeout della richiesta o della risposta in alcune condizioni. L'effetto è più pronunciato nei livelli Consumo e Sviluppatore del servizio.

È consigliabile eseguire test di carico con i carichi di lavoro di produzione previsti per valutare l'impatto dei criteri di convalida sulla velocità effettiva dell'API.

Esempio

In questo esempio tutti i parametri di query e percorso sono convalidati nella modalità di prevenzione e nelle intestazioni nella modalità di rilevamento. La convalida viene sottoposta a override per diversi parametri di intestazione:

<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="prevent" errors-variable-name="requestParametersValidation"> 
    <headers specified-parameter-action="detect" unspecified-parameter-action="detect">
        <parameter name="Authorization" action="prevent" />
        <parameter name="User-Agent" action="ignore" />
        <parameter name="Host" action="ignore" />
        <parameter name="Referrer" action="ignore" />
    </headers>   
</validate-parameters>

Errori di convalida

API Management genera errori di convalida del contenuto nel formato seguente:

{
 "Name": string,
 "Type": string,
 "ValidationRule": string,
 "Details": string,
 "Action": string
}

Nella tabella seguente sono elencati tutti i possibili errori dei criteri di convalida.

  • Dettagli: può essere usato per analizzare gli errori. Non è destinato a essere condiviso pubblicamente.
  • Risposta pubblica: errore restituito al client. Non perde i dettagli di implementazione.

Quando un criterio di convalida specifica l'azione prevent e genera un errore, la risposta da API Management include un codice di stato HTTP: 400 quando il criterio viene applicato nella sezione in ingresso e 502 quando il criterio viene applicato nella sezione in uscita.

Nome Type Regola di convalida Dettagli Risposta pubblica Azione
validate-content
RequestBody SizeLimit Il corpo della richiesta ha una lunghezza di {size} byte e supera il limite configurato di {maxSize} byte. Il corpo della richiesta è di {size} byte e supera il limite di {maxSize} byte. detect/prevent
ResponseBody SizeLimit Il corpo della risposta ha una lunghezza di {size} byte e supera il limite configurato di {maxSize} byte. Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
{messageContentType} RequestBody Non specificato Il tipo di contenuto {messageContentType} non specificato non è consentito. Il tipo di contenuto {messageContentType} non specificato non è consentito. detect/prevent
{messageContentType} ResponseBody Non specificato Il tipo di contenuto {messageContentType} non specificato non è consentito. Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
ApiSchema Lo schema dell'API non esiste o non è stato possibile risolverlo. Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
ApiSchema Lo schema dell'API non specifica le definizioni. Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
{messageContentType} RequestBody/ResponseBody MissingDefinition Lo schema dell'API non contiene la definizione {definitionName}, la quale è associata al tipo di contenuto {messageContentType}. Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
{messageContentType} RequestBody IncorrectMessage Il corpo della richiesta non è conforme alla definizione {definitionName}, la quale è associata al tipo di contenuto {messageContentType}.

Riga {valError.Message}: {valError.LineNumber}, Posizione: {valError.LinePosition}		 Il corpo della richiesta non è conforme alla definizione {definitionName}, la quale è associata al tipo di contenuto {messageContentType}.

Riga {valError.Message}: {valError.LineNumber}, Posizione: {valError.LinePosition}		 detect/prevent
{messageContentType} ResponseBody IncorrectMessage Il corpo della risposta non è conforme alla definizione {definitionName}, la quale è associata al tipo di contenuto {messageContentType}.

Riga {valError.Message}: {valError.LineNumber}, Posizione: {valError.LinePosition}		 Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
RequestBody Validationexception Non è possibile convalidare il corpo della richiesta per il tipo di contenuto {messageContentType}.

{exception details}		 Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
ResponseBody Validationexception Non è possibile convalidare il corpo della risposta per il tipo di contenuto {messageContentType}.

{exception details}		 Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
validate-parameters / validate-headers
{paramName} / {headerName} QueryParameter/PathParameter/RequestHeader Non specificato {parametro percorso/parametro query/intestazione} {paramName} non specificato non è consentito. {parametro percorso/parametro query/intestazione} {paramName} non specificato non è consentito. detect/prevent
{headerName} ResponseHeader Non specificato L'intestazione {headerName} non specificata non è consentita. Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
ApiSchema Lo schema dell'API non esiste o non è stato possibile risolverlo. Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
ApiSchema Lo schema dell'API non specifica le definizioni. Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
{paramName} QueryParameter / PathParameter / RequestHeader / ResponseHeader MissingDefinition Lo schema dell'API non contiene la definizione {definitionName}, la quale è associata al {parametro query/parametro percorso/intestazione} {paramName}. Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage La richiesta non può contenere valori multipli per {parametro query/parametro percorso/intestazione} {paramName}. La richiesta non può contenere valori multipli per {parametro query/parametro percorso/intestazione} {paramName}. detect/prevent
{headerName} ResponseHeader IncorrectMessage La risposta non può contenere valori multipli per l'intestazione {headerName}. Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage Il valore di {parametro query/ parametro percorso/intestazione} {paramName} non è conforme alla definizione.

Riga {valError.Message}: {valError.LineNumber}, Posizione: {valError.LinePosition}		 Il valore di {parametro query/parametro percorso/intestazione} {paramName} non è conforme alla definizione.

Riga {valError.Message}: {valError.LineNumber}, Posizione: {valError.LinePosition}		 detect/prevent
{headerName} ResponseHeader IncorrectMessage Il valore dell'intestazione {headerName} non è conforme alla definizione.

Riga {valError.Message}: {valError.LineNumber}, Posizione: {valError.LinePosition}		 Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage Non è possibile analizzare il valore di {parametro query/parametro percorso/intestazione} {paramName} in base alla definizione.

{ex.Message}		 Non è stato possibile analizzare il valore di {parametro query/parametro percorso/intestazione} {paramName} in base alla definizione.

{ex.Message}		 detect/prevent
{headerName} ResponseHeader IncorrectMessage Non è stato possibile analizzare il valore dell'intestazione {headerName} in base alla definizione. Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
{paramName} QueryParameter/PathParameter/RequestHeader ValidationError Non è stato possibile convalidare {Parametro query/Parametro percorso/Intestazione} {paramName}.

{exception details}		 Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
{headerName} ResponseHeader ValidationError Non è stato possibile convalidare l'intestazione {headerName}.

{exception details}		 Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
validate-status-code
{status-code} StatusCode Non specificato Il codice di stato della risposta {status-code} non è consentito. Non è stato possibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent

Nella tabella seguente sono elencati tutti i possibili valori Motivo di un errore di convalida insieme ai possibili valori Messaggio:

Motivo Message
Richiesta non valida {Details} per la variabile di contesto, {Public response} per il client
Risposta non consentita {Details} per la variabile di contesto, {Public response} per il client

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere: