Espressioni di criteri di Gestione API

La sintassi delle espressioni di criteri è C# 6.0. Ogni espressione ha accesso alla variabile context fornita implicitamente e a un subset autorizzato di tipi di .NET Framework.

Nota

Per ulteriori informazioni sulle espressioni di criteri, vedere il video Espressioni di criteri.

Per una dimostrazione relativa alla configurazione dei criteri usando le espressioni, vedere l'episodio 177 di Cloud Cover su altre funzionalità di Gestione API con Vlad Vinogradsky. Il video include le seguenti dimostrazioni di espressioni di criteri.

  • 10:30: informazioni su come applicare criteri al livello dell'API per fornire informazioni di contesto al servizio back-end usando i criteri Imposta parametro di stringa della query e Imposta intestazione HTTP. A 12:10 minuti viene illustrata una dimostrazione su come chiamare un'operazione nel portale per sviluppatori, dove è possibile vedere all'opera i criteri stessi.
    • 13:50: informazioni su come usare il criterio Convalida JWT per preautorizzare l'accesso alle operazioni in base alle attestazioni dei token. Passare a 15:00 minuti per vedere i criteri configurati nell'editor dei criteri e quindi a 18:50 minuti per una dimostrazione della chiamata di un'operazione dal portale per sviluppatori, con e senza il token di autorizzazione richiesto.
    • 21:00: informazioni su come usare una traccia di Controllo API per visualizzare il modo in cui i criteri vengono valutati e le valutazioni stesse.
    • 25:25: informazioni su come usare le espressioni di criteri con i criteri Recupera dalla cache e Archivia nella cache per configurare la durata della memorizzazione nella cache di Gestione API corrispondente alla memorizzazione delle risposte nella cache del serivzio back-end, come specificato dalla direttiva Cache-Control del servizio in questione.
    • 34:30: informazioni su come eseguire operazioni di filtro sui contenuti rimuovendo elementi dati dalla risposta ricevuta dal servizio back-end usando i criteri Flusso di controllo e Imposta corpo. Andare al minuto 31:50 per visualizzare una panoramica di The Dark Sky Forecast API, l'API usata in questa dimostrazione.
    • Le istruzioni dei criteri usate in questo video sono disponibili nel repository di github api-management-samples/policies.

Sintassi

Le espressioni a istruzione singola sono racchiuse tra @(expression), dove expression è un'istruzione di espressione C# ben formata.

Le espressioni a più istruzioni sono racchiuse tra @{expression}. Tutti i percorsi di codice all'interno di espressioni a più istruzioni devono terminare con un'istruzione return.

Esempi

@(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))   
  {   
    return Encoding.UTF8.GetString(Convert.FromBase64String(value));  
  }   
  else   
  {   
    return null;  
  }  
}  

Uso

Le espressioni possono essere usate come valori di attributo o valori di testo in uno qualsiasi dei criteri di Gestione API, salvo diversamente specificato dai criteri.

Importante

Si noti che quando si usano espressioni di criteri, è prevista solo una verifica limitata di tali espressioni quando i criteri vengono definiti. Poiché le espressioni vengono eseguite dal gateway al momento del runtime nella pipeline in entrata o in uscita, eventuali eccezioni di runtime generate dalle espressioni di criteri porteranno a un errore di runtime nella chiamata dell'API.

Tipi di .NET framework consentiti nelle espressioni di criteri

Nella tabella seguente sono elencati i tipi di .NET Framework e i relativi membri consentiti nelle espressioni di criteri.

Tipo CLR Metodi supportati
Newtonsoft.Json.Linq.Extensions Tutti i metodi sono supportati
Newtonsoft.Json.Linq.JArray Tutti i metodi sono supportati
Newtonsoft.Json.Linq.JConstructor Tutti i metodi sono supportati
Newtonsoft.Json.Linq.JContainer Tutti i metodi sono supportati
Newtonsoft.Json.Linq.JObject Tutti i metodi sono supportati
Newtonsoft.Json.Linq.JProperty Tutti i metodi sono supportati
Newtonsoft.Json.Linq.JRaw Tutti i metodi sono supportati
Newtonsoft.Json.Linq.JToken Tutti i metodi sono supportati
Newtonsoft.Json.Linq.JTokenType Tutti i metodi sono supportati
Newtonsoft.Json.Linq.JValue Tutti i metodi sono supportati
System.Collections.Generic.IReadOnlyCollection Tutti
System.Collections.Generic.IReadOnlyDictionary Tutti
System.Collections.Generic.ISet Tutti
System.Collections.Generic.KeyValuePair Chiave, valore
System.Collections.Generic.List Tutti
System.Collections.Generic.Queue Tutti
System.Collections.Generic.Stack Tutti
System.Convert Tutti
System.DateTime Tutti
System.DateTimeKind UTC
System.DateTimeOffset Tutti
System.Decimal Tutti
System.Double Tutti
System.Guid Tutti
System.IEnumerable Tutti
System.IEnumerator Tutti
System.Int16 Tutti
System.Int32 Tutti
System.Int64 Tutti
System.Linq.Enumerable Tutti i metodi sono supportati
System.Math Tutti
System.MidpointRounding Tutti
System.Nullable Tutti
System.Random Tutti
System.SByte Tutti
System.Security.Cryptography. HMACSHA384 Tutti
System.Security.Cryptography. HMACSHA512 Tutti
System.Security.Cryptography.HashAlgorithm Tutti
System.Security.Cryptography.HMAC Tutti
System.Security.Cryptography.HMACMD5 Tutti
System.Security.Cryptography.HMACSHA1 Tutti
System.Security.Cryptography.HMACSHA256 Tutti
System.Security.Cryptography.KeyedHashAlgorithm Tutti
System.Security.Cryptography.MD5 Tutti
System.Security.Cryptography.RNGCryptoServiceProvider Tutti
System.Security.Cryptography.SHA1 Tutti
System.Security.Cryptography.SHA1Managed Tutti
System.Security.Cryptography.SHA256 Tutti
System.Security.Cryptography.SHA256Managed Tutti
System.Security.Cryptography.SHA384 Tutti
System.Security.Cryptography.SHA384Managed Tutti
System.Security.Cryptography.SHA512 Tutti
System.Security.Cryptography.SHA512Managed Tutti
System.Single Tutti
System.String Tutti
System.StringSplitOptions Tutti
System.Text.Encoding Tutti
System.Text.RegularExpressions.Capture Indice, lunghezza, valore
System.Text.RegularExpressions.CaptureCollection Conteggio, elemento
System.Text.RegularExpressions.Group Acquisizioni, esito positivo
System.Text.RegularExpressions.GroupCollection Conteggio, elemento
System.Text.RegularExpressions.Match Empty, Groups, Result
System.Text.RegularExpressions.Regex .ctor, IsMatch, Match, Matches, Replace
System.Text.RegularExpressions.RegexOptions Compiled, IgnoreCase, IgnorePatternWhitespace, Multiline, None, RightToLeft, Singleline
System.TimeSpan Tutti
System.Tuple Tutti
System.UInt16 Tutti
System.UInt32 Tutti
System.UInt64 Tutti
System.Uri Tutti
System.Xml.Linq.Extensions Tutti i metodi sono supportati
System.Xml.Linq.XAttribute Tutti i metodi sono supportati
System.Xml.Linq.XCData Tutti i metodi sono supportati
System.Xml.Linq.XComment Tutti i metodi sono supportati
System.Xml.Linq.XContainer Tutti i metodi sono supportati
System.Xml.Linq.XDeclaration Tutti i metodi sono supportati
System.Xml.Linq.XDocument Tutti i metodi sono supportati
System.Xml.Linq.XDocumentType Tutti i metodi sono supportati
System.Xml.Linq.XElement Tutti i metodi sono supportati
System.Xml.Linq.XName Tutti i metodi sono supportati
System.Xml.Linq.XNamespace Tutti i metodi sono supportati
System.Xml.Linq.XNode Tutti i metodi sono supportati
System.Xml.Linq.XNodeDocumentOrderComparer Tutti i metodi sono supportati
System.Xml.Linq.XNodeEqualityComparer Tutti i metodi sono supportati
System.Xml.Linq.XObject Tutti i metodi sono supportati
System.Xml.Linq.XProcessingInstruction Tutti i metodi sono supportati
System.Xml.Linq.XText Tutti i metodi sono supportati
System.Xml.XmlNodeType Tutti

Variabile di contesto

Una variabile denominata context è disponibile in modo implicito in ogni espressione di criteri. I suoi membri forniscono informazioni riguardanti \request. Tutti i membri di context sono di sola lettura.

Variabile di contesto Metodi, proprietà e valori di parametro consentiti
context Api: IApi

Distribuzione

LastError

Operazione

Prodotto

Richiesta

RequestId: string

Response

Sottoscrizione

Tracing: bool

Utente

Variables:IReadOnlyDictionary

void Trace(message: string)
context.Api Id: string

Name: string

Path: string

ServiceUrl: IUrl
context.Deployment Region: string

ServiceName: string
context.LastError Source: string

Reason: string

Message: string

Scope: string

Section: string

Path: string

PolicyId: string

Per ulteriori informazioni su context.LastError, vedere Gestione degli errori.
context.Operation Id: string

Method: string

Name: string

UrlTemplate: string
context.Product Apis: IEnumerable

ApprovalRequired: bool

Groups: IEnumerable

Id: string

Name: string

State: enum ProductState {NotPublished, Published}

SubscriptionLimit: int?

SubscriptionRequired: bool
context.Request Body: IMessageBody

Certificate: System.Security.Cryptography.X509Certificates.X509Certificate2

Headers: IReadOnlyDictionary

IpAddress: string

MatchedParameters: IReadOnlyDictionary

Method: string

OriginalUrl:IUrl

Url: IUrl
string context.Request.Headers.GetValueOrDefault(headerName: string, defaultValue: string) headerName: string

defaultValue: string

Restituisce valori di intestazione di richiesta separati da virgole oppure defaultValue se non viene trovata l'intestazione.
context.Response Body: IMessageBody

Headers: IReadOnlyDictionary

StatusCode: int

StatusReason: string
string context.Response.Headers.GetValueOrDefault(headerName: string, defaultValue: string) headerName: string

defaultValue: string

Restituisce valori di intestazione di risposta separati da virgole oppure defaultValue se non viene trovata l'intestazione.
context.Subscription CreatedTime: DateTime

EndDate: DateTime?

Id: string

Key: string

Name: string

PrimaryKey: string

SecondaryKey: string

StartDate: DateTime?
context.User Email: string

FirstName: string

Groups: IEnumerable

Id: string

Identities: IEnumerable

LastName: string

Note: string

RegistrationDate: DateTime
IApi Id: string

Name: string

Path: string

Protocols: IEnumerable

ServiceUrl: IUrl

SubscriptionKeyParameterNames: ISubscriptionKeyParameterNames
IGroup Id: string

Name: string
IMessageBody As(preserveContent: bool = false): Where T: string, JObject, JToken, JArray, XNode, XElement, XDocument

I metodi context.Request.Body.As<T> e context.Response.Body.As<T> vengono usati per leggere il corpo dei messaggi di richiesta e di risposta in un tipo T specificato. Per impostazione predefinita, il metodo usa il flusso del corpo del messaggio originale e lo rende non disponibile dopo aver restituito un valore. Per evitarlo, far sì che il metodo venga eseguito su una copia del flusso del corpo impostando il parametro preserveContent su true. Per un esempio, vedere qui.
IUrl Host: string

Path: string

Port: int

Query: IReadOnlyDictionary

QueryString: string

Scheme: string
IUserIdentity Id: string

Provider: string
ISubscriptionKeyParameterNames Header: string

Query: string
string IUrl.Query.GetValueOrDefault(queryParameterName: string, defaultValue: string) queryParameterName: string

defaultValue: string

Restituisce valori di parametro separati da virgole oppure defaultValue se il parametro non viene trovato.
T context.Variables.GetValueOrDefault(variableName: string, defaultValue: T) variableName: string

defaultValue: T

Restituisce il valore della variabile nel tipo T oppure defaultValue se la variabile non viene trovata.

Questo metodo genera un'eccezione se il tipo specificato non corrisponde al tipo effettivo della variabile restituita.
BasicAuthCredentials AsBasic(input: this string) input: string

Se il parametro di input contiene un valore di intestazione di richiesta di autorizzazione Autenticazione HTTP di base valido, il metodo restituisce un oggetto di tipo BasicAuthCredentials; in caso contrario restituisce un valore null.
bool TryParseBasic(input: this string, result: out BasicAuthCredentials) input: string

result: out BasicAuthCredentials

Se il parametro di input contiene un valore di intestazione di richiesta di autorizzazione Autenticazione HTTP di base valido, il metodo restituisce un oggetto di tipo true e il parametro risultante contiene un valore di tipo BasicAuthCredentials; in caso contrario restituisce false.
BasicAuthCredentials Password: string

UserId: string
Jwt AsJwt(input: this string) input: string

Se il parametro di input contiene un valore di token JWT valido, il metodo restituisce un oggetto di tipo Jwt; in caso contrario restituisce null.
bool TryParseJwt(input: this string, result: out Jwt) input: string

result: out Jwt

Se il parametro di input contiene un valore di token JWT valido, il metodo restituisce true e il parametro del risultato contiene un valore di tipo Jwt; in caso contrario il metodo restituisce false.
Jwt Algorithm: string

Audience: IEnumerable

Claims: IReadOnlyDictionary

ExpirationTime: DateTime?

Id: string

Issuer: string

NotBefore: DateTime?

Subject: string

Type: string
string Jwt.Claims.GetValueOrDefault(claimName: string, defaultValue: string) claimName: string

defaultValue: string

Restituisce valori di attestazione separati da virgole oppure defaultValue se non viene trovata l'intestazione.

Passaggi successivi

Per altre informazioni sull'uso dei criteri, vedere Criteri di Gestione API.