Questa pagina è stata tradotta dall'API Cloud Translation.

Norme di OASValidation

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza documentazione di Apigee Edge.

Informazioni sulle norme di OASValidation

Il criterio OASValidation (OpenAPI Specification Validation) consente di convalidare una messaggio di richiesta o risposta contro una 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 viene archiviata come risorsa nella seguente posizione standard all'interno del bundle proxy API: apiproxy/resources/oas. Il documento della specifica OpenAPI deve avere un'estensione .json, .yml o .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.

Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Non tutte gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per ciascun tipo di ambiente, consulta Tipi di criteri.

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 supererà 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/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>

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	Predefinito	Obbligatorio?	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ò superare i 255 caratteri. Facoltativamente, 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 in caso di errore del criterio. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su `true` per continuare l'esecuzione del flusso anche dopo un errore nel criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (su continueOnError) Gestione degli errori nel 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	Deprecato	Questo attributo è stato ritirato.

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 più naturale.

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

Valore predefinito	N/A
Obbligatorio?	Facoltativo. Se ometti `<DisplayName>`, viene utilizzato il valore dell'attributo `name` del criterio.
Tipo	Stringa
Elemento principale	<`PolicyElement`>
Elementi secondari	Nessuna esperienza

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 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.

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 Deve essere impostato a livello di operazione nella specifica OpenAPI passata nell'elemento <OASResource> di questo criterio. Per ulteriori informazioni, vedi Problemi noti di Apigee.

<Options>

Configura le opzioni per il criterio.

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 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>

<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 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.

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 avrà esito positivo 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 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/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

<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.

Schema per questo criterio

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 che vengono restituiti e le variabili di errore impostate da Apigee 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`	`400`	Il corpo del messaggio della richiesta non può essere convalidato in base alla specifica OpenAPI fornita.
`steps.oasvalidation.Failed`	`500`	Il corpo del messaggio di risposta 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.NonMessageVariable`	`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.

Variabile	Descrizione	Esempio
`fault.category`	La categoria dell'errore. Quando il criterio rifiuta una richiesta, viene sempre conservato `Step`.	`fault.category = "Step"`
`fault.name`	Il nome dell'errore, indicato nella precedente tabella Errori di runtime. Il nome del guasto è l'ultima parte del codice di errore.	`fault.name Matches "ResourceDoesNotExist"`
`fault.reason`	Il motivo dell'errore. Si tratta di una stringa leggibile che spiega il motivo dell'errore.	`OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"`
`fault.subcategory`	La sottocategoria del guasto. Quando il criterio rifiuta una richiesta, viene sempre conservato `OASValidationFailure`.	`fault.subcategory = "OASValidationFailure"`
`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

Utilizzo dei pattern nello schema

Lo standard OpenAPI Specification consente alle specifiche di indicare un schema da 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 moduli validi per la stringa.

Considera ad esempio 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 alle data una regex, che prevede una sequenza di 3 caratteri parola, un trattino e 4 cifre decimali.

La specifica OpenAPI definisce allo standard JSON Schema Validation per definire formalmente il comportamento del pattern per la convalida del valore della stringa, oltre al Standard JSON Schema Core per suggerimenti agli autori dello schema relativi all'insieme limitato di sintassi delle espressioni regolari. Quest'ultimo standard consiglia di evitare l'uso di lookaround (lookahead e lookbehind), backreference e ottali espressioni di caratteri, tra le altre caratteristiche, all'interno di pattern all'interno dei documenti della specifica OpenAPI.

Per impostazione predefinita, Apigee convalida il documento della specifica OpenAPI a cui fa riferimento il criterio OASValidation e segnala errori se il documento di specifica non è in un formato corretto. Apigee convalida anche i pattern regex nel documento delle specifiche e segnala eventuali problemi.

È importante notare che se utilizzi caratteristiche regex al di fuori del sottoinsieme consigliato, Apigee non convaliderà l'espressione regolare e sospenderà qualsiasi convalida aggiuntiva di del documento della specifica OpenAPI. Se è presente un errore nel documento o nella regex che utilizza una caratteristica esterna al sottoinsieme consigliato o se la funzionalità regex non è supportata dal runtime Apigee, l'errore verrà rilevato solo in fase di runtime, quando il criterio viene eseguito.

La seguente tabella fornisce alcuni esempi.

Pattern	Comportamento
`^\w{3}-\d{4}$`	Il pattern è valido. Utilizza solo caratteristiche regex 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, convalidando il parametro rispetto al pattern.
`^([a-z]\w{3}-\d{4}$`	Il pattern non è valido. manca una parentesi di chiusura. Il pattern non utilizza caratteristiche 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 di chiusura. Tuttavia, Apigee non segnalerà questo errore quando salvi o importi il proxy API, perché l'espressione regolare utilizza un lookahead negativo, che non rientra nel sottoinsieme consigliato di caratteristiche regex. L'errore viene rilevato solo in fase di runtime quando il criterio .
`^(?![a-z])\w{3}-\d{4}$`	Il pattern è valido, ma utilizza un lookahead negativo, che è esterno sottoinsieme consigliato di caratteristiche regex. Apigee sospenderà la convalida di OpenAPI Documento di specifica. In fase di runtime, quando esegui il criterio OASValidation fa riferimento a una specifica utilizzando questo pattern, perché il runtime Apigee in realtà supporta i lookahead negativi, Apigee applicherà correttamente questa espressione regolare per convalidare .
`^(a)?b(?(1)c\|d)$`	Il pattern è valido, ma utilizza un condizionale del gruppo di acquisizione, che è esterno al sottoinsieme consigliato di caratteristiche regex. Apigee sospenderà la convalida di OpenAPI Documento di specifica. In fase di runtime, quando esegui il criterio OASValidation fa riferimento a una specifica utilizzando questo pattern, perché il runtime Apigee non questa funzionalità regex, Apigee restituirà un errore.

Ti consigliamo di utilizzare solo il sottoinsieme consigliato di caratteristiche nella tua espressione regolare per evitare errori di runtime.

Norme di OASValidation

Informazioni sulle norme di OASValidation

Quali contenuti vengono convalidati?

Esempi

Convalida messaggio di richiesta

Convalida dei parametri

<OASValidation> elemento

Sintassi

Criterio predefinito

Riferimento elemento secondario

<DisplayName>

Sintassi

Esempio

<OASResource>

Sintassi

Esempio

&lt;Options&gt;

Sintassi

Esempio

&lt;ValidateMessageBody&gt;

Sintassi

Esempio

<AllowUnspecifiedParameters>

Sintassi

Esempio

Sintassi

Esempio

Sintassi

Esempio

Sintassi

Esempio

<Source>

Sintassi

Esempio

Schema per questo criterio

Codici di errore

Errori di runtime

Errori di deployment

Variabili di errore

Funzionalità supportate dalle specifiche OpenAPI

Utilizzo dei pattern nello schema

Argomenti correlati

`<OASValidation>` elemento

`<DisplayName>`

`<OASResource>`

<Options>

<ValidateMessageBody>

`<AllowUnspecifiedParameters>`

`<Source>`