Validar conteúdo

Artigo
08/30/2024

APLICA-SE A: Todas as camadas de gerenciamento de API

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

A tabela seguinte mostra os formatos de esquema e os tipos de conteúdo de pedido ou resposta suportados pela política. Os valores de tipo de conteúdo não diferenciam maiúsculas de minúsculas.

Formato	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

Nota

O tamanho máximo do esquema de API que pode ser usado por essa 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 aumentá-lo, entre em contato com o suporte.

Que conteúdo é validado

A política valida o seguinte conteúdo no pedido ou resposta relativamente ao esquema:

Presença de todas as propriedades necessárias.
Presença ou ausência de propriedades adicionais, se o esquema tiver o additionalProperties campo definido. Pode ser substituído pelo allow-additional-properties atributo.
Tipos de todas as propriedades. Por exemplo, se um esquema especificar uma propriedade como um número inteiro, o pedido (ou resposta) tem de 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.

Gorjeta

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

Nota

Defina os elementos da política e os elementos filho na ordem fornecida na declaração de política. Para ajudá-lo a configurar essa política, o portal fornece um editor guiado baseado em formulários. Saiba mais sobre como definir ou editar 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	Description	Necessário	Predefinição
unspecified-content-type-action	Ação a ser executada para solicitações ou respostas com um tipo de conteúdo não especificado no esquema da API. São permitidas expressões de política.	Sim	N/A
tamanho-máximo	Comprimento máximo do corpo da solicitação ou resposta em bytes, verificado em relação ao `Content-Length` cabeçalho. Se o corpo da solicitação ou o corpo da resposta estiver compactado, esse valor será o comprimento descompactado. Valor máximo permitido: 4 MB. São permitidas expressões de política.	Sim	N/A
tamanho-excedido-ação	Ação a ser executada para solicitações ou respostas cujo corpo exceda o tamanho especificado em `max-size`. São permitidas expressões de política.	Sim	N/A
erros-nome-variável	Nome da variável em `context.Variables` para registrar erros de validação. Expressões de política não são permitidas.	No	N/A

Elementos

Nome	Descrição	Obrigatório
conteúdo-tipo-mapa	Adicione esse 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
content	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	Description	Necessário	Predefinição
qualquer-conteúdo-tipo-valor	Tipo de conteúdo usado para validação do corpo de uma solicitação ou resposta, independentemente do tipo de conteúdo de entrada. Expressões de política não são permitidas.	No	N/A
valor do tipo de conteúdo ausente	Tipo de conteúdo usado para validação do corpo de uma solicitação ou resposta, quando o tipo de conteúdo de entrada está ausente ou vazio. Expressões de política não são permitidas.	No	N/A

content-type-map-elements

Nome	Descrição	Obrigatório
tipo	Adicione um ou mais desses elementos para mapear um tipo de conteúdo de entrada para um tipo de conteúdo usado para 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	Description	Necessário	Predefinição
tipo	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 no `content-type-mapping`, se especificado. Se estiver vazio, ele se aplica 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"), definido `type` como `application/soap+xml` para APIs SOAP 1.2 ou `text/xml` para APIs SOAP 1.1.	No	N/A
validar-como	Motor de validação a utilizar para validação do corpo de um pedido ou resposta com uma correspondência `type`. Valores suportados: "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/A
ID do esquema	Nome de um esquema existente que foi adicionado à instância de Gerenciamento de API para validação de conteúdo. Se não for especificado, o esquema padrão da definição de API será usado.	No	N/A
esquema-ref	Para um esquema JSON especificado em `schema-id`, 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 há suporte e qualquer elemento de esquema de nível superior pode ser usado como a raiz da carga útil de solicitação ou resposta XML. A validação verifica se todos os elementos a partir da raiz da carga útil de solicitação ou resposta XML aderem ao esquema XML fornecido.	No	N/A
permitir-adicional-propriedades	Booleano. Para um esquema JSON, especifica se deve implementar uma substituição de tempo de execução do `additionalProperties` valor configurado no esquema: - `true`: permitir propriedades adicionais no corpo da solicitação ou resposta, mesmo que o campo do `additionalProperties` 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 do `additionalProperties` 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 `additionalProperties` configuração do campo no esquema.	No	N/A
nomes de propriedade que não diferenciam maiúsculas de minúsculas	Booleano. Para um esquema JSON, especifica se os nomes de propriedade de objetos JSON devem ser comparados sem considerar maiúsculas e minúsculas. - `true`: Compare nomes de propriedades sem distinção entre maiúsculas e minúsculas. - `false`: compare nomes de propriedades com diferenciação de 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 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:

Ação	Descrição
ignorar	Ignorar validação.
prevenir	Bloqueie o processamento de solicitação ou resposta, registre o erro de validação detalhado e retorne um erro. O processamento é interrompido quando o primeiro conjunto de erros é detetado.
detect	Registrar erros de validação, sem interromper o processamento de solicitações ou respostas.

Utilização

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

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.

Esquemas de validação de conteúdo

Por padrão, a validação do conteúdo da 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 validate-content política, você pode, opcionalmente, validar em relação a um ou mais esquemas JSON ou XML que você adicionou à sua instância de Gerenciamento de API e que não fazem parte da definição de API. Um esquema que você adiciona ao Gerenciamento de API pode ser reutilizado em várias APIs.

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

No portal, navegue até sua instância de Gerenciamento de API.
Na seção APIs do menu à esquerda, selecione Schemas>+ Add.
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 Método Create, siga um destes procedimentos:
  - Selecione Criar novo e insira ou cole o esquema.
  - Selecione Importar do arquivo ou Importar da URL e insira um local do esquema.
    
    Nota
    
    Para importar um esquema da URL, o esquema precisa estar acessível pela Internet a partir do navegador.
5. Selecione Guardar.

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

Nota

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

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

Gorjeta

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

Exemplos

Validação de 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 application/hal+json de tipo de conteúdo como solicitações com o tipo application/jsonde conteúdo. Em seguida, o Gerenciamento de API executa a validação no modo de deteção em relação a um esquema definido para o application/json tipo de conteúdo na definição de API. As mensagens com cargas úteis superiores a 100 KB são bloqueadas. As solicitações que contêm propriedades adicionais são bloqueadas, mesmo que o campo do additionalProperties 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 application/soap+xml de conteúdo (o tipo de conteúdo usado pelas APIs SOAP 1.2), independentemente do tipo de conteúdo de entrada. A solicitação pode chegar com um cabeçalho de tipo de conteúdo vazio, cabeçalho de tipo de conteúdo (usado por APIs SOAP 1.1) ou outro cabeçalho de tipo de text/xml conteúdo. Em seguida, o Gerenciamento de API extrai a carga XML do envelope SOAP e executa a validação no modo de prevenção em relação ao esquema chamado "myschema". As mensagens com cargas úteis superiores a 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 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.

Nome	Tipo	Regra de validação	Detalhes	Resposta do público	Ação
validar-conteúdo
	RequestBody	Limite de tamanho	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.	detetar/prevenir
	ResponseBody	Limite de tamanho	O corpo da resposta tem {size} bytes de comprimento e excede o limite configurado de {maxSize} bytes.	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
{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.	detetar/prevenir
{messageContentType}	ResponseBody	Não especificado	O tipo de conteúdo não especificado {messageContentType} não é permitido.	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
	ApiSchema		O esquema da API não existe ou não pôde ser resolvido.	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
	ApiSchema		O esquema da API não especifica definições.	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
{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}.	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
{messageContentType}	RequestBody	Mensagem incorreta	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}	detetar/prevenir
{messageContentType}	ResponseBody	Mensagem incorreta	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}	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
	RequestBody	ValidationException	O corpo da solicitação não pode ser validado para o tipo de conteúdo {messageContentType}. {detalhes da exceção}	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
	ResponseBody	ValidationException	O corpo da resposta não pode ser validado para o tipo de conteúdo {messageContentType}. {detalhes da exceção}	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
validate-parameters / validate-headers
{paramName} / {headerName}	QueryParameter / PathParameter / RequestHeader	Não especificado	Não especificado {path parameter / query parameter / header} {paramName} não é permitido.	Não especificado {path parameter / query parameter / header} {paramName} não é permitido.	detetar/prevenir
{headerName}	ResponseHeader	Não especificado	O cabeçalho não especificado {headerName} não é permitido.	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
	ApiSchema		O esquema da API não existe ou não pôde ser resolvido.	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
	ApiSchema		O esquema da API não especifica definições.	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
{paramName}	QueryParameter / PathParameter / RequestHeader / ResponseHeader	MissingDefinition	O esquema da API não contém a definição {definitionName}, que está associada ao {query parameter / path parameter / header} {paramName}.	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
{paramName}	QueryParameter / PathParameter / RequestHeader	Mensagem incorreta	A solicitação não pode conter vários valores para o {query parameter / path parameter / header} {paramName}.	A solicitação não pode conter vários valores para o {query parameter / path parameter / header} {paramName}.	detetar/prevenir
{headerName}	ResponseHeader	Mensagem incorreta	A resposta não pode conter vários valores para o cabeçalho {headerName}.	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
{paramName}	QueryParameter / PathParameter / RequestHeader	Mensagem incorreta	O valor do {query parameter / path parameter / header} {paramName} não está de acordo com a definição. {valError.Message} Linha: {valError.LineNumber}, Posição: {valError.LinePosition}	O valor do {query parameter / path parameter / header} {paramName} não está de acordo com a definição. {valError.Message} Linha: {valError.LineNumber}, Posição: {valError.LinePosition}	detetar/prevenir
{headerName}	ResponseHeader	Mensagem incorreta	O valor do cabeçalho {headerName} não está de acordo com a definição. {valError.Message} Linha: {valError.LineNumber}, Posição: {valError.LinePosition}	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
{paramName}	QueryParameter / PathParameter / RequestHeader	Mensagem incorreta	O valor do {query parameter / path parameter / header} {paramName} não pode ser analisado de acordo com a definição. {ex. Mensagem}	O valor do {query parameter / path parameter / header} {paramName} não pôde ser analisado de acordo com a definição. {ex. Mensagem}	detetar/prevenir
{headerName}	ResponseHeader	Mensagem incorreta	O valor do cabeçalho {headerName} não pôde ser analisado de acordo com a definição.	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
{paramName}	QueryParameter / PathParameter / RequestHeader	Erro de validação	{Parâmetro de consulta / Parâmetro de caminho / Cabeçalho} {paramName} não pode ser validado. {detalhes da exceção}	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
{headerName}	ResponseHeader	Erro de validação	Header {headerName} não pode ser validado. {detalhes da exceção}	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir
validate-status-code
{código de status}	StatusCode	Não especificado	O código de status da resposta {status-code} não é permitido.	O pedido não pôde ser processado devido a um erro interno. Entre em contato com o proprietário da API.	detetar/prevenir

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

Razão	Mensagem
Solicitação inválida	{Details} para variável de contexto, {Public response} para cliente
Resposta não permitida	{Details} para variável de contexto, {Public response} para cliente

Validação de conteúdo

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

Partilhar via

Validar conteúdo

Que conteúdo é validado

Declaração de política

Atributos

Elementos

atributos content-type-map

content-type-map-elements

Atributos de conteúdo

Ações

Utilização

Registos

Implicações de desempenho

Esquemas de validação de conteúdo

Exemplos

Validação de esquema JSON

Validação do esquema SOAP

Erros de validação

Comentários

Recursos adicionais

Partilhar via

Validar conteúdo

Que conteúdo é validado

Declaração de política

Atributos

Elementos

atributos content-type-map

content-type-map-elements

Atributos de conteúdo

Ações

Utilização

Registos

Implicações de desempenho

Esquemas de validação de conteúdo

Exemplos

Validação de esquema JSON

Validação do esquema SOAP

Erros de validação

Políticas relacionadas

Conteúdos relacionados

Comentários

Recursos adicionais