Convalidare il codice di stato

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Il criterio validate-status-code convalida i codici di stato HTTP nelle risposte rispetto allo schema API. Questo criterio può essere usato per evitare perdite di errori back-end, che possono contenere tracce dello stack.

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.

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-status-code unspecified-status-code-action="ignore | prevent | detect" errors-variable-name="variable name">
    <status-code code="HTTP status code number" action="ignore | prevent | detect" />
</validate-status-code>

Attributi

Attributo Descrizione Richiesto Valore predefinito
unspecified-status-code-action Azione da eseguire per i codici di stato HTTP nelle risposte non specificate nello schema dell'API. 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
status-code Aggiungere uno o più elementi per i codici di stato HTTP per eseguire l'override delle azioni di convalida predefinite per i codici di stato nelle risposte. No

attributi status-code

Attributo Descrizione Richiesto Valore predefinito
codice Codice di stato HTTP per cui eseguire l'override dell'azione di convalida. Sì N/D
action Azione da eseguire per il codice di stato corrispondente, che non è specificato nello schema dell'API. Se il codice di stato viene specificato nello schema dell'API, questa override non ha effetto. Sì N/D

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

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

<validate-status-code unspecified-status-code-action="prevent" errors-variable-name="responseStatusCodeValidation" />

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: