Convalidare i parametri

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.

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

Elementi

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:

Utilizzo

• Sezioni del criterio: inbound
• Ambiti del criterio: globale, area di lavoro, prodotto, API, operazione
• Gateway: classico, v2, consumo, self-hosted, area di lavoro

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.

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

Criteri correlati

• Convalida del contenuto

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere:

• Esercitazione: trasformare e proteggere l'API
• Informazioni di riferimento sui criteri per un elenco completo delle istruzioni dei criteri e delle relative impostazioni
• Espressioni di criteri
• Impostare o modificare criteri
• Riutilizzare le configurazioni dei criteri
• Repository dei frammenti di criteri
• Creare criteri usando Microsoft Copilot in Azure