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
- Sections de la stratégie : inbound
- Étendues de la stratégie : global, espace de travail, produit, API, opération
- Passerelles : classiques, v2, consommation, auto-hébergées, espace de travail
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 |
Stratégies connexes
Contenu connexe
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
- Créer des stratégies à l’aide de Microsoft Copilot dans Azure