Validar o código de status

  • Artigo

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.

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-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

Atributo Descrição Obrigatório Padrão
unspecified-status-code-action Ação a ser executada para códigos de status HTTP em respostas que não são especificadas no esquema da API. 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
status-code Adicione um ou mais elementos para códigos de status HTTP para substituir a ação de validação padrão para códigos de status em respostas. Não

atributos de código de status

Atributo Descrição Obrigatório Padrão
code Código de status HTTP pelo qual substituir a ação de validação. Sim N/D
ação Ação a ser executada para o código de status correspondente, que não está especificado no esquema da API. Se o código de status for especificado no esquema da API, essa substituição não terá efeito. Sim N/D

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

<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.

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: