Template pesan

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca dokumentasi Apigee Edge.

Topik ini membahas cara menggunakan template pesan di proxy API dan memberikan referensi fungsi.

Apa itu template pesan?

Template pesan memungkinkan Anda melakukan penggantian string variabel dalam kebijakan dan elemen <TargetEndpoint> tertentu. Jika didukung, fitur ini memungkinkan Anda mengisi string secara dinamis saat proxy dieksekusi.

Anda dapat menyertakan kombinasi referensi variabel flow dan teks literal dalam template pesan. Nama variabel flow harus diapit dalam tanda kurung kurawal, sedangkan teks yang tidak dalam tanda kurung kurawal akan ditampilkan sebagai teks literal.

Lihat juga Di mana Anda bisa menggunakan template pesan?

Contoh

Misalnya, kebijakanAssignMessage memungkinkan Anda menggunakan template pesan di dalam elemen <Payload>:

<AssignMessage name="set-dynamic-content">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Payload contentType="application/json">
      {"name":"Alert", "message":"You entered an invalid username: {user.name}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Pada contoh di atas, nilai variabel flow user.name (dalam tanda kurung kurawal) akan dievaluasi dan diganti ke string payload saat runtime. Jadi, misalnya, jika user.name=jdoe, output pesan yang dihasilkan dalam payload adalah: You entered an invalid username: jdoe. Jika variabel tidak dapat di-resolve, string kosong yang dihasilkan.

Contoh

Ketika kuota terlampaui, sebaiknya tampilkan pesan yang bermakna kepada pemanggil. Pola ini biasanya digunakan dengan "aturan kesalahan" untuk memberikan output guna memberikan informasi kepada pemanggil tentang pelanggaran kuota. Dalam kebijakanAssignMessage berikut, template pesan digunakan untuk mengisi informasi kuota secara dinamis dalam beberapa elemen XML:

<AssignMessage name='AM-QuotaViolationMessage'>
  <Description>message for quota exceeded</Description>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name='X-Quota-Reset'>{ratelimit.Quota-1.expiry.time}</Header>
      <Header name='X-Quota-Allowed'>{ratelimit.Quota-1.allowed.count}</Header>
      <Header name='X-Quota-Available'>{ratelimit.Quota-1.available.count}</Header>
    </Headers>
    <Payload contentType='application/json'>{
  "error" : {
    "message" : "you have exceeded your quota",
    "clientId" : "{request.queryparam.apikey}"
  }
}
    </Payload>
    <StatusCode>429</StatusCode>
  </Set>
</AssignMessage>

Dalam kebijakanAssignMessage, elemen berikut di elemen <Set> mendukung template pesan:

• <Header>
• <QueryParam>
• <FormParam>
• <PayLoad>
• <Version>
• <Verb>
• <Path>
• <StatusCode>

Sekali lagi, perhatikan bahwa variabel alur dalam template pesan harus diapit dalam tanda kurung kurawal.

Saat kebijakan ini dijalankan:

• Elemen <Header> menerima nilai dari variabel alur yang ditentukan.
• Payload mencakup campuran teks dan variabel literal (client_id diisi secara dinamis).
• <StatusCode> hanya menyertakan teks literal; tetapi, elemen ini juga mendukung pembuatan template pesan jika Anda ingin menggunakannya.

Contoh

Dalam definisi <TargetEndpoint> proxy, elemen turunan dari <SSLInfo> mendukung template pesan. Dengan mengikuti pola yang sama yang digunakan dalam kebijakan, variabel alur dalam tanda kurung kurawal diganti saat proxy dieksekusi.

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <SSLInfo>
        <Enabled>{myvars.ssl.enabled}</Enabled>
        <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
        <KeyStore>{myvars.ssl.keystore}</KeyStore>
        <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
        <TrustStore>{myvars.ssl.trustStore}</TrustStore>
    </SSLInfo>
  </HTTPTargetConnection>
  ...
</TargetEndpoint>

Di mana Anda dapat menggunakan template pesan?

Template pesan didukung dalam beberapa kebijakan serta elemen tertentu yang digunakan dalam konfigurasi TargetEndpoint.

Catatan: Anda juga dapat membaca dokumentasi kebijakan untuk mempelajari kebijakan dan elemen <TargetEndpoint> mana yang mendukung template pesan.

Kebijakan yang menerima template pesan

Tabel berikut mencantumkan kebijakan dan elemen/elemen turunan yang didukung:

Kebijakan	Elemen/Elemen Turunan
Kebijakan AccessControl	<SourceAddress>, untuk atribut mask dan alamat IP.
KebijakanAssignMessage	Elemen turunan <Set>: Payload, ContentType, Verb, Versi, Path, StatusCode, Headers, QueryParams, FormParams Elemen turunan <Add>: Header, QueryParams, FormParams Elemen turunan <AssignVariable>: <Template>
Kebijakan CORS	<AllowHeaders> <AllowMethods> <AllowOrigins> <ExposeHeaders>
Kebijakan ExtractVariables	<JsonPath> Catatan: Template pesan tidak diterima untuk <XMLPath>.
Kebijakan GenerateJWS Kebijakan VerifyJWS	<Payload> (khusus kebijakan GenerateJWS) <AdditionalHeaders><Claim> * Elemen ini hanya mendukung template pesan jika type=map.
Kebijakan GenerateJWT Kebijakan VerifyJWT	<AdditionalClaims><Claim> <AdditionalHeaders><Claim> * Elemen ini hanya mendukung template pesan jika type=map.
Kebijakan HTTPModifier	Elemen turunan <Set>: <ContentType> <Verb> <Version> <Path> <StatusCode> <Headers> <QueryParams> <FormParams> Elemen turunan <Add>: <Headers> <QueryParams> <FormParams>
Kebijakan MessageLogging	<CloudLogging><Message> <Syslog><Message> <File><Message>
Kebijakan OASValidation	Elemen <OASResource>
Kebijakan RaiseFault	Elemen <Set>: <ContentType> <FormParams> <Headers> <QueryParams> <StatusCode> <Path> <Payload> <Verb> <Version> Elemen <Add>: <FormParams> <Headers> <QueryParams>
Kebijakan SAMLAssertion	<Template> * Hanya jika tanda tangan kebijakan adalah <GenerateSAMLAssertion>
Kebijakan InfoService	Elemen <Set>: <ContentType> <FormParams> <Headers> <QueryParams> <StatusCode> <Path> <Payload> <Verb> <Version> Elemen <Add>: <FormParams> <Headers> <QueryParams> <HTTPTargetConnection>/<URL>: Lihat Pembuatan template URL.

<TargetEndpoint> elemen yang menerima template pesan

<HTTPTargetConnection> elemen	Elemen turunan yang mendukung template pesan
<SSLInfo>	<Enabled>, <KeyAlias>, <KeyStore>, <TrustStore>, <ClientAuthEnabled>, <CLRStore>
<LocalTargetConnection>	<ApiProxy>, <ProxyEndpoint>, <Path>
<Path>	T/A
<URL>	Tidak ada elemen turunan. Lihat Pembuatan template URL untuk penggunaan.

Sintaksis template pesan

Bagian ini menjelaskan aturan yang harus Anda ikuti untuk menggunakan template pesan.

Gunakan tanda kurung kurawal untuk menunjukkan variabel

Sertakan nama variabel dalam tanda kurung kurawal { }. Jika variabel tidak ada, string kosong akan ditampilkan dalam output; namun, Anda dapat menentukan nilai default dalam template pesan (nilai yang diganti jika variabel tidak terselesaikan). Lihat Menetapkan nilai default dalam template pesan.

Perhatikan bahwa menyertakan seluruh string template pesan dalam tanda kutip diperbolehkan, tetapi opsional. Misalnya, dua template pesan berikut setara:

<Set>
  <Headers>
    <Header name="x-h1">"Hello {user.name}"</Header>
    <Header name="x-h1">Hello {user.name}</Header>
  </Headers>
</Set>

Spasi tidak diizinkan dalam ekspresi fungsi

Spasi tidak diizinkan di mana pun dalam ekspresi fungsi template pesan. Contoh:

Diizinkan:

{substring(alpha,0,4)}
{createUuid()}
{randomLong(10)}

Tidak Diizinkan:

{substring( alpha, 0, 4 )}
{ createUuid( ) }
{randomLong( 10 )}

Fungsi bertingkat tidak didukung

Memanggil fungsi dalam fungsi lain di template tidak didukung. Misalnya, Anda tidak dapat menggunakan:

{substring({timeFormat('yyyy-MM-dd','1494390266')},0,4)}

Menyertakan literal string dalam fungsi template dalam tanda kutip tunggal

Saat menyediakan literal string dalam fungsi, kurung menggunakan tanda kutip tunggal, bukan tanda kutip ganda.

Misalnya,

{replaceAll('BEARER: 1234','^Bearer ','TOKEN:')}

Hindari penggunaan karakter khusus dalam literal string

Hindari karakter khusus, seperti ':', '/', '\', '<', atau '>', dalam literal string. Karakter ini dapat menyebabkan error. Jika literal string memerlukan karakter khusus, tetapkan nilai ke variabel menggunakan kebijakan Python atau JavaScript, lalu gunakan variabel tersebut dalam template.

Menetapkan nilai default dalam template pesan

Jika variabel dengan template tidak dapat diselesaikan, Apigee akan mengganti string kosong. Namun, Anda dapat menentukan nilai default sebagai berikut:

<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>

Dalam contoh di atas, jika variabel request.header.id tidak dapat diselesaikan, nilainya akan diganti dengan Unknown. Contoh:

Test message. id = Unknown

Template URL

Elemen URL mendukung template dengan mengikuti sintaksis yang sama dengan elemen lainnya.

Contoh ini menunjukkan URL yang dibuat menggunakan variabel:

<URL>{targeturl}</URL>

Contoh ini menunjukkan nilai default untuk protokol:

<URL>{protocol:https}://{site:google.com}/path</URL>

Sintaksis lama untuk payload JSON

Pada versi Apigee sebelum Cloud rilis 16.08.17, Anda tidak boleh menggunakan tanda kurung kurawal untuk menunjukkan referensi variabel dalam payload JSON. Pada versi yang lebih lama tersebut, Anda harus menggunakan atribut variablePrefix dan variableSuffix untuk menentukan karakter pembatas, dan menggunakannya untuk menggabungkan nama variabel, seperti berikut:

<Set>
  <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
    {"name":"foo","type":"@variable_name#"}
  </Payload>
</Set>

Meskipun Apigee merekomendasikan agar Anda menggunakan sintaksis kurung kurawal yang lebih baru, sintaksis lama tetap berfungsi.

Menggunakan fungsi template pesan

Apigee menyediakan serangkaian fungsi yang dapat Anda gunakan dalam template pesan untuk meng-escape, mengenkode, melakukan hash, dan memformat variabel string, seperti yang dijelaskan di bawah ini.

Contoh: toLowerCase()

Gunakan fungsi toLowerCase() bawaan untuk mengubah variabel string menjadi huruf kecil:

<AssignMessage name="AM-Set-Custom-Response">
  <AssignTo createNew="false" type="response"/>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name="x-h1">Test header: {toLowerCase(foo.bar:FOO)}</Header>
    </Headers>
  </Set>
</AssignMessage>

Jika variabel alur foo.bar di-resolve, karakternya akan menggunakan huruf kecil semua. Jika foo.bar tidak terselesaikan, nilai default FOO akan diganti dan dikonversi menjadi karakter huruf kecil. Contoh:

Test header: foo

Contoh: escapeJSON()

Berikut ini kasus penggunaan yang menarik: Misalnya aplikasi backend Anda menampilkan respons JSON yang berisi karakter escape yang valid. Contoh:

{
  "code": "INVALID",
  "user_message": "Invalid value for \"logonId\" check your input."
}

Kemudian, misalkan Anda ingin mengembalikan pesan ini ke pemanggil klien dalam payload kustom. Cara yang biasa untuk melakukannya adalah dengan mengekstrak pesan dari payload respons target dan menggunakan assignMessage untuk menambahkannya ke respons proxy kustom (yaitu, mengirimkannya kembali ke klien).

Berikut adalah kebijakan ExtractVariables yang mengekstrak informasi user_message ke dalam variabel bernama standard.systemMessage:

<ExtractVariables name="EV-BackendErrorResponse">
  <DisplayName>EV-BackendErrorResponse</DisplayName>
  <JSONPayload>
    <Variable name="standard.systemMessage">
      <JSONPath>$.user_message</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Sekarang, berikut adalah kebijakanAssignMessage yang sangat valid yang menambahkan variabel yang diekstrak ke payload respons (respons proxy):

<AssignMessage name="AM-SetStandardFaultResponse">
  <DisplayName>AM-SetStandardFaultResponse</DisplayName>
  <Set>
    <Payload contentType="application/json">
     {
       "systemMessage": "{standard.systemMessage}"
     }
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Sayangnya, ada masalah. Kebijakan ExtractVariables menghapus karakter kutipan yang di-escape di sekitar bagian pesan. Ini berarti respons yang ditampilkan ke klien adalah JSON tidak valid. Ini jelas bukan yang Anda inginkan.

{
  "systemMessage": "Invalid value for "logonId" check your input."
}

Untuk mengatasi masalah ini, Anda dapat mengubah kebijakan produksi yang ada agar menggunakan fungsi template pesan yang mengecualikan tanda kutip dalam JSON. Fungsi ini, escapeJSON(), meng-escape tanda kutip atau karakter khusus lainnya yang muncul dalam ekspresi JSON:

<AssignMessage name="AM-SetStandardFaultResponse">
  <DisplayName>AM-SetStandardFaultResponse</DisplayName>
  <Set>
    <Payload contentType="application/json">
     {
       "systemMessage": "{escapeJSON(standard.systemMessage)}"
     }
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Fungsi ini meng-escape tanda petik yang disematkan, sehingga menghasilkan JSON valid yang persis seperti yang Anda inginkan:

{
  "systemMessage": "Invalid value for \"logonId\" check your input.",
}

Template pesan adalah fitur substitusi string dinamis yang dapat Anda gunakan dalam kebijakan tertentu dan definisi <TargetEndpoint>. Fungsi template pesan memungkinkan Anda menjalankan operasi yang berguna, seperti hashing, manipulasi string, escape karakter, dan lainnya dalam template pesan.

Misalnya, dalam kebijakan TetapkanMessage berikut, fungsi toLowerCase() digunakan dalam template pesan:

<AssignMessage name="AM-Set-Custom-Response">
  <AssignTo createNew="false" type="response"/>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Set>
   <Headers>
     <Header name="x-h1">Test header: {Hello,toLowerCase(user.name)}</Header>
   </Headers>
  </Set>
</AssignMessage>

Bagian ini menjelaskan fungsi template pesan, argumen, dan output-nya. Topik ini mengasumsikan bahwa Anda telah memahami template pesan dan konteks yang digunakannya.

Fungsi hash

Menghitung nilai hash dan menampilkan representasi string dari hash tersebut.

Catatan: Spasi tidak diizinkan di mana pun dalam ekspresi fungsi. Lihat Spasi tidak diizinkan dalam ekspresi fungsi.

Fungsi hash heksadesimal

Menghitung nilai hash dan menampilkan representasi string dari hash tersebut sebagai angka heksadesimal.

Sintaksis

Fungsi	Deskripsi
md5Hex(string)	Menghitung hash MD5 yang dinyatakan sebagai angka heksadesimal.
sha1Hex(string)	Menghitung hash SHA1 yang dinyatakan sebagai angka heksadesimal.
sha256Hex(string)	Menghitung hash SHA256 yang dinyatakan sebagai angka heksadesimal.
sha384Hex(string)	Menghitung hash SHA384 yang dinyatakan sebagai angka heksadesimal.
sha512Hex(string)	Menghitung hash SHA512 yang dinyatakan sebagai angka heksadesimal.

Arguments

string: Fungsi hash menggunakan argumen string tunggal yang digunakan untuk menghitung algoritma hash. Argumennya dapat berupa string literal (dikurung dalam tanda kutip tunggal) atau variabel alur string.

Contoh

Panggilan fungsi:

sha256Hex('abc')

Hasil:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Panggilan fungsi:

var str = 'abc';
sha256Hex(str)

Hasil:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Fungsi hash Base64

Menghitung nilai hash dan menampilkan representasi string dari hash tersebut sebagai nilai yang dienkode Base64.

Sintaksis

Fungsi	Deskripsi
md5Base64(string)	Menghitung hash MD5 yang dinyatakan sebagai nilai yang dienkode Base64.
sha1Base64(string)	Menghitung hash SHA1 yang dinyatakan sebagai nilai yang dienkode Base64.
sha256Base64(string)	Menghitung hash SHA256 yang dinyatakan sebagai nilai yang dienkode Base64.
sha384Base64(string)	Menghitung hash SHA384 yang dinyatakan sebagai penilai berenkode Base64.
sha512Base64(string)	Menghitung hash SHA512 yang dinyatakan sebagai nilai yang dienkode Base64.

Arguments

string: Fungsi hash menggunakan argumen string tunggal yang digunakan untuk menghitung algoritma hash. Argumennya bisa berupa string literal (disertakan dalam tanda kutip tunggal) atau variabel aliran string.

Contoh

Panggilan fungsi:

sha256Base64('abc')

Hasil:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Panggilan fungsi:

var str = 'abc';
sha256Base64(str)

Hasil:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Fungsi string

Menjalankan operasi pada string dalam template pesan.

Catatan: Spasi tidak diizinkan di mana pun dalam ekspresi fungsi. Lihat Spasi tidak diizinkan dalam ekspresi fungsi.

Fungsi encoding Base64

Mengenkode dan mendekode string menggunakan skema encoding Base64.

Sintaksis

Fungsi	Deskripsi
encodeBase64(string)	Mengenkode string menggunakan encoding Base64. Misalnya: encodeBase64(value), jika value menyimpan abc, fungsi akan menampilkan string: YWJj
decodeBase64(string)	Mendekode string berenkode Base64. Misalnya: decodeBase64(value) saat value menyimpan aGVsbG8sIHdvcmxk, fungsi ini akan menampilkan string hello, world.

Arguments

string: String yang akan dienkode atau didekode. Dapat berupa string literal (dikurung dalam tanda kutip tunggal) atau variabel alur string.

Contoh

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {decodeBase64('d29ybGQK')}</Header>
       </Headers>
    </Set>
</AssignMessage>

Catatan: Encoding Base64 berbeda dengan Base64URL. Mencoba mendekode string yang dienkode Base64URL akan menghasilkan string kosong.

Fungsi konversi kasus

Mengonversi string menjadi huruf besar semua atau huruf kecil semua.

Sintaksis

Fungsi	Deskripsi
toUpperCase(string)	Mengonversi string menjadi huruf besar.
toLowerCase(string)	Mengonversi string menjadi huruf kecil.

Arguments

string: String yang akan dikonversi. Dapat berupa string literal (dikurung dalam tanda kutip tunggal) atau variabel alur string.

Contoh

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {toLowerCase(user.name)}</Header>
       </Headers>
    </Set>
</AssignMessage>

Fungsi substring

Menampilkan karakter di antara indeks awal dan akhir dari string yang ditentukan.

Sintaksis

substring(str,start_index,end_index)

Arguments

• str: String literal (yang diapit tanda kutip tunggal) atau variabel aliran string.
• start_index: Indeks awal ke dalam string.
• end_index: (Opsional) Indeks akhir ke dalam string. Jika tidak diberikan, indeks akhir adalah akhir dari string.

Contoh

Untuk contoh berikut, anggaplah variabel alur ini ada:

Nama variabel	Nilai
alpha	ABCDEFGHIJKLMNOPQRSTUVWXYZ
seven	7

Berikut adalah hasil panggilan fungsi yang menggunakan variabel ini:

Ekspresi template pesan	Hasil
{substring(alpha,22)}	WXYZ
hello {substring(alpha,22)}	hello WXYZ
{substring(alpha,-4)}	WXYZ
{substring(alpha,-8,-4)}	STUV
{substring(alpha,0,10)}	ABCDEFGHIJ
{substring(alpha,0,seven)}	ABCDEFG

Fungsi Replace All

Menerapkan ekspresi reguler ke string dan untuk setiap kecocokan, mengganti pencocokan dengan nilai pengganti.

Sintaksis

replaceAll(string,regex,value)

Arguments

• string - String literal (yang diapit tanda kutip tunggal) atau variabel aliran string yang digunakan untuk melakukan penggantian.
• regex - Ekspresi reguler.
• nilai - Nilai yang akan menggantikan semua pencocokan ekspresi reguler dalam string.

Contoh

Untuk contoh berikut, anggaplah variabel alur ini ada:

Nama variabel	Nilai
header	Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
regex1	"^Bearer "
replacement	"TOKEN: "

Berikut adalah hasil panggilan fungsi yang menggunakan variabel ini:

Ekspresi template pesan	Hasil
{replaceAll(header,'9993','')}	Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-
{replaceAll(header,regex1,'')}	ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
{replaceAll(header,regex1,replacement)}	TOKEN: ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993

Fungsi Replace First

Hanya mengganti kemunculan pertama dari pencocokan ekspresi reguler yang ditentukan dalam string.

Sintaksis

replaceFirst(string,regex,value)

Arguments

• string: String literal (disertakan dalam tanda kutip tunggal) atau variabel aliran string yang digunakan untuk melakukan penggantian.
• regex: Ekspresi reguler.
• value: Nilai untuk mengganti ekspresi reguler yang cocok dalam string.

Fungsi escape dan encoding karakter

Fungsi yang meng-escape atau mengenkode karakter khusus dalam string.

Catatan: Spasi tidak diizinkan di mana pun dalam ekspresi fungsi. Lihat Spasi tidak diizinkan dalam ekspresi fungsi.

Sintaksis

Fungsi	Deskripsi
escapeJSON(string)	Menghindari tanda kutip ganda dengan garis miring terbalik.
escapeXML(string)	Mengganti tanda kurung sudut, apostrof, tanda kutip ganda, dan ampersand dengan masing-masing entitas XML. Digunakan untuk dokumen XML 1.0. Gunakan escapeXML untuk dokumen XML1.0 dan escapeXML11 untuk dokumen XML 1.1.
escapeXML11(string)	Bekerja dengan cara yang sama seperti escapeXML, tetapi untuk entitas XML v1.1. Lihat Catatan penggunaan di bawah.
encodeHTML(string)	Mengenkode apostrof, tanda kurung sudut, dan ampersan.

Arguments

string: String yang akan di-escape. Dapat berupa string literal (disertakan dalam tanda kutip tunggal) atau variabel alur string.

Catatan penggunaan

XML 1.1 dapat merepresentasikan karakter kontrol tertentu, tetapi tidak dapat merepresentasikan byte null atau codepoint surrogate surrogate Unicode yang tidak tersambung, bahkan setelah escape. Fungsi escapeXML11() menghapus karakter yang tidak sesuai dalam rentang berikut:

[#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

Fungsi escapeXML11() meng-escape karakter dalam rentang berikut:

[#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]

Contoh

Asumsikan ada variabel flow yang disebut food dengan nilai ini: "bread" & "butter". Kemudian, fungsinya:

{escapeHTML(food)}

Hasil dalam:

"bread" & "butter"

Fungsi format waktu

Menampilkan representasi string waktu, dengan format UTC.

Catatan:

Spasi tidak diizinkan di mana pun dalam ekspresi fungsi. Lihat Spasi tidak diizinkan dalam ekspresi fungsi.

Titik dua di dalam literal string format waktu (seperti "HH:mm:ss") mengganggu saat menetapkan nilai default dalam template pesan. Gunakan variabel, bukan literal untuk menentukan format string yang melibatkan titik dua. Lihat Menghindari penggunaan karakter khusus dalam literal string.

Sintaksis

Fungsi	Deskripsi
timeFormat(format,str)	Menampilkan tanggal dengan format UTC. DEPRECATED: Menampilkan tanggal dengan format dalam zona waktu lokal.
timeFormatMs(format,str)	Menampilkan tanggal dengan format UTC. DEPRECATED: Menampilkan tanggal dengan format dalam zona waktu lokal.
timeFormatUTC(format,str)	Menampilkan tanggal dengan format UTC.
timeFormatUTCMs(format,str)	Menampilkan tanggal dengan format UTC.

Arguments

• format: String format tanggal/waktu. Dapat berupa string literal (disertakan dalam tanda kutip tunggal) atau variabel string. Gunakan variabel, bukan literal jika format menyertakan titik dua. Lihat catatan sebelumnya di bagian ini.
• str: Variabel string atau aliran string yang berisi nilai waktu. Nilainya dapat dalam detik-sejak-epoch atau milidetik-sejak-epoch untuk timeFormatMs.

Contoh

Asumsikan nilai berikut dan asumsikan zona waktu lokal adalah Pasifik:

• epoch_time_ms = 1494390266000
• epoch_time = 1494390266
• fmt1 = yyyy-MM-dd
• fmt2 = yyyy-MM-dd HH-mm-ss
• fmt3 = yyyyMMddHHmmss

Fungsi ini menampilkan hasil berikut:

Fungsi	Output
timeFormatMs(fmt1,epoch_time_ms)	2017-05-09
timeFormat(fmt1,epoch_time)	2017-05-09
timeFormat(fmt2,epoch_time)	2017-05-09 21:24:26
timeFormat(fmt3,epoch_time)	20170509212426
timeFormatUTC(fmt1,epoch_time)	2017-05-10
timeFormatUTC(fmt2,epoch_time)	2017-05-10 04:24:26
timeFormatUTC(fmt3,epoch_time)	20170510042426

Fungsi penghitungan HMAC

Fungsi penghitungan HMAC memberikan alternatif penggunaan kebijakan HMAC untuk menghitung HMAC. Fungsi ini berguna saat melakukan penghitungan HMAC bertingkat, seperti saat output dari satu HMAC digunakan sebagai kunci untuk HMAC kedua.

Catatan: Spasi tidak diizinkan di mana pun dalam ekspresi fungsi. Lihat Spasi tidak diizinkan dalam ekspresi fungsi.

Sintaksis

Fungsi	Deskripsi
hmacSha224(key,valueToSign[,keyencoding[,outputencoding]])	Menghitung HMAC dengan fungsi hash SHA-224.
hmacSha256(key,valueToSign[,keyencoding[,outputencoding]])	Mengenkode HMAC dengan fungsi hash SHA-256.
hmacSha384(key,valueToSign[,keyencoding[,outputencoding]])	Mengenkode HMAC dengan fungsi hash SHA-384.
hmacSha512(key,valueToSign[,keyencoding[,outputencoding]])	Mengenkode HMAC dengan fungsi hash SHA-512.
hmacMd5(key,valueToSign[,keyencoding[,outputencoding]])	Mengenkode HMAC dengan fungsi hash MD5.
hmacSha1(key,valueToSign[,keyencoding[,outputencoding]])	Mengenkode HMAC dengan algoritma enkripsi SHA-1.

Catatan keamanan: SHA-1 dan MD-5 disertakan di sini demi kelengkapan, tetapi Google merekomendasikan agar pengguna tidak menggunakan hash ini. Google pertama kali mendemonstrasikan serangan tabrakan terhadap SHA-1 pada tahun 2017, dan merekomendasikan untuk tidak menggunakannya. NIST juga merekomendasikan agar pengguna berhenti menggunakan SHA-1. CMU Software Engineering Institute pertama kali merekomendasikan agar orang-orang menghindari penggunaan algoritma MD5 dalam kapasitas apa pun, pada tahun 2008.

Arguments

• key - (Wajib) Menentukan kunci rahasia, yang dienkode sebagai string, yang digunakan untuk menghitung HMAC.
• valueToSign - (Wajib) Menentukan pesan yang akan ditandatangani. Atribut ini harus berupa string.
• keyencoding - (Opsional) String kunci rahasia akan didekode menurut encoding yang ditentukan ini. Nilai yang valid: hex, base16, base64, utf-8. Default: utf-8
• outputencoding - (Opsional) Menentukan algoritma encoding yang akan digunakan untuk output. Nilai valid: hex, base16, base64. Nilainya tidak peka huruf besar/kecil; hex dan base16 adalah sinonim. Default: base64

Contoh

Contoh ini menggunakan kebijakan TetapkanMessage untuk menghitung HMAC-256 dan menetapkannya ke variabel flow:

<AssignMessage name='AM-HMAC-1'>
  <AssignVariable>
    <Name>valueToSign</Name>
    <Template>{request.header.apikey}.{request.header.date}</Template>
  </AssignVariable>
  <AssignVariable>
    <Name>hmac_value</Name>
    <Template>{hmacSha256(private.secretkey,valueToSign)}</Template>
  </AssignVariable>
</AssignMessage>

Contoh ini menggambarkan cara menghasilkan HMAC bertingkat yang dapat digunakan dengan proses penandatanganan AWS Signature v4. Contoh ini menggunakan kebijakan ProvideMessage untuk menghasilkan lima level cascaded HMAC yang digunakan untuk menghitung tanda tangan untuk AWS Signature v4:

<AssignMessage name='AM-HMAC-AWS-1'>
  <!-- 1 -->
  <AssignVariable>
    <Name>DateValue</Name>
    <Template>{timeFormatUTCMs('yyyyMMdd',system.timestamp)}</Template>
  </AssignVariable>
  <!-- 2 -->
  <AssignVariable>
    <Name>FirstKey</Name>
    <Template>AWS4{private.secret_aws_access_key}</Template>
  </AssignVariable>
  <!-- 3 -->
  <AssignVariable>
    <Name>DateKey</Name>
    <Template>{hmacSha256(FirstKey,DateValue,'utf-8','base16')}</Template>
  </AssignVariable>
  <!-- 4 -->
  <AssignVariable>
    <Name>DateRegionKey</Name>
    <Template>{hmacSha256(DateKey,aws_region,'base16','base16')}</Template>
  </AssignVariable>
  <!-- 5 -->
  <AssignVariable>
    <Name>DateRegionServiceKey</Name>
    <Template>{hmacSha256(DateRegionKey,aws_service,'base16','base16')}</Template>
  </AssignVariable>
  <!-- 6 -->
  <AssignVariable>
    <Name>SigningKey</Name>
    <Template>{hmacSha256(DateRegionServiceKey,'aws4_request','base16','base16')}</Template>
  </AssignVariable>
  <!-- 7 -->
  <AssignVariable>
    <Name>aws4_hmac_value</Name>
    <Template>{hmacSha256(SigningKey,stringToSign,'base16','base16')}</Template>
  </AssignVariable>
</AssignMessage>

Fungsi lainnya

Membuat fungsi UUID

Menghasilkan dan menampilkan UUID.

Catatan: Spasi tidak diizinkan di mana pun dalam ekspresi fungsi. Lihat Spasi tidak diizinkan dalam ekspresi fungsi.

Sintaksis

createUuid()

Arguments

Tidak ada.

Contoh

{createUuid()}

Contoh hasil:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Fungsi Generator Panjang Acak

Menampilkan bilangan bulat panjang acak.

Sintaksis

randomLong(args)

Arguments

• Jika tidak ada argumen yang ditentukan, fungsi akan menampilkan bilangan bulat panjang acak, seperti yang dihitung oleh class Java SecureRandom.
• Jika ada satu argumen, argumen tersebut diperlakukan sebagai nilai minimum komputasi.
• Jika ada argumen kedua, argumen tersebut diperlakukan sebagai nilai komputasi maksimum.

Contoh

{randomLong()}

Menghasilkan sesuatu seperti ini:

5211338197474042880

Generator teks regex

Membuat string teks yang cocok dengan ekspresi reguler yang diberikan.

Sintaksis

xeger(regex)

Argumen

regex: Ekspresi reguler.

Contoh

Contoh ini menghasilkan string tujuh digit tanpa angka nol:

xeger( '[1-9]{7}' )

Contoh hasil:

9857253

Fungsi penggabungan null

Fungsi firstnonnull() menampilkan nilai argumen non-null yang paling kiri.

Sintaksis

firstnonnull(var1,varn)

Argumen

var1: Variabel konteks.

varn: Satu atau beberapa variabel konteks. Anda dapat menetapkan argumen yang paling kanan ke string untuk memberikan nilai penggantian (nilai yang akan ditetapkan jika tidak ada argumen sebelah kiri yang ditetapkan).

Contoh

Tabel berikut mengilustrasikan cara menggunakan fungsi ini:

Template	Var1	Var2	Var3	Hasil
{firstnonnull(var1,var2)}	Belum disetel	foo	T/A	foo
{firstnonnull(var1,var2)}	foo	bar	T/A	foo
{firstnonnull(var1,var2)}	foo	Belum disetel	T/A	foo
{firstnonnull(var1,var2,var3)}	foo	bar	baz	foo
{firstnonnull(var1,var2,var3)}	Belum disetel	bar	baz	bar
{firstnonnull(var1,var2,var3)}	Belum disetel	Belum disetel	baz	baz
{firstnonnull(var1,var2,var3)}	Belum disetel	Belum disetel	Belum disetel	null
{firstnonnull(var1)}	Belum disetel	T/A	T/A	null
{firstnonnull(var1)}	foo	T/A	T/A	foo
{firstnonnull(var1,var2)}	""	bar	T/A	""
{firstnonnull(var1,var2,'fallback value')}	null	null	fallback value	fallback value

Fungsi XPath

Menerapkan ekspresi XPath ke variabel XML.

Sintaksis

xpath(xpath_expression,xml_string[,datatype])

Arguments

xpath_expression: Ekspresi XPath.

xml_string: Variabel flow atau string yang berisi XML.

datatype: (Opsional) Menentukan jenis kueri yang ditampilkan. Nilai yang valid adalah nodeset, node, number, boolean, atau string. Nilai defaultnya adalah nodeset. {i>Default<i} biasanya merupakan pilihan yang tepat.

Fungsi menampilkan string kosong jika ekspresi tidak cocok.

Contoh 1

Misalkan variabel konteks ini mendefinisikan string XML dan ekspresi XPath:

xml = "<tag><tagid>250397</tagid><readerid>1</readerid><rssi>74</rssi><date>2019/06/15</date></tag>"
xpath = "/tag/tagid"

Selain itu, fungsi xpath() digunakan dalam kebijakan ProvideMessage, seperti berikut:

<AssignMessage>
  <AssignVariable>
    <Name>extracted_tag</Name>
    <Template>{xpath(xpath,xml)}</Template>
  </AssignVariable>
</AssignMessage>

Fungsi ini menampilkan nilai <tagid>250397</tagid>. Nilai ini ditempatkan dalam variabel konteks yang disebut extracted_tag.

Contoh 2: Namespace XML

Untuk menentukan namespace, tambahkan parameter tambahan, masing-masing dengan string yang terlihat seperti prefix:namespaceuri. Misalnya, fungsi xpath() yang memilih elemen turunan dari isi SOAP mungkin seperti ini:

<AssignMessage>
  <AssignVariable>
    <Name>soapns</Name>
    <Value>soap:http://schemas.xmlsoap.org/soap/envelope/</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>xpathexpression</Name>
    <Value>/soap:Envelope/soap:Body/*</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>extracted_element</Name>
    <Template>{xpath(xpathexpression,xml,soapns)}</Template>
  </AssignVariable>
</AssignMessage>

Untuk namespace tambahan, Anda dapat menambahkan hingga 10 parameter tambahan ke fungsi xpath().

Daripada menentukan ekspresi XPath dengan karakter khusus sebagai literal string, gunakan variabel untuk menyertakan string tersebut dalam fungsi. Lihat Menghindari penggunaan karakter khusus dalam literal string untuk informasi selengkapnya.

{xpath(xpathexpression,xml,ns1)}

Contoh 3: Menentukan jenis nilai yang ditampilkan yang diinginkan

Parameter ketiga opsional yang diteruskan ke fungsi xpath() menentukan jenis nilai yang ditampilkan kueri yang diinginkan.

Beberapa kueri XPath dapat mengembalikan nilai numerik atau boolean. Misalnya, fungsi count() menampilkan angka. Ini adalah kueri XPath yang valid:

count(//Record/Fields/Pair)

Kueri yang valid ini mengembalikan boolean:

count(//Record/Fields/Pair)>0

Dalam kasus tersebut, panggil fungsi xpath() dengan parameter ketiga yang menentukan jenis tersebut:

{xpath(expression,xml,'number')}
{xpath(expression,xml,'boolean')}

Jika parameter ketiga berisi titik dua, hal itu akan ditafsirkan sebagai argumen namespace. Jika tidak, jenis nilai yang ditampilkan akan diperlakukan sebagai yang diinginkan. Dalam hal ini, jika parameter ketiga bukan salah satu dari nilai yang valid (mengabaikan huruf besar/kecil), fungsi xpath() secara default akan menampilkan nodeset.

Fungsi Jalur JSON

Menerapkan ekspresi Jalur JSON ke variabel JSON.

Sintaksis

jsonPath(json-path,json-var,want-array)

Arguments

• (Wajib) json-path: (String) Ekspresi Jalur JSON.
• (Wajib) json-var: (String) Variabel alur atau string yang berisi JSON.
• (Opsional) want-array: (String) Jika parameter ini ditetapkan ke 'true' dan jika kumpulan hasilnya adalah array, semua elemen array akan ditampilkan. Jika ditetapkan ke nilai lain atau jika parameter ini dihilangkan, hanya elemen ke-nol dari array set hasil yang ditampilkan. Jika kumpulan hasil bukan array, parameter ketiga ini, jika ada, akan diabaikan.

Fungsi ini menampilkan string kosong jika ekspresi tidak cocok.

Contoh 1

Jika ini adalah template pesan:

The address is {jsonPath($.results[?(@.name == 'Mae West')].address.line1,the_json_variable)}

dan the_json_variable berisi:

{
  "results" : [
    {
      "address" : {
        "line1" : "18250 142ND AV NE",
        "city" : "Woodinville",
        "state" : "Washington",
        "zip" : "98072"
      },
      "name" : "Fred Meyer"
    },
    {
      "address" : {
        "line1" : "1060 West Addison Street",
        "city" : "Chicago",
        "state" : "Illinois",
        "zip" : "60613"
      },
      "name" : "Mae West"
    }
  ]
} 

Hasil fungsinya adalah:

The address is 1060 West Addison Street

Perhatikan bahwa dalam hal ini, set hasil adalah elemen tunggal (bukan array elemen). Jika kumpulan hasilnya adalah array, maka hanya elemen ke-nol dari array tersebut yang akan ditampilkan. Untuk menampilkan array lengkap, panggil fungsi dengan 'true' sebagai parameter ketiga, seperti yang ditunjukkan pada contoh berikutnya.

Contoh 2

Jika ini adalah template pesan:

{jsonPath($.config.quota[?(@.operation=='ManageOrder')].appname,the_json_variable,'true')}

dan the_json_variable berisi:

{
  "results" : [
     {
      "config": {
        "quota": [
          {
            "appname": "A",
            "operation": "ManageOrder",
            "value": "900"
          },
          {
            "appname": "B",
            "operation": "ManageOrder",
            "value": "1000"
          },
          {
            "appname": "B",
            "operation": "SubmitOrder",
            "value": "800"
          }
        ]
      }
    }
  ]
} 

Hasil fungsinya adalah:

['A','B']