Compartilhar via

Validar parâmetros

  • Artigo

APLICA-SE A: todas as camadas do Gerenciamento de API

A política validate-parameters valida os parâmetros de cabeçalho, consulta ou caminho em solicitações em relação ao esquema da API.

Importante

Se você importou uma API usando uma versão de API de gerenciamento anterior a 2021-01-01-preview, a política validate-parameters pode não funcionar. Talvez seja necessário reimportar sua API usando a versão de API de gerenciamento 2021-01-01-preview ou posterior.

Observação

O tamanho máximo do esquema de API que pode ser usado por esta política de validação é de 4 MB. Se o esquema exceder esse limite, as políticas de validação retornarão erros no tempo de execução. Para aumentar o limite, entre em contato com o suporte.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Para ajudá-lo a configurar essa política, o portal fornece um editor guiado baseado em formulário. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

<validate-parameters specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect" errors-variable-name="variable name"> 
    <headers specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </headers>
    <query specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </query>
    <path specified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </path>
</validate-parameters>

Atributos

Atributo Descrição Obrigatório Padrão
specified-parameter-action Ação a ser executada para parâmetros de solicitação especificados no esquema da API.

Quando fornecido em um elemento headers, query ou path, o valor substitui o valor de specified-parameter-action no elemento validate-parameters. Expressões de política são permitidas.		 Sim N/D
unspecified-parameter-action Ação a ser executada para parâmetros de solicitação que não são especificados no esquema da API.

Quando fornecido em um elemento headers ou query, o valor substitui o valor de unspecified-parameter-action no elemento validate-parameters. Expressões de política são permitidas.		 Sim N/D
errors-variable-name Nome da variável em context.Variables para o qual registrar erros de validação. Expressões de política não são permitidas. Não N/D

Elementos

Nome Descrição Obrigatório
headers Adicione esse elemento e um ou mais subelementos de parameter para substituir ações de validação padrão para determinados parâmetros nomeados em solicitações. Se o parâmetro for especificado no esquema de API, esse valor substituirá a configuração specified-parameter-action de nível superior. Se o parâmetro não for especificado no esquema da API, esse valor substituirá a configuração unspecified-parameter-action de nível superior. Não
Consulta Adicione esse elemento e um ou mais subelementos de parameter para substituir ações de validação padrão para determinados parâmetros de consulta nomeados em solicitações. Se o parâmetro for especificado no esquema de API, esse valor substituirá a configuração specified-parameter-action de nível superior. Se o parâmetro não for especificado no esquema da API, esse valor substituirá a configuração unspecified-parameter-action de nível superior. Não
caminho Adicione esse elemento e um ou mais subelementos de parameter para substituir ações de validação padrão para determinados parâmetros de caminhos de URL em solicitações. Se o parâmetro for especificado no esquema de API, esse valor substituirá a configuração specified-parameter-action de nível superior. Se o parâmetro não for especificado no esquema da API, esse valor substituirá a configuração unspecified-parameter-action de nível superior. Não

Ações

As políticas de validação de conteúdo incluem um ou mais atributos que especificam uma ação, que o Gerenciamento de API usa ao validar uma entidade em uma solicitação de API ou resposta em relação ao esquema de API.

  • Uma ação pode ser especificada para elementos que são representados no esquema de API e, dependendo da política, para elementos que não são representados no esquema de API.

  • Uma ação especificada no elemento filho de uma política substitui uma ação especificada para seu pai.

Ações disponíveis:

Ação Descrição
ignore Ignorar validação.
evitar Bloqueie o processamento da solicitação ou da resposta, registre o erro de validação detalhada e retorne um erro. O processamento é interrompido quando o primeiro conjunto de erros é detectado.
detectar Registra erros de validação, sem interromper o processamento de solicitações ou respostas.

Uso

Observações de uso

  • Essa política só pode ser usada uma vez em uma seção de política.

Logs

Os detalhes sobre os erros de validação durante a execução da política são registrados na variável context.Variables especificada no atributo errors-variable-name no elemento raiz da política. Quando configurado em uma ação prevent, um erro de validação bloqueia o processamento de solicitações ou respostas adicional e também é propagado para a propriedade context.LastError.

Para investigar os erros, use uma política de rastreamento para registrar os erros de variáveis de contexto para Application Insights.

Implicações de desempenho

Adicionar uma política de validação pode afetar a taxa de transferência da API. Os seguintes princípios gerais se aplicam:

  • Quanto maior o tamanho do esquema da API, menor será a taxa de transferência.
  • Quanto maior o payload em uma solicitação ou resposta, menor será a taxa de transferência.
  • O tamanho do esquema da API tem um impacto maior no desempenho do que o tamanho do payload.
  • A validação em relação a um esquema de API que tenha vários megabytes de tamanho pode causar tempos limite de solicitação ou resposta em algumas condições. O efeito é mais pronunciado nas camadas Consumo e Desenvolvedor do serviço.

É recomendável executar testes de carga com suas cargas de trabalho de produção esperadas para avaliar o impacto das políticas de validação na taxa de transferência da API.

Exemplo

Neste exemplo, todos os parâmetros de consulta e caminho são validados no modo de prevenção e nos cabeçalhos no modo de detecção. A validação é substituída para vários parâmetros de cabeçalho:

<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="prevent" errors-variable-name="requestParametersValidation"> 
    <headers specified-parameter-action="detect" unspecified-parameter-action="detect">
        <parameter name="Authorization" action="prevent" />
        <parameter name="User-Agent" action="ignore" />
        <parameter name="Host" action="ignore" />
        <parameter name="Referrer" action="ignore" />
    </headers>   
</validate-parameters>

Erros de validação

O Gerenciamento de API gera erros de validação de conteúdo no seguinte formato:

{
 "Name": string,
 "Type": string,
 "ValidationRule": string,
 "Details": string,
 "Action": string
}

A tabela a seguir lista todos os possíveis erros das políticas da validação.

  • Detalhes: ela pode ser usada para investigar erros. Não deve ser compartilhado publicamente.
  • Resposta pública: erro retornado ao cliente. Não vaza detalhes de implementação.

Quando uma política de validação especifica a ação prevent e produz um erro, a resposta do gerenciamento de API inclui um código de status HTTP: 400 quando a política é aplicada na seção de entrada e 502 quando a política é aplicada na seção de saída.

Nome Tipo Regra de validação Detalhes Resposta pública Ação
validate-content
RequestBody SizeLimit O corpo da solicitação tem {size} bytes de comprimento e excede o limite configurado de {maxSize} bytes. O corpo da solicitação tem {size} bytes de comprimento e excede o limite de {maxSize} bytes. detectar/evitar
ResponseBody SizeLimit O corpo da resposta tem {size} bytes de comprimento e excede o limite configurado de {maxSize} bytes. A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
{messageContentType} RequestBody Não Especificado O tipo de conteúdo não especificado {messageContentType} não é permitido. O tipo de conteúdo não especificado {messageContentType} não é permitido. detectar/evitar
{messageContentType} ResponseBody Não Especificado O tipo de conteúdo não especificado {messageContentType} não é permitido. A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
ApiSchema O esquema da API não existe ou não pôde ser resolvido. A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
ApiSchema O esquema da API não especifica definições. A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
{messageContentType} RequestBody/ResponseBody MissingDefinition O esquema da API não contém a definição {definitionName}, que está associada ao tipo de conteúdo {messageContentType}. A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
{messageContentType} RequestBody IncorrectMessage O corpo da solicitação não está de acordo com a definição {definitionName}, que está associada ao tipo de conteúdo {messageContentType}.

{valError.Message} Linha: {valError.LineNumber}, Posição: {valError.LinePosition}		 O corpo da solicitação não está de acordo com a definição {definitionName}, que está associada ao tipo de conteúdo {messageContentType}.

{valError.Message} Linha: {valError.LineNumber}, Posição: {valError.LinePosition}		 detectar/evitar
{messageContentType} ResponseBody IncorrectMessage O corpo da resposta não está de acordo com a definição {definitionName}, que está associada ao tipo de conteúdo {messageContentType}.

{valError.Message} Linha: {valError.LineNumber}, Posição: {valError.LinePosition}		 A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
RequestBody ValidationException O corpo da solicitação não pode ser validado para o tipo de conteúdo {messageContentType}.

{exception details}		 A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
ResponseBody ValidationException O corpo da resposta não pode ser validado para o tipo de conteúdo {messageContentType}.

{exception details}		 A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
validate-parameters / validate-headers
{paramName}/{headerName} QueryParameter/PathParameter/RequestHeader Não Especificado {caminho/parâmetro de consulta/cabeçalho} {paramName} não é permitido. {caminho/parâmetro de consulta/cabeçalho} {paramName} não é permitido. detectar/evitar
{headerName} ResponseHeader Não Especificado O cabeçalho não especificado {headerName} não é permitido. A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
ApiSchema O esquema da API não existe ou não pôde ser resolvido. A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
ApiSchema O esquema de API não especifica definições. A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
{paramName} QueryParameter/PathParameter/RequestHeader/ResponseHeader MissingDefinition O esquema da API não contém a definição {definitionName}, que está associada ao {parâmetro de consulta/parâmetro de caminho/cabeçalho} {paramName}. A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage A solicitação não pode conter vários valores para o {parâmetro de consulta/parâmetro de caminho/cabeçalho} {paramName}. A solicitação não pode conter vários valores para o {parâmetro de consulta/parâmetro de caminho/cabeçalho} {paramName}. detectar/evitar
{headerName} ResponseHeader IncorrectMessage A resposta não pode conter vários valores para o cabeçalho {headerName}. A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage O valor do {parameter de consulta/parâmetro de caminho/cabeçalho} {paramName} não está de acordo com a definição.

{valError.Message} Linha: {valError.LineNumber}, Posição: {valError.LinePosition}		 O valor do {parameter de consulta/parâmetro de caminho/cabeçalho} {paramName} não está de acordo com a definição.

{valError.Message} Linha: {valError.LineNumber}, Posição: {valError.LinePosition}		 detectar/evitar
{headerName} ResponseHeader IncorrectMessage O valor do cabeçalho {headerName} não está de acordo com a definição.

{valError.Message} Linha: {valError.LineNumber}, Posição: {valError.LinePosition}		 A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage O valor do {parâmetro de consulta/parâmetro de caminho/cabeçalho} {paramName} não pode ser analisado de acordo com a definição.

{ex.Message}		 O valor do {parâmetro de consulta/parâmetro de caminho/cabeçalho} {paramName} não pôde ser analisado de acordo com a definição.

{ex.Message}		 detectar/evitar
{headerName} ResponseHeader IncorrectMessage O valor do cabeçalho {headerName} não pôde ser analisado de acordo com a definição. A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
{paramName} QueryParameter/PathParameter/RequestHeader ValidationError {parâmetro de consulta/parâmetro de caminho/cabeçalho} {paramName} não pode ser validado.

{exception details}		 A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
{headerName} ResponseHeader ValidationError O cabeçalho {headerName} não pode ser validado.

{exception details}		 A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar
validate-status-code
{status-code} StatusCode Não Especificado O código de status de resposta {status-code} não é permitido. A solicitação não pôde ser processada devido a um erro interno. Contate o proprietário da API. detectar/evitar

A tabela a seguir lista todos os valores possíveis de Motivo de um erro de validação junto com os possíveis valores de mensagem:

Motivo Message
Solicitação incorreta {Detalhes} para variável de contexto, {Resposta pública} para o cliente
Resposta não permitida {Detalhes} para variável de contexto, {Resposta pública} para o cliente

Conteúdo relacionado

Para obter mais informações sobre como trabalhar com políticas, consulte: