Expressions de stratégie de la Gestion des API

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

Cet article décrit la syntaxe des expressions de stratégie dans C# 7. Chaque expression a accès à :

• La variable de contexte fournie implicitement.
• Un sous-ensemble autorisé de types .NET Framework.

Syntaxe

• Expressions à instruction unique :
  • Inclus dans @(expression), où expression est une instruction d’expression C# bien formée.
• Expressions à plusieurs instructions :
  • Inclus dans @{expression}.
  • Tous les chemins d’accès de code au sein des expressions à instructions multiples doivent se terminer par une instruction return.

Exemples

@(true)

@((1+1).ToString())

@("Hi There".Length)

@(Regex.Match(context.Response.Headers.GetValueOrDefault("Cache-Control",""), @"max-age=(?<maxAge>\d+)").Groups["maxAge"]?.Value)

@(context.Variables.ContainsKey("maxAge") ? int.Parse((string)context.Variables["maxAge"]) : 3600)

@{
  string[] value;
  if (context.Request.Headers.TryGetValue("Authorization", out value))
  {
      if(value != null && value.Length > 0)
      {
          return Encoding.UTF8.GetString(Convert.FromBase64String(value[0]));
      }
  }
  return null;

}

Utilisation

Sauf si la référence de stratégie spécifie le contraire, les expressions peuvent être utilisées comme valeurs d’attribut ou valeurs de texte dans l’une des stratégies de la Gestion des API.

Important

Lorsque la stratégie est définie, les expressions de stratégie ne disposent que d’une vérification limitée. Les expressions sont exécutées par la passerelle au moment de l’exécution. Toutes les exceptions générées par les expressions de stratégie entraînent une erreur d’exécution.

Types .NET Framework autorisés dans les expressions de stratégie

Le tableau suivant liste les types .NET Framework et les membres autorisés dans les expressions de stratégie.

Catégorie	Membres pris en charge
Newtonsoft.Json.Formatting	Tous
Newtonsoft.Json.JsonConvert	SerializeObject, DeserializeObject
Newtonsoft.Json.Linq.Extensions	Tous
Newtonsoft.Json.Linq.JArray	Tous
Newtonsoft.Json.Linq.JConstructor	Tous
Newtonsoft.Json.Linq.JContainer	Tous
Newtonsoft.Json.Linq.JObject	Tous
Newtonsoft.Json.Linq.JProperty	Tous
Newtonsoft.Json.Linq.JRaw	Tous
Newtonsoft.Json.Linq.JToken	Tous
Newtonsoft.Json.Linq.JTokenType	Tous
Newtonsoft.Json.Linq.JValue	Tous
System.Array	Tous
System.BitConverter	Tous
System.Boolean	Tous
System.Byte	Tous
System.Char	Tous
System.Collections.Generic.Dictionary<TKey, TValue>	Tous
System.Collections.Generic.HashSet<T>	Tous
System.Collections.Generic.ICollection<T>	Tous
System.Collections.Generic.IDictionary<TKey, TValue>	Tous
System.Collections.Generic.IEnumerable<T>	Tous
System.Collections.Generic.IEnumerator<T>	Tous
System.Collections.Generic.IList<T>	Tous
System.Collections.Generic.IReadOnlyCollection<T>	Tous
System.Collections.Generic.IReadOnlyDictionary<TKey, TValue>	Tous
System.Collections.Generic.ISet<T>	Tous
System.Collections.Generic.KeyValuePair<TKey, TValue>	Tous
System.Collections.Generic.List<T>	Tous
System.Collections.Generic.Queue<T>	Tous
System.Collections.Generic.Stack<T>	Tous
System.Convert	Tous
System.DateTime	(Constructeur), Add, AddDays, AddHours, AddMilliseconds, AddMinutes, AddMonths, AddSeconds, AddTicks, AddYears, Date, Day, DayOfWeek, DayOfYear, DaysInMonth, Hour, IsDaylightSavingTime, IsLeapYear, MaxValue, Millisecond, Minute, MinValue, Month, Now, Parse, Second, Subtract, Ticks, TimeOfDay, Today, ToString, UtcNow, Year
System.DateTimeKind	Utc
System.DateTimeOffset	Tous
System.Decimal	Tous
System.Double	Tous
System.Enum	Parse, , TryParseToString
System.Exception	Tous
System.Guid	Tous
System.Int16	Tous
System.Int32	Tous
System.Int64	Tous
System.IO.StringReader	Tous
System.IO.StringWriter	Tous
System.Linq.Enumerable	Tous
System.Math	Tous
System.MidpointRounding	Tous
System.Net.IPAddress	AddressFamily, Equals, , GetAddressBytesIsLoopback, Parse, , TryParse,ToString
System.Net.WebUtility	Tous
System.Nullable	Tous
System.Random	Tous
System.SByte	Tous
System.Security.Cryptography.AsymmetricAlgorithm	Tous
System.Security.Cryptography.CipherMode	Tous
System.Security.Cryptography.HashAlgorithm	Tous
System.Security.Cryptography.HashAlgorithmName	Tous
System.Security.Cryptography.HMAC	Tous
System.Security.Cryptography.HMACMD5	Tous
System.Security.Cryptography.HMACSHA1	Tous
System.Security.Cryptography.HMACSHA256	Tous
System.Security.Cryptography.HMACSHA384	Tous
System.Security.Cryptography.HMACSHA512	Tous
System.Security.Cryptography.KeyedHashAlgorithm	Tous
System.Security.Cryptography.MD5	Tous
System.Security.Cryptography.Oid	Tous
System.Security.Cryptography.PaddingMode	Tous
System.Security.Cryptography.RNGCryptoServiceProvider	Tous
System.Security.Cryptography.RSA	Tous
System.Security.Cryptography.RSAEncryptionPadding	Tous
System.Security.Cryptography.RSASignaturePadding	Tous
System.Security.Cryptography.SHA1	Tous
System.Security.Cryptography.SHA1Managed	Tous
System.Security.Cryptography.SHA256	Tous
System.Security.Cryptography.SHA256Managed	Tous
System.Security.Cryptography.SHA384	Tous
System.Security.Cryptography.SHA384Managed	Tous
System.Security.Cryptography.SHA512	Tous
System.Security.Cryptography.SHA512Managed	Tous
System.Security.Cryptography.SymmetricAlgorithm	Tous
System.Security.Cryptography.X509Certificates.PublicKey	Tous
System.Security.Cryptography.X509Certificates.RSACertificateExtensions	Tous
System.Security.Cryptography.X509Certificates.X500DistinguishedName	Name
System.Security.Cryptography.X509Certificates.X509Certificate	Tous
System.Security.Cryptography.X509Certificates.X509Certificate2	Tous
System.Security.Cryptography.X509Certificates.X509ContentType	Tous
System.Security.Cryptography.X509Certificates.X509NameType	Tous
System.Single	Tous
System.String	Tous
System.StringComparer	Tous
System.StringComparison	Tous
System.StringSplitOptions	Tous
System.Text.Encoding	Tous
System.Text.RegularExpressions.Capture	Index, , LengthValue
System.Text.RegularExpressions.CaptureCollection	Count, Item
System.Text.RegularExpressions.Group	Captures, Success
System.Text.RegularExpressions.GroupCollection	Count, Item
System.Text.RegularExpressions.Match	Empty, , GroupsResult
System.Text.RegularExpressions.Regex	(Constructeur), IsMatch, Match, Matches, Replace, Unescape, Split
System.Text.RegularExpressions.RegexOptions	Tous
System.Text.StringBuilder	Tous
System.TimeSpan	Tous
System.TimeZone	Tous
System.TimeZoneInfo.AdjustmentRule	Tous
System.TimeZoneInfo.TransitionTime	Tous
System.TimeZoneInfo	Tous
System.Tuple	Tous
System.UInt16	Tous
System.UInt32	Tous
System.UInt64	Tous
System.Uri	Tous
System.UriPartial	Tous
System.Xml.Linq.Extensions	Tous
System.Xml.Linq.XAttribute	Tous
System.Xml.Linq.XCData	Tous
System.Xml.Linq.XComment	Tous
System.Xml.Linq.XContainer	Tous
System.Xml.Linq.XDeclaration	Tous
System.Xml.Linq.XDocument	Tous sauf Load
System.Xml.Linq.XDocumentType	Tous
System.Xml.Linq.XElement	Tous
System.Xml.Linq.XName	Tous
System.Xml.Linq.XNamespace	Tous
System.Xml.Linq.XNode	Tous
System.Xml.Linq.XNodeDocumentOrderComparer	Tous
System.Xml.Linq.XNodeEqualityComparer	Tous
System.Xml.Linq.XObject	Tous
System.Xml.Linq.XProcessingInstruction	Tous
System.Xml.Linq.XText	Tous
System.Xml.XmlNodeType	Tous

Variable contextuelle

La variable context est implicitement disponible dans toutes les expressions de stratégie. Ses membres :

• Fournissent des informations relatives à la demande et à la réponse de l’API, ainsi que les propriétés associées.
• Sont en lecture seule.

Variable de contexte	Méthodes, propriétés et valeurs de paramètres autorisées
context	Api: IApi Deployment Écoulé : TimeSpanintervalle de temps entre la valeur Timestamp et l’heure actuelle GraphQL LastError Operation Request RequestId: Guid : identificateur de demande unique Response Subscription Timestamp : DateTime : point dans le temps où la requête a été reçue Tracing : bool : indique si le traçage est activé ou désactivé Utilisateur Variables: IReadOnlyDictionary<string, object> void Trace(message: string) Workspace
context.Api	Id: string IsCurrentRevision: bool Name: string Path: string Revision: string ServiceUrl: IUrl Version: string
context.Deployment	Gateway GatewayId : string (retourne « managé » pour les passerelles managées) Region: string ServiceId: string ServiceName: string SustainabilityInfo Certificates: IReadOnlyDictionary<string, X509Certificate2>
context.Deployment.Gateway	Id : string (retourne « managé » pour les passerelles managées) InstanceId : string (retourne « managé » pour les passerelles managées) IsManaged: bool
context.Deployment.SustainabilityInfo	CurrentCarbonIntensity: Enum CarbonIntensityCategory
context.GraphQL	GraphQLArguments: IGraphQLDataObject Parent: IGraphQLDataObject Exemples
context.LastError	Source: string Reason: string Message: string Scope: string Section: string Path: string PolicyId: string Pour plus d’informations sur context.LastError, consultez Gestion des erreurs.
context.Operation	Id: string Method: string Name: string UrlTemplate: string
context.Product	ApprovalRequired: bool Groups: IEnumerable<IGroup> Id: string Name: string State: enum ProductState {NotPublished, Published} SubscriptionsLimit: int? SubscriptionRequired: bool
context.Request	Body : IMessageBody ou null si la requête n’a pas de corps. Certificate: System.Security.Cryptography.X509Certificates.X509Certificate2 Headers: IReadOnlyDictionary<string, string[]> IpAddress: string MatchedParameters: IReadOnlyDictionary<string, string> Method: string OriginalUrl: IUrl Url: IUrl PrivateEndpointConnection : IPrivateEndpointConnection ou null si la requête ne provient pas d’une connexion de point de terminaison privé.
string context.Request.Headers.GetValueOrDefault(headerName: string, defaultValue: string)	headerName: string defaultValue: string Renvoie des valeurs d’en-tête de demande séparées par des virgules ou defaultValue si l’en-tête est introuvable.
context.Response	Body: IMessageBody Headers: IReadOnlyDictionary<string, string[]> StatusCode: int StatusReason: string
string context.Response.Headers.GetValueOrDefault(headerName: string, defaultValue: string)	headerName: string defaultValue: string Renvoie des valeurs d’en-tête de réponse séparées par des virgules ou defaultValue si l’en-tête est introuvable.
context.Subscription	CreatedDate: DateTime EndDate: DateTime? Id: string Key: string Name: string PrimaryKey: string SecondaryKey: string StartDate: DateTime?
context.User	Email: string FirstName: string Groups: IEnumerable<IGroup> Id: string Identities: IEnumerable<IUserIdentity> LastName: string Note: string RegistrationDate: DateTime
context.Workspace	Id: string Name: string
IApi	Id: string Name: string Path: string Protocols: IEnumerable<string> ServiceUrl: IUrl SubscriptionKeyParameterNames: ISubscriptionKeyParameterNames
IGraphQLDataObject	À déterminer
IGroup	Id: string Name: string
IMessageBody	As<T>(bool preserveContent = false): Where T: string, byte[], JObject, JToken, JArray, XNode, XElement, XDocument - Les méthodes context.Request.Body.As<T>etcontext.Response.Body.As<T>lisent un corps de message de requête et de réponse dans un type T spécifié. - Ou - AsFormUrlEncodedContent(bool preserveContent = false) - Les context.Request.Body.AsFormUrlEncodedContent() méthodes et context.Response.Body.AsFormUrlEncodedContent() lisent les données de formulaire encodées par URL dans un corps de message de demande ou de réponse et retournent un objetIDictionary<string, IList<string>. L’objet décodé prend en charge IDictionary les opérations et les expressions suivantes : ToQueryString(), JsonConvert.SerializeObject(), ToFormUrlEncodedContent(). Par défaut, les As<T> méthodes et AsFormUrlEncodedContent() : Utilise le flux du corps du message d’origine. Le rend non disponible après son retour. Pour éviter cela et faire en sorte que la méthode agisse sur une copie du flux du corps, définissez le paramètre preserveContent sur true, comme dans les exemples fournis pour la stratégie set-body.
IPrivateEndpointConnection	Name: string GroupId: string MemberName: string Pour plus d’informations, consultez API REST.
IUrl	Host: string Path: string Port: int Query: IReadOnlyDictionary<string, string[]> QueryString: string Scheme: string
ISubscriptionKeyParameterNames	Header: string Query: string
string IUrl.Query.GetValueOrDefault(queryParameterName: string, defaultValue: string)	queryParameterName: string defaultValue: string Renvoie des valeurs de paramètre de requête séparées par des virgules ou defaultValue si le paramètre est introuvable.
IUserIdentity	Id: string Provider: string
T context.Variables.GetValueOrDefault<T>(variableName: string, defaultValue: T)	variableName: string defaultValue: T Renvoie la valeur de variable avec forçage de type T ou defaultValue si la variable est introuvable. Cette méthode lève une exception si le type spécifié ne correspond pas au type réel de la variable renvoyée.
BasicAuthCredentials AsBasic(input: this string)	input: string Si le paramètre d’entrée contient une valeur valide d’en-tête de demande d’authentification de base HTTP, la méthode renvoie un objet de type BasicAuthCredentials ; sinon, la méthode renvoie Null.
bool TryParseBasic(input: this string, result: out BasicAuthCredentials)	input: string result: out BasicAuthCredentials Si le paramètre d’entrée contient une valeur valide d’autorisation d’authentification de base HTTP dans l’en-tête de demande, la méthode renvoie true et le paramètre de résultats contient une valeur de type BasicAuthCredentials ; sinon, la méthode renvoie false.
BasicAuthCredentials	Password: string UserId: string
Jwt AsJwt(input: this string)	input: string Si le paramètre d’entrée contient une valeur JWT valide, la méthode retourne un objet de type Jwt; sinon, la méthode retourne null.
bool TryParseJwt(input: this string, result: out Jwt)	input: string result: out Jwt Si le paramètre d’entrée contient une valeur JWT valide, la méthode retourne true et le paramètre de résultat contient une valeur de type Jwt; sinon, la méthode retourne false.
Jwt	Algorithm: string Audiences: IEnumerable<string> Claims: IReadOnlyDictionary<string, string[]> ExpirationTime: DateTime? Id: string Issuer: string IssuedAt: DateTime? NotBefore: DateTime? Subject: string Type: string
string Jwt.Claims.GetValueOrDefault(claimName: string, defaultValue: string)	claimName: string defaultValue: string Renvoie des valeurs de revendication séparées par des virgules ou defaultValue si l’en-tête est introuvable.
byte[] Encrypt(input: this byte[], alg: string, key:byte[], iv:byte[])	input - texte en clair à chiffrer alg - nom de l'algorithme de chiffrement symétrique key - clé de chiffrement iv - vecteur d’initialisation Renvoie un texte brut chiffré.
byte[] Encrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm)	input - texte en clair à chiffrer alg - algorithme de chiffrement Renvoie un texte brut chiffré.
byte[] Encrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm, key:byte[], iv:byte[])	input - texte en clair à chiffrer alg - algorithme de chiffrement key - clé de chiffrement iv - vecteur d’initialisation Renvoie un texte brut chiffré.
byte[] Decrypt(input: this byte[], alg: string, key:byte[], iv:byte[])	input - texte de code à déchiffrer alg - nom de l'algorithme de chiffrement symétrique key - clé de chiffrement iv - vecteur d’initialisation Renvoie un texte brut.
byte[] Decrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm)	input - texte de code à déchiffrer alg - algorithme de chiffrement Renvoie un texte brut.
byte[] Decrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm, key:byte[], iv:byte[])	input - texte de code à déchiffrer alg - algorithme de chiffrement key - clé de chiffrement iv - vecteur d’initialisation Renvoie un texte brut.
bool VerifyNoRevocation(input: this System.Security.Cryptography.X509Certificates.X509Certificate2)	Effectue une validation de la chaîne X.509 sans vérifier l’état de révocation du certificat. input - objet de certificat Renvoie true si la validation réussit et false si elle échoue.

Contenu connexe

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

• Tutoriel : Transformer et protéger votre API
• Référence de stratégie pour obtenir la liste complète des instructions et des paramètres de stratégie
• Expressions de stratégie
• Définir ou modifier des stratégies
• Réutilisation de configurations de stratégie
• Référentiel d’extrait de stratégie
• Dépôt de terrain de jeu de stratégie
• Kit de ressources des stratégies Gestion des API Azure
• Obtenez de l’aide de Copilot pour créer, expliquer et dépanner des politiques

Pour plus d'informations :

• Découvrez comment fournir des informations de contexte à votre service backend. Utilisez les stratégies Set query string parameter et Set HTTP header pour fournir ces informations.
• Découvrez comment utiliser la stratégie Validate JWT pour pré-autoriser l’accès aux opérations à partir de revendications de jetons.
• Découvrez comment utiliser le suivi des API pour détecter la façon dont les stratégies sont évaluées et les résultats de ces évaluations.
• Découvrez comment utiliser les expressions avec les stratégies Get from cache et Store to cache pour configurer la durée de mise en cache des réponses de Gestion des API. Définissez une durée qui correspond à la mise en cache des réponses du service principal comme le spécifie la directive Cache-Control du service principal.
• Découvrez comment effectuer le filtrage de contenu. Supprimez des éléments de données de la réponse reçue du service principal à l’aide des stratégies Control flow et Set body.
• Pour télécharger les instructions de stratégie, consultez le référentiel GitHub api-management-samples/policies.