Criterio OASValidation

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. info

Informazioni sulle norme relative a OASValidation

Il criterio OASValidation (convalida della specifica OpenAPI) consente di convalidare un messaggio di richiesta o risposta in entrata rispetto a una specifica OpenAPI 3.0 (JSON o YAML). Consulta la pagina 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 del proxy API: apiproxy/resources/oas. La specifica OpenAPI deve avere un'estensione .json, .yml o .yaml.

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

Quali contenuti vengono convalidati?

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

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

Esempi

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

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

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

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

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

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.

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

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

<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 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 ulteriori informazioni, vedi Modelli di messaggi.

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

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

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

<Options>

Configura le opzioni per il criterio.

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

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

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

<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 non definiti nella specifica OpenAPI.

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

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

<Header> (elemento 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 nella richiesta di parametri di intestazione non definiti nella specifica OpenAPI, imposta questo parametro su true. In caso contrario, imposta questo parametro su false per causare l'errore di esecuzione del criterio.

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

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

<Query> (elemento 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 causare l'errore di esecuzione del criterio.

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

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

<Cookie> (elemento figlio di <AllowUnspecifiedParameters>)

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

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

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

<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 di payload JSON. Di solito viene impostato su request, in quanto in genere dovrai 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 è associato al flusso di richiesta e il messaggio di risposta quando il criterio è associato al flusso di risposta.

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

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

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

Schemi

Ogni tipo di norma è definito da uno schema XML (.xsd). Come riferimento, gli schemi delle norme 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.

Errori di deployment

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

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.

Funzionalità delle specifiche OpenAPI supportate

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

Argomenti correlati

• Criteri di protezione dalle minacce in formato JSON
• Norme relative a SOAPMessageValidation