Ekspresi kebijakan API Management

  • Artikel

BERLAKU UNTUK: Semua tingkatAN API Management

Artikel ini membahas sintaks ekspresi kebijakan di C# 7. Setiap ekspresi memiliki akses ke:

  • Variabel konteks yang disediakan secara implisit.
  • Subset yang diperbolehkan dari jenis .NET Framework.

Sintaks

  • Ekspresi pernyataan tunggal:
    • Diapit di @(expression), di mana expression merupakan adalah pernyataan ekspresi C# yang terbentuk dengan baik.
  • Ekspresi multi-pernyataan:
    • Diapit di @{expression}.
    • Semua jalur kode dalam ekspresi multi-pernyataan harus diakhiri dengan pernyataan return.

Contoh

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

}

Penggunaan

Kecuali jika kebijakan menentukan sebaliknya, ekspresi dapat digunakan sebagai nilai atribut atau nilai teks dalam kebijakan API Management mana pun.

Penting

Ketika kebijakan ditentukan, ekspresi kebijakan hanya memiliki verifikasi terbatas. Ekspresi dijalankan oleh gateway pada run-time. Setiap pengecualian yang dihasilkan oleh ekspresi kebijakan mengakibatkan kesalahan runtime.

Jenis .NET Framework yang diizinkan dalam ekspresi kebijakan

Tabel berikut ini mencantumkan jenis .NET Framework dan anggota yang diperbolehkan dalam ekspresi kebijakan.

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

Variabel konteks

Variabel context secara implisit tersedia dalam setiap ekspresi kebijakan. Anggotanya:

  • Memberikan informasi yang relevan dengan permintaan dan responsAPI, serta properti terkait.
  • Semuanya bersifat baca-saja.
Variabel Konteks Metode, properti, dan nilai parameter yang diizinkan
context Api: IApi

Deployment

Berlalu: TimeSpan - interval waktu antara nilai dari Timestamp dan waktu saat ini

GraphQL

LastError

Operation

Request

RequestId: Guid - pengidentifikasi permintaan unik

Response

Subscription

Timestamp: DateTime - titik waktu saat permintaan diterima

Tracing: bool - menunjukkan apakah pelacakan aktif atau nonaktif

Pengguna

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 (mengembalikan 'dikelola' untuk gateway terkelola)

Region: string

ServiceId: string

ServiceName: string

Certificates: IReadOnlyDictionary<string, X509Certificate2>
context.Deployment.Gateway Id: string (mengembalikan 'dikelola' untuk gateway terkelola)

InstanceId: string (mengembalikan 'dikelola' untuk gateway terkelola)

IsManaged: bool
context.GraphQL GraphQLArguments: IGraphQLDataObject

Parent: IGraphQLDataObject

Contoh
context.LastError Source: string

Reason: string

Message: string

Scope: string

Section: string

Path: string

PolicyId: string

Untuk informasi selengkapnya tentang context.LastError, lihat Penanganan kesalahan.
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 atau null jika permintaan tidak memiliki isi.

Certificate: System.Security.Cryptography.X509Certificates.X509Certificate2

Headers: IReadOnlyDictionary<string, string[]>

IpAddress: string

MatchedParameters: IReadOnlyDictionary<string, string>

Method: string

OriginalUrl: IUrl

Url: IUrl

PrivateEndpointConnection: IPrivateEndpointConnection atau null jika permintaan tidak datang dari koneksi titik akhir privat.
string context.Request.Headers.GetValueOrDefault(headerName: string, defaultValue: string) headerName: string

defaultValue: string

Mengembalikan nilai header permintaan yang dipisahkan koma atau defaultValue jika header tidak ditemukan.
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

Mengembalikan nilai header respons yang dipisahkan koma atau defaultValue jika header tidak ditemukan.
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

- Metode context.Request.Body.As<T> dan context.Response.Body.As<T> membaca isi pesan permintaan atau respons dalam jenis Tyang ditentukan .

-Atau-

AsFormUrlEncodedContent(bool preserveContent = false)

- Metode context.Request.Body.AsFormUrlEncodedContent() dan context.Response.Body.AsFormUrlEncodedContent() membaca data formulir yang dikodekan URL dalam isi pesan permintaan atau respons dan mengembalikan IDictionary<string, IList<string> objek. Objek yang didekodekan mendukung IDictionary operasi dan ekspresi berikut: ToQueryString(), , JsonConvert.SerializeObject()ToFormUrlEncodedContent().

Secara default, As<T> metode dan AsFormUrlEncodedContent() :
  • Gunakan aliran isi pesan asli.
  • Render tidak tersedia setelah kembali.

Untuk menghindarinya dan meminta metode beroperasi pada salinan aliran isi, atur preserveContent parameter ke true, seperti yang ditunjukkan dalam contoh untuk kebijakan set-body .
IPrivateEndpointConnection Name: string

GroupId: string

MemberName: string

Untuk informasi selengkapnya, lihat 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

Mengembalikan nilai parameter kueri yang dipisahkan koma atau defaultValue jika parameter tidak ditemukan.
IUserIdentity Id: string

Provider: string
IWorkspace Id: string

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

defaultValue: T

Mengembalikan nilai variabel yang ditransmisikan ke jenis T atau defaultValue jika variabel tidak ditemukan.

Metode ini memberikan pengecualian jika jenis yang ditentukan tidak cocok dengan jenis aktual dari variabel yang dikembalikan.
BasicAuthCredentials AsBasic(input: this string) input: string

Jika parameter input berisi nilai header permintaan Autentikasi Dasar HTTP yang valid, metode mengembalikan objek berjenis BasicAuthCredentials; jika tidak, metode mengembalikan null.
bool TryParseBasic(input: this string, result: out BasicAuthCredentials) input: string

result: out BasicAuthCredentials

Jika parameter input berisi nilai otorisasi Autentikasi Dasar HTTP yang valid di header permintaan, metode mengembalikan true dan parameter hasil berisi nilai berjenis BasicAuthCredentials; jika tidak, metode akan mengembalikan false.
BasicAuthCredentials Password: string

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

Jika parameter input berisi nilai token JWT yang valid, metode mengembalikan objek berjenis Jwt; jika tidak, metode akan mengembalikan null.
bool TryParseJwt(input: this string, result: out Jwt) input: string

result: out Jwt

Jika parameter input berisi nilai token JWT yang valid, metode mengembalikan true dan parameter hasil berisi nilai berjenis Jwt; jika tidak, metode akan mengembalikan 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

Mengembalikan nilai klaim yang dipisahkan koma atau defaultValue jika header tidak ditemukan.
byte[] Encrypt(input: this byte[], alg: string, key:byte[], iv:byte[]) input - plaintext yang akan dienkripsi

alg - nama algoritma enkripsi simetris

key - kunci enkripsi

iv - vektor inisialisasi

Mengembalikan plaintext terenkripsi.
byte[] Encrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm) input - plaintext yang akan dienkripsi

alg - algoritma enkripsi

Mengembalikan plaintext terenkripsi.
byte[] Encrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm, key:byte[], iv:byte[]) input - plaintext yang akan dienkripsi

alg - algoritma enkripsi

key - kunci enkripsi

iv - vektor inisialisasi

Mengembalikan plaintext terenkripsi.
byte[] Decrypt(input: this byte[], alg: string, key:byte[], iv:byte[]) input - teks cypher yang akan didekripsi

alg - nama algoritma enkripsi simetris

key - kunci enkripsi

iv - vektor inisialisasi

Mengembalikan plaintext.
byte[] Decrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm) input - teks cypher yang akan didekripsi

alg - algoritma enkripsi

Mengembalikan plaintext.
byte[] Decrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm, key:byte[], iv:byte[]) input - teks cypher yang akan didekripsi

alg - algoritma enkripsi

key - kunci enkripsi

iv - vektor inisialisasi

Mengembalikan plaintext.
bool VerifyNoRevocation(input: this System.Security.Cryptography.X509Certificates.X509Certificate2) Melakukan validasi rantai X.509 tanpa memeriksa status pencabutan sertifikat.

input - objek sertifikat

Mengembalikan true jika validasi berhasil; false jika validasi gagal.

Konten terkait

Untuk informasi selengkapnya tentang bekerja dengan kebijakan, lihat:

Untuk informasi selengkapnya:

  • Lihat cara memberikan informasi konteks ke layanan backend Anda. Gunakan kebijakan Atur parameter string kueri dan Atur header HTTP untuk menyediakan informasi ini.
  • Lihat cara menggunakan kebijakan Validasi JWT untuk mengotorisasi akses terlebih dahulu ke operasi berdasarkan klaim token.
  • Lihat cara menggunakan jejak API Inspector untuk mendeteksi bagaimana kebijakan dievaluasi dan hasil evaluasi tersebut.
  • Lihat cara menggunakan ekspresi dengan kebijakan Dapatkan dari cache dan Simpan ke cache untuk mengonfigurasi pembuatan cache respons API Management. Atur durasi yang cocok dengan pembuatan cache respons layanan backend seperti yang ditentukan oleh arahan Cache-Control layanan backend.
  • Lihat cara melakukan pemfilteran konten. Hapus elemen data dari respons yang diterima dari backend menggunakan kebijakan Alur kontrol dan Isi kumpulan.
  • Untuk mengunduh pernyataan kebijakan, lihat repo GitHub api-management-samples/policies.