Esta página foi traduzida pela API Cloud Translation.

Política OASValidation

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

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 das mensagens de solicitação validadas pela política OASValidation por componente.

Componentes	Validação da solicitação
Caminho base	Valida o caminho base definido pelo proxy de API. Ignora o caminho base definido na especificação OpenAPI.
Caminho	Valida se o caminho da solicitação (menos o caminho base) corresponde a um dos padrões de caminho definidos na especificação OpenAPI.
Verbo	Valida se o verbo foi definido para o caminho na especificação OpenAPI.
Corpo da mensagem da solicitação	Valida a existência do corpo da mensagem na solicitação, se necessário. Opcionalmente, valida o corpo da mensagem com o esquema de corpo da solicitação da operação na especificação OpenAPI. Configure essa opção usando `<ValidateMessageBody>` Observação: a política valida um corpo de mensagem de solicitação com a especificação OpenAPI apenas se o Content-Type está definido como `application/json`. Se o tipo de conteúdo não for definido como `application/json`, a validação do corpo da mensagem de solicitação será aprovada automaticamente (sem realmente validar o conteúdo).
Parâmetros	Valida se os parâmetros necessários estão presentes na solicitação, incluindo os parâmetros de caminho, cabeçalho, consulta e cookie. Valida se os valores de parâmetro correspondem aos definidos na especificação OpenAPI. Opcionalmente, valida se existem parâmetros na solicitação que não estão definidos na especificação OpenAPI. Configure essa opção usando `<AllowUnspecifiedParameters>`

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

Componentes	Validação da resposta
Caminho	Valida se o caminho da solicitação (menos o caminho base) corresponde a um dos padrões de caminho definidos na especificação OpenAPI.
Verbo	Valida se o verbo foi definido para o caminho na especificação OpenAPI.
Corpo da mensagem da resposta	Valida a existência do corpo da mensagem na resposta, se necessário. Valida se os cabeçalhos de resposta na especificação OpenAPI estão presentes na mensagem de resposta e se o valor dos cabeçalhos de resposta corresponde ao esquema. Opcionalmente, valida o corpo da mensagem com o esquema de corpo de resposta da operação na especificação OpenAPI. Configure essa opção usando `<ValidateMessageBody>`

Exemplos

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.

Validar a mensagem de solicitação

No exemplo a seguir, a política myoaspolicy valida o corpo da mensagem de solicitação em relação ao esquema de corpo da mensagem de solicitação da operação definido na especificação OpenAPI my-spec.json.

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

Se o corpo da mensagem não estiver em conformidade com a especificação OpenAPI, o erro policies.oasvalidation.Failed será retornado.

Validar parâmetros

O exemplo a seguir configura a política para falhar se um parâmetro de cabeçalho, consulta ou cookie for especificado na solicitação que não foi definida na especificação 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>`

Define a política de validação da especificação OpenAPI.

Valor padrão	Consulte a guia Política padrão a seguir
Obrigatório?	Obrigatório
Tipo	Objeto complexo
Elemento pai	N/A
Elemento filho	`<DisplayName>` `<OASResource>` `<Source>` `<Options>` `<Source>`

Sintaxe

O elemento <OASValidation> usa a seguinte sintaxe:

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

Política padrão

O exemplo a seguir mostra as configurações padrão quando você adiciona uma política de validação de OAS ao seu fluxo na IU da 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>

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

Atributo	Padrão	Obrigatório?	Descrição
`name`	N/A	Obrigatório	O nome interno da política. O valor do atributo `name` pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento `<DisplayName>` para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
`continueOnError`	falso	Opcional	Defina como "false" para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como "true" para que a execução do fluxo continue mesmo após a falha de uma política.
`enabled`	verdadeiro	Opcional	Defina como "true" para aplicar a política. Defina como "false" para "turn off" a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
`async`	falso	Descontinuado	Esse atributo está obsoleto.

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.

Valor padrão	N/A
Obrigatório?	Opcional. Se você omitir `<DisplayName>`, o valor do atributo `name` da política será usado
Tipo	String
Elemento pai	<`PolicyElement`>
Elemento filho	Nenhuma

O elemento <DisplayName> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

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

Valor padrão	Nenhuma
Obrigatório?	Obrigatório
Tipo	String
Elemento pai	`<OASValidation>`
Elemento filho	Nenhuma

Sintaxe

O elemento <OASResource> usa a seguinte sintaxe:

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

Exemplo

O exemplo a seguir refere-se à especificação my-spec.yaml armazenada em /apiproxy/resources/oas no pacote de proxy de API:

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

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	`<OASValidation>`
Elemento filho	`<ValidateMessageBody>` `<AllowUnspecifiedParameters>`

Sintaxe

O elemento <Options> usa a seguinte sintaxe:

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

Exemplo

No exemplo a seguir, configuramos as opções da política. Cada uma das opções está descrita mais detalhadamente abaixo.

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

É possível controlar se a execução do fluxo continua após um erro de validação, definindo o atributo continueOnError para o elemento <OASValidation> como true.

Observação: a política valida um corpo de mensagem de solicitação na especificação OpenAPI apenas se o Content-Type está definido como application/json. Se o tipo de conteúdo não for definido como application/json, a validação do corpo da mensagem de solicitação será bem-sucedida automaticamente (sem realmente validar o conteúdo).

Valor padrão	false
Obrigatório?	Opcional
Tipo	Booleano
Elemento pai	`<Options>`
Elemento filho	Nenhuma

Sintaxe

O elemento <ValidateMessageBody> usa a seguinte sintaxe:

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

Exemplo

O exemplo a seguir permite a validação do conteúdo do corpo da mensagem:

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

`<AllowUnspecifiedParameters>`

Configura o comportamento da política se houver parâmetros de cabeçalho, consulta ou cookie presentes na solicitação que não estão definidos na especificação OpenAPI.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	`<Options>`
Elemento filho	`<Header>` `<Query>` `<Cookie>`

Sintaxe

O elemento <AllowUnspecifiedParameters> usa a seguinte sintaxe:

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

Exemplo

O exemplo a seguir configura a política para falhar se um parâmetro de cabeçalho, consulta ou cookie for especificado na solicitação que não foi definida na especificação OpenAPI.

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

Configura o comportamento da política quando há parâmetros de cabeçalho presentes 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.

Valor padrão	true
Obrigatório?	Booleanos
Tipo	Tipo complexo
Elemento pai	`<AllowUnspecifiedParameters>`
Elemento filho	Nenhuma

Sintaxe

O elemento <Header> usa a seguinte sintaxe:

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

Exemplo

No exemplo a seguir, a política falhará se um parâmetro de cabeçalho for especificado na solicitação não definida na especificação OpenAPI.

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

Valor padrão	true
Obrigatório?	Booleanos
Tipo	Tipo complexo
Elemento pai	`<AllowUnspecifiedParameters>`
Elemento filho	Nenhuma

Sintaxe

O elemento <Query> usa a seguinte sintaxe:

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

Exemplo

No exemplo a seguir, a política falha se um parâmetro de consulta é especificado na solicitação que não foi definida na especificação OpenAPI.

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

Configura o comportamento da política quando há parâmetros de cookie presentes na solicitação que não estão definidos na especificação da 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.

Valor padrão	true
Obrigatório?	Booleanos
Tipo	Tipo complexo
Elemento pai	`<AllowUnspecifiedParameters>`
Elemento filho	Nenhuma

Sintaxe

O elemento <Cookie> usa a seguinte sintaxe:

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

Exemplo

No exemplo a seguir, a política falha se um parâmetro de consulta é especificado na solicitação que não foi definida na especificação OpenAPI.

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

Valor padrão	request
Obrigatório?	Opcional
Tipo	String
Elemento pai	`<Source>`
Elemento filho	Nenhuma

Sintaxe

O elemento <Source> usa a seguinte sintaxe:

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

Exemplo

O exemplo a seguir avalia automaticamente a mensagem de solicitação quando a política está anexada ao fluxo de solicitação e a mensagem de resposta quando a política está anexada ao fluxo de resposta:

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

Código de falha	Status HTTP	Causa
`steps.oasvalidation.Failed`	500	O corpo da mensagem da solicitação não pode ser validado de acordo com a especificação OpenAPI fornecida.
`steps.oasvalidation.SourceMessageNotAvailable`	500	A variável especificada no elemento `<Source>` da política está fora do escopo ou não pode ser resolvida.
`steps.oasvalidation.NotMessageVariable`	500	O elemento `<Source>` é definido como uma variável que não é do tipo message.

Erros na implantação

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

Nome do erro	Causa
`ResourceDoesNotExist`	A especificação OpenAPI mencionada no elemento `<OASResource>` não existe.
`ResourceCompileFailed`	A especificação OpenAPI incluída na implantação contém erros que impedem que ela seja compilada. Geralmente, isso indica que a especificação não é uma Especificação OpenAPI 3.0 bem formada.
`BadResourceURL`	A especificação OpenAPI referenciada no elemento `<OASResource>` não pode ser processada. Isso poderá ocorrer se o arquivo não for JSON ou YAML ou se o URL do arquivo não estiver especificado corretamente.

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.

Variáveis	Onde	Exemplo
`fault.name="fault_name"`	`fault_name` é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha.	`fault.name Matches "ResourceDoesNotExist"`
`oasvalidation.policy_name.failed`	`policy_name` é o nome da política especificada pelo usuário que gerou a falha.	`oasvalidation.myoaspolicy.failed = true`

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.

Categoria	Compatível	Sem suporte
Formatos de tipo de dados	booleano data data-hora double e-mail flutuante int32/int64 ipv4/ipv6 md5 sha1/sha256/sha512 string uri uri-template uuid	binário byte senha
Objeto discriminador	mapeamento propertyName	N/A
Objeto de tipo de mídia	schema	codificação exemplo exemplos
Objeto de operações	parâmetros requestBody respostas segurança (suporte parcial)	callbacks servidores descontinuados
Objeto de parâmetros	allowEmptyValue em (`query`, `header`, `path`) obrigatório respostas esquema estilo (`deepObject`, `form`, `formmatrix`, `label`, `pipeDelimited`, `simple`, `spaceDelimited`) Observação:`deepObject` aceita apenas parâmetros de string, e não matrizes e objetos aninhados.	allowReserva descontinuado exemplo exemplos conteúdo
Objeto de caminhos	excluir get head opções parâmetros patch post put trace variáveis	Servidores
Objeto de corpo da solicitação	application/json application/hal+json application/x-www-form-urlencoded (objeto `encoding` incompatível) conteúdo obrigatório	application/xml multipart/form-data text/plain text/xml
Objeto de resposta	application/json application/hal+json application/x-www-form-urlencoded (objeto `encoding` não compatível) conteúdo cabeçalhos	application/xml links text/plain text/xml
Objeto de respostas	Código de status HTTP padrão	N/A
Objeto de esquema	$ref additionalProperties (somente variante de flag booleana) allOf (ignorado se `additionalProperties` for `false`) anyOf tipo exclusivo de itens exclusivos formato itens máximo/mínimo maxItems/minItems maxLength/minLength maxProperties/minProperties multipleOf não tipo anulável título exclusivo propriedades exclusivo	descontinuado exemplo readOnly writeOnly xml
Objeto do esquema de segurança	em (`header`, `query`) (ignorado se `type` for `http`) nome tipo (`apiKey`, `http`)	bearerFormat fluxos openIdConnectUrl esquema
Objeto de servidor	variáveis de URL	Várias definições de servidor

Política OASValidation

Sobre a política OASValidation

Qual conteúdo é validado?

Exemplos

Validar a mensagem de solicitação

Validar parâmetros

Elemento <OASValidation>

Sintaxe

Política padrão

Referência a elementos filhos

<DisplayName>

Sintaxe

Exemplo

<OASResource>

Sintaxe

Exemplo

<Options>

Sintaxe

Exemplo

<ValidateMessageBody>

Sintaxe

Exemplo

<AllowUnspecifiedParameters>

Sintaxe

Exemplo

Sintaxe

Exemplo

Sintaxe

Exemplo

Sintaxe

Exemplo

<Source>

Sintaxe

Exemplo

Esquemas

Códigos de erro

Erros de execução

Erros na implantação

Variáveis de falha

Recursos compatíveis das especificações OpenAPI

Temas relacionados

Elemento `<OASValidation>`

`<DisplayName>`

`<OASResource>`

`<AllowUnspecifiedParameters>`

`<Source>`