Richtlinienausdrücke in API Management

  • Artikel

GILT FÜR: Alle API Management-Ebenen

In diesem Artikel wird die Syntax für Richtlinienausdrücke in C# 7 erläutert. Jeder Ausdruck besitzt Zugriff auf Folgendes:

Syntax

  • Ausdrücke mit einer einzelnen Anweisung:
    • Werden in @(expression) eingeschlossen, wobei expression eine wohlgeformte C#-Ausdrucksanweisung ist.
  • Ausdrücke mit mehreren Anweisungen:
    • Werden in @{expression} eingeschlossen.
    • Alle Codepfade in Ausdrücken mit mehreren Anweisungen müssen mit einer return-Anweisung enden.

Beispiele

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

}

Verwendung

Sofern in der Richtlinienreferenz nicht anders angegeben, können Ausdrücke als Attributwerte oder Textwerte in beliebigen API Management-Richtlinien verwendet werden.

Wichtig

Wenn die Richtlinie definiert wird, erhalten Richtlinienausdrücke nur eine eingeschränkte Überprüfung. Ausdrücke werden vom Gateway zur Laufzeit ausgeführt. Alle Ausnahmen, die von Richtlinienausdrücken generiert werden, führen zu einem Laufzeitfehler.

In Richtlinienausdrücken zulässige .NET Framework-Typen

Die folgende Tabelle enthält die .NET Framework-Typen und die Member, die in Richtlinienausdrücken zulässig sind.

type Unterstützte Member
Newtonsoft.Json.Formatting All
Newtonsoft.Json.JsonConvert SerializeObject, DeserializeObject
Newtonsoft.Json.Linq.Extensions Alle
Newtonsoft.Json.Linq.JArray Alle
Newtonsoft.Json.Linq.JConstructor Alle
Newtonsoft.Json.Linq.JContainer Alle
Newtonsoft.Json.Linq.JObject Alle
Newtonsoft.Json.Linq.JProperty Alle
Newtonsoft.Json.Linq.JRaw Alle
Newtonsoft.Json.Linq.JToken Alle
Newtonsoft.Json.Linq.JTokenType Alle
Newtonsoft.Json.Linq.JValue Alle
System.Array Alle
System.BitConverter Alle
System.Boolean Alle
System.Byte Alle
System.Char Alle
System.Collections.Generic.Dictionary<TKey, TValue> Alle
System.Collections.Generic.HashSet<T> Alle
System.Collections.Generic.ICollection<T> Alle
System.Collections.Generic.IDictionary<TKey, TValue> Alle
System.Collections.Generic.IEnumerable<T> Alle
System.Collections.Generic.IEnumerator<T> Alle
System.Collections.Generic.IList<T> Alle
System.Collections.Generic.IReadOnlyCollection<T> Alle
System.Collections.Generic.IReadOnlyDictionary<TKey, TValue> Alle
System.Collections.Generic.ISet<T> Alle
System.Collections.Generic.KeyValuePair<TKey, TValue> Alle
System.Collections.Generic.List<T> Alle
System.Collections.Generic.Queue<T> Alle
System.Collections.Generic.Stack<T> Alle
System.Convert Alle
System.DateTime (Konstruktor), 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 Alle
System.Decimal Alle
System.Double Alle
System.Enum Parse, TryParse, ToString
System.Exception All
System.Guid Alle
System.Int16 Alle
System.Int32 Alle
System.Int64 Alle
System.IO.StringReader Alle
System.IO.StringWriter Alle
System.Linq.Enumerable Alle
System.Math Alle
System.MidpointRounding All
System.Net.IPAddress AddressFamily, Equals, GetAddressBytes, IsLoopback, Parse, TryParse, ToString
System.Net.WebUtility Alle
System.Nullable Alle
System.Random Alle
System.SByte Alle
System.Security.Cryptography.AsymmetricAlgorithm Alle
System.Security.Cryptography.CipherMode Alle
System.Security.Cryptography.HashAlgorithm Alle
System.Security.Cryptography.HashAlgorithmName Alle
System.Security.Cryptography.HMAC Alle
System.Security.Cryptography.HMACMD5 Alle
System.Security.Cryptography.HMACSHA1 Alle
System.Security.Cryptography.HMACSHA256 Alle
System.Security.Cryptography.HMACSHA384 Alle
System.Security.Cryptography.HMACSHA512 Alle
System.Security.Cryptography.KeyedHashAlgorithm Alle
System.Security.Cryptography.MD5 Alle
System.Security.Cryptography.Oid Alle
System.Security.Cryptography.PaddingMode Alle
System.Security.Cryptography.RNGCryptoServiceProvider Alle
System.Security.Cryptography.RSA Alle
System.Security.Cryptography.RSAEncryptionPadding Alle
System.Security.Cryptography.RSASignaturePadding Alle
System.Security.Cryptography.SHA1 Alle
System.Security.Cryptography.SHA1Managed Alle
System.Security.Cryptography.SHA256 Alle
System.Security.Cryptography.SHA256Managed Alle
System.Security.Cryptography.SHA384 Alle
System.Security.Cryptography.SHA384Managed Alle
System.Security.Cryptography.SHA512 Alle
System.Security.Cryptography.SHA512Managed Alle
System.Security.Cryptography.SymmetricAlgorithm Alle
System.Security.Cryptography.X509Certificates.PublicKey Alle
System.Security.Cryptography.X509Certificates.RSACertificateExtensions Alle
System.Security.Cryptography.X509Certificates.X500DistinguishedName Name
System.Security.Cryptography.X509Certificates.X509Certificate Alle
System.Security.Cryptography.X509Certificates.X509Certificate2 Alle
System.Security.Cryptography.X509Certificates.X509ContentType Alle
System.Security.Cryptography.X509Certificates.X509NameType Alle
System.Single Alle
System.String Alle
System.StringComparer Alle
System.StringComparison Alle
System.StringSplitOptions Alle
System.Text.Encoding Alle
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 (Konstruktor), IsMatch, Match, Matches, Replace, Unescape, Split
System.Text.RegularExpressions.RegexOptions Alle
System.Text.StringBuilder Alle
System.TimeSpan Alle
System.TimeZone Alle
System.TimeZoneInfo.AdjustmentRule Alle
System.TimeZoneInfo.TransitionTime Alle
System.TimeZoneInfo Alle
System.Tuple Alle
System.UInt16 Alle
System.UInt32 Alle
System.UInt64 Alle
System.Uri Alle
System.UriPartial Alle
System.Xml.Linq.Extensions Alle
System.Xml.Linq.XAttribute Alle
System.Xml.Linq.XCData Alle
System.Xml.Linq.XComment Alle
System.Xml.Linq.XContainer Alle
System.Xml.Linq.XDeclaration Alle
System.Xml.Linq.XDocument Alle außer Load
System.Xml.Linq.XDocumentType Alle
System.Xml.Linq.XElement Alle
System.Xml.Linq.XName Alle
System.Xml.Linq.XNamespace Alle
System.Xml.Linq.XNode Alle
System.Xml.Linq.XNodeDocumentOrderComparer Alle
System.Xml.Linq.XNodeEqualityComparer Alle
System.Xml.Linq.XObject Alle
System.Xml.Linq.XProcessingInstruction Alle
System.Xml.Linq.XText Alle
System.Xml.XmlNodeType All

Context-Variable

Die context-Variable steht implizit in jedem Richtlinienausdruck zur Verfügung. Für ihre Member gilt:

  • Sie stellen Informationen bereit, die für die API-Anforderung und -Antwort und zugehörige Eigenschaften relevant sind.
  • Alle sind alle schreibgeschützt.
Kontextvariable Zulässige Methoden, Eigenschaften und Parameterwerte
context Api: IApi

Deployment

Elapsed: TimeSpan – Zeitintervall zwischen dem Wert von Timestamp und der aktuellen Uhrzeit

GraphQL

LastError

Operation

Request

RequestId: Guid – eindeutiger Anforderungsbezeichner

Response

Subscription

Timestamp: DateTime – Zeitpunkt des Empfangs der Anforderung

Tracing: bool – gibt an, ob die Ablaufverfolgung aktiviert oder deaktiviert ist

Benutzer

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 (gibt für verwaltete Gateways „managed“ zurück)

Region: string

ServiceId: string

ServiceName: string

Certificates: IReadOnlyDictionary<string, X509Certificate2>
context.Deployment.Gateway Id: string (gibt für verwaltete Gateways „managed“ zurück)

InstanceId: string (gibt für verwaltete Gateways „managed“ zurück)

IsManaged: bool
context.GraphQL GraphQLArguments: IGraphQLDataObject

Parent: IGraphQLDataObject

Beispiele
context.LastError Source: string

Reason: string

Message: string

Scope: string

Section: string

Path: string

PolicyId: string

Weitere Informationen zu context.LastError finden Sie unter Fehlerbehandlung.
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 oder null, wenn die Anforderung keinen Text enthält.

Certificate: System.Security.Cryptography.X509Certificates.X509Certificate2

Headers: IReadOnlyDictionary<string, string[]>

IpAddress: string

MatchedParameters: IReadOnlyDictionary<string, string>

Method: string

OriginalUrl: IUrl

Url: IUrl

PrivateEndpointConnection: IPrivateEndpointConnection oder null, wenn die Anforderung nicht von einer Verbindung mit privaten Endpunkten stammt.
string context.Request.Headers.GetValueOrDefault(headerName: string, defaultValue: string) headerName: string

defaultValue: string

Gibt durch Trennzeichen getrennte Anforderungsheaderwerte oder defaultValue zurück, wenn der Header nicht gefunden wurde.
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

Gibt durch Trennzeichen getrennte Antwortheaderwerte oder defaultValue zurück, wenn der Header nicht gefunden wurde.
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

- Die context.Request.Body.As<T>- und context.Response.Body.As<T>-Methoden lesen einen Anforderungs- oder Antwortnachrichtentext im angegebenen Typ T.

- Oder -

AsFormUrlEncodedContent(bool preserveContent = false)

- Die Methoden context.Request.Body.AsFormUrlEncodedContent() und context.Response.Body.AsFormUrlEncodedContent() lesen URL-codierte Formulardaten in einem Anforderungs- oder Antwortnachrichtentext und geben ein IDictionary<string, IList<string>-Objekt zurück. Das decodierte Objekt unterstützt IDictionary-Vorgänge und die folgenden Ausdrücke: ToQueryString(), JsonConvert.SerializeObject(), ToFormUrlEncodedContent().

Standardmäßig gilt für die Methoden As<T> und AsFormUrlEncodedContent() Folgendes:
  • Sie verwenden den ursprünglichen Nachrichtentextstream.
  • Sie rendern ihn nach der Rückgabe als nicht verfügbar.

Um dies zu vermeiden und in der Methode eine Kopie des Textdatenstroms zu verarbeiten, legen Sie den preserveContent-Parameter wie in den Beispielen zur Richtlinie set-body auf true fest.
IPrivateEndpointConnection Name: string

GroupId: string

MemberName: string

Weitere Informationen finden Sie in der REST-API.
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

Gibt durch Trennzeichen getrennte Abfrageparameterwerte oder defaultValue zurück, wenn der Parameter nicht gefunden wurde.
IUserIdentity Id: string

Provider: string
IWorkspace Id: string

Name: string
T context.Variables.GetValueOrDefault<T>(variableName: string, defaultValue: T) variableName: string

defaultValue: T

Gibt eine Variablenwertumwandlung in den Typ T oder defaultValue zurück, wenn die Variable nicht gefunden wird.

Diese Methode löst eine Ausnahme aus, wenn der angegebene Typ nicht mit dem tatsächlichen Typ der zurückgegebenen Variablen übereinstimmt.
BasicAuthCredentials AsBasic(input: this string) input: string

Wenn der Eingabeparameter einen gültigen Anforderungsheaderwert für die Autorisierung der HTTP-Standardauthentifizierung enthält, gibt die Methode ein Objekt des Typs BasicAuthCredentials zurück; andernfalls gibt die Methode NULL zurück.
bool TryParseBasic(input: this string, result: out BasicAuthCredentials) input: string

result: out BasicAuthCredentials

Wenn der Eingabeparameter einen gültigen Wert für die HTTP-Standardauthentifizierungsautorisierung im Anforderungsheader enthält, gibt die Methode true zurück, und der Ergebnisparameter enthält einen Wert des Typs BasicAuthCredentials. Andernfalls gibt die Methode false zurück.
BasicAuthCredentials Password: string

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

Wenn der Eingabeparameter einen gültigen JWT-Tokenwert enthält, gibt die Methode ein Objekt des Typs Jwt zurück; andernfalls gibt die Methode null zurück.
bool TryParseJwt(input: this string, result: out Jwt) input: string

result: out Jwt

Wenn der Eingabeparameter einen gültigen JWT-Tokenwert enthält, gibt die Methode true zurück, und der Ergebnisparameter enthält einen Wert des Typs Jwt; andernfalls gibt die Methode false zurück.
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

Gibt durch Trennzeichen getrennte Anspruchswerte oder defaultValue zurück, wenn der Header nicht gefunden wurde.
byte[] Encrypt(input: this byte[], alg: string, key:byte[], iv:byte[]) input – zu verschlüsselnder Klartext

alg – Name eines symmetrischen Verschlüsselungsalgorithmus

key – Verschlüsselungsschlüssel

iv – Initialisierungsvektor

Gibt verschlüsselten Klartext zurück.
byte[] Encrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm) input – zu verschlüsselnder Klartext

alg – Verschlüsselungsalgorithmus

Gibt verschlüsselten Klartext zurück.
byte[] Encrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm, key:byte[], iv:byte[]) input – zu verschlüsselnder Klartext

alg – Verschlüsselungsalgorithmus

key – Verschlüsselungsschlüssel

iv – Initialisierungsvektor

Gibt verschlüsselten Klartext zurück.
byte[] Decrypt(input: this byte[], alg: string, key:byte[], iv:byte[]) input – zu entschlüsselnder Verschlüsselungstext

alg – Name eines symmetrischen Verschlüsselungsalgorithmus

key – Verschlüsselungsschlüssel

iv – Initialisierungsvektor

Gibt Klartext zurück.
byte[] Decrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm) input – zu entschlüsselnder Verschlüsselungstext

alg – Verschlüsselungsalgorithmus

Gibt Klartext zurück.
byte[] Decrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm, key:byte[], iv:byte[]) input – zu entschlüsselnder Verschlüsselungstext

alg – Verschlüsselungsalgorithmus

key – Verschlüsselungsschlüssel

iv – Initialisierungsvektor

Gibt Klartext zurück.
bool VerifyNoRevocation(input: this System.Security.Cryptography.X509Certificates.X509Certificate2) Führt eine X.509-Kettenüberprüfung ohne Überprüfung des Zertifikatsperrungsstatus aus.

input – Zertifikatobjekt

Gibt true zurück, wenn die Überprüfung erfolgreich ist, false, wenn die Validierung fehlschlägt.

Zugehöriger Inhalt

Weitere Informationen zur Verwendung von Richtlinien finden Sie unter:

Weitere Informationen finden Sie unter:

  • Erfahren Sie, wie Kontextinformationen für Ihren Back-End-Dienst bereitgestellt werden. Verwenden Sie die Richtlinien Abfragezeichenfolgenparameter festlegen und HTTP-Header festlegen, um diese Informationen bereitzustellen.
  • Erfahren Sie, wie die Richtlinie JWT überprüfen verwendet wird, um den Zugriff auf Vorgänge basierend auf Tokenansprüchen vorab zu autorisieren.
  • Erfahren Sie, wie eine API-Inspektor-Ablaufverfolgung verwendet wird, um die Auswertung von Richtlinien und die Ergebnisse dieser Auswertungen anzuzeigen.
  • Erfahren Sie, wie Ausdrücke mit den Richtlinien Aus Cache abrufen und In Cache speichern verwendet werden, um das Zwischenspeichern von Antworten für API Management zu konfigurieren. Legen Sie eine Dauer fest, die dem Zwischenspeichern von Antworten des Back-End-Diensts entspricht, wie in der Cache-Control-Anweisung des Back-End-Diensts angegeben.
  • Erfahren Sie, wie Inhalte gefiltert werden. Entfernen Sie Datenelemente mit den Richtlinien Ablaufsteuerung und Text festlegen aus der vom Back-End empfangenen Antwort.
  • Informationen zum Herunterladen der Richtlinienanweisungen finden Sie im GitHub-Repository unter api-management-samples/policies.