Criterio OASValidation

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Informazioni sulle norme OASValidation

La policy OASValidation (convalida della specifica OpenAPI) consente di convalidare un messaggio di richiesta o risposta in entrata rispetto a una specifica OpenAPI 3.0, utilizzando il formato 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 è archiviata come risorsa nella seguente posizione standard all'interno del bundle del proxy API: apiproxy/resources/oas. Il documento di specifica OpenAPI deve avere un'estensione .json, .yml o .yaml.

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

Questa policy è una policy standard e può essere implementata in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per ogni tipo di ambiente, consulta Tipi di criteri.

Nota:puoi archiviare la specifica OpenAPI solo con la revisione del proxy API. Consulta Dove sono archiviate le risorse.

Quali contenuti vengono convalidati?

La seguente tabella riepiloga i contenuti del messaggio di richiesta convalidati dal criterio OASValidation, per componente.

Componenti	Richiedi convalida
Basepath	Convalida il basepath definito dal proxy API; ignora il basepath specificato nella specifica OpenAPI.
Percorso	Verifica che il percorso della richiesta (meno il percorso di 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	Verifica l'esistenza del corpo del messaggio nella richiesta, se necessario. In via facoltativa, 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 convalida il corpo di un messaggio di richiesta in base alla specifica OpenAPI solo se Content-Type è impostato su application/json. Se il tipo di contenuto non è impostato su application/json, la convalida del corpo del messaggio di richiesta verrà superata automaticamente (senza convalidare effettivamente il contenuto).
Parametri	Verifica che i parametri obbligatori siano presenti nella richiesta, inclusi i parametri di percorso, intestazione, query e cookie. Verifica che i valori dei parametri corrispondano a quelli definiti nella specifica OpenAPI. (Facoltativo) Convalida l'esistenza nella richiesta di parametri non definiti nella specifica OpenAPI. Configura questa opzione utilizzando <AllowUnspecifiedParameters>

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

Componenti	Convalida della risposta
Percorso	Verifica che il percorso della richiesta (meno il percorso di 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	Verifica 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. Se vuoi, convalida il corpo del messaggio in base allo schema del corpo della risposta dell'operazione nella Specifica OpenAPI. Configura questa opzione utilizzando <ValidateMessageBody>

Nota:il criterio OASValidation di Apigee convalida i percorsi di richiesta e risposta in modo diverso.
Per la convalida delle richieste, convalida il percorso della richiesta del proxy API (ad esempio, /hello per https://<BasePath>/hello).
Per la convalida delle risposte, convalida il percorso dell'endpoint di destinazione chiamato da Apigee (ad esempio, /apigee/hello per https://{target-basepath}}/apigee/hello).
Questa distinzione è fondamentale se i percorsi del proxy e di destinazione sono diversi, in quanto devi allineare la specifica OpenAPI di conseguenza per la convalida delle risposte.

Esempi

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

Convalida del messaggio di richiesta

Nell'esempio seguente, il criterio myoaspolicy convalida il corpo del messaggio di richiesta rispetto allo 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 i parametri

Il seguente esempio configura la policy in modo che non riesca se nella richiesta viene specificato un parametro di intestazione, query o cookie che non è definito 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>

Elemento <OASValidation>

Definisce il criterio di convalida della specifica OpenAPI.

Valore predefinito	Consulta la scheda Policy predefinita di seguito.
Obbligatorio?	Obbligatorio
Tipo	Oggetto complesso
Elemento principale	n/a
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>

Norme predefinite

L'esempio seguente mostra le impostazioni predefinite quando aggiungi una norma di convalida OAS al flusso nell'interfaccia utente 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	Predefinito	Obbligatorio?	Descrizione
name	N/D	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ò superare i 255 caratteri. Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError	falso	Facoltativo	Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente
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	falso	Ritirato	Questo attributo è stato ritirato.

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <OASValidation>.

<DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente 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>, viene utilizzato il valore dell'attributo name del criterio.
Tipo	Stringa
Elemento principale	<PolicyElement>
Elementi secondari	Nessuno

La sintassi dell'elemento <DisplayName> è la seguente:

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 da convalidare. Puoi archiviare questo file:

• Nell'ambito del proxy API in /apiproxy/resources/oas nel pacchetto del proxy API
• Nella sezione Resources della visualizzazione Navigator 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, il valore della variabile di flusso oas.resource.url (tra parentesi graffe) verrà valutato e sostituito nella stringa del payload in fase di runtime. Per saperne di più, vedi Modelli di messaggi.

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 del proxy API:

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

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

Nota: se il criterio OASValidation specifica un <OASResource> con requisiti di sicurezza impostati a livello globale, i requisiti di sicurezza non vengono applicati. Per garantire l'applicazione, tutti i requisiti di sicurezza devono essere impostati a livello di operazione nella specifica OpenAPI passata nell'elemento <OASResource> di questo criterio. Per saperne di più, vedi Problemi noti di Apigee.

<Opzioni>

Configura le opzioni per la policy.

Valore predefinito	n/a
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 la policy. Ciascuna opzione è descritta in modo più dettagliato 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>

Specifica se la policy deve convalidare il corpo del messaggio in base allo schema del corpo della richiesta dell'operazione nella specifica OpenAPI. Imposta su true per convalidare i contenuti del corpo del messaggio. Imposta il valore false per convalidare 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 l'elemento <OASValidation> su true.

Nota:il criterio convalida 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 andrà a buon fine automaticamente (senza convalidare effettivamente i contenuti).

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 attiva 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 nella richiesta sono presenti parametri di intestazione, query o cookie che non sono definiti nella specifica OpenAPI.

Valore predefinito	n/a
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

Il seguente esempio configura la policy in modo che non riesca se nella richiesta viene specificato un parametro di intestazione, query o cookie che non è definito 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> (figlio di <AllowUnspecifiedParameters>)

Configura il comportamento del criterio se nella richiesta sono presenti parametri di intestazione non definiti nella specifica OpenAPI.

Per consentire la specifica dei parametri di intestazione nella richiesta 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
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 la policy in modo che non vada a buon fine se nella richiesta viene specificato un parametro di intestazione non definito 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 se nella richiesta sono presenti parametri di ricerca non definiti nella specifica OpenAPI.

Per consentire la specifica nella richiesta di parametri di ricerca non 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
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 la policy in modo che non vada a buon fine 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>

<Cookie> (figlio di <AllowUnspecifiedParameters>)

Configura il comportamento del criterio se nella richiesta sono presenti parametri dei cookie non definiti nella specifica OpenAPI.

Per consentire la specifica nella richiesta di parametri dei cookie non 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
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 la policy in modo che non vada a buon fine 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 in base agli attacchi al payload JSON. Questo valore è in genere impostato su request, in quanto in genere è necessario valutare le richieste in entrata dalle app client. Imposta 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 al flusso di risposta.

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 la policy è collegata al flusso di richiesta e il messaggio di risposta quando la policy è collegata 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 per queste norme

Ogni tipo di policy è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle policy 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 Apigee 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	400	The Request message body cannot be validated against the provided OpenAPI Specification.
steps.oasvalidation.Failed	500	The Response 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.NonMessageVariable	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.

Variable	Description	Example
fault.category	The category of the fault. When the policy rejects a request, this will always hold Step.	fault.category = "Step"
fault.name	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"
fault.reason	The reason for the fault. It is a human-readable string explaining the reason for the fault.	OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"
fault.subcategory	The subcategory of the fault. When the policy rejects a request, this will always hold OASValidationFailure.	fault.subcategory = "OASValidationFailure"
OASValidation.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	OASValidation.myoaspolicy.failed = true

Funzionalità supportate delle specifiche OpenAPI

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

Nota:il criterio OASValidation rifiuterà le specifiche OpenAPI che utilizzano funzionalità non supportate. In questo caso, il criterio non supererà la convalida delle funzionalità non supportate e il deployment del proxy API non andrà a buon fine.

Categoria	Supportato	Non supportata
Formati dei tipi di dati	booleano data data e ora double email float int32/int64 ipv4/ipv6 md5 sha1/sha256/sha512 string uri uri-template uuid	binary byte password
Oggetto discriminatore	mapping propertyName	N/D
Oggetto tipo di media	schema	codifica esempio esempi
Oggetto Operations	parametri requestBody responses security (supporto parziale)	callback ritirati server
Oggetto parametri	allowEmptyValue in (query, header, path) required responses schema style (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited) Nota: deepObject supporta solo i parametri stringa; array e oggetti nidificati non sono supportati.	allowReserved deprecated example examples content
Oggetto Percorsi	delete get head options parameters patch post put trace variables	server
Oggetto del corpo della richiesta	application/json application/hal+json application/x-www-form-urlencoded (oggetto encoding non supportato) content required	application/xml multipart/form-data text/plain text/xml
Oggetto Response	application/json application/hal+json application/x-www-form-urlencoded (oggetto encoding non supportato) content headers	application/xml links text/plain text/xml
Oggetto Responses	default Codice di stato HTTP	N/D
Oggetto schema	$ref additionalProperties (solo variante del flag booleano) allOf (ignorato se additionalProperties è false) anyOf enum exclusiveMaximum/exclusiveMinimum format items maximum/minimum maxItems/minItems maxLength/minLength maxProperties/minProperties multipleOf not nullable oneOf pattern properties required title type uniqueItems	deprecated example readOnly writeOnly xml
Oggetto schema di sicurezza	in (header, query) (ignorato se type è http) name type (apiKey, http)	bearerFormat flows openIdConnectUrl scheme
Oggetto server	url variables	Definizioni di più server

Utilizzo di pattern nello schema

Lo standard OpenAPI Specification consente alle specifiche di stabilire un schema per descrivere il tipo di dati di un parametro o di un campo. Per un parametro o un campo di tipo stringa, lo schema può anche definire un pattern, ovvero un'espressione regolare (regex) che definisce le forme valide per la stringa.

Ad esempio, considera il seguente frammento della specifica OpenAPI:

paths:
  /products/{product-id}:
    get:
      operationId: getProduct
      summary: Get product by id
      description: returns information regarding a product, by id
      parameters:
        - name: product-id
          in: path
          description: id of the product
          required: true
          schema:
            type: string
            pattern: '^\w{3}-\d{4}$'

Questa specifica richiede che per l'operazione getProduct, il parametro product-id sia conforme all'espressione regolare fornita, che prevede una sequenza di tre caratteri alfanumerici, un trattino e quattro cifre decimali.

La specifica OpenAPI rimanda allo standard di convalida dello schema JSON per definire formalmente il comportamento del pattern nella convalida del valore della stringa e allo standard JSON Schema Core per i consigli agli autori dello schema in merito al set limitato di sintassi delle espressioni regolari. Quest'ultimo standard consiglia di evitare l'uso di lookaround (lookahead e lookbehind), backreference ed espressioni di caratteri ottali, tra le altre funzionalità, all'interno dei pattern nei documenti della specifica OpenAPI.

Per impostazione predefinita, Apigee convalida il documento di specifica OpenAPI a cui fa riferimento il criterio OASValidation e segnala gli errori se il documento di specifica non è ben formato. Apigee convalida anche i pattern regex nel documento di specifica e segnala i problemi riscontrati.

È importante notare che se utilizzi funzionalità regex al di fuori del sottoinsieme consigliato, Apigee non convaliderà l'espressione regolare e sospenderà qualsiasi ulteriore convalida del documento delle specifiche OpenAPI. Se si verifica un errore nel documento o nell'espressione regolare che utilizza una funzionalità al di fuori del sottoinsieme consigliato o se la funzionalità dell'espressione regolare non è supportata dal runtime Apigee, l'errore verrà rilevato solo in fase di runtime durante l'esecuzione del criterio.

La tabella seguente fornisce alcuni esempi.

Pattern	Comportamento
^\w{3}-\d{4}$	Il pattern è valido. Utilizza solo le funzionalità delle espressioni regolari all'interno del sottoinsieme consigliato. Apigee consentirà il salvataggio o l'importazione del proxy e in fase di runtime il criterio OASValidation funzionerà come previsto, con la convalida del parametro in base al pattern.
^([a-z]\w{3}-\d{4}$	Il pattern non è valido perché manca una parentesi di chiusura. Il pattern non utilizza funzionalità regex al di fuori del sottoinsieme consigliato. Apigee segnalerà questo errore al momento dell'importazione o del salvataggio del proxy API.
^(?![a-z]\w{3}-\d{4}$	Il pattern non è valido. Come nell'esempio precedente, manca una parentesi chiusa. Tuttavia, Apigee non segnalerà questo errore quando salvi o importi il proxy API, perché l'espressione regolare utilizza un'asserzione negativa, che non rientra nel sottoinsieme consigliato di funzionalità delle espressioni regolari. L'errore verrà rilevato solo in fase di runtime durante l'esecuzione del criterio.
^(?![a-z])\w{3}-\d{4}$	Il pattern è valido, ma utilizza un lookahead negativo, che non rientra nel sottoinsieme consigliato di funzionalità regex. Apigee sospenderà la convalida del documento delle specifiche OpenAPI. In fase di runtime, quando esegui il criterio OASValidation che fa riferimento a una specifica utilizzando questo pattern, poiché il runtime Apigee supporta effettivamente i lookahead negativi, Apigee applicherà correttamente questa espressione regolare per convalidare il valore parametro.
^(a)?b(?(1)c|d)$	Il pattern è valido, ma utilizza una condizione di gruppo di acquisizione, che non rientra nel sottoinsieme consigliato di funzionalità delle espressioni regolari. Apigee sospenderà la convalida del documento delle specifiche OpenAPI. In fase di runtime, quando esegui il criterio OASValidation che fa riferimento a una specifica utilizzando questo pattern, poiché il runtime Apigee non supporta questa funzionalità di espressione regolare, Apigee restituirà un errore.

Ti consigliamo di utilizzare solo il sottoinsieme di funzionalità consigliato nelle espressioni regolari per evitare errori di runtime.

Argomenti correlati

• Policy di protezione dalle minacce JSON
• Norme SOAPMessageValidation