Explorer les stratégies Gestion des API

Effectué

Dans Gestion des API Azure, les stratégies permettent au publieur de modifier le comportement de l’API via une configuration. Les stratégies sont un ensemble d'instructions qui sont exécutées dans l'ordre sur demande ou sur réponse d'une API.

Les stratégies sont appliquées au niveau de la passerelle qui se trouve entre le consommateur de l’API et l’API managée. La passerelle reçoit toutes les demandes et les transfère normalement sans les modifier à l’API sous-jacente. Cependant, une stratégie peut appliquer des modifications à la demande entrante et à la réponse sortante. Les expressions de stratégie peuvent être utilisées comme valeurs d’attribut ou valeurs de texte dans l’une des stratégies de Gestion des API, sauf si la stratégie le spécifie autrement.

Configuration de la stratégie

La définition de la stratégie est un simple document XML qui décrit une séquence d'instructions entrantes et sortantes. Le code XML peut être modifié directement dans la fenêtre de définition.

La configuration est composée des sections inbound, backend, outbound et on-error. La série d’instructions de stratégie spécifiées s’exécute dans l’ordre pour une demande 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>

S’il se produit une erreur lors du traitement d’une demande, les autres étapes des sections inbound, backend ou outbound sont ignorées et 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 consulter l'erreur à l'aide de la propriété context.LastError, inspecter et personnaliser la réponse à l'erreur à l'aide de la stratégie set-body, puis configurer ce qui se passe si une erreur se produit.

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.

L’exemple suivant utilise des expressions de stratégie et la stratégie set-header pour ajouter des données utilisateur à la demande 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>

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

Si vous avez une stratégie au niveau global et une stratégie configurée pour une API, quand cette API est utilisée, les deux stratégies sont appliquées. 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 de base.

<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 va s’exécuter en premier. La find-and-replace stratégie s’exécuterait après toutes les stratégies dans une étendue plus large.

Filtrer le contenu de la réponse

La stratégie définie dans l’exemple suivant montre comment filtrer des éléments de données dans la charge utile de la réponse en fonction du produit associé à la demande.

L’extrait de code suppose que le contenu de la réponse est au format JSON et qu’il contient des propriétés de niveau racine nommées minutely, hourly, daily et flags.

<policies>
  <inbound>
    <base />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <choose>
      <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
        <!-- NOTE that we are not using preserveContent=true when deserializing response body stream into a JSON object since we don't intend to access it again. See details on /azure/api-management/api-management-transformation-policies#SetBody -->
        <set-body>
          @{
            var response = context.Response.Body.As<JObject>();
            foreach (var key in new [] {"minutely", "hourly", "daily", "flags"}) {
            response.Property (key).Remove ();
           }
          return response.ToString();
          }
    </set-body>
      </when>
    </choose>    
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>