Gestion des erreurs dans les stratégies de la Gestion des API

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

En fournissant un objet ProxyError, Gestion des API Azure permet aux éditeurs de répondre aux conditions d’erreur, qui peuvent se produire pendant le traitement des demandes. L’objet ProxyError est accessible via la propriété context.LastError. Les stratégies de la section de stratégie on-error peuvent utiliser l’objet ProxyError . Cet article est une ressource de référence au sujet des fonctionnalités de gestion des erreurs dans la Gestion des API Azure.

Gestion des erreurs dans la Gestion des API

Les stratégies de la Gestion des API Azure sont divisées en sections inbound, backend, outbound et on-error, comme l’indique l’exemple suivant.

<policies>
    <inbound>
        <!-- statements to be applied to the request go here -->
    </inbound>
    <backend>
        <!-- statements to be applied before the request is
             forwarded to the backend service go here -->
    </backend>
    <outbound>
        <!-- statements to be applied to the response go here -->
    </outbound>
    <on-error>
        <!-- statements to be applied if there is an error
             condition go here -->
    </on-error>
</policies>

Pendant le traitement d'une demande, les étapes intégrées au processus s'exécutent avec toutes les politiques qui sont dans l'étendue de la requête. Si une erreur se produit, le traitement passe immédiatement à la section de stratégie on-error.

La section de stratégie on-error peut être utilisée, quelle que soit l’étendue. Les éditeurs d’API peuvent configurer un comportement personnalisé, par exemple la journalisation de l’erreur sur Azure Event Hubs ou la création d’une nouvelle réponse pour revenir à l’appelant.

Note

La on-error section n’est pas présente dans les stratégies par défaut. Pour ajouter la section on-error à une stratégie, accédez à la stratégie de votre choix dans l’éditeur de stratégies et ajoutez-la. Pour plus d’informations sur la configuration des stratégies, consultez la page Stratégies dans la Gestion des API.

S’il n’existe aucune on-error section, les appelants reçoivent 400 ou 500 messages de réponse HTTP si une condition d’erreur se produit.

Politiques autorisées en cas d'erreur

Les stratégies suivantes peuvent être utilisées dans la section de stratégie on-error.

DernièreErreur

Lorsqu'une erreur se produit et que le contrôle passe à la on-error section de stratégie, l'erreur est stockée dans la propriété contexte.LastError. Les stratégies dans la section on-error peuvent accéder à context.LastError. LastError contient les propriétés suivantes.

Nom Catégorie Descriptif Obligatoire
Source ficelle Nom de l’élément où l’erreur s’est produite. Peut être une stratégie ou un nom d’étape de pipeline préconfigurée. Oui
Reason ficelle Code d'erreur convivial pour les machines, utilisable pour gérer les erreurs. Non
Message ficelle Description lisible de l’erreur. Oui
Scope ficelle Nom de l’étendue dans laquelle l’erreur s’est produite. Non
Section ficelle Nom de la section où l’erreur s’est produite. Valeurs possibles : inbound, backend, outboundou on-error. Non
Path ficelle Spécifie la hiérarchie de stratégie imbriquée, par exemple choose[3]\\when[2]. Plusieurs instances d’une stratégie imbriquée sont indexées à partir de 1. Non
PolicyId ficelle Valeur de l’attribut id, s’il est spécifié par le client, sur la stratégie où l’erreur s’est produite. Non

Conseil

Vous pouvez accéder au code d’état via context.Response.StatusCode.

Note

Toutes les stratégies ont un attribut id facultatif qui peut être ajouté à l’élément racine de la stratégie. Si cet attribut est présent dans une stratégie lorsqu’une condition d’erreur se produit, vous pouvez récupérer la valeur de l’attribut à l’aide de la context.LastError.PolicyId propriété.

Erreurs prédéfinies pour les étapes intégrées

Les erreurs suivantes sont prédéfinies pour les conditions d’erreur qui peuvent se produire lors de l’évaluation des étapes de traitement intégrées.

Origine État Motif Message
paramétrage L’URI ne correspond à aucune API ou opération OpérationIntrouvable Impossible de faire correspondre la demande entrante à une opération.
autorisation Clé d’abonnement non fournie. CléD'abonnementNonTrouvée Accès refusé en raison de l’absence de clé d’abonnement. Veillez à inclure la clé d’abonnement pour effectuer des demandes auprès de cette API.
autorisation La valeur de la clé d’abonnement n’est pas valide. Clé d'abonnement invalide Accès refusé en raison d’une clé d’abonnement non valide. Veillez à fournir une clé valide pour un abonnement actif.
plusieurs Le client a abandonné une connexion en aval (d’un client à une passerelle Gestion des API) pendant que la requête était en attente ClientConnectionFailure multiple
multiple Le serveur principal a abandonné ou n’a pas pu établir une connexion en amont (d’une passerelle Gestion des API vers un service back-end) Échec de connexion au backend multiple
multiple Une exception runtime s’est produite lors de l’évaluation d’une expression particulière Échec d'évaluation de la valeur de l'expression multiple

Erreurs prédéfinies pour les stratégies

Les erreurs suivantes sont prédéfinies pour les conditions d’erreur qui peuvent se produire lors de l’évaluation de la stratégie.

Origine État Motif Message
limitation du taux Limite de débit dépassée. LimiteDeTauxDépassée Limite de débit dépassée.
Quota Quota dépassé QuotaDépassé Quota de volume d’appels dépassé. Le quota sera réapprovisionné dans xx:xx:xx. \- ou - Quota de bande passante épuisé. Le quota sera réapprovisionné dans xx:xx:xx.
jsonp La valeur du paramètre de rappel n’est pas valide (contient des caractères incorrects). CallbackParameterInvalid La valeur du paramètre de rappel {callback-parameter-name} n’est pas un identificateur JavaScript valide.
filtre IP Impossible d’analyser l’adresse IP de l’appelant à partir de la demande. Échec de l'analyse de l'IP de l'appelant Impossible d’établir l’adresse IP de l’appelant. Accès refusé.
filtre IP L’adresse IP de l’appelant n’est pas dans la liste autorisée AdresseIpAppelantNonAutorisée L’adresse IP de l’appelant {ip-address} n’est pas autorisée. Accès refusé.
filtre IP L’adresse IP de l’appelant figure dans la liste de blocage. L'adresse IP de l'appelant est bloquée L’adresse IP de l’appelant est bloquée. Accès refusé.
check-header L’en-tête requis n’est pas présenté ou sa valeur est manquante. En-têteNonTrouvé En-tête {header-name} introuvable dans la demande. Accès refusé.
check-header L’en-tête requis n’est pas présenté ou sa valeur est manquante. ValeurEntêteNonPermise La valeur {header-value} de l’en-tête {header-name} n’est pas autorisée. Accès refusé.
validate-jwt Json Web Token (JWT) est manquant dans la requête TokenNotPresent (Jeton non présent) JWT non présent.
validate-jwt Échec de validation de la signature. SignatureDuJetonInvalide <message de la bibliothèque jwt>. Accès refusé.
validate-jwt Audience non valide. AudienceDeJetonNonAutorisée <message de la bibliothèque jwt>. Accès refusé.
validate-jwt Émetteur non valide. Émetteur de jeton non autorisé <message de la bibliothèque jwt>. Accès refusé.
validate-jwt Jeton expiré. TokenExpired <message de la bibliothèque jwt>. Accès refusé.
validate-jwt La clé de signature n’a pas été résolue par ID TokenSignatureKeyNotFound <message de la bibliothèque jwt>. Accès refusé.
validate-jwt Les données requises sont manquantes dans le jeton. TokenClaimNotFound JWT manque les revendications suivantes : <c1>, <c2>, ... Accès refusé.
validate-jwt Incompatibilité des valeurs des revendications. ValeurDeRéclamationDuJetonNonAutorisée La réclamation {claim-name} valeur de {claim-value} n’est pas autorisée. Accès refusé.
validate-jwt (valider le token JWT) Autres échecs de validation. JwtInvalid <message de la bibliothèque JWT>
transmettre-une-demande ou envoyer-une-demande Le code d’état de la réponse HTTP et les en-têtes n’ont pas été reçus du serveur principal dans le délai d’expiration configuré Délai d'attente multiple

Exemple

Définissez une stratégie d’API sur la valeur suivante :

<policies>
    <inbound>
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <set-header name="ErrorSource" exists-action="override">
            <value>@(context.LastError.Source)</value>
        </set-header>
        <set-header name="ErrorReason" exists-action="override">
            <value>@(context.LastError.Reason)</value>
        </set-header>
        <set-header name="ErrorMessage" exists-action="override">
            <value>@(context.LastError.Message)</value>
        </set-header>
        <set-header name="ErrorScope" exists-action="override">
            <value>@(context.LastError.Scope)</value>
        </set-header>
        <set-header name="ErrorSection" exists-action="override">
            <value>@(context.LastError.Section)</value>
        </set-header>
        <set-header name="ErrorPath" exists-action="override">
            <value>@(context.LastError.Path)</value>
        </set-header>
        <set-header name="ErrorPolicyId" exists-action="override">
            <value>@(context.LastError.PolicyId)</value>
        </set-header>
        <set-header name="ErrorStatusCode" exists-action="override">
            <value>@(context.Response.StatusCode.ToString())</value>
        </set-header>
        <base />
    </on-error>
</policies>

L’envoi d’une requête non autorisée entraîne la réponse suivante :

Capture d’écran montrant la réponse à l’exemple, qui inclut un message d’erreur.

Contenu connexe

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

  • Last updated on