Stratégies dans Gestion des API Azure

  • Article

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

Dans Gestion des API Azure, les éditeurs d’API peuvent modifier le comportement des API par le biais d’une configuration à l’aide de stratégies. Les stratégies sont un ensemble d'instructions qui sont exécutées de manière séquentielle sur demande ou sur réponse d'une API. Gestion des API fournit plus de 50 stratégies prêtes à l’emploi que vous pouvez configurer pour résoudre les scénarios d’API courants tels que l’authentification, la limitation du débit, la mise en cache et la transformation des demandes ou réponses. Pour obtenir une liste complète, consultez Référence de stratégie de la Gestion des API.

Les stratégies populaires sont les suivantes :

  • Conversion de format XML en JSON.
  • Limitation de la fréquence des appels pour restreindre le nombre d’appels entrants provenant d’un développeur.
  • Filtrage des demandes provenant de certaines adresses IP

Les stratégies sont appliquées à l’intérieur de la passerelle entre le consommateur de l’API et l’API managée. Tandis que la passerelle reçoit les requêtes et les transmet, intactes, à l’API sous-jacente, une stratégie peut appliquer des modifications à la requête entrante et à la réponse sortante.

Configuration de la stratégie

Les définitions de stratégie sont des documents XML simples qui décrivent une séquence d’instructions à appliquer aux requêtes et réponses. Pour vous aider à configurer les définitions de stratégie, le portail fournit ces options :

  • Éditeur guidé et basé sur des formulaires pour simplifier la configuration des stratégies populaires sans code XML
  • Éditeur de code dans lequel vous pouvez insérer des extraits de code XML ou modifier directement du code XML

Pour plus d’informations sur la configuration des stratégies, consultez Définir ou modifier des stratégies.

La configuration XML de stratégie est divisée selon les sections inbound, backend, outbound, et on-error. Cette série d’instructions de stratégie spécifiées s’exécute dans l’ordre pour une requête et une réponse.

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

Pour obtenir des exemples XML de stratégie, consultez Référentiel d’extraits de stratégie de la Gestion des API.

Gestion des erreurs

Si une erreur se produit pendant le traitement d’une requête :

  • Les étapes restantes dans les sections inbound, backend ou outbound sont ignorées.
  • L’exécution passe aux instructions de la section on-error.

En plaçant des instructions de stratégie dans la section on-error, vous pouvez :

  • Examiner l’erreur à l’aide de la propriété context.LastError.
  • Inspecter et personnaliser la réponse d’erreur à l’aide de la stratégie set-body.
  • Configurer ce qui se passe si une erreur se produit.

Pour plus d'informations, consultez Gestion des erreurs dans les stratégies de gestion des API.

Expressions de stratégie

Sauf indication contraire de la stratégie, les expressions de stratégie peuvent être utilisées comme valeurs d’attribut ou valeurs de texte dans n’importe quelle stratégie de Gestion des API. Une expression de stratégie est soit :

  • une seule instruction C# placée dans @(expression), ou
  • un bloc de code C# multi-instruction, placé dans @{expression}, qui retourne une valeur

Chaque expression a accès à la variable context fournie implicitement et à un sous-ensemble autorisé de types .NET Framework.

Les expressions de stratégie fournissent un moyen sophistiqué de contrôler le trafic et de modifier le comportement de l’API sans avoir à écrire du code spécialisé ou à modifier des services back-end. Certaines stratégies sont basées sur des expressions de stratégie, telles que Control flow et Set variable.

Étendues

La Gestion des API vous permet de définir des stratégies dans les étendues suivantes, de la plus large à la plus étroite :

  • Global (toutes les API)
  • Espace de travail (toutes les API associées à un espace de travail sélectionné)
  • Produit (toutes les API associées à un produit sélectionné)
  • API (toutes les opérations dans une API)
  • Opération (opération unique dans une API)

Lors de la configuration d’une stratégie, vous devez d’abord sélectionner l’étendue à laquelle elle doit s’appliquer.

Étendues de stratégie

À savoir

  • Pour un contrôle affiné pour différents consommateurs d’API, vous pouvez configurer des définitions de stratégie à plusieurs étendues

  • Toutes les stratégies ne sont pas prises en charge à chaque étendue et section de stratégie

  • Lors de la configuration des définitions de stratégie à plusieurs étendues, vous contrôlez l’héritage de la stratégie ainsi que l’ordre d’évaluation de la stratégie dans chaque section de stratégie en positionnant l’élément base

  • Les stratégies appliquées aux demandes d’API sont également affectées par le contexte de la demande, notamment la présence ou l’absence d’une clé d’abonnement utilisée dans la demande, l’API ou l’étendue du produit de la clé d’abonnement et si l’API ou le produit nécessite un abonnement.

    Remarque

    Si vous utilisez un abonnement dont l’étendue est basée sur l’API, un abonnement basé sur tout les APIs ou le ou l’abonnement avec accès complet incorporé, les stratégies configurées dans l’étendue du produit ne sont pas appliquées aux requêtes provenant de cet abonnement.

Pour en savoir plus, consultez :

Stratégies du résolveur GraphQL

Dans Gestion des API, un résolveur GraphQL est configuré à l’aide de stratégies étendues vers un type d’opération et un champ spécifiques dans un schéma GraphQL.

  • Actuellement, Gestion des API prend en charge les résolveurs de GraphQL qui spécifient l’API HTTP, Cosmos DB ou les sources de données Azure SQL. Par exemple, configurez une stratégie http-data-source unique avec des éléments pour spécifier une requête à (et éventuellement une réponse depuis) une source de données HTTP.
  • Vous ne pouvez pas inclure une stratégie de résolveur dans les définitions de stratégie à d’autres étendues comme l’API, le produit ou toutes les API. Il n’hérite pas non plus des stratégies configurées au niveau d’autres étendues.
  • La passerelle évalue une stratégie resolver-scoped après toutes les stratégies inbound et backend configurées dans le pipeline d’exécution de stratégie.

Pour plus d’informations, voir Configurer un résolveur GraphQL.

Obtenir de l’aide pour créer des stratégies à l’aide de Microsoft Azure Copilot (préversion)

Microsoft Azure Copilot (préversion) fournit des fonctionnalités de création de stratégies pour Gestion des API Azure. En utilisant Azure Copilot dans le contexte de l’éditeur de stratégie de Gestion des API, vous pouvez créer des stratégies qui correspondent à vos besoins spécifiques sans connaître la syntaxe ou vous faire expliquer les stratégies déjà configurées.

Vous pouvez demander à Azure Copilot de générer des définitions de stratégie, puis copier les résultats dans l’éditeur de stratégie et effectuer les ajustements nécessaires. Posez des questions pour obtenir des informations sur différentes options, modifier la stratégie fournie ou clarifier la stratégie que vous avez déjà. En savoir plus

Exemples

Appliquer des stratégies spécifiées à différentes portées

Si vous avez une stratégie configurée au niveau global et une stratégie configurée pour une API, les deux stratégies sont appliquées dès que cette API spécifique est utilisée. Le service Gestion des API permet de trier de façon déterminée les instructions de stratégie combinées via l’élément base.

Exemple de définition de stratégie dans l’étendue de l’API :

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

Dans l’exemple de définition de stratégie ci-dessus :

  • L’instruction cross-domain s’exécuterait d’abord.
  • La find-and-replace stratégie s’exécuterait après toutes les stratégies dans une étendue plus large.

Notes

Si vous supprimez l’élément base au niveau de l’étendue de l’API, seules les stratégies configurées dans l’étendue de l’API seront appliquées. Aucune stratégie de produit ou d’étendue globale ne sera appliquée.

Utiliser des expressions de stratégie pour modifier les demandes

L’exemple suivant utilise des expressions de stratégie et la stratégie set-header pour ajouter des données utilisateur à la requête entrante. L’en-tête ajouté inclut l’ID utilisateur associé à la clé d’abonnement dans la requête et la région où la passerelle qui traite la requête est hébergée.

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

Contenu associé

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