Criterio di convalida OAS

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X.
informazioni

Informazioni sul criterio OASValidation

Il criterio OASValidation (OpenAPI Specification Validation) consente di convalidare una richiesta o un messaggio di risposta in entrata rispetto 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 è associato 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 del messaggio di richiesta convalidati dal criterio OASValidation, per componente.

Componenti Richiedi convalida
Percorso base Convalida il basepath definito dal proxy API; ignora il basepath specificato nella specifica OpenAPI.
Percorso Verifica che il percorso della richiesta (meno il basepath) 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 della richiesta
  • Convalida l'esistenza del corpo del messaggio nella richiesta, se necessario.
  • Facoltativamente, convalida il corpo del messaggio in base allo schema di corpo della richiesta dell'operazione nella specifica OpenAPI. Configura questa opzione utilizzando <ValidateMessageBody>

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

Parametri
  • Verifica la presenza dei parametri obbligatori nella richiesta, tra cui i parametri di percorso, intestazione, query e cookie.
  • Verifica che i valori dei parametri corrispondano a quelli definiti nella specifica OpenAPI.
  • Facoltativamente, convalida l'esistenza nella richiesta di parametri non definiti nella specifica OpenAPI. Configura questa opzione utilizzando <AllowUnspecifiedParameters>

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

Componenti Convalida della risposta
Percorso Verifica che il percorso della richiesta (meno il basepath) 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 delle intestazioni della risposta corrisponda 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>

Campioni

I seguenti esempi mostrano alcuni dei modi in cui è possibile utilizzare il criterio 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 allo schema del corpo del messaggio 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 parametri

L'esempio seguente consente di configurare il criterio in modo che abbia esito negativo se un parametro di intestazione, query o cookie viene specificato nella richiesta non 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
Digitare 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 flusso nell'interfaccia utente 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>

Utilizzalo in aggiunta all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso e dal suono più naturale.

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

Valore predefinito n/d
Obbligatorio? Campo facoltativo. Se ometti <DisplayName>, viene utilizzato il valore dell'attributo name del criterio
Digitare Stringa
Elemento principale <PolicyElement>
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 a cui eseguire la convalida. Puoi archiviare questo file:

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

Per saperne di più, vedi Gestire le risorse.

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

Valore predefinito Nessuno
Obbligatorio? Obbligatorio
Digitare 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.

<Opzioni>

Consente di configurare le opzioni per il criterio.

Valore predefinito n/d
Obbligatorio? Facoltativo
Digitare 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 del criterio. Ognuna di queste opzioni è descritta dettagliatamente 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>

<ValidateMessageBody>

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 i contenuti del corpo del messaggio. Impostalo su false per confermare solo che il corpo del messaggio esista.

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

Valore predefinito false
Obbligatorio? Facoltativo
Digitare 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 consente la convalida dei contenuti del corpo del messaggio:

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

<AllowUnspecifiedParameters>

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

Valore predefinito n/d
Obbligatorio? Facoltativo
Digitare 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 consente di configurare il criterio in modo che abbia esito negativo se un parametro di intestazione, query o cookie viene specificato nella richiesta non 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 se nella richiesta sono presenti parametri di intestazione che non sono definiti nella specifica OpenAPI.

Per consentire la specifica nella richiesta di 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 l'esecuzione del criterio.

Valore predefinito true
Obbligatorio? Booleano
Digitare 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 abbia esito negativo se nella richiesta viene specificato un parametro di intestazione che non è definito nella specifica OpenAPI.

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

<Query> (secondario di <AllowUnspecifiedParameters>)

Consente di configurare il comportamento del criterio se nella richiesta sono presenti parametri di query che non sono definiti nella specifica OpenAPI.

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

Valore predefinito true
Obbligatorio? Booleano
Digitare 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 abbia esito negativo se nella richiesta viene specificato un parametro di query non definito nella specifica OpenAPI.

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

Consente di configurare il comportamento del criterio se nella richiesta sono presenti parametri di cookie che non sono definiti nella specifica OpenAPI.

Per consentire l'indicazione nella richiesta di 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 l'esecuzione del criterio.

Valore predefinito true
Obbligatorio? Booleano
Digitare 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 abbia esito negativo se nella richiesta viene specificato un parametro di query non definito 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 contro attacchi di payload JSON. In genere è impostato su request, perché in genere dovrai valutare le richieste in entrata dalle app client. Imposta su risposta per valutare i messaggi di risposta. Imposta su message per valutare automaticamente il messaggio di richiesta quando il criterio è associato al flusso di richiesta e il messaggio di risposta quando il criterio è allegato al flusso di risposta.

Valore predefinito richiesta
Obbligatorio? Facoltativo
Digitare 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 associato al flusso di richiesta e il messaggio di risposta quando il criterio viene associato 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.

Schema

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

Codici di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
steps.oasvalidation.Failed 500 Request message body cannot be validated against the provided OpenAPI Specification.
steps.oasvalidation.SourceMessageNotAvailable 500

Variable specified in the <Source> element of the policy is either out of scope or cannot be resolved.

steps.oasvalidation.NotMessageVariable 500

<Source> element is set to a variable that is not of type message.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause
ResourceDoesNotExist OpenAPI Specification referenced in the <OASResource> element does not exist.
ResourceCompileFailed OpenAPI Specification that is included in the deployment contains errors that prevent it from being compiled. This generally indicates that the specification is not a well-formed OpenAPI Specification 3.0.
BadResourceURL OpenAPI Specification referenced in the <OASResource> element cannot be processed. This can occur if the file is not a JSON or YAML file or the file URL is not specified correctly.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ResourceDoesNotExist"
oasvalidation.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oasvalidation.myoaspolicy.failed = true

Funzionalità supportate dalle specifiche OpenAPI

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

Categoria Prove di supporto Non supportata
Formati dei tipi di dati booleano
data
data-ora
doppio
email
float
int32/int64
ipv4/ipv6
md5
sha1/sha256/sha512
string
uri
uri-template
uuid
password
byte
codice binario
Oggetto discriminatore mapping
propertyName
N/A
Oggetto tipo multimediale schema codifica
esempio
esempi
Oggetto operazioni parametri
requestBody
responses
security (supporto parziale)
callback
deprecati
server
Oggetto Parametri allowvoidValue
in (query, header, path)
obbligatorio
lo stile di
risposte (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited)

Nota: deepObject supporta solo i parametri stringa; gli array e gli oggetti nidificati non sono supportati.
allowPrenotato
deprecato
esempio
esempi
contenuti
Oggetto Paths elimina
get
head
opzioni
parametri
applicazione
post
put
trace
variabili
Server
Richiedi oggetto di corpo application/json
application/hal+json
application/x-www-form-urlcoded (encoding oggetto non supportato)
contenuti
obbligatori
applicazione/xml
multipart/form-data
text/plain
text/xml
Oggetto risposta application/json
application/hal+json
application/x-www-form-urlcoded (encoding oggetto non supportato)
content
headers
applicazione/xml
link
testo/normale
testo/xml
Oggetto Risposte predefinito
Codice di stato HTTP
N/A
Oggetto schema $ref
additionalProperties (solo per variante con flag booleano)
allOf (ignorato se additionalProperties è false)
anyOf
enum
uniqueMax/uniqueminimum
formato
elementi
max/minimum
maxItems/minItems
maxLength/minLength
maxProperties/minProperties
multipleOf
not
nullable
oneOf
pattern
titlesunivoco
proprietà obbligatoria


deprecato
esempio
readOnly
writeOnly
xml
Oggetto schema di sicurezza in (header, query) (ignorata se type è http)
nome
tipo (apiKey, http)
BearerFormat
Flussi
openIdConnectUrl
schema
Oggetto server variabili
url
Più definizioni di server

Argomenti correlati