api-management-policy-expressions.md

title	description	services	documentationcenter	author	manager	editor	ms.assetid	ms.service	ms.workload	ms.tgt_pltfrm	ms.devlang	ms.topic	ms.date	ms.author
Azure API Management policy expressions | Microsoft Docs	Learn about policy expressions in Azure API Management.	api-management		vladvino	erikre		ea160028-fc04-4782-aa26-4b8329df3448	api-management	mobile	na	na	article	11/28/2017	apimpm

API Management policy expressions

This article discusses policy expressions syntax is C# 7. Each expression has access to the implicitly provided context variable and an allowed subset of .NET Framework types.

For more information:

• See how to supply context information to your backend service. Use the Set query string parameter and Set HTTP header policies to supply this information.
• See how to use the Validate JWT policy to pre-authorize access to operations based on token claims.
• See how to use an API Inspector trace to see how policies are evaluated and the results of those evaluations.
• See how to use expressions with the Get from cache and Store to cache policies to configure API Management response caching. Set a duration that matches the response caching of the backend service as specified by the backed service's Cache-Control directive.
• See how to perform content filtering. Remove data elements from the response received from the backend using the Control flow and Set body policies.
• To download the policy statements, see the api-management-samples/policies github repo.

Syntax

Single statement expressions are enclosed in @(expression), where expression is a well-formed C# expression statement.

Multi-statement expressions are enclosed in @{expression}. All code paths within multi-statement expressions must end with a return statement.

Examples

@(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;  
  }  
}  

Usage

Expressions can be used as attribute values or text values in any API Management policies (unless the policy reference specifies otherwise).

Important

When you use policy expressions, there is only limited verification of the policy expressions when the policy is defined. Expressions are executed by the gateway at run-time, any exceptions generated by policy expressions result in a runtime error.

.NET Framework types allowed in policy expressions

The following table lists the .NET Framework types and their members that are allowed in policy expressions.

CLR type	Supported methods
Newtonsoft.Json.Linq.Extensions	All methods are supported
Newtonsoft.Json.Linq.JArray	All methods are supported
Newtonsoft.Json.Linq.JConstructor	All methods are supported
Newtonsoft.Json.Linq.JContainer	All methods are supported
Newtonsoft.Json.Linq.JObject	All methods are supported
Newtonsoft.Json.Linq.JProperty	All methods are supported
Newtonsoft.Json.Linq.JRaw	All methods are supported
Newtonsoft.Json.Linq.JToken	All methods are supported
Newtonsoft.Json.Linq.JTokenType	All methods are supported
Newtonsoft.Json.Linq.JValue	All methods are supported
System.Collections.Generic.IReadOnlyCollection<T>	All
System.Collections.Generic.IReadOnlyDictionary<TKey, TValue>	All
System.Collections.Generic.ISet<TKey, TValue>	All
System.Collections.Generic.KeyValuePair<TKey, TValue>	Key, Value
System.Collections.Generic.List<TKey, TValue>	All
System.Collections.Generic.Queue<TKey, TValue>	All
System.Collections.Generic.Stack<TKey, TValue>	All
System.Convert	All
System.DateTime	All
System.DateTimeKind	Utc
System.DateTimeOffset	All
System.Decimal	All
System.Double	All
System.Guid	All
System.IEnumerable<T>	All
System.IEnumerator<T>	All
System.Int16	All
System.Int32	All
System.Int64	All
System.Linq.Enumerable<T>	All methods are supported
System.Math	All
System.MidpointRounding	All
System.Nullable<T>	All
System.Random	All
System.SByte	All
System.Security.Cryptography. HMACSHA384	All
System.Security.Cryptography. HMACSHA512	All
System.Security.Cryptography.HashAlgorithm	All
System.Security.Cryptography.HMAC	All
System.Security.Cryptography.HMACMD5	All
System.Security.Cryptography.HMACSHA1	All
System.Security.Cryptography.HMACSHA256	All
System.Security.Cryptography.KeyedHashAlgorithm	All
System.Security.Cryptography.MD5	All
System.Security.Cryptography.RNGCryptoServiceProvider	All
System.Security.Cryptography.SHA1	All
System.Security.Cryptography.SHA1Managed	All
System.Security.Cryptography.SHA256	All
System.Security.Cryptography.SHA256Managed	All
System.Security.Cryptography.SHA384	All
System.Security.Cryptography.SHA384Managed	All
System.Security.Cryptography.SHA512	All
System.Security.Cryptography.SHA512Managed	All
System.Single	All
System.String	All
System.StringSplitOptions	All
System.Text.Encoding	All
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	(Constructor),IsMatch, Match, Matches, Replace
System.Text.RegularExpressions.RegexOptions	Compiled, IgnoreCase, IgnorePatternWhitespace, Multiline, None, RightToLeft, Singleline
System.TimeSpan	All
System.Tuple	All
System.UInt16	All
System.UInt32	All
System.UInt64	All
System.Uri	All
System.Xml.Linq.Extensions	All methods are supported
System.Xml.Linq.XAttribute	All methods are supported
System.Xml.Linq.XCData	All methods are supported
System.Xml.Linq.XComment	All methods are supported
System.Xml.Linq.XContainer	All methods are supported
System.Xml.Linq.XDeclaration	All methods are supported
System.Xml.Linq.XDocument	All methods are supported
System.Xml.Linq.XDocumentType	All methods are supported
System.Xml.Linq.XElement	All methods are supported
System.Xml.Linq.XName	All methods are supported
System.Xml.Linq.XNamespace	All methods are supported
System.Xml.Linq.XNode	All methods are supported
System.Xml.Linq.XNodeDocumentOrderComparer	All methods are supported
System.Xml.Linq.XNodeEqualityComparer	All methods are supported
System.Xml.Linq.XObject	All methods are supported
System.Xml.Linq.XProcessingInstruction	All methods are supported
System.Xml.Linq.XText	All methods are supported
System.Xml.XmlNodeType	All

Context variable

A variable named context is implicitly available in every policy expression. Its members provide information pertinent to the \request. All of the context members are read-only.

Context Variable	Allowed methods, properties, and parameter values
context	Api: IApi Deployment Elapsed: TimeSpan - time interval between the value of Timestamp and current time LastError Operation Product Request RequestId: Guid - unique request identifier Response Subscription Timestamp: DateTime - point in time when request was received Tracing: bool - indicates if tracing is on or off User Variables: IReadOnlyDictionary<string, object> void Trace(message: string)
context.Api	Id: string IsCurrentRevision: bool Name: string Path: string Revision: string ServiceUrl: IUrl Version: string
context.Deployment	Region: string ServiceName: string Certificates: IReadOnlyDictionary<string, X509Certificate2>
context.LastError	Source: string Reason: string Message: string Scope: string Section: string Path: string PolicyId: string For more information about context.LastError, see Error handling.
context.Operation	Id: string Method: string Name: string UrlTemplate: string
context.Product	Apis: IEnumerable<IApi> ApprovalRequired: bool Groups: IEnumerable<IGroup> 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<string, string[]> IpAddress: string MatchedParameters: IReadOnlyDictionary<string, string> Method: string OriginalUrl:IUrl Url: IUrl
string context.Request.Headers.GetValueOrDefault(headerName: string, defaultValue: string)	headerName: string defaultValue: string Returns comma-separated request header values or defaultValue if the header is not found.
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 Returns comma-separated response header values or defaultValue if the header is not found.
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<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
IGroup	Id: string Name: string
IMessageBody	As<T>(preserveContent: bool = false): Where T: string, JObject, JToken, JArray, XNode, XElement, XDocument The context.Request.Body.As<T> and context.Response.Body.As<T> methods are used to read a request and response message bodies in a specified type T. By default the method uses the original message body stream and renders it unavailable after it returns. To avoid that by having the method operate on a copy of the body stream, set the preserveContent parameter to true. Go here to see an example.
IUrl	Host: string Path: string Port: int Query: IReadOnlyDictionary<string, string[]> 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 Returns comma-separated query parameter values or defaultValue if the parameter is not found.
T context.Variables.GetValueOrDefault<T>(variableName: string, defaultValue: T)	variableName: string defaultValue: T Returns variable value cast to type T or defaultValue if the variable is not found. This method throws an exception if the specified type does not match the actual type of the returned variable.
BasicAuthCredentials AsBasic(input: this string)	input: string If the input parameter contains a valid HTTP Basic Authentication authorization request header value, the method returns an object of type BasicAuthCredentials; otherwise the method returns null.
bool TryParseBasic(input: this string, result: out BasicAuthCredentials)	input: string result: out BasicAuthCredentials If the input parameter contains a valid HTTP Basic Authentication authorization value in the request header the method returns true and the result parameter contains a value of type BasicAuthCredentials; otherwise the method returns false.
BasicAuthCredentials	Password: string UserId: string
Jwt AsJwt(input: this string)	input: string If the input parameter contains a valid JWT token value, the method returns an object of type Jwt; otherwise the method returns null.
bool TryParseJwt(input: this string, result: out Jwt)	input: string result: out Jwt If the input parameter contains a valid JWT token value, the method returns true and the result parameter contains a value of type Jwt; otherwise the method returns false.
Jwt	Algorithm: string Audience: IEnumerable<string> Claims: IReadOnlyDictionary<string, string[]> ExpirationTime: DateTime? Id: string Issuer: string NotBefore: DateTime? Subject: string Type: string
string Jwt.Claims.GetValueOrDefault(claimName: string, defaultValue: string)	claimName: string defaultValue: string Returns comma-separated claim values or defaultValue if the header is not found.
byte[] Encrypt(input: this byte[], alg: string, key:byte[], iv:byte[])	input - plaintext to be encrypted alg - name of a symmetric encryption algorithm key - encryption key iv - initialization vector Returns encrypted plaintext.
byte[] Encrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm)	input - plaintext to be encrypted alg - encryption algorithm Returns encrypted plaintext.
byte[] Encrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm, key:byte[], iv:byte[])	input - plaintext to be encrypted alg - encryption algorithm key - encryption key iv - initialization vector Returns encrypted plaintext.
byte[] Decrypt(input: this byte[], alg: string, key:byte[], iv:byte[])	input - cypher text to be decrypted alg - name of a symmetric encryption algorithm key - encryption key iv - initialization vector Returns plaintext.
byte[] Decrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm)	input - cypher text to be decrypted alg - encryption algorithm Returns plaintext.
byte[] Decrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm, key:byte[], iv:byte[])	input - input - cypher text to be decrypted alg - encryption algorithm key - encryption key iv - initialization vector Returns plaintext.

Next steps

For more information working with policies, see:

• Policies in API Management
• Transform APIs
• Policy Reference for a full list of policy statements and their settings
• Policy samples