Validar o conteúdo

Artigo
08/30/2024

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

A política validate-content valida o tamanho ou o conteúdo de um corpo de resposta ou solicitação em relação a um ou mais esquemas com suporte.

A tabela a seguir mostra os formatos de esquema e os tipos de conteúdo de solicitação ou resposta aos quais a política dá suporte. Os valores de tipo de conteúdo não diferenciam maiúsculas de minúsculas.

Formatar	Tipos de conteúdo
JSON	Exemplos: `application/json` `application/hal+json`
XML	Exemplo: `application/xml`
SOAP	Valores permitidos: `application/soap+xml` para APIs SOAP 1.2 `text/xml` para APIs SOAP 1.1

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.

Qual conteúdo é validado

A política valida o seguinte conteúdo na solicitação ou resposta em relação ao esquema:

Presença de todas as propriedades necessárias.
Presença ou ausência de propriedades adicionais, se o esquema tiver o campo additionalProperties definido. Pode ser substituído pelo atributo allow-additional-properties.
Tipos de todas as propriedades. Por exemplo, se um esquema especifica uma propriedade como um número inteiro, a solicitação (ou resposta) deve incluir um número inteiro e não outro tipo, como uma cadeia.
O formato das propriedades, se especificado no esquema - por exemplo, regex (se a pattern palavra-chave for especificada), minimum para inteiros e assim por diante.

Dica

Para obter exemplos de restrições de padrão regex que podem ser usadas em esquemas, consulte OWASP Validation Regex Repository.

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-content unspecified-content-type-action="ignore | prevent | detect" max-size="size in bytes" size-exceeded-action="ignore | prevent | detect" errors-variable-name="variable name">
    <content-type-map any-content-type-value="content type string" missing-content-type-value="content type string">
        <type from | when="content type string" to="content type string" />
    </content-type-map>
    <content type="content type string" validate-as="json | xml | soap" schema-id="schema id" schema-ref="#/local/reference/path" action="ignore | prevent | detect" allow-additional-properties="true | false" case-insensitive-property-names="true | false"/>
</validate-content>

Atributos

Atributo	Descrição	Obrigatório	Padrão
unspecified-content-type-action	Ação a ser executada para solicitações ou respostas com um tipo de conteúdo que não é especificado no esquema da API. Expressões de política são permitidas.	Sim	N/D
max-size	O comprimento máximo do corpo da solicitações ou respostas em bytes, verificado em relação ao cabeçalho `Content-Length`. Se o corpo da solicitação ou o corpo da resposta for compactado, esse valor será o comprimento descompactado. Valor máximo permitido: 4 MB. Expressões de política são permitidas.	Sim	N/D
size-exceeded-action	Ação a ser executada para solicitações ou respostas cujo corpo excede o tamanho especificado em `max-size`. 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
content-type-map	Adicione este elemento para mapear o tipo de conteúdo da solicitação ou resposta de entrada para outro tipo de conteúdo usado para disparar a validação.	Não
conteúdo	Adicione um ou mais desses elementos para validar o tipo de conteúdo na solicitação ou resposta, ou o tipo de conteúdo mapeado, e execute a ação especificada.	Não

atributos content-type-map

Atributo	Descrição	Obrigatório	Padrão
any-content-type-value	Tipo de conteúdo usado para a validação do corpo de uma solicitação ou resposta, sem importar o tipo de conteúdo de entrada. Expressões de política não são permitidas.	Não	N/D
missing-content-type-value	Tipo de conteúdo usado para a validação do corpo de uma solicitação ou resposta, qundo o tipo de conteúdo de entrada está ausente ou vazio. Expressões de política não são permitidas.	Não	N/D

content-type-map-elements

Nome	Descrição	Obrigatório
type	Adicione um ou mais desses elementos para mapear um tipo de conteúdo de entrada para um tipo de conteúdo usado para a validação do corpo de uma solicitação ou resposta. Use `from` para especificar um tipo de conteúdo de entrada conhecido ou use `when` com uma expressão de política para especificar qualquer tipo de conteúdo de entrada que corresponda a uma condição. Substitui o mapeamento em `any-content-type-value` e `missing-content-type-value`, se especificado.	Não

atributos de conteúdo

Atributo	Descrição	Obrigatório	Padrão
type	Tipo de conteúdo para o qual executar a validação do corpo, verificado em relação ao cabeçalho do tipo de conteúdo ou ao valor mapeado em `content-type-mapping`, se especificado. Se estiver vazio, ele se aplicará a todos os tipos de conteúdo especificados no esquema da API. Para validar solicitações e respostas SOAP (`validate-as`atributo definido como "soap"), defina `type` como `application/soap+xml` para APIs SOAP 1.2 ou como `text/xml` para APIs SOAP 1.1.	Não	N/D
validate-as	Mecanismo de validação a ser usado para a validação do corpo de uma solicitação ou resposta com um `type` correspondente. Valores com suporte: "json", "xml", "soap". Quando "soap" é especificado, o XML da solicitação ou resposta é extraído do envelope SOAP e validado em relação a um esquema XML.	Sim	N/D
schema-id	Nome de um esquema existente que foi adicionado à instância do Gerenciamento de API para validação de conteúdo. Se não for especificado, será usado o esquema padrão da definição da API.	Não	N/D
schema-ref	Para um esquema JSON especificado em `schema-id`, um referência opcional a um caminho de referência local válido no documento JSON. Exemplo: `#/components/schemas/address`. O atributo deve retornar um objeto JSON que o Gerenciamento de API manipula como um esquema JSON válido. Para um esquema XML, `schema-ref` não tem suporte e qualquer elemento de esquema de nível superior pode ser usado como raiz do conteúdo de solicitação ou resposta XML. A validação verifica se todos os elementos a partir da raiz do conteúdo de resposta ou solicitação XML aderem ao esquema XML fornecido.	Não	N/D
allow-additional-properties	Booliano. Para um esquema JSON, especifica se é necessário implementar uma substituição de runtime do valor `additionalProperties` configurado no esquema: - `true`: permita propriedades adicionais no corpo da solicitação ou da resposta, mesmo que o campo `additionalProperties` do esquema JSON esteja configurado para não permitir propriedades adicionais. - `false`: não permita propriedades adicionais no corpo da solicitação ou da resposta, mesmo que o campo `additionalProperties` do esquema JSON esteja configurado para permitir propriedades adicionais. Se o atributo não for especificado, a política validará propriedades adicionais de acordo com a configuração do campo `additionalProperties` no esquema.	Não	N/D
case-insensitive-property-names	Booliano. Para um esquema JSON, especifica se os nomes das propriedades dos objetos JSON devem ser comparados sem diferenciar letras maiúsculas e minúsculas. - `true`: compara os nomes de propriedade sem considerar a diferenciação entre letras maiúsculas e minúsculas. - `false`: compara os nomes de propriedade considerando a diferenciação de letras maiúsculas e minúsculas.	Não	false

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

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.

Esquemas para validação de conteúdo

Por padrão, a validação do conteúdo de solicitação ou resposta usa esquemas JSON ou XML da definição da API. Esses esquemas podem ser especificados manualmente ou gerados automaticamente ao importar uma API de uma especificação OpenAPI ou WSDL para o Gerenciamento de API.

Usando a política validate-content, você pode validar opcionalmente um ou mais esquemas JSON ou XML que você tiver adicionado à sua instância do Gerenciamento de API e que não fazem parte da definição da API. Um esquema que você adiciona ao Gerenciamento de API pode ser reutilizado em várias APIs.

Para adicionar um esquema à sua instância do Gerenciamento de API usando o portal do Azure:

No portal do Azure, navegue até a instância do Gerenciamento de API.
Na seção APIs do menu à esquerda, selecione Esquemas>+ Adicionar.
Na janela Criar esquema, faça o seguinte:
1. Insira um Nome (ID) para o esquema.
2. Em Tipo de esquema, selecione JSON ou XML.
3. Insira uma Descrição.
4. Em Criar método, faça um dos seguintes:
  - Selecione Criar novo e insira ou cole o esquema.
  - Selecione Importar do arquivo ou Importar da URL e insira um local de esquema.
    
    Observação
    
    Para importar um esquema da URL, o esquema precisa estar acessível pela Internet por meio do navegador.
5. Selecione Salvar.

O Gerenciamento de API adiciona o recurso de esquema no URI relativo /schemas/<schemaId>, e o esquema é exibido na lista da página Esquemas. Selecione um esquema para exibir suas propriedades ou editar em um editor de esquema.

Observação

Um esquema pode fazer referência cruzada a outro esquema que seja adicionado à instância do Gerenciamento de API. Por exemplo, inclua um esquema XML adicionado ao Gerenciamento de API usando um elemento semelhante a:

<xs:include schemaLocation="/schemas/myschema" />

Dica

Ferramentas de código aberto para resolver referências de esquema WSDL e XSD e importar esquemas gerados por lote para o Gerenciamento de API estão disponíveis no GitHub.

Exemplos

Validação do esquema JSON

No exemplo a seguir, o Gerenciamento de API interpreta solicitações com um cabeçalho de tipo de conteúdo vazio ou solicitações com um cabeçalho de tipo de conteúdo application/hal+json como solicitações com o tipo de conteúdo application/json. Em seguida, o Gerenciamento de API executa a validação no modo de detecção em relação a um esquema definido para o tipo de conteúdo application/json na definição da API. Mensagens com payloads maiores que 100 KB são bloqueadas. As solicitações que contêm propriedades adicionais são bloqueadas, mesmo que o campo additionalProperties do esquema esteja configurado para permitir propriedades adicionais.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map missing-content-type-value="application/json">
        <type from="application/hal+json" to="application/json" />
    </content-type-map>
    <content type="application/json" validate-as="json" action="detect" allow-additional-properties="false" />
</validate-content>

Validação do esquema SOAP

No exemplo a seguir, o Gerenciamento de API interpreta qualquer solicitação como uma solicitação com o tipo de conteúdo application/soap+xml (o tipo de conteúdo usado por APIs SOAP 1.2), sem importar o tipo de conteúdo de entrada. A solicitação pode chegar com um cabeçalho de tipo de conteúdo vazio, um cabeçalho de tipo de conteúdo de text/xml (usado por APIs SOAP 1.1) ou outro cabeçalho de tipo de conteúdo. Em seguida, o Gerenciamento de API extrai o conteúdo de XML do envelope SOAP e executa a validação no modo de prevenção em relação ao esquema chamado "myschema". Mensagens com payloads maiores que 100 KB são bloqueadas.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map any-content-type-value="application/soap+xml" />
    <content type="application/soap+xml" validate-as="soap" schema-id="myschema" action="prevent" /> 
</validate-content>

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

Validação de conteúdo

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

Compartilhar via

Validar o conteúdo

Qual conteúdo é validado

Declaração de política

Atributos

Elementos

atributos content-type-map

content-type-map-elements

atributos de conteúdo

Ações

Uso

Logs

Implicações de desempenho

Esquemas para validação de conteúdo

Exemplos

Validação do esquema JSON

Validação do esquema SOAP

Erros de validação

Comentários

Recursos adicionais

Compartilhar via

Validar o conteúdo

Qual conteúdo é validado

Declaração de política

Atributos

Elementos

atributos content-type-map

content-type-map-elements

atributos de conteúdo

Ações

Uso

Logs

Implicações de desempenho

Esquemas para validação de conteúdo

Exemplos

Validação do esquema JSON

Validação do esquema SOAP

Erros de validação

Políticas relacionadas

Conteúdo relacionado

Comentários

Recursos adicionais