Validar parâmetros
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
- Seções de política: de entrada
- Escopos de política: global, espaço de trabalho, produto, API, operação
- Gateways: clássico, v2, consumo, auto-hospedado, espaço de trabalho
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 |
Políticas relacionadas
Conteúdo relacionado
Para obter mais informações sobre como trabalhar com políticas, consulte:
- Tutorial: Transformar e proteger sua API
- Referência de Política para uma lista completa das instruções de política e suas configurações
- Expressões de política
- Definir ou editar políticas
- Reutilizar configurações de política
- Repositório de snippets de política
- Criar políticas usando o Microsoft Copilot no Azure