Partager via

Stratégies dans Gestion des API Azure

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

Dans Gestion des API Azure, les éditeurs d’API peuvent modifier le comportement de l’API via la configuration à l’aide de stratégies. Cet article explique comment utiliser des 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 75 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 de débit, la mise en cache et la transformation des requêtes ou des 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 du débit d’appels pour limiter le nombre d’appels entrants d’un développeur.
  • Filtrage des requêtes 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. Bien que la passerelle reçoive des demandes et les transfère, non modifiées, à l’API sous-jacente, une stratégie peut appliquer des modifications à la fois à la demande 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. Voici ce à quoi il ressemble :

<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's 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 :

  • Passez en revue l’erreur à l’aide de la context.LastError propriété.
  • 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 l’une des suivantes :

  • Une seule instruction C# placée dans @(expression)
  • Bloc de code C# à plusieurs instructions, placé entre parenthèses @{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

Gestion des API vous permet de définir des stratégies dans les étendues suivantes, présentées ici de la plus large au 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 (une seule opération dans une API)

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

Diagramme illustrant les cinq étendues de stratégie.

À savoir

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

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

  • Lorsque vous configurez des définitions de stratégie dans plusieurs étendues, vous contrôlez l’héritage de la stratégie et l’ordre d’évaluation de la stratégie dans chaque section de stratégie en placement de 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 programme de résolution GraphQL est configuré avec des stratégies délimitées à un type d’opération et un champ spécifiques dans un schéma GraphQL.

  • Actuellement, Gestion des API prend en charge les programmes de résolution GraphQL qui spécifient l’API HTTP, Azure Cosmos DB ou les sources de données Azure SQL. Par exemple, vous pouvez configurer une stratégie unique http-data-source avec des éléments pour spécifier une requête à (et éventuellement répondre à partir) d’une source de données HTTP.
  • Vous ne pouvez pas inclure de stratégie de résolution dans les définitions de stratégie à d'autres niveaux, tels que l'API, le produit ou toutes les API. La stratégie n’hérite pas non plus des stratégies configurées dans 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 de Copilot

Vous pouvez obtenir de l'aide de Copilot basé sur l'IA pour créer et modifier vos définitions de stratégie de gestion des API. Vous pouvez utiliser Copilot pour créer et mettre à jour des stratégies qui correspondent à vos besoins spécifiques sans avoir à connaître la syntaxe XML. Vous pouvez également obtenir des explications sur les stratégies existantes. Et Copilot peut vous aider à traduire des stratégies que vous avez peut-être configurées dans d’autres solutions de gestion des API.

  • Microsoft Copilot dans Azure fournit une assistance en matière de création de stratégies avec des invites en langage naturel dans le portail Azure. Vous pouvez créer des stratégies dans l’éditeur de stratégie Gestion des API et demander à Copilot d’expliquer les sections de stratégie.
  • GitHub Copilot pour Azure dans Visual Studio Code fournit une assistance de création de stratégie dans Visual Studio Code, et vous pouvez utiliser l’extension Gestion des API Azure pour Visual Studio Code pour accélérer la configuration de la stratégie. Vous pouvez inviter Copilot Chat ou Copilot Edits avec le langage naturel pour créer et affiner les définitions de stratégie en place.

Exemple d'invite :

Generate a policy that adds an Authorization header to the request with a Bearer token.

Copilot est alimenté par l’IA, donc les surprises et les erreurs sont possibles. Pour plus d’informations, consultez les FAQ sur l’utilisation générale de Copilot.

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 précédent :

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

Remarque

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. Les stratégies configurées au niveau du produit et des étendues plus larges ne seront pas appliquées.

Utiliser des expressions de stratégie pour modifier les demandes

L’exemple suivant utilise des expressions de stratégie et la set-header stratégie pour ajouter des données utilisateur aux requêtes entrantes. L’en-tête ajouté inclut l’ID utilisateur associé à la clé d’abonnement dans la demande et la région où la passerelle 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 :