Política de validação da OAS

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Acerca da política OASValidation

A política OASValidation (validação da especificação OpenAPI) permite-lhe validar uma mensagem de pedido ou resposta recebida em função de uma especificação OpenAPI 3.0, usando o formato JSON ou YAML. Consulte Que conteúdo é validado?

A política OASValidation especifica o nome da especificação OpenAPI a usar para validação quando o passo ao qual a política está anexada é executado. A especificação OpenAPI é armazenada como um recurso na seguinte localização padrão no pacote do proxy de API: apiproxy/resources/oas. O documento de especificação OpenAPI tem de ter uma extensão .json, .yml ou .yaml.

Adicione uma especificação OpenAPI como um recurso a um pacote de proxy de API através da IU ou da API, conforme descrito em Gerir recursos.

Esta política é uma política padrão e pode ser implementada em qualquer tipo de ambiente. Para obter informações sobre os tipos de políticas e a disponibilidade com cada tipo de ambiente, consulte Tipos de políticas.

Que conteúdo é validado?

A tabela seguinte resume o conteúdo da mensagem de pedido validado pela política OASValidation, por componente.

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

Amostras

Os exemplos seguintes mostram algumas das formas como pode usar a política OASValidation para validar mensagens com base numa 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>

<OASValidation> elemento

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 de elemento secundário

Esta secção descreve os elementos subordinados de <OASValidation>.

<DisplayName>

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome 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 nem elementos subordinados.

<OASResource>

Especifica a especificação OpenAPI para validação. Pode armazenar este ficheiro:

• No âmbito do proxy de API em /apiproxy/resources/oas no pacote do proxy de API
• Na secção Resources da vista Navigator do editor de proxy de API.

Para mais informações, consulte o artigo Faça a gestão dos recursos.

Pode especificar a especificação OpenAPI através de um modelo de mensagem, como {oas.resource.url}. Neste caso, o valor da variável de fluxo oas.resource.url (entre chavetas) vai ser avaliado e substituído na string de payload no momento da execução. Para mais informações, consulte o artigo Modelos de mensagens.

<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 nem elementos subordinados.

<Options>

Configura opções para a 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 em relação ao esquema do corpo do pedido da operação na especificação OpenAPI. Definido como verdadeiro para validar o conteúdo do corpo da mensagem. Defina como false para validar apenas se o corpo da mensagem existe.

Pode controlar se a execução do fluxo continua 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 se existirem parâmetros de cabeçalho, de consulta ou de cookies presentes no pedido 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 se existirem parâmetros de cabeçalho presentes no pedido que não estão definidos na especificação OpenAPI.

Para permitir que os parâmetros do cabeçalho sejam especificados no pedido que não estão definidos na especificação OpenAPI, defina este parâmetro como verdadeiro. Caso contrário, defina este parâmetro como false para fazer com 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 se existirem parâmetros de consulta presentes no pedido que não estão definidos na especificação da OpenAPI.

Para permitir que os parâmetros de consulta sejam especificados no pedido que não estão definidos na especificação OpenAPI, defina este parâmetro como true. Caso contrário, defina este parâmetro como false para fazer com 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 se existirem parâmetros de cookies presentes no pedido que não estão definidos na especificação da OpenAPI.

Para permitir que os parâmetros de cookies sejam especificados no pedido que não estão definidos na especificação OpenAPI, defina este parâmetro como verdadeiro. Caso contrário, defina este parâmetro como false para fazer com 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 a ataques de payload JSON. Normalmente, esta opção está definida como request, uma vez que, normalmente, tem de avaliar os pedidos recebidos de apps de cliente. Defina como response para avaliar mensagens de resposta. Definido como message para avaliar automaticamente a mensagem de pedido quando a política está anexada ao fluxo de pedido e a mensagem de resposta quando a política está 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 nem elementos subordinados.

Esquema para esta política

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

Códigos de erro

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e Como processar falhas.

Erros de tempo de execução

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

Erros de implementação

Estes erros podem ocorrer quando implementa um proxy que contém esta política.

Variáveis de falha

Estas variáveis são definidas quando esta política aciona um erro no tempo de execução. Para mais informações, consulte o artigo O que precisa de saber sobre os erros de políticas.

Funcionalidades das especificações da OpenAPI suportadas

A política OASValidation suporta as funcionalidades da especificação OpenAPI resumidas na tabela seguinte, por categoria. As funcionalidades que não são suportadas também são apresentadas.

Usar padrões no esquema

A norma da especificação OpenAPI permite que as especificações estipulem um schema para descrever o tipo de dados de um parâmetro ou um campo. Para um parâmetro ou um campo do tipo string, o esquema também pode definir um pattern, que é uma expressão regular (regex) que define formas válidas para a string.

Por exemplo, considere o seguinte fragmento da especificação 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}$'

Esta especificação requer que, para a operação getProduct, o parâmetro product-id esteja em conformidade com a regex fornecida, que estipula uma sequência de 3 carateres de palavras, um traço e 4 dígitos decimais.

A especificação OpenAPI remete para a norma de validação de esquemas JSON para definir formalmente o comportamento do padrão na validação do valor de string e para a norma JSON Schema Core para recomendações aos autores de esquemas relativamente ao conjunto restrito de sintaxe de expressões regulares. Essa norma recomenda que se evite a utilização de lookarounds (lookaheads e lookbehinds), referências anteriores e expressões de carateres octais, entre outras funcionalidades, em padrões nos documentos de especificação OpenAPI.

Por predefinição, o Apigee valida o documento de especificação OpenAPI referenciado pela política OASValidation e comunica erros se o documento de especificação não estiver bem formado. O Apigee também valida padrões de regex no seu documento de especificação e comunica os problemas encontrados.

É importante ter em atenção que, se usar funcionalidades de regex fora do subconjunto recomendado, o Apigee não valida a regex e suspende qualquer validação adicional do seu documento de especificação OpenAPI. Se existir um erro no documento ou na regex que usa uma funcionalidade fora do subconjunto recomendado, ou se a funcionalidade regex não for suportada pelo runtime do Apigee, o erro só é detetado no runtime quando a política é executada.

A tabela seguinte apresenta alguns exemplos.

Recomendamos que use apenas o subconjunto de funcionalidades recomendado na sua regex para evitar falhas de tempo de execução.

Tópicos relacionados

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