Validar o código de status

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

A política validate-status-code valida os códigos de status HTTP em respostas em relação ao esquema da API. Essa política pode ser usada para evitar o vazamento de erros de back-end, que podem conter rastreamentos de pilha.

Declaração de política

<validate-status-code unspecified-status-code-action="ignore | prevent | detect" errors-variable-name="variable name">
    <status-code code="HTTP status code number" action="ignore | prevent | detect" />
</validate-status-code>

Atributos

Elementos

atributos de código de status

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:

Uso

• Seções de política: saída, em caso de erro
• 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

<validate-status-code unspecified-status-code-action="prevent" errors-variable-name="responseStatusCodeValidation" />

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.

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:

Políticas relacionadas

• Validação de conteúdo

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