Partilhar via

Validar parâmetros

  • Artigo

APLICA-SE A: Todas as camadas de gerenciamento de API

A validate-parameters política 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 da API de gerenciamento anterior ao 2021-01-01-preview, a validate-parameters política pode não funcionar. Talvez seja necessário reimportar sua API usando a versão 2021-01-01-preview da API de gerenciamento ou posterior.

Nota

O tamanho máximo do esquema de API que pode ser usado por essa 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 aumentá-lo, entre em contato com o suporte.

Nota

Defina os elementos da política e os elementos filho na ordem fornecida na declaração de política. Para ajudá-lo a configurar essa política, o portal fornece um editor guiado baseado em formulários. Saiba mais sobre como definir ou editar 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 Description Necessário Predefinição
especificado-parâmetro-ação Ação a ser executada para parâmetros de solicitação especificados no esquema da API.

Quando fornecido em um headerselemento , query, ou , o path valor substitui o valor de specified-parameter-action no validate-parameters elemento. São permitidas expressões de política.		 Sim N/A
ação-parâmetro-não especificada 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 headerselemento ou query , o valor substitui o valor de unspecified-parameter-action no validate-parameters elemento. São permitidas expressões de política.		 Sim N/A
erros-nome-variável Nome da variável em context.Variables para registrar erros de validação. Expressões de política não são permitidas. No N/A

Elementos

Nome Descrição Obrigatório
cabeçalhos Adicione esse elemento e um ou mais parameter subelementos para substituir as ações de validação padrão para determinados parâmetros nomeados em solicitações. Se o parâmetro for especificado no esquema da API, esse valor substituirá a configuração de nível specified-parameter-action superior. Se o parâmetro não for especificado no esquema da API, esse valor substituirá a configuração de nível unspecified-parameter-action superior. Não
query Adicione esse elemento e um ou mais parameter subelementos 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 da API, esse valor substituirá a configuração de nível specified-parameter-action superior. Se o parâmetro não for especificado no esquema da API, esse valor substituirá a configuração de nível unspecified-parameter-action superior. Não
path Adicione esse elemento e um ou mais parameter subelementos para substituir as ações de validação padrão para determinados parâmetros de caminho de URL em solicitações. Se o parâmetro for especificado no esquema da API, esse valor substituirá a configuração de nível specified-parameter-action superior. Se o parâmetro não for especificado no esquema da API, esse valor substituirá a configuração de nível unspecified-parameter-action 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 executa ao validar uma entidade em uma solicitação ou resposta de API em relação ao esquema de API.

  • Uma ação pode ser especificada para elementos representados no esquema da API e, dependendo da política, para elementos que não são representados no esquema da 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
ignorar Ignorar validação.
prevenir Bloqueie o processamento de solicitação ou resposta, registre o erro de validação detalhado e retorne um erro. O processamento é interrompido quando o primeiro conjunto de erros é detetado.
detect Registrar erros de validação, sem interromper o processamento de solicitações ou respostas.

Utilização

Notas de utilização

  • Esta política só pode ser utilizada uma vez numa secção de política.

Registos

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

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

Implicações de desempenho

Adicionar uma política de validação pode afetar a taxa de transferência da API. São aplicáveis os seguintes princípios gerais:

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

Recomendamos a realização de testes de carga com as 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 cabeçalhos no modo de deteçã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 de validação.

  • Detalhes: Pode ser usado para investigar erros. Não se destina a ser partilhado publicamente.
  • Resposta pública: Erro devolvido ao cliente. Não vaza detalhes da implementação.

Quando uma política de validação especifica a prevent ação 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 do público Ação
validar-conteúdo
RequestBody Limite de tamanho 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. detetar/prevenir
ResponseBody Limite de tamanho O corpo da resposta tem {size} bytes de comprimento e excede o limite configurado de {maxSize} bytes. O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
{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. detetar/prevenir
{messageContentType} ResponseBody Não especificado O tipo de conteúdo não especificado {messageContentType} não é permitido. O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
ApiSchema O esquema da API não existe ou não pôde ser resolvido. O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
ApiSchema O esquema da API não especifica definições. O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
{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}. O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
{messageContentType} RequestBody Mensagem incorreta 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}		 detetar/prevenir
{messageContentType} ResponseBody Mensagem incorreta 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}		 O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
RequestBody ValidationException O corpo da solicitação não pode ser validado para o tipo de conteúdo {messageContentType}.

{detalhes da exceção}		 O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
ResponseBody ValidationException O corpo da resposta não pode ser validado para o tipo de conteúdo {messageContentType}.

{detalhes da exceção}		 O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
validate-parameters / validate-headers
{paramName} / {headerName} QueryParameter / PathParameter / RequestHeader Não especificado Não especificado {path parameter / query parameter / header} {paramName} não é permitido. Não especificado {path parameter / query parameter / header} {paramName} não é permitido. detetar/prevenir
{headerName} ResponseHeader Não especificado O cabeçalho não especificado {headerName} não é permitido. O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
ApiSchema O esquema da API não existe ou não pôde ser resolvido. O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
ApiSchema O esquema da API não especifica definições. O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
{paramName} QueryParameter / PathParameter / RequestHeader / ResponseHeader MissingDefinition O esquema da API não contém a definição {definitionName}, que está associada ao {query parameter / path parameter / header} {paramName}. O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
{paramName} QueryParameter / PathParameter / RequestHeader Mensagem incorreta A solicitação não pode conter vários valores para o {query parameter / path parameter / header} {paramName}. A solicitação não pode conter vários valores para o {query parameter / path parameter / header} {paramName}. detetar/prevenir
{headerName} ResponseHeader Mensagem incorreta A resposta não pode conter vários valores para o cabeçalho {headerName}. O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
{paramName} QueryParameter / PathParameter / RequestHeader Mensagem incorreta O valor do {query parameter / path parameter / header} {paramName} não está de acordo com a definição.

{valError.Message} Linha: {valError.LineNumber}, Posição: {valError.LinePosition}		 O valor do {query parameter / path parameter / header} {paramName} não está de acordo com a definição.

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

{valError.Message} Linha: {valError.LineNumber}, Posição: {valError.LinePosition}		 O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
{paramName} QueryParameter / PathParameter / RequestHeader Mensagem incorreta O valor do {query parameter / path parameter / header} {paramName} não pode ser analisado de acordo com a definição.

{ex. Mensagem}		 O valor do {query parameter / path parameter / header} {paramName} não pôde ser analisado de acordo com a definição.

{ex. Mensagem}		 detetar/prevenir
{headerName} ResponseHeader Mensagem incorreta O valor do cabeçalho {headerName} não pôde ser analisado de acordo com a definição. O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
{paramName} QueryParameter / PathParameter / RequestHeader Erro de validação {Parâmetro de consulta / Parâmetro de caminho / Cabeçalho} {paramName} não pode ser validado.

{detalhes da exceção}		 O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
{headerName} ResponseHeader Erro de validação Header {headerName} não pode ser validado.

{detalhes da exceção}		 O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir
validate-status-code
{código de status} StatusCode Não especificado O código de status da resposta {status-code} não é permitido. O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API. detetar/prevenir

A tabela a seguir lista todos os possíveis valores Reason de um erro de validação, juntamente com possíveis valores de Message:

Razão Mensagem
Solicitação inválida {Details} para variável de contexto, {Public response} para cliente
Resposta não permitida {Details} para variável de contexto, {Public response} para cliente

Conteúdos relacionados

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