Convalidare il contenuto
SI APPLICA A: Tutti i livelli di Gestione API
Il validate-content criterio 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/jsonapplication/hal+json |
| XML | Esempio: application/xml |
| SOAP | Valori consentiti: application/soap+xml per le API SOAP 1.2text/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 il supporto tecnico.
Contenuto 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
additionalPropertiescampo impostato. Può essere sottoposto a override con l'attributoallow-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.
- Formato delle proprietà, se specificato nello schema, ad esempio regex (se la
patternparola chiave è specificata),minimumper 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 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-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" />
</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: 102.400 byte (100 KB). (Se è necessario aumentare questo limite, contattare il supporto tecnico.) 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 per 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 |
|---|---|---|---|
| any-content-type-value | 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 usare 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 ( validate-as attributo impostato su "soap"), impostato su typeapplication/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 oggetto corrispondente type. 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 Gestione API 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 che Gestione API handle 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 additionalProperties valore configurato nello schema: - true: consente proprietà aggiuntive nel corpo della richiesta o della risposta, anche se il campo dello additionalProperties schema JSON è configurato per non consentire proprietà aggiuntive. - false: non consentono proprietà aggiuntive nel corpo della richiesta o della risposta, anche se il campo dello additionalProperties schema JSON è configurato per consentire proprietà aggiuntive.Se l'attributo non viene specificato, il criterio convalida proprietà aggiuntive in base alla configurazione del additionalProperties campo nello schema. |
No | N/D |
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
- Sezioni del criterio: inbound, outbound, on-error
- Ambiti del criterio: globale, area di lavoro, prodotto, API, operazione
- Gateway: classico, v2, consumo, self-hosted
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.
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 Gestione API.
Usando i validate-content criteri, è possibile convalidare facoltativamente in base a uno o più schemi JSON o XML aggiunti all'istanza di Gestione API e che non fanno parte della definizione dell'API. Uno schema aggiunto a Gestione API può essere riutilizzato in molte API.
Per aggiungere uno schema all'istanza di Gestione API usando il portale di Azure:
Nel portale, passare all'istanza di Gestione API.
Nella sezione API del menu a sinistra selezionare Schemi>+ Aggiungi.
Nella finestra Crea schema eseguire le operazioni seguenti:
- Immettere un nome (ID) per lo schema.
- In Tipo di schema selezionare JSON o XML.
- Compilare il campo Descrizione.
- In Create method (Metodo Create) eseguire una delle operazioni seguenti:
- Selezionare Crea nuovo e immettere o incollare lo schema.
- Selezionare Import from file (Importa da file ) o Import from URL (Importa da URL ) e immettere un percorso dello schema.
Nota
Per importare uno schema dall'URL, lo schema deve essere accessibile tramite Internet dal browser.
- Seleziona Salva.
Gestione API 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 incrociato a un altro schema aggiunto all'istanza di Gestione API. Ad esempio, includere un XML Schema aggiunto a Gestione API 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 per Gestione API sono disponibili in GitHub.
Esempi
Convalida dello schema JSON
Nell'esempio seguente Gestione API interpreta le richieste con un'intestazione del tipo di contenuto vuoto o le richieste con un'intestazione application/hal+json del tipo di contenuto come richieste con il tipo di application/jsoncontenuto . Quindi, Gestione API esegue la convalida in modalità di rilevamento rispetto a uno schema definito per il application/json tipo di contenuto nella definizione DELL'API. I messaggi con payload maggiori di 100 KB vengono bloccati. Le richieste contenenti proprietà aggiuntive vengono bloccate, anche se il campo dello additionalProperties 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 Gestione API interpreta qualsiasi richiesta come richiesta con il tipo di application/soap+xml contenuto (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 di text/xml (usata dalle API SOAP 1.1) o un'altra intestazione del tipo di contenuto. Quindi, Gestione API estrae 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
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 |
Criteri correlati
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 con Microsoft Copilot per Azure