Partager via

Valider le contenu

  • Article

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

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 :

  1. Dans le portail, accédez à votre instance Gestion des API.

  2. Dans la section API du menu de gauche, sélectionnez Schémas>+ Ajouter.

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

    Créer un schéma

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

Contenu connexe

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