Valider le code d’état

  • Article

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

La stratégie validate-status-code valide les codes d’état HTTP dans les réponses par rapport au schéma API. Cette stratégie peut être utilisée pour empêcher les fuites d’erreurs du serveur principal, qui peuvent contenir des traces de la pile.

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-status-code unspecified-status-code-action="ignore | prevent | detect" errors-variable-name="variable name">
    <status-code code="HTTP status code number" action="ignore | prevent | detect" />
</validate-status-code>

Attributs

Attribut Description Obligatoire Default
unspecified-status-code-action Action à effectuer pour les codes d’état HTTP des réponses qui ne sont pas spécifiés dans le schéma API. 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
status-code Ajoutez un ou plusieurs éléments pour les codes d’état HTTP pour remplacer l’action de validation par défaut pour les codes d’état dans les réponses. Non

Attributs status-code

Attribut Description Obligatoire Default
code Code d’état HTTP pour lequel remplacer l’action de validation. Oui N/A
action Action à effectuer pour le code d’état correspondant qui n’est pas spécifié dans le schéma API. Si le code d’état est spécifié dans le schéma API, ce remplacement ne s’applique pas. Oui N/A

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

<validate-status-code unspecified-status-code-action="prevent" errors-variable-name="responseStatusCodeValidation" />

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 :