Norme di OASValidation

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Informazioni sulle norme di OASValidation

Il criterio OASValidation (OpenAPI Specification Validation) consente di convalidare una richiesta o un messaggio di risposta in arrivo in base a una specifica OpenAPI 3.0 (JSON o YAML). Consulta la sezione Quali contenuti vengono convalidati?

Il criterio OASValidation specifica il nome della specifica OpenAPI da utilizzare per la convalida quando viene eseguito il passaggio a cui è collegato il criterio. La specifica OpenAPI viene archiviata come risorsa nella seguente posizione standard all'interno del bundle proxy API: apiproxy/resources/oas. La specifica OpenAPI deve avere un'estensione .json, .yml, .yaml.

Aggiungi una specifica OpenAPI come risorsa a un bundle proxy API utilizzando l'interfaccia utente o l'API, come descritto in Gestire le risorse.

Quali contenuti vengono convalidati?

La seguente tabella riassume i contenuti dei messaggi della richiesta convalidati dalle norme di OASValidation, per componente.

Componenti Richiedi convalida
Percorso di base Convalida il percorso base definito dal proxy API. ignora il percorso base specificato nella specifica OpenAPI.
Percorso Verifica che il percorso di richiesta (meno il percorso base) corrisponda a uno dei pattern di percorso definiti nella specifica OpenAPI.
Verbo Verifica che il verbo sia definito per il percorso nella specifica OpenAPI.
Corpo del messaggio di richiesta
  • Convalida l'esistenza del corpo del messaggio nella richiesta, se necessario.
  • Facoltativamente, convalida il corpo del messaggio in base allo schema del corpo della richiesta dell'operazione nella specifica OpenAPI. Configura questa opzione utilizzando <ValidateMessageBody>

Nota: il criterio consente di convalidare il corpo di un messaggio di richiesta in base alla specifica OpenAPI solo se Content-Type è impostato su application/json. Se il tipo di contenuti non è impostato su application/json, la convalida del corpo del messaggio di richiesta verrà superata automaticamente (senza convalidare effettivamente i contenuti).

Parametri
  • Verifica che i parametri obbligatori siano presenti nella richiesta, inclusi percorso, intestazione, query e parametri dei cookie.
  • Verifica che i valori dei parametri corrispondano a quelli definiti nella specifica OpenAPI.
  • Facoltativamente, convalida se nella richiesta esistono parametri che non sono definiti nella specifica OpenAPI. Configura questa opzione utilizzando <AllowUnspecifiedParameters>

La seguente tabella riassume i contenuti dei messaggi di risposta convalidati dal criterio OASValidation, suddivisi per componente.

Componenti Convalida della risposta
Percorso Verifica che il percorso di richiesta (meno il percorso base) corrisponda a uno dei pattern di percorso definiti nella specifica OpenAPI.
Verbo Verifica che il verbo sia definito per il percorso nella specifica OpenAPI.
Corpo del messaggio di risposta
  • Convalida l'esistenza del corpo del messaggio nella risposta, se necessario.
  • Verifica che le intestazioni della risposta nella specifica OpenAPI siano presenti nel messaggio di risposta e che il valore della risposta corrispondenti allo schema.
  • Facoltativamente, convalida il corpo del messaggio in base allo schema del corpo della risposta dell'operazione nella specifica OpenAPI. Configura questa opzione utilizzando <ValidateMessageBody>

Esempi

I seguenti esempi mostrano alcuni modi in cui puoi utilizzare OASValidation per convalidare i messaggi in base a una specifica OpenAPI 3.0.

Convalida messaggio di richiesta

Nell'esempio seguente, il criterio myoaspolicy convalida il corpo del messaggio di richiesta in base al schema del corpo del messaggio di richiesta dell'operazione definito nella specifica OpenAPI my-spec.json. 

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.json</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
   <Source>request</Source>
</OASValidation>

Se il corpo del messaggio non è conforme alla specifica OpenAPI, viene restituito un errore policies.oasvalidation.Failed.

Convalida dei parametri

L'esempio seguente configura il criterio in modo che non vada a buon fine se nella richiesta vengono specificati parametri di intestazione, query o cookie che non sono definita nella specifica OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<OASValidation> elemento

Definisce il criterio di convalida delle specifiche OpenAPI.

Valore predefinito Consulta la scheda Criterio predefinito di seguito
Obbligatorio? Obbligatorio
Tipo Oggetto complesso
Elemento principale n/d
Elementi secondari <DisplayName>
<OASResource>
<Source>
<Options>
<Source>

Sintassi

L'elemento <OASValidation> utilizza la seguente sintassi:

<OASValidation
  continueOnError="[true|false]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All OASValidation child elements are optional except OASResource -->
    <DisplayName>policy_display_name</DisplayName>
    <OASResource>validation_JSON_or_YAML</OASResource>
    <Options>
        <ValidateMessageBody>[true|false]</ValidateMessageBody>
        <AllowUnspecifiedParameters>
            <Header>[true|false]</Header>
            <Query>[true|false]</Query>
            <Cookie>[true|false]</Cookie>
        </AllowUnspecifiedParameters>
    </Options>
    <Source>message_to_validate</Source>
</OASValidation>

Criterio predefinito

L'esempio seguente mostra le impostazioni predefinite quando aggiungi un criterio di convalida OAS al tuo flusso nella UI di Apigee:

<OASValidation continueOnError="false" enabled="true" name="OpenAPI-Spec-Validation-1">
    <DisplayName>OpenAPI Spec Validation-1</DisplayName>
    <Properties/>
    <Source>request</Source>
    <OASResource>oas://OpenAPI-Spec-Validation-1.yaml</OASResource>
</OASValidation>

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo Predefinita Obbligatorio? Description (Descrizione)
name N/A Obbligatorio

Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può contenere più di 255 caratteri.

Facoltativamente, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor del proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError false Facoltativo Imposta su "false" per restituire un errore quando un criterio non va a buon fine. Si tratta di un comportamento previsto per la maggior parte dei criteri. Impostalo su "true" per far sì che l'esecuzione del flusso continui anche dopo l'esito negativo di un criterio.
enabled true Facoltativo Imposta su "true" per applicare il criterio. Imposta su "false" per "disattivare" il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.
async   false Deprecazione Questo attributo è obsoleto.

Riferimento elemento secondario

In questa sezione vengono descritti gli elementi secondari di <OASValidation>.

<DisplayName>

Da utilizzare in aggiunta all'attributo name per etichettare il criterio in editor proxy UI di gestione con un nome diverso e più naturale.

L'elemento <DisplayName> è comune a tutti i criteri.

Valore predefinito n/d
Obbligatorio? (Facoltativo) Se ometti <DisplayName>, il valore del valore viene utilizzato l'attributo name del criterio
Tipo Stringa
Elemento principale &lt;PolicyElement&gt;
Elementi secondari Nessuno

L'elemento <DisplayName> utilizza la seguente sintassi:

Sintassi

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

Esempio

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

L'elemento <DisplayName> non ha attributi o elementi secondari.

<OASResource>

Specifica la specifica OpenAPI in base alla quale eseguire la convalida. Puoi archiviare questo file:

  • Nell'ambito del proxy API in /apiproxy/resources/oas nel bundle di proxy API
  • Nella sezione Resources della visualizzazione Navigatore dell'editor del proxy API.

Per saperne di più, consulta Gestire le risorse.

Puoi specificare la specifica OpenAPI utilizzando un modello di messaggio, ad esempio {oas.resource.url}. In questo caso, verrà valutato il valore della variabile di flusso oas.resource.url (tra parentesi graffe) e sostituito nella stringa del payload in fase di runtime. Per ulteriori informazioni, vedi Modelli di messaggio.

Valore predefinito Nessuno
Obbligatorio? Obbligatorio
Tipo Stringa
Elemento principale <OASValidation>
Elementi secondari Nessuno

Sintassi

L'elemento <OASResource> utilizza la seguente sintassi:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   ...
</OASValidation>

Esempio

L'esempio seguente fa riferimento alla specifica my-spec.yaml archiviata in /apiproxy/resources/oas nel bundle proxy API:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
</OASValidation>

L'elemento <OASResource> non ha attributi o elementi secondari.

&lt;Options&gt;

Configura le opzioni per il criterio.

Valore predefinito n/d
Obbligatorio? Facoltativo
Tipo Tipo complesso
Elemento principale <OASValidation>
Elementi secondari <ValidateMessageBody>
<AllowUnspecifiedParameters>

Sintassi

L'elemento <Options> utilizza la seguente sintassi:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <ValidateMessageBody>[true|false]</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Esempio

L'esempio seguente configura le opzioni per il criterio. Ciascuna opzione è descritta in maggiore dettaglio di seguito.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>false</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

&lt;ValidateMessageBody&gt;

Consente di specificare se il criterio deve convalidare il corpo del messaggio in base allo schema del corpo della richiesta dell'operazione nella specifica OpenAPI. Impostalo su true per convalidare il valore i contenuti del corpo del messaggio. Impostalo su false per confermare solo l'esistenza del corpo del messaggio.

Puoi controllare se l'esecuzione del flusso continua dopo un errore di convalida impostando l'attributo continueOnError per <OASValidation> su true.

Valore predefinito falso
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <Options>
Elementi secondari Nessuno

Sintassi

L'elemento <ValidateMessageBody> utilizza la seguente sintassi:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
         <ValidateMessageBody>[true|false]</ValidateMessageBody>
   </Options>
   ...
</OASValidation>

Esempio

L'esempio seguente abilita la convalida dei contenuti del corpo del messaggio:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
</OASValidation>

<AllowUnspecifiedParameters>

Configura il comportamento del criterio se sono presenti parametri di intestazione, query o cookie presenti nella richiesta che non sono definite nella specifica OpenAPI.

Valore predefinito n/d
Obbligatorio? Facoltativo
Tipo Tipo complesso
Elemento principale <Options>
Elementi secondari <Header>
<Query>
<Cookie>

Sintassi

L'elemento <AllowUnspecifiedParameters> utilizza la seguente sintassi:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Esempio

L'esempio seguente configura il criterio in modo che non vada a buon fine se nella richiesta vengono specificati parametri di intestazione, query o cookie che non sono definita nella specifica OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

Consente di configurare il comportamento del criterio in presenza di parametri di intestazione presenti nella richiesta che non sono definite nella specifica OpenAPI.

Per consentire di specificare nella richiesta parametri di intestazione che non sono definiti nella specifica OpenAPI, imposta questo parametro su true. In caso contrario, imposta questo parametro su false per impedire che l'esecuzione del criterio non vada a buon fine.

Valore predefinito true
Obbligatorio? Booleano
Tipo Tipo complesso
Elemento principale <AllowUnspecifiedParameters>
Elementi secondari Nessuno

Sintassi

L'elemento <Header> utilizza la seguente sintassi:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Esempio

L'esempio seguente configura il criterio in modo che non vada a buon fine se nella richiesta viene specificato un parametro di intestazione che non è definita nella specifica OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Query> (figlio di <AllowUnspecifiedParameters>)

Configura il comportamento del criterio in caso di parametri di ricerca presenti nella richiesta che non sono definite nella specifica OpenAPI.

Per consentire di specificare nella richiesta parametri di ricerca che non sono definiti nella specifica OpenAPI, imposta questo parametro su true. In caso contrario, imposta questo parametro su false per impedire che l'esecuzione del criterio non vada a buon fine.

Valore predefinito true
Obbligatorio? Booleano
Tipo Tipo complesso
Elemento principale <AllowUnspecifiedParameters>
Elementi secondari Nessuno

Sintassi

L'elemento <Query> utilizza la seguente sintassi:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Esempio

L'esempio seguente configura il criterio in modo che non vada a buon fine se nella richiesta viene specificato un parametro di query che non è definita nella specifica OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>false</Query>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

Configura il comportamento delle norme in caso di parametri dei cookie presenti nella richiesta che non sono definite nella specifica OpenAPI.

Per consentire di specificare nella richiesta parametri dei cookie che non sono definiti nella specifica OpenAPI, imposta questo parametro su true. In caso contrario, imposta questo parametro su false per impedire che l'esecuzione del criterio non vada a buon fine.

Valore predefinito true
Obbligatorio? Booleano
Tipo Tipo complesso
Elemento principale <AllowUnspecifiedParameters>
Elementi secondari Nessuno

Sintassi

L'elemento <Cookie> utilizza la seguente sintassi:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Esempio

L'esempio seguente configura il criterio in modo che non vada a buon fine se nella richiesta viene specificato un parametro di query che non è definita nella specifica OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Source>

Messaggio JSON da valutare rispetto agli attacchi di payload JSON. Il valore generalmente impostato è request, poiché in genere occorre valutare le richieste in entrata provenienti dalle app client. Impostalo su response per valutare i messaggi di risposta. Imposta su message per valutare automaticamente il messaggio di richiesta quando il criterio è collegato al flusso di richiesta e il messaggio di risposta quando il criterio è collegato alla risposta flusso di lavoro.

Valore predefinito richiesta
Obbligatorio? Facoltativo
Tipo Stringa
Elemento principale <Source>
Elementi secondari Nessuno

Sintassi

L'elemento <Source> utilizza la seguente sintassi:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Source>[message|request|response]</Source>
   ...
</OASValidation>

Esempio

L'esempio seguente valuta automaticamente il messaggio di richiesta quando il criterio viene collegato al flusso di richiesta e il messaggio di risposta quando il criterio viene collegato al flusso di risposta:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Source>message</Source>
</OASValidation>

L'elemento <Source> non ha attributi o elementi secondari.

Schemi

Ogni tipo di criterio è definito da uno schema XML (.xsd). Come riferimento, consulta gli schemi dei criteri sono disponibili su GitHub.

Codici di errore

Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Edge quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Codice di errore Stato HTTP Causa
steps.oasvalidation.Failed 500 Il corpo del messaggio della richiesta non può essere convalidato in base alla specifica OpenAPI fornita.
steps.oasvalidation.SourceMessageNotAvailable 500

La variabile specificata nell'elemento <Source> del criterio non rientra nell'ambito o non può essere risolta.
steps.oasvalidation.NotMessageVariable 500

L'elemento <Source> è impostato su una variabile non di tipo message.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Nome errore Causa
ResourceDoesNotExist La specifica OpenAPI a cui viene fatto riferimento nell'elemento <OASResource> non esiste.
ResourceCompileFailed La specifica OpenAPI inclusa nel deployment contiene errori che ne impediscono la compilazione. In genere, ciò indica che la specifica non è una specifica OpenAPI 3.0 ben strutturata.
BadResourceURL Impossibile elaborare la specifica OpenAPI a cui viene fatto riferimento nell'elemento <OASResource>. Questo può accadere se il file non è un file JSON o YAML oppure se l'URL del file non è specificato correttamente.

Variabili di errore

Queste variabili vengono impostate quando questo criterio attiva un errore in fase di runtime. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori dei criteri.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è l'ultima parte del codice di errore. fault.name Matches "ResourceDoesNotExist"
oasvalidation.policy_name.failed policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. oasvalidation.myoaspolicy.failed = true

Funzionalità supportate dalle specifiche OpenAPI

Il criterio OASValidation supporta le funzionalità della specifica OpenAPI riassunte nella seguente tabella, per categoria. Sono elencate anche le funzionalità non supportate.

Categoria Supportato Non supportata
Formati dei tipi di dati booleano
data
data-ora
doppio
email
numero in virgola mobile
int32/int64
ipv4/ipv6
md5
sha1/sha256/sha512
stringa
URI
uri-template
uuid
 binario
byte
password
Oggetto discriminatore mappatura
propertyName 		N/D
Oggetto tipo multimediale schema codifica
esempio
esempi
Oggetto operazioni parametri
requestBody
risposte
sicurezza (supporto parziale) 		callback
obsoleto
Server
Oggetto parametri allowEmptyValue
tra (query, header, path)
obbligatorio
risposte
schema
stile (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited)

Nota: deepObject supporta solo parametri stringa; gli array e gli oggetti nidificati non sono supportati. 		allowReserved
obsoleto
esempio
esempi
contenuti
Oggetto Paths elimina
prendi
testa
opzioni
parametri
patch
pubblica
metti
traccia
variabili 		Server
Oggetto corpo della richiesta application/json
application/hal+json
application/x-www-form-urlcoded (oggetto encoding non supportato)
contenuti
obbligatorio 		applicazione/xml
multiparte/dati-modulo
testo/normale
testo/xml
Oggetto risposta application/json
application/hal+json
application/x-www-form-urlcoded (oggetto encoding non supportato)
contenuti
intestazioni 		applicazione/xml
link
testo/normale
testo/xml
Oggetto Risposte predefinita
Codice di stato HTTP 		N/D
Oggetto schema $ref
aggiuntiveProperties (solo variante con flag booleano)
allOf (ignorato se additionalProperties è false)
anyOf
enum
exclusiveMaximum/exclusiveMinimum
formato
elementi
massimo/minimo
maxItems/minItems
maxLength/minLength
maxProperties/minProperties
multipleOf
non
null
oneOf
motivo
proprietà
obbligatorio
titolo
tipo
uniqueItems 		obsoleto
esempio
readOnly
writeOnly
XML
Oggetto schema di sicurezza in (header, query) (ignorato se type è http)
nome
tipo (apiKey, http) 		bearerFormat
flussi
openIdConnectUrl
schema
Oggetto server url
variabili 		Più definizioni di server

Argomenti correlati