Convalidare i parametri

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Il validate-parameters criterio 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 validate-parameters criterio potrebbe non funzionare. Potrebbe essere necessario reimportare l'API usando la versione 2021-01-01-preview dell'API di gestione o versione 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 il supporto tecnico.

Nota

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

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 headerselemento , queryo path , il valore esegue l'override del 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 headerselemento o query , il valore esegue l'override del 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 per 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ù parameter sottoelementi 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 di livello specified-parameter-action superiore. Se il parametro non viene specificato nello schema dell'API, questo valore esegue l'override della configurazione di livello unspecified-parameter-action superiore. No
query Aggiungere questo elemento e uno o più parameter sottoelementi 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 di livello specified-parameter-action superiore. Se il parametro non viene specificato nello schema dell'API, questo valore esegue l'override della configurazione di livello unspecified-parameter-action superiore. No
path Aggiungere questo elemento e uno o più parameter sottoelementi 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 di livello specified-parameter-action superiore. Se il parametro non viene specificato nello schema dell'API, questo valore esegue l'override della configurazione di livello unspecified-parameter-action superiore. No

Azioni

I criteri di convalida del contenuto includono uno o più attributi che specificano un'azione, che Gestione API accetta 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 dell'API e, a seconda dei criteri, per gli elementi che non sono rappresentati nello schema DELL'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 Ignorare la convalida.
Impedire 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 specificata context.Variables nell'attributo nell'elemento errors-variable-name radice del criterio. Se configurato in un'azione prevent , un errore di convalida blocca ulteriormente l'elaborazione della richiesta o della risposta e viene propagata anche alla context.LastError proprietà .

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

Implicazioni per le prestazioni

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

  • Maggiore sarà la dimensione dello schema DELL'API, minore sarà la velocità effettiva.
  • Maggiore sarà il payload in una richiesta o una risposta, 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 diverse 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 vengono 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

Gestione API 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 deve 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 Gestione API 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 è di 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 è di tipo {size} byte e supera il limite configurato di {maxSize} byte. Impossibile 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. Impossibile 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. Impossibile 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. Impossibile 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}, associata al tipo di contenuto {messageContentType}. Impossibile 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}, associata al tipo di contenuto {messageContentType}.

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

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

Riga {valError.Message}: {valError.LineNumber}, Position: {valError.LinePosition}		 Impossibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
RequestBody Validationexception Il corpo della richiesta non può essere convalidato per il tipo di contenuto {messageContentType}.

{dettagli eccezione}		 Impossibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
ResponseBody Validationexception Il corpo della risposta non può essere convalidato per il tipo di contenuto {messageContentType}.

{dettagli eccezione}		 Impossibile 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 di query/intestazione} {paramName} non è consentito. {parametro percorso/parametro di query/intestazione} {paramName} non è consentito. detect/prevent
{headerName} ResponseHeader Non specificato L'intestazione {headerName} non specificata non è consentita. Impossibile 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. Impossibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
ApiSchema Lo schema API non specifica le definizioni. Impossibile 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}, associata al {parametro di query/parametro/percorso/intestazione} {paramName}. Impossibile 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 più valori per il parametro {query/parametro/intestazione} {paramName}. La richiesta non può contenere più valori per il parametro {query/parametro/intestazione} {paramName}. detect/prevent
{headerName} ResponseHeader IncorrectMessage La risposta non può contenere più valori per l'intestazione {headerName}. Impossibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage Il valore del parametro {query/parametro/intestazione} {paramName} non è conforme alla definizione.

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

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

Riga {valError.Message}: {valError.LineNumber}, Position: {valError.LinePosition}		 Impossibile 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 del {parametro query/parametro percorso/intestazione} {paramName} in base alla definizione.

{ex. Messaggio}		 Non è stato possibile analizzare il valore del {parametro query/parametro path/header} {paramName} in base alla definizione.

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

{dettagli eccezione}		 Impossibile elaborare la richiesta a causa di un errore interno. Contattare il proprietario dell'API. detect/prevent
{headerName} ResponseHeader ValidationError Impossibile convalidare l'intestazione {headerName}.

{dettagli eccezione}		 Impossibile 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. Impossibile 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 Reason di un errore di convalida insieme ai possibili valori message:

Motivo Messaggio
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: