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 |
Nota: il criterio convalida il corpo del messaggio di una richiesta in base alla specifica OpenAPI solo se il Content-Type è impostato su |
Parametri |
|
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 |
|
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 Facoltativamente, utilizza l'elemento |
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>
<Header>
(secondario di <AllowUnspecifiedParameters>
)
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
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 |
|
steps.oasvalidation.NotMessageVariable |
500 |
L'elemento |
build |
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 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 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 |