Política OASValidation

Você está visualizando a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Sobre a política OASValidation

A política OASValidation (Validação da especificação OpenAPI) permite que você valide uma solicitação de entrada ou mensagem de resposta em relação a uma especificação OpenAPI 3.0 (JSON ou YAML). Consulte Qual conteúdo é validado?

A política OASValidation especifica o nome da especificação OpenAPI a ser usada para validação quando a etapa a que a política está anexada é executada. A especificação OpenAPI é armazenada como um recurso no seguinte local padrão no pacote de proxy da API: apiproxy/resources/oas. A especificação OpenAPI precisa ter uma extensão .json, .yml ou .yaml.

Adicione uma especificação OpenAPI como um recurso a um pacote de proxy de API usando a IU ou a API, conforme descrito em Gerenciar recursos.

Qual conteúdo é validado?

A tabela a seguir resume o conteúdo da mensagem de solicitação validado pela política OASValidation, por componente.

A tabela a seguir resume o conteúdo da mensagem de resposta que é validado pela política OASValidation, por componente.

Amostras

Os exemplos a seguir mostram algumas das maneiras em que é possível usar a política OASValidation para validar mensagens em uma especificação 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>

Define a política de validação da especificação 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>

Este elemento tem os seguintes atributos comuns a todas as políticas:

Referência a elementos filhos

Esta seção descreve os elementos filhos de <OASValidation>.

<DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.

O elemento <DisplayName> é comum a todas as políticas.

O elemento <DisplayName> usa a seguinte sintaxe:

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

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

O elemento <DisplayName> não tem atributos ou elementos filhos.

<OASResource>

Define a especificação OpenAPI para usar na validação. Você pode armazenar este arquivo:

• No escopo do proxy da API em /apiproxy/resources/oas no pacote de proxy de API
• Na seção Resources da visualização do navegador do editor de proxy de API.

Para mais informações, consulte Gerenciar recursos.

É possível definir a especificação OpenAPI usando um modelo de mensagem, como {oas.resource.url}. Nesse caso, o valor da variável de fluxo oas.resource.url (entre chaves) será avaliado e substituído na string de payload no ambiente de execução. Para mais informações, consulte Modelos de mensagem.

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

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

O elemento <OASResource> não tem atributos ou elementos filhos.

<Options>

Configura as opções da política.

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

Especifica se a política deve validar o corpo da mensagem com o esquema de corpo da solicitação da operação na especificação OpenAPI. Defina como true para validar o conteúdo do corpo da mensagem. Defina como false para validar apenas que o corpo da mensagem existe.

Você pode controlar se a execução do fluxo continuará após um erro de validação definindo o atributo continueOnError do elemento <OASValidation> como 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 o comportamento da política quando há parâmetros de cabeçalho, consulta ou cookie presentes na solicitação que não estão definidos na especificação 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> (filho de <AllowUnspecifiedParameters>)

Configura o comportamento da política quando há parâmetros de cabeçalho na solicitação que não estão definidos na especificação OpenAPI.

Para permitir que os parâmetros do cabeçalho sejam especificados na solicitação que não estejam definidos na especificação OpenAPI, defina esse parâmetro como true. Caso contrário, defina esse parâmetro como false para que a execução da política falhe.

<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> (filho de <AllowUnspecifiedParameters>)

Configura o comportamento da política quando há parâmetros de consulta na solicitação que não estão definidos na especificação OpenAPI.

Para permitir que os parâmetros de consulta sejam especificados na solicitação que não estão definidos na especificação OpenAPI, defina esse parâmetro como true. Caso contrário, defina esse parâmetro como false para que a execução da política falhe.

<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> (filho de <AllowUnspecifiedParameters>)

Configura o comportamento da política quando há parâmetros de cookies presentes na solicitação que não estão definidos na especificação OpenAPI.

Para permitir que parâmetros de cookie sejam especificados em uma solicitação não definida na especificação OpenAPI, configure esse parâmetro como verdadeiro. Caso contrário, defina esse parâmetro como false para que a execução da política falhe.

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

Mensagem JSON a ser avaliada em relação ao ataques de payload JSON. Geralmente, essa configuração é definida como request, já que você normalmente precisará avaliar as solicitações recebidas de apps clientes. Defina como response para avaliar as mensagens de resposta. Defina como message para avaliar automaticamente a mensagem de solicitação quando a política estiver anexada ao fluxo de solicitação e a mensagem de resposta quando a política estiver anexada ao fluxo de resposta.

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

O elemento <Source> não tem atributos ou elementos filhos.

Esquemas

Cada tipo de política é definido por um esquema XML (.xsd). Para referência, os esquemas de política estão disponíveis no GitHub.

Códigos de erro

Nesta seção, descrevemos os códigos e as mensagens de erro retornados, além das variáveis de falha definidas pelo Edge quando esta política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Erros na implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Variáveis de falha

Essas variáveis são definidas quando essa política aciona um erro no ambiente de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Recursos compatíveis das especificações OpenAPI

A política OASValidation é compatível com os recursos de especificação OpenAPI resumidos na tabela a seguir por categoria. Os recursos que não são compatíveis também estão listados.

Temas relacionados

• Política de proteção contra ameaças JSON
• Política SOAPMessageValidation