Expressions de stratégie de la Gestion des API

  • Article

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

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.

Type 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, TryParse, ToString
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, GetAddressBytes, IsLoopback, 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, Length, Value
System.Text.RegularExpressions.CaptureCollection Count, Item
System.Text.RegularExpressions.Group Captures, Success
System.Text.RegularExpressions.GroupCollection Count, Item
System.Text.RegularExpressions.Match Empty, Groups, Result
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)
context.Api Id: string

IsCurrentRevision: bool

Name: string

Path: string

Revision: string

ServiceUrl: IUrl

Version: string

Workspace: IWorkspace
context.Deployment Gateway

GatewayId : string (retourne « managé » pour les passerelles managées)

Region: string

ServiceId: string

ServiceName: string

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

Workspace: IWorkspace
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
IApi Id: string

Name: string

Path: string

Protocols: IEnumerable<string>

ServiceUrl: IUrl

SubscriptionKeyParameterNames: ISubscriptionKeyParameterNames
IGraphQLDataObject TBD
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
IWorkspace Id: string

Name: 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 valide d’en-tête de jeton JWT, la méthode renvoie un objet de type Jwt ; sinon, la méthode renvoie null.
bool TryParseJwt(input: this string, result: out Jwt) input: string

result: out Jwt

Si le paramètre d’entrée contient une valeur valide d’en-tête de jeton JWT, la méthode renvoie true et le paramètre de résultats contient une valeur de type Jwt ; sinon, la méthode renvoie 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 de stratégies, consultez les pages :

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 une trace Inspecteur d’API pour détecter comment les stratégies sont évaluées et connaître 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.