Convalida contenuto

Articolo
08/30/2024

SI APPLICA A: Tutti i livelli di Gestione API

Il criterio validate-content convalida le dimensioni o il contenuto di una richiesta o del corpo della risposta rispetto a uno o più schemi supportati.

La tabella seguente illustra i formati di schema e i tipi di contenuto di richiesta o risposta supportati dal criterio. I valori del tipo di contenuto non fanno distinzione tra maiuscole e minuscole.

Formato	Tipi di contenuto
JSON	Esempi: `application/json` `application/hal+json`
XML	Esempio: `application/xml`
SOAP	Valori consentiti: `application/soap+xml` per le API SOAP 1.2 `text/xml` per le API SOAP 1.1

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.

Quale contenuto viene convalidato

Il criterio convalida il seguente contenuto nella richiesta o nella risposta rispetto allo schema:

Presenza di tutte le proprietà obbligatorie.
Presenza o assenza di proprietà aggiuntive, se lo schema ha il campo additionalProperties impostato. Può essere sottoposto a override con l'attributo allow-additional-properties.
Tipi di tutte le proprietà. Ad esempio, se uno schema specifica una proprietà come numero intero, la richiesta (o la risposta) deve includere un numero intero e non un altro tipo, come ad esempio una stringa.
Il formato delle proprietà, se specificato nello schema, viene definito utilizzando diverse modalità, come ad esempio l'utilizzo di espressioni regolari (se viene specificata la parola chiave pattern), minimum per i numeri interi, e così via.

Suggerimento

Per esempi di vincoli di pattern regex che possono essere usati negli schemi, vedere Repository regex di convalida OWASP.

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-content unspecified-content-type-action="ignore | prevent | detect" max-size="size in bytes" size-exceeded-action="ignore | prevent | detect" errors-variable-name="variable name">
    <content-type-map any-content-type-value="content type string" missing-content-type-value="content type string">
        <type from | when="content type string" to="content type string" />
    </content-type-map>
    <content type="content type string" validate-as="json | xml | soap" schema-id="schema id" schema-ref="#/local/reference/path" action="ignore | prevent | detect" allow-additional-properties="true | false" case-insensitive-property-names="true | false"/>
</validate-content>

Attributi

Attributo	Descrizione	Richiesto	Valore predefinito
unspecified-content-type-action	Azione da eseguire per le richieste o le risposte con un tipo di contenuto non specificato nello schema dell'API. Le espressioni di criteri sono consentite.	Sì	N/D
max_size	Lunghezza massima del corpo della richiesta o della risposta in byte, verificata rispetto all'intestazione `Content-Length`. Se il corpo della richiesta o il corpo della risposta è compresso, questo valore è la lunghezza decompressa. Valore massimo consentito: 4 MB. Le espressioni di criteri sono consentite.	Sì	N/D
size-exceeded-action	Azione da eseguire per le richieste o le risposte il cui corpo supera le dimensioni specificate in `max-size`. 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
content-type-map	Aggiungere questo elemento per eseguire il mapping del tipo di contenuto della richiesta o della risposta in ingresso a un altro tipo di contenuto usato per attivare la convalida.	No
content	Aggiungere uno o più di questi elementi per convalidare il tipo di contenuto nella richiesta o nella risposta o nel tipo di contenuto mappato ed eseguire l'azione specificata.	No

Attributi content-type-map

Attributo	Descrizione	Richiesto	Valore predefinito
Valore any-content-type	Tipo di contenuto utilizzato per la convalida del corpo di una richiesta o di una risposta, indipendentemente dal tipo di contenuto in ingresso. Le espressioni di criteri non sono consentite.	No	N/D
missing-content-type-value	Tipo di contenuto utilizzato per la convalida del corpo di una richiesta o di una risposta, quando il tipo di contenuto in ingresso è mancante o vuoto. Le espressioni di criteri non sono consentite.	No	N/D

content-type-map-elements

Nome	Descrizione	Richiesto
type	Aggiungere uno o più di questi elementi per eseguire il mapping di un tipo di contenuto in ingresso a un tipo di contenuto usato per la convalida del corpo di una richiesta o di una risposta. Utilizzare `from` per specificare un tipo di contenuto in ingresso noto o `when` con un'espressione di criteri per specificare qualsiasi tipo di contenuto in ingresso corrispondente a una condizione. Esegue l'override del mapping in `any-content-type-value` e `missing-content-type-value`, se specificato.	No

Attributi del contenuto

Attributo	Descrizione	Richiesto	Valore predefinito
type	Tipo di contenuto per cui eseguire la convalida del corpo, verificato in base all'intestazione del tipo di contenuto o al valore mappato in `content-type-mapping`, se specificato. Se vuoto, si applica a ogni tipo di contenuto specificato nello schema dell'API. Per convalidare le richieste e le risposte SOAP ( attributo `validate-as` impostato su "soap"), impostare `type` su `application/soap+xml` per le API SOAP 1.2 o `text/xml` per le API SOAP 1.1.	No	N/D
validate-as	Motore di convalida da usare per la convalida del corpo di una richiesta o di una risposta con un `type`corrispondente. Valori supportati: "json", "xml", "soap". Quando si specifica "soap", il codice XML dalla richiesta o dalla risposta viene estratto dalla SOAP envelope e convalidato in base a uno schema XML.	Sì	N/D
schema-id	Nome di uno schema esistente aggiunto all'istanza di API Management per la convalida del contenuto. Se non specificato, viene usato lo schema predefinito dalla definizione dell'API.	No	N/D
schema-ref	Per uno schema JSON specificato in `schema-id`, riferimento facoltativo a un percorso di riferimento locale valido nel documento JSON. Esempio: `#/components/schemas/address`. L'attributo deve restituire un oggetto JSON gestito da API Management come schema JSON valido. Per uno schema XML, `schema-ref` non è supportato e qualsiasi elemento dello schema di primo livello può essere usato come radice del payload della richiesta o della risposta XML. La convalida verifica che tutti gli elementi a partire dalla radice del payload della richiesta o della risposta XML siano conformi allo schema XML fornito.	No	N/D
allow-additional-properties	Booleano. Per uno schema JSON, specifica se implementare un override di runtime del valore `additionalProperties` configurato nello schema: - `true`: consente proprietà aggiuntive nel corpo della richiesta o della risposta, anche se il campo `additionalProperties` dello schema JSON è configurato per non consentire proprietà aggiuntive. - `false`: non consentire proprietà aggiuntive nel corpo della richiesta o della risposta, anche se il campo `additionalProperties` dello schema JSON è configurato per consentire proprietà aggiuntive. Se l'attributo non viene specificato, il criterio convalida proprietà aggiuntive in base alla configurazione del campo `additionalProperties` nello schema.	No	N/D
case-insensitive-property-names	Valorebooleano. Per uno schema JSON, specifica se confrontare i nomi delle proprietà degli oggetti JSON senza considerare la distinzione tra maiuscole e minuscole. - `true`: confrontare i nomi delle proprietà senza distinzione tra maiuscole e minuscole. - `false`: confrontare i nomi delle proprietà con distinzione tra maiuscole e minuscole.	No	false

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

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

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.

Schemi per la convalida del contenuto

Per impostazione predefinita, la convalida del contenuto della richiesta o della risposta usa schemi JSON o XML dalla definizione dell'API. Questi schemi possono essere specificati manualmente o generati automaticamente durante l'importazione di un'API da una specifica OpenAPI o WSDL in API Management.

Usando il criterio validate-content, è possibile convalidare facoltativamente in base a uno o più SCHEMI JSON o XML aggiunti all'istanza di API Management e che non fanno parte della definizione API. Uno schema aggiunto a API Management può essere riutilizzato in molte API.

Per aggiungere uno schema all'istanza di API Management usando il portale di Azure:

Nel portale, andare all'istanza di API Management.
Nella sezione API del menu a sinistra selezionare Schemi>+ Aggiungi.
Nella finestra Crea schema seguire questa procedura:
1. Immettere un Nome (ID) per lo schema.
2. In Tipo di schemaselezionare JSON o XML.
3. Compilare il campo Descrizione.
4. In Metodo di creazione eseguire una delle operazioni seguenti:
  - Selezionare Crea nuovo e immettere o incollare lo schema.
  - Selezionare Importa dal file o Importa da URL e immettere un percorso dello schema.
    
    Nota
    
    Per importare uno schema da URL, lo schema deve essere accessibile tramite Internet dal browser.
5. Seleziona Salva.

API Management aggiunge la risorsa dello schema all'URI /schemas/<schemaId>relativo e lo schema viene visualizzato nell'elenco nella pagina Schemi. Selezionare uno schema per visualizzarne le proprietà o per modificarle in un editor di schemi.

Nota

Uno schema può fare riferimento a un altro schema aggiunto all'istanza di API Management. Ad esempio, includere un XML Schema aggiunto a API Management usando un elemento simile al seguente:

<xs:include schemaLocation="/schemas/myschema" />

Suggerimento

Gli strumenti open source per risolvere i riferimenti allo schema WSDL e XSD e agli schemi generati in batch in API Management sono disponibili in GitHub.

Esempi

Convalida dello schema JSON

Nell'esempio seguente API Management interpreta le richieste con un'intestazione o una richiesta di tipo di contenuto vuoto con un'intestazione del tipo di contenuto application/hal+json come richieste con il tipo di contenuto application/json. API Management esegue quindi la convalida in modalità di rilevamento rispetto a uno schema definito per il tipo di contenuto application/json nella definizione API. I messaggi con payload maggiori di 100 KB vengono bloccati. Le richieste contenenti proprietà aggiuntive vengono bloccate, anche se il campo additionalProperties dello schema è configurato per consentire proprietà aggiuntive.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map missing-content-type-value="application/json">
        <type from="application/hal+json" to="application/json" />
    </content-type-map>
    <content type="application/json" validate-as="json" action="detect" allow-additional-properties="false" />
</validate-content>

Convalida dello schema SOAP

Nell'esempio seguente API Management interpreta qualsiasi richiesta come richiesta con il tipo di contenuto application/soap+xml (il tipo di contenuto usato dalle API SOAP 1.2), indipendentemente dal tipo di contenuto in ingresso. La richiesta potrebbe arrivare con un'intestazione del tipo di contenuto vuota, un'intestazione del tipo di contenuto text/xml (usata dalle API SOAP 1.1) o un'altra intestazione del tipo di contenuto. API Management estrae quindi il payload XML dalla SOAP envelope ed esegue la convalida in modalità di prevenzione rispetto allo schema denominato "myschema". I messaggi con payload maggiori di 100 KB vengono bloccati.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map any-content-type-value="application/soap+xml" />
    <content type="application/soap+xml" validate-as="soap" schema-id="myschema" action="prevent" /> 
</validate-content>

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

Convalida del contenuto

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

Condividi tramite

Convalida contenuto

Quale contenuto viene convalidato

Istruzione del criterio

Attributi

Elementi

Attributi content-type-map

content-type-map-elements

Attributi del contenuto

Azioni

Utilizzo

Registri

Implicazioni per le prestazioni

Schemi per la convalida del contenuto

Esempi

Convalida dello schema JSON

Convalida dello schema SOAP

Errori di convalida

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Convalida contenuto

Quale contenuto viene convalidato

Istruzione del criterio

Attributi

Elementi

Attributi content-type-map

content-type-map-elements

Attributi del contenuto

Azioni

Utilizzo

Registri

Implicazioni per le prestazioni

Schemi per la convalida del contenuto

Esempi

Convalida dello schema JSON

Convalida dello schema SOAP

Errori di convalida

Criteri correlati

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive