Valider le contenu

Article
08/30/2024

S’APPLIQUE À : Tous les niveaux de Gestion des API

La stratégie validate-content valide la taille ou le contenu du corps de la demande ou de la réponse par rapport à un ou plusieurs schémas API pris en charge.

Le tableau suivant répertorie les formats de schéma et les types de contenu de la demande ou de la réponse pris en charge par la stratégie. Les valeurs de type de contenu ne respectent pas la casse.

Format	Types de contenu
JSON	Exemples : `application/json` `application/hal+json`
XML	Exemple : `application/xml`
SOAP	Valeurs autorisées : `application/soap+xml` pour les API SOAP 1.2 `text/xml` pour les API SOAP 1.1

Notes

La taille maximale du schéma API qui peut être utilisée par cette stratégie de validation est de 4 Mo. Si le schéma dépasse cette limite, les stratégies de validation retournent des erreurs au moment de l’exécution. Pour l’augmenter, contactez le support technique.

Contenu validé

La stratégie valide le contenu suivant dans la requête ou la réponse par rapport au schéma :

Présence de toutes les propriétés requises.
Présence ou absence de propriétés supplémentaires, si le champ additionalProperties du schéma est défini. Peut être remplacé par l’attribut allow-additional-properties.
Types de toutes les propriétés. Par exemple, si un schéma spécifie une propriété en tant qu’entier, la requête (ou réponse) doit inclure un entier et non un autre type, tel qu’une chaîne.
Format des propriétés, s’il est spécifié dans le schéma, par exemple regex (si le mot clé pattern est spécifié), minimum pour les entiers, et ainsi de suite.

Conseil

Pour obtenir des exemples de contraintes de modèle regex qui peuvent être utilisées dans les schémas, consultez le référentiel regex de validation OWASP.

Notes

Définissez les éléments enfants et de stratégie dans l’ordre fourni dans l’instruction de stratégie. Pour vous aider à configurer cette stratégie, le portail fournit un éditeur guidé basé sur des formulaires. En savoir plus sur comment définir ou modifier des stratégies du service Gestion des API.

Instruction de la stratégie

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

Attributs

Attribut	Description	Obligatoire	Default
unspecified-content-type-action	Action à effectuer pour les demandes ou les réponses avec un type de contenu qui n’est pas spécifié dans le schéma API. Les expressions de stratégie sont autorisées.	Oui	N/A
max-size	Longueur maximale, en octets, du corps de la demande ou de la réponse, vérifiée par rapport à l'en-tête `Content-Length`. Si le corps de la demande ou le corps de la réponse est compressé, cette valeur est la longueur décompressée. La valeur maximale autorisée est : 4 Mo. Les expressions de stratégie sont autorisées.	Oui	N/A
size-exceeded-action	Action à effectuer pour les demandes ou les réponses dont le corps dépasse la taille spécifiée dans `max-size`. Les expressions de stratégie sont autorisées.	Oui	N/A
errors-variable-name	Nom de la variable dans `context.Variables` dans laquelle enregistrer les erreurs de validation. Les expressions de stratégie ne sont pas autorisées.	Non	N/A

Éléments

Nom	Description	Obligatoire
content-type-map	Ajoutez cet élément pour mapper le type de contenu de la demande ou de la réponse entrante à un autre type de contenu qui est utilisé pour déclencher la validation.	Non
contenu	Ajoutez un ou plusieurs de ces éléments pour valider le type de contenu dans la demande ou la réponse, ou le type de contenu mappé, puis exécutez l’action spécifiée.	Non

attributs content-type-map

Attribut	Description	Obligatoire	Default
any-content-type-value	Type de contenu utilisé pour la validation du corps d’une demande ou d’une réponse, quel que soit le type de contenu entrant. Les expressions de stratégie ne sont pas autorisées.	Non	N/A
missing-content-type-value	Type de contenu utilisé pour la validation du corps d’une demande ou d’une réponse, quand le type de contenu entrant est manquant ou vide. Les expressions de stratégie ne sont pas autorisées.	Non	N/A

content-type-map-elements

Nom	Description	Obligatoire
type	Ajoutez un ou plusieurs de ces éléments pour mapper un type de contenu entrant à un type de contenu utilisé pour la validation du corps d’une demande ou d’une réponse. Utilisez `from` pour spécifier un type de contenu entrant connu, ou utilisez `when` avec une expression de stratégie pour spécifier un type de contenu entrant qui correspond à une condition. Remplace le mappage dans `any-content-type-value` et `missing-content-type-value` si la valeur est spécifiée.	Non

attributs de contenu

Attribut	Description	Obligatoire	Default
type	Type de contenu pour exécuter la validation du corps, vérifié par rapport à l’en-tête de type de contenu ou la valeur mappée dans `content-type-mapping` si elle est spécifiée. S’il est vide, il s’applique à chaque type de contenu spécifié dans le schéma API. Pour valider les demandes et réponses SOAP (attribut `validate-as` défini sur « soap »), définissez `type` sur `application/soap+xml` pour les API SOAP 1.2 ou `text/xml` pour les API SOAP 1.1.	Non	N/A
validate-as	Moteur de validation à utiliser pour la validation du corps d’une demande ou d’une réponse avec un `type` correspondant. Valeurs prises en charge : « json », « xml », « soap ». Quand « soap » est spécifié, le XML de la demande ou de la réponse est extrait de l’enveloppe SOAP et validé par rapport à un schéma XML.	Oui	N/A
schema-id	Nom d’un schéma existant qui a été ajouté à l’instance Gestion des API pour la validation du contenu. S’il n’est pas spécifié, le schéma par défaut de la définition de l’API est utilisé.	Non	N/A
schema-ref	Pour un schéma JSON spécifié dans `schema-id`, référence facultative à un chemin de référence local valide dans le document JSON. Exemple : `#/components/schemas/address`. L’attribut doit retourner un objet JSON géré via la Gestion des API comme un schéma JSON valide. Pour un schéma XML, `schema-ref` n’est pas pris en charge, et tout élément de schéma de niveau supérieur peut être utilisé comme racine de la charge utile de la demande ou de la réponse XML. La validation vérifie que tous les éléments à partir de la racine de la charge utile de la demande ou de la réponse XML correspondent au schéma XML fourni.	Non	N/A
allow-additional-properties	Booléenne. Pour un schéma JSON, spécifie s’il faut implémenter un remplacement d’exécution de la valeur `additionalProperties` configurée dans le schéma : - `true` : autorisez des propriétés supplémentaires dans le corps de la demande ou de la réponse, même si le champ du `additionalProperties` schéma JSON est configuré pour ne pas autoriser les propriétés supplémentaires. - `false` : n’autorisez pas les propriétés supplémentaires dans le corps de la demande ou de la réponse, même si le champ du `additionalProperties` schéma JSON est configuré pour autoriser les propriétés supplémentaires. Si l’attribut n’est pas spécifié, la stratégie valide les propriétés supplémentaires en fonction de la configuration du champ `additionalProperties` dans le schéma.	Non	N/A
noms de propriétés insensibles à la casse	Boolean. Pour un schéma JSON, spécifie s’il faut comparer les noms de propriétés d’objets JSON sans tenir compte du cas. - `true` : comparer les noms de propriétés sans tenir compte de la casse. - `false` : comparer les noms de propriétés en tenant compte de la casse.	Non	false

Actions

Les stratégies de validation de contenu comprennent un ou plusieurs attributs qui spécifient une action, que Gestion des API effectue lors de la validation d’une entité dans une demande ou une réponse d’API par rapport au schéma API.

Une action peut être spécifiée pour les éléments représentés dans le schéma API et, selon la stratégie, pour ceux qui ne sont pas représentés dans le schéma API.
Une action spécifiée dans l’élément enfant d’une stratégie remplace une action spécifiée pour son parent.

Actions disponibles :

Action	Désignation
ignore	Ignorer la validation.
empêcher	Bloque le traitement de la demande ou de la réponse, journalise l’erreur de validation détaillée et retourne une erreur. Le traitement est interrompu lorsque le premier ensemble d’erreurs est détecté.
détecter	Journalise les erreurs de validation, sans interrompre le traitement de la demande ou de la réponse.

Utilisation

Sections de la stratégie : inbound, outbound, on-error
Étendues de la stratégie : global, espace de travail, produit, API, opération
Passerelles : classiques, v2, consommation, auto-hébergées, espace de travail

Journaux d’activité

Les détails des erreurs de validation survenues pendant l’exécution de la stratégie sont journalisés dans la variable context.Variables spécifiée dans l’attribut errors-variable-name de l’élément racine de la stratégie. Lorsqu’elle est configurée dans une action prevent, une erreur de validation bloque le traitement de la demande ou de la réponse et est également propagée à la propriété context.LastError.

Pour examiner les erreurs, utilisez une stratégie de trace pour consigner les erreurs des variables de contexte vers Application Insights.

Impact sur les performances

L’ajout d’une stratégie de validation peut affecter le débit de l’API. Les principes suivants s’appliquent :

Plus la taille du schéma API est grande, plus le débit est faible.
Plus la charge utile est importante dans une demande ou une réponse, plus le débit est faible.
La taille du schéma API a un impact plus important sur les performances que la taille de la charge utile.
La validation par rapport à un schéma API dont la taille est de plusieurs mégaoctets peut entraîner des délais d’attente de demande ou de réponse dans certaines conditions. L’effet est plus prononcé dans les niveaux de consommation et de développement du service.

Nous vous recommandons d’effectuer des tests de charge avec vos charges de travail de production attendues pour évaluer l’impact des stratégies de validation sur le débit de l’API.

Schémas pour la validation du contenu

Par défaut, la validation du contenu de la demande ou de la réponse utilise des schémas JSON ou XML à partir de la définition de l’API. Ces schémas peuvent être spécifiés manuellement ou générés automatiquement lors de l’importation d’une API à partir d’une spécification OpenAPI ou WSDL dans Gestion des API.

À l’aide de la stratégie validate-content, vous pouvez éventuellement effectuer une validation par rapport à un ou plusieurs schémas JSON ou XML que vous avez ajoutés à votre instance Gestion des API et qui ne font pas partie de la définition de l’API. Un schéma que vous ajoutez à Gestion des API peut être réutilisé dans de nombreuses API.

Pour ajouter un schéma à votre instance Gestion des API à l’aide du portail Azure :

Dans le portail, accédez à votre instance Gestion des API.
Dans la section API du menu de gauche, sélectionnez Schémas>+ Ajouter.
Dans la fenêtre Créer un schéma, procédez comme suit :
1. Entrez un nom (ID) pour le schéma.
2. Dans Type de schéma, sélectionnez JSON ou XML.
3. Entrez une Description.
4. Dans Créer une méthode, effectuez l’une des opérations suivantes :
  - Sélectionnez Créer, puis entrez ou collez le schéma.
  - Sélectionnez Importer à partir d’un fichier ou Importer à partir d’une URL et entrez un emplacement de schéma.
    
    Notes
    
    Pour importer un schéma à partir d’une URL, le schéma doit être accessible via Internet à partir du navigateur.
5. Sélectionnez Enregistrer.

Gestion des API ajoute la ressource de schéma à l’URI relatif /schemas/<schemaId> et le schéma apparaît dans la liste figurant dans la page Schémas. Sélectionnez un schéma pour afficher ses propriétés ou pour le modifier dans un éditeur de schéma.

Notes

Un schéma peut faire référence à un autre schéma qui est ajouté à l’instance Gestion des API. Par exemple, incluez un schéma XML ajouté à Gestion des API à l’aide d’un élément similaire à :

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

Conseil

Les outils open source permettant de résoudre les références de schéma WSDL et XSD et d’importer des schémas générés par lot vers Gestion des API sont disponibles sur GitHub.

Exemples

Validation de schéma JSON

Dans l’exemple suivant, le service Gestion des API interprète les demandes avec un en-tête de type de contenu vide ou les demandes avec un en-tête de type de contenu application/hal+json comme des demandes avec le type de contenu application/json. Ensuite, le service Gestion des API effectue la validation en mode de détection par rapport à un schéma défini pour le type de contenu application/json dans la définition de l’API. Les messages avec des charges utiles supérieures à 100 Ko sont bloqués. Les requêtes contenant des propriétés supplémentaires sont bloquées, même si le champ additionalProperties du schéma est configuré pour autoriser des propriétés supplémentaires.

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

Validation de schéma SOAP

Dans l’exemple suivant, le service Gestion des API interprète toutes les demandes comme des demandes avec le type de contenu application/soap+xml (le type de contenu utilisé par les API SOAP 1.2), quel que soit le type de contenu entrant. La demande peut arriver avec un en-tête de type de contenu vide, un en-tête de type de contenu (utilisé par les API SOAP 1.1) ou un autre en-tête de type de contenu text/xml. Le service Gestion des API extrait ensuite la charge utile XML de l’enveloppe SOAP et effectue la validation en mode de prévention par rapport au schéma nommé « myschema ». Les messages avec des charges utiles supérieures à 100 Ko sont bloqués.

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

Erreurs de validation

La Gestion des API génère des erreurs de validation de contenu au format suivant :

{
 "Name": string,
 "Type": string,
 "ValidationRule": string,
 "Details": string,
 "Action": string
}

Le tableau suivant répertorie toutes les erreurs possibles des stratégies de validation.

Détails : peut être utilisé pour examiner les erreurs. Non destiné à être partagé publiquement.
Réponse publique : erreur retournée au client. Ne divulgue pas les détails de l’implémentation.

Quand une stratégie de validation spécifie l’action prevent et génère une erreur, la réponse de la gestion des API comprend un code d’état HTTP : 400 lorsque la stratégie est appliquée dans la section entrante, et 502 lorsque la stratégie est appliquée dans la section sortante.

Nom	Type	Règle de validation	Détails	Réponse publique	Action
validate-content
	RequestBody	SizeLimit	Le corps de la demande a une longueur de {size} octets, ce qui dépasse la limite configurée de {maxSize} octets.	Le corps de la demande a une longueur de {size} octets, ce qui dépasse la limite de {maxSize} octets.	détecter/empêcher
	ResponseBody	SizeLimit	Le corps de la réponse a une longueur de {size} octets, ce qui dépasse la limite configurée de {maxSize} octets.	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
{messageContentType}	RequestBody	Non spécifié	Le type de contenu non spécifié {messageContentType} n’est pas autorisé.	Le type de contenu non spécifié {messageContentType} n’est pas autorisé.	détecter/empêcher
{messageContentType}	ResponseBody	Non spécifié	Le type de contenu non spécifié {messageContentType} n’est pas autorisé.	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
	ApiSchema		Le schéma API n’existe pas ou n’a pas pu être résolu.	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
	ApiSchema		Le schéma API ne spécifie pas de définitions.	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
{messageContentType}	RequestBody/ResponseBody	MissingDefinition	Le schéma API ne contient pas la définition {definitionName}, qui est associée au type de contenu {messageContentType}.	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
{messageContentType}	RequestBody	IncorrectMessage	Le corps de la demande n’est pas conforme à la définition {definitionName}, qui est associée au type de contenu {messageContentType}. {valError.Message} Ligne : {valError.LineNumber}, Position : {valError.LinePosition}	Le corps de la demande n’est pas conforme à la définition {definitionName}, qui est associée au type de contenu {messageContentType}. {valError.Message} Ligne : {valError.LineNumber}, Position : {valError.LinePosition}	détecter/empêcher
{messageContentType}	ResponseBody	IncorrectMessage	Le corps de la réponse n’est pas conforme à la définition {definitionName}, qui est associée au type de contenu {messageContentType}. {valError.Message} Ligne : {valError.LineNumber}, Position : {valError.LinePosition}	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
	RequestBody	ValidationException	Impossible de valider le corps de la demande pour le type de contenu {messageContentType}. {détails de l’exception}	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
	ResponseBody	ValidationException	Impossible de valider le corps de la réponse pour le type de contenu {messageContentType}. {détails de l’exception}	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
validate-parameters / validate-headers
{paramName} / {headerName}	QueryParameter / PathParameter / RequestHeader	Non spécifié	Le {paramètre de chemin d’accès/paramètre de requête/en-tête} {paramName} non spécifié n’est pas autorisé.	Le {paramètre de chemin d’accès/paramètre de requête/en-tête} {paramName} non spécifié n’est pas autorisé.	détecter/empêcher
{headerName}	ResponseHeader	Non spécifié	L’en-tête non spécifié {headerName} n’est pas autorisé.	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
	ApiSchema		Le schéma API n’existe pas ou n’a pas pu être résolu.	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
	ApiSchema		Le schéma API ne spécifie pas de définitions.	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
{paramName}	QueryParameter / PathParameter / RequestHeader / ResponseHeader	MissingDefinition	Le schéma API ne contient pas la définition {definitionName}, qui est associée au {paramètre de requête/paramètre de chemin d’accès/en-tête} {paramName}.	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	La demande ne peut pas contenir plusieurs valeurs pour le {paramètre de requête/paramètre de chemin d’accès/en-tête} {paramName}.	La demande ne peut pas contenir plusieurs valeurs pour le {paramètre de requête/paramètre de chemin d’accès/en-tête} {paramName}.	détecter/empêcher
{headerName}	ResponseHeader	IncorrectMessage	La réponse ne peut pas contenir plusieurs valeurs pour l’en-tête {headerName}.	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	La valeur du {paramètre de requête/paramètre de chemin d’accès/en-tête} {paramName} n’est pas conforme à la définition. {valError.Message} Ligne : {valError.LineNumber}, Position : {valError.LinePosition}	La valeur du {paramètre de requête/paramètre de chemin d’accès/en-tête} {paramName} n’est pas conforme à la définition. {valError.Message} Ligne : {valError.LineNumber}, Position : {valError.LinePosition}	détecter/empêcher
{headerName}	ResponseHeader	IncorrectMessage	La valeur de l’en-tête {headerName} n’est pas conforme à la définition. {valError.Message} Ligne : {valError.LineNumber}, Position : {valError.LinePosition}	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	La valeur du {paramètre de requête/paramètre de chemin d’accès/en-tête} {paramName} ne peut pas être analysée en fonction de la définition. {ex.Message}	La valeur du {paramètre de requête/paramètre de chemin d’accès/en-tête} {paramName} n’a pas pu être analysée en fonction de la définition. {ex.Message}	détecter/empêcher
{headerName}	ResponseHeader	IncorrectMessage	La valeur de l’en-tête {headerName} n’a pas pu être analysée en fonction de la définition.	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
{paramName}	QueryParameter / PathParameter / RequestHeader	ValidationError	Le {paramètre de requête/paramètre de chemin d’accès/en-tête} {paramName} ne peut pas être validé. {détails de l’exception}	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
{headerName}	ResponseHeader	ValidationError	Impossible de valider l’en-tête {headerName}. {détails de l’exception}	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher
validate-status-code
{status-code}	StatusCode	Non spécifié	Le code d’état de réponse {status-code} n’est pas autorisé.	Impossible de traiter la demande en raison d’une erreur interne. Contactez le propriétaire de l’API.	détecter/empêcher

Le tableau suivant répertorie toutes les raisons possibles d’une erreur de validation, ainsi que les valeurs de message possibles :

Motif	Message
Demande incorrecte	{Details} pour la variable de contexte, {réponse publique} pour le client
Réponse non autorisée	{Details} pour la variable de contexte, {réponse publique} pour le client

Validation du contenu

Pour plus d’informations sur l’utilisation des stratégies, consultez :

Tutoriel : Transformer et protéger votre API
Référence de stratégie pour obtenir la liste complète des instructions et des paramètres de stratégie
Expressions de stratégie
Définir ou modifier des stratégies
Réutilisation de configurations de stratégie
Référentiel d’extrait de stratégie
Kit de ressources des stratégies Gestion des API Azure
Créer des stratégies à l’aide de Microsoft Copilot dans Azure

Partager via

Valider le contenu

Contenu validé

Instruction de la stratégie

Attributs

Éléments

attributs content-type-map

content-type-map-elements

attributs de contenu

Actions

Utilisation

Journaux d’activité

Impact sur les performances

Schémas pour la validation du contenu

Exemples

Validation de schéma JSON

Validation de schéma SOAP

Erreurs de validation

Commentaires

Ressources supplémentaires

Partager via

Valider le contenu

Contenu validé

Instruction de la stratégie

Attributs

Éléments

attributs content-type-map

content-type-map-elements

attributs de contenu

Actions

Utilisation

Journaux d’activité

Impact sur les performances

Schémas pour la validation du contenu

Exemples

Validation de schéma JSON

Validation de schéma SOAP

Erreurs de validation

Stratégies connexes

Contenu connexe

Commentaires

Ressources supplémentaires