Convalida contenuto

  • Articolo

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 typecorrispondente. 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

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:

  1. Nel portale, andare all'istanza di API Management.

  2. Nella sezione API del menu a sinistra selezionare Schemi>+ Aggiungi.

  3. 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.

    Creare uno schema

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

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere: