Validar parâmetros

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.

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

Elementos

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:

Utilização

• Secções políticas: entrada
• Âmbitos de política: global, área de trabalho, produto, API, operação
• Gateways: clássico, v2, consumo, auto-hospedado, espaço de trabalho

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.

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

Políticas relacionadas

• Validação de conteúdo

Conteúdos relacionados

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

• Tutorial: Transforme e proteja sua API
• Referência de política para uma lista completa de declarações de política e suas configurações
• Expressões de política
• Definir ou editar políticas
• Reutilizar configurações de política
• Recompra de trechos de política
• Kit de ferramentas de política de Gerenciamento de API do Azure
• Criar políticas usando o Microsoft Copilot no Azure