Partager via


Valider les paramètres

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

La stratégie validate-parameters valide les paramètres d’en-tête, de demande ou de chemin d’accès dans les demandes par rapport au schéma API.

Important

Si vous avez importé une API à l’aide d’une version de l’API de gestion antérieure à 2021-01-01-preview, la stratégie validate-parameters peut ne pas fonctionner. Vous pouvez être amené à réimporter votre API à l'aide de la version 2021-01-01-preview ou ultérieure de l'API de gestion.

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.

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-parameters specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect" errors-variable-name="variable name"> 
    <headers specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </headers>
    <query specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </query>
    <path specified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </path>
</validate-parameters>

Attributs

Attribut Description Obligatoire Default
specified-parameter-action Action à effectuer pour les paramètres de demande spécifiés dans le schéma API.

Lorsqu’il est fourni dans un élément headers, query ou path, la valeur se substitue à la valeur de specified-parameter-action dans l’élément validate-parameters. Les expressions de stratégie sont autorisées.
Oui N/A
unspecified-parameter-action Action à effectuer pour les paramètres de la demande non spécifiés dans le schéma API.

Lorsqu’il est fourni dans un élément headers ou query, la valeur se substitue à la valeur de unspecified-parameter-action dans l’élément validate-parameters. 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
headers Ajoutez cet élément et un ou plusieurs sous-éléments parameter afin de remplacer les actions de validation par défaut pour certains paramètres nommés dans des requêtes. Si le paramètre est spécifié dans le schéma API, cette valeur remplace la configuration specified-parameter-action de niveau supérieur. Si le paramètre n’est pas spécifié dans le schéma API, cette valeur remplace la configuration unspecified-parameter-action de niveau supérieur. Non
query Ajoutez cet élément et un ou plusieurs sous-éléments parameter pour remplacer les actions de validation par défaut pour certains paramètres de requête nommés dans des requêtes. Si le paramètre est spécifié dans le schéma API, cette valeur remplace la configuration specified-parameter-action de niveau supérieur. Si le paramètre n’est pas spécifié dans le schéma API, cette valeur remplace la configuration unspecified-parameter-action de niveau supérieur. Non
path Ajoutez cet élément et un ou plusieurs sous-éléments parameter pour remplacer les actions de validation par défaut de certains paramètres de chemin d’accès d’URL dans des demandes. Si le paramètre est spécifié dans le schéma API, cette valeur remplace la configuration specified-parameter-action de niveau supérieur. Si le paramètre n’est pas spécifié dans le schéma API, cette valeur remplace la configuration unspecified-parameter-action de niveau supérieur. Non

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

Notes d’utilisation

  • Cette stratégie ne peut être employée qu’une seule fois dans une section stratégie.

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.

Exemple

Dans cet exemple, tous les paramètres de requête et de chemin d’accès sont validés dans le mode de prévention, et les en-têtes dans le mode de détection. La validation est remplacée pour plusieurs paramètres d’en-tête :

<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="prevent" errors-variable-name="requestParametersValidation"> 
    <headers specified-parameter-action="detect" unspecified-parameter-action="detect">
        <parameter name="Authorization" action="prevent" />
        <parameter name="User-Agent" action="ignore" />
        <parameter name="Host" action="ignore" />
        <parameter name="Referrer" action="ignore" />
    </headers>   
</validate-parameters>

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

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