Template pesan

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

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

Apa yang dimaksud dengan template pesan?

Template pesan memungkinkan Anda melakukan penggantian string variabel di elemen kebijakan dan TargetEndpoint tertentu. Fitur ini, jika didukung, memungkinkan Anda mengisi string secara dinamis saat proxy dieksekusi.

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

Lihat juga Di mana Anda dapat menggunakan template pesan?

Contoh

Misalnya, kebijakan Tetapkan Pesan memungkinkan Anda menggunakan template pesan 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>

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

Contoh

Jika kuota terlampaui, sebaiknya tampilkan pesan yang bermakna kepada pemanggil. Pola ini biasanya digunakan dengan "aturan error" untuk memberikan output guna memberi informasi kepada pemanggil tentang pelanggaran kuota. Dalam kebijakan Tetapkan Pesan berikut, template pesan digunakan untuk mengisi informasi kuota secara dinamis di 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>
    <ReasonPhrase>Quota Exceeded</ReasonPhrase>
  </Set>
</AssignMessage>

Dalam kebijakan AssignMessage, elemen berikut dalam elemen <Set> mendukung pembuatan template pesan:

• Header
• QueryParam
• FormParam
• PayLoad
• Versi
• Kata kerja
• Jalur
• StatusCode
• ReasonPhrase

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

Saat kebijakan ini dieksekusi:

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

Contoh

Dalam definisi TargetEndpoint proxy, elemen turunan <SSLInfo> mendukung pembuatan template pesan. Dengan mengikuti pola yang sama yang digunakan dalam kebijakan, variabel alur dalam tanda kurung kurawal akan 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 di beberapa kebijakan serta elemen tertentu yang digunakan dalam konfigurasi TargetEndpoint.

Kebijakan yang menerima template pesan

Elemen TargetEndpoint yang menerima template pesan

Sintaksis template pesan

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

Menggunakan 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 diizinkan, tetapi bersifat 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>

Menetapkan nilai default dalam template pesan

Jika variabel dengan template tidak dapat di-resolve, Edge akan menggantinya dengan string kosong. Namun, Anda dapat menentukan nilai default sebagai berikut:

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

Pada contoh di atas, jika variabel request.header.id tidak dapat di-resolve, nilainya akan diganti dengan Unknown. Contoh:

Test message. id = Unknown

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 )}

Sintaksis lama untuk payload JSON

Di versi Edge sebelum rilis Cloud 16.08.17, Anda tidak dapat menggunakan kurung kurawal untuk menunjukkan referensi variabel dalam payload JSON. Pada versi lama tersebut, Anda harus menggunakan atribut variablePrefix dan variableSuffix untuk menentukan karakter pemisah, dan menggunakannya untuk menggabungkan nama variabel, seperti ini:

<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 yang lebih lama masih berfungsi.

Menggunakan fungsi template pesan

Edge menyediakan serangkaian fungsi yang dapat Anda gunakan dalam template pesan untuk meng-escape, mengenkode, melakukan hash, dan memformat variabel string.

Fungsi template pesan dijelaskan secara mendetail di Referensi fungsi template pesan.

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, semua karakternya akan menjadi huruf kecil. Jika foo.bar tidak terselesaikan, nilai default FOO akan diganti dan dikonversi menjadi karakter huruf kecil. Contoh:

Test header: foo

Contoh: escapeJSON()

Berikut adalah 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 menampilkan pesan ini kepada pemanggil klien dalam payload kustom. Cara biasa untuk melakukannya adalah mengekstrak pesan dari payload respons target dan menggunakan Assign Message untuk menambahkannya ke respons proxy kustom (yaitu, mengirimnya kembali ke klien).

Berikut adalah kebijakan Ekstrak Variabel yang mengekstrak informasi user_message ke dalam variabel yang disebut 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 kebijakan Tetapkan Pesan yang valid dan sempurna 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 Extract Variables menghapus karakter tanda petik yang di-escape di sekitar bagian pesan. Artinya, respons yang ditampilkan ke klien adalah JSON yang tidak valid. Ini jelas bukan yang Anda inginkan.

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

Untuk mengatasi masalah ini, Anda dapat mengubah kebijakan Tetapkan Pesan untuk menggunakan fungsi template pesan yang meng-escape tanda kutip dalam JSON untuk Anda. Fungsi ini, escapeJSON(), akan meng-escape tanda petik 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 akan meng-escape tanda kutip yang disematkan, sehingga menghasilkan JSON yang valid, yang persis seperti yang Anda inginkan:

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

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

Misalnya, dalam kebijakan AssignMessage 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>

Topik ini menjelaskan fungsi template pesan, argumennya, dan outputnya. Topik ini mengasumsikan bahwa Anda sudah memahami template pesan dan konteks penggunaannya.

Fungsi hash

Menghitung nilai hash dan menampilkan representasi string dari hash tersebut.

Fungsi hash heksadesimal

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

Sintaksis

Argumen

string - Fungsi Hash menggunakan satu argumen string yang digunakan untuk menghitung algoritma hash. Argumen dapat berupa string literal 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

Argumen

string - Fungsi Hash menggunakan satu argumen string yang digunakan untuk menghitung algoritma hash. Argumen dapat berupa string literal atau variabel alur string.

Contoh

Panggilan fungsi:

sha256Base64('abc')

Hasil:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Panggilan fungsi:

var str = 'abc';
sha256Base64(str)

Hasil:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Fungsi string

Melakukan operasi pada string dalam template pesan.

Fungsi encoding base64

Mengenkode dan mendekode string menggunakan skema encoding Base64.

Sintaksis

Argumen

string - String yang akan dienkode atau didekode. Dapat berupa string literal 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>

Fungsi konversi huruf besar/kecil

Mengonversi string menjadi semua huruf besar atau semua huruf kecil.

Sintaksis

Argumen

string - String yang akan dikonversi. Dapat berupa string literal 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 antara indeks awal dan akhir string yang ditentukan.

Sintaksis

substring(str,start_index,end_index)

Argumen

• str - Variabel alur string atau string literal.
• start_index - Indeks awal ke dalam string.
• end_index - (Opsional) Indeks akhir ke dalam string. Jika tidak diberikan, indeks akhir adalah akhir string.

Contoh

Untuk contoh berikut, anggaplah variabel alur ini ada:

Berikut adalah hasil panggilan fungsi yang menggunakan variabel ini:

Fungsi Ganti Semua

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

Sintaksis

replaceAll(string,regex,value)

Argumen

• string - String literal atau variabel alur string tempat penggantian dilakukan.
• regex - Ekspresi reguler.
• value - Nilai untuk mengganti semua kecocokan ekspresi reguler dalam string.

Contoh

Untuk contoh berikut, anggaplah variabel alur ini ada:

Berikut adalah hasil panggilan fungsi yang menggunakan variabel ini:

Mengganti fungsi Pertama

Hanya mengganti kemunculan pertama kecocokan ekspresi reguler yang ditentukan dalam string.

Sintaksis

replaceFirst(string,regex,value)

Argumen

• string - String literal atau variabel alur string tempat penggantian dilakukan.
• regex - Ekspresi reguler.
• nilai - Nilai untuk mengganti kecocokan ekspresi reguler dalam string.

Fungsi encoding dan escape karakter

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

Sintaksis

Argumen

string - String yang akan di-escape. Dapat berupa string literal atau variabel alur string.

Catatan penggunaan

XML 1.1 dapat merepresentasikan karakter kontrol tertentu, tetapi tidak dapat merepresentasikan byte null atau codepoint pengganti Unicode yang tidak berpasangan, bahkan setelah escape. Fungsi escapeXML11() menghapus karakter yang tidak sesuai dengan 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 variabel flow bernama food ada dengan nilai ini: "bread" & "butter". Kemudian, fungsi:

{escapeHTML(food)}

menghasilkan:

Fungsi format waktu

Menampilkan representasi string waktu, yang diformat dalam zona waktu lokal, atau dalam UTC.

Sintaksis

Argumen

• format - String format tanggal/waktu. Dapat berupa string literal atau variabel string.
• str - Variabel alur string atau string yang berisi nilai waktu. Nilainya dapat berupa 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 untuk menggunakan kebijakan HMAC guna menghitung HMAC. Fungsi ini berguna saat melakukan penghitungan HMAC berurutan, seperti saat output dari satu HMAC digunakan sebagai kunci untuk HMAC kedua.

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.

Argumen

• key - (Wajib) Menentukan kunci rahasia, yang dienkode sebagai string, yang digunakan untuk menghitung HMAC.
• valueToSign - (Wajib) Menentukan pesan yang akan ditandatangani. Harus berupa string.
• keyencoding - (Opsional) String kunci rahasia akan didekode sesuai dengan 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 yang valid: hex, base16, base64. Nilainya tidak peka huruf besar/kecil; hex dan base16 adalah sinonim. Default: base64

Contoh

Contoh ini menggunakan kebijakan AssignMessage untuk menghitung HMAC-256 dan menetapkannya ke variabel alur:

<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 mengilustrasikan cara membuat HMAC cascading yang dapat digunakan dengan proses penandatanganan AWS Signature v4. Contoh ini menggunakan kebijakan AssignMessage untuk membuat lima tingkat HMAC berurutan 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.

Sintaksis

createUuid()

Argumen

Tidak ada.

Contoh

{createUuid()}

Contoh hasil:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Fungsi Random Long Generator

Menampilkan bilangan bulat panjang acak.

Sintaksis

randomLong(args)

Argumen

• 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 akan diperlakukan sebagai nilai minimum komputasi.
• Jika ada, argumen kedua akan diperlakukan sebagai nilai maksimum komputasi.

Contoh

{random()}

akan menghasilkan sesuatu seperti ini:

5211338197474042880

Pembuat teks ekspresi reguler

Buat string teks yang cocok dengan ekspresi reguler tertentu.

Sintaksis

xeger(regex)

Argumen

regex - Ekspresi reguler.

Contoh

Contoh ini menghasilkan string tujuh digit tanpa nol:

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

Contoh hasil:

9857253

Fungsi penggabungan null

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

Sintaksis

firstnonnull(var1,varn)

Argumen

var1 - Variabel konteks.

var_n - Satu atau beberapa variabel konteks. Anda dapat menetapkan argumen 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:

Template	Var1	Var2	Var3	Hasil
{firstnonnull(var1,var2)}	Tidak ditetapkan	foo	T/A	foo
{firstnonnull(var1,var2)}	foo	bar	T/A	foo
{firstnonnull(var1,var2)}	foo	Tidak ditetapkan	T/A	foo
{firstnonnull(var1,var2,var3)}	foo	bar	baz	foo
{firstnonnull(var1,var2,var3)}	Tidak ditetapkan	bar	baz	bar
{firstnonnull(var1,var2,var3)}	Tidak ditetapkan	Tidak ditetapkan	baz	baz
{firstnonnull(var1,var2,var3)}	Tidak ditetapkan	Tidak ditetapkan	Tidak ditetapkan	null
{firstnonnull(var1)}	Tidak ditetapkan	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])

Argumen

xpath_expression - Ekspresi XPath.

xml_string - Variabel alur atau string yang berisi XML.

datatype - (Opsional) Menentukan jenis nilai yang ditampilkan kueri yang diinginkan. Dapat berupa nodeset, node, angka, boolean, string. Setelan defaultnya adalah nodeset. Nilai default biasanya merupakan pilihan yang tepat.

Contoh 1

Misalkan variabel konteks ini menentukan 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"

Dan fungsi xpath() digunakan dalam kebijakan AssignMessage, sebagai 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

Jika Anda hanya menginginkan nilai node, gunakan fungsi text(), sebagai berikut:

<AssignMessage>
  <AssignVariable>
    <Name>extracted_tag</Name>
    <Template>{xpath('/tag/tagid/text()',xml)}</Template>
  </AssignVariable>
</AssignMessage>

Sebagai hasil dari operasi ini, variabel konteks extracted_tag ditetapkan ke 250397

Jika beberapa node dipilih, hasil xpath() adalah semua nilai pilihan, yang digabungkan dengan koma.

Contoh 3: Namespace XML

Untuk menentukan namespace, tambahkan parameter tambahan, yang masing-masing merupakan string yang terlihat seperti prefix:namespaceuri. Misalnya, fungsi xpath() yang memilih elemen turunan 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().

Anda dapat menentukan ekspresi XPath sederhana sebagai string yang diapit tanda kutip tunggal:

{xpath('/tag/tagid/text()',xml)}

Jika ekspresi XPath menyertakan awalan namespace (dan titik dua), Anda harus menetapkan ekspresi XPath tersebut ke variabel dan menentukan nama variabel, bukan ekspresi secara langsung.

{xpath(xpathexpression,xml,ns1)}

Contoh 4: 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 menampilkan nilai numerik atau boolean. Misalnya, fungsi count() menampilkan angka. Ini adalah kueri XPath yang valid:

count(//Record/Fields/Pair)

Kueri yang valid ini menampilkan 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, parameter tersebut akan ditafsirkan sebagai argumen namespace. Jika tidak, nilai tersebut akan diperlakukan sebagai jenis nilai yang diinginkan. Dalam hal ini, jika parameter ketiga bukan salah satu nilai yang valid (mengabaikan huruf besar/kecil), fungsi xpath() akan menampilkan nodeset secara default.

Fungsi Jalur JSON

Menerapkan ekspresi Jalur JSON ke variabel JSON.

Sintaksis

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

Argumen

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

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, kumpulan hasil adalah satu elemen (bukan array elemen). Jika kumpulan hasil adalah array, hanya elemen nol array yang akan ditampilkan. Untuk menampilkan array lengkap, panggil fungsi dengan 'true' sebagai parameter ketiga, seperti yang ditunjukkan dalam 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']