Template pesan

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

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

Apa itu template pesan?

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

Anda dapat menyertakan kombinasi apa pun dari referensi variabel alur dan teks literal dalam template pesan. Nama variabel alur harus diapit dalam tanda kurung kurawal, sedangkan teks 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 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 alur user.name (dalam tanda kurung kurawal) akan dievaluasi dan diganti dengan string payload saat runtime. Jadi, misalnya, jika user.name=jdoe, maka output pesan yang dihasilkan dalam payload adalah: 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 bersama "aturan kesalahan" untuk memberikan output guna memberi pemanggil informasi tentang pelanggaran kuota. Dalam kebijakan Tetapkan Pesan 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>
    <ReasonPhrase>Quota Exceeded</ReasonPhrase>
  </Set>
</AssignMessage>

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

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

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

Saat kebijakan ini dijalankan:

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

Contoh

Dalam definisi TargetEndpoint proxy, elemen turunan <SSLInfo> mendukung template pesan. Dengan mengikuti pola yang sama dengan yang digunakan dalam kebijakan, variabel flow 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.

Kebijakan yang menerima template pesan

Kebijakan Elemen dan elemen turunan yang mendukung template pesan
Kebijakan AccessControl <SourceAddress>, untuk atribut mask dan alamat IP.
KebijakanAssignMessage Elemen turunan <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams

Elemen turunan <Add>: Header, QueryParams, FormParams

Elemen turunan <AssignVariable>: <Template>

Kebijakan ExtensionInfo <Input>
Kebijakan ExtractVariables <JsonPath>
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 LDAP <SearchQuery>
Kebijakan MessageLogging <Syslog><Message>

<File><Message>
Kebijakan OASValidation Elemen <OASResource>
Kebijakan RaiseFault Elemen <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams

Elemen <Add>: Header, QueryParams, FormParams

Kebijakan SAMLAssertion <Template>

* Hanya jika tanda tangan kebijakan adalah <GenerateSAMLAssertion>
Kebijakan InfoService Elemen <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, /Headers, QueryParams, FormParams

Elemen <Add>: Header, QueryParams, FormParams

<HTTPTargetConnection>/<URL>: Perhatikan bahwa bagian pertama string harus http atau https.

Elemen TargetEndpoint yang menerima template pesan

Elemen HTTPTargetConnection Elemen turunan yang mendukung template pesan
SSLInfo Diaktifkan, KeyAlias, KeyStore, TrustStore, ClientAuthEnabled, CLRStore
LocalTargetConnection ApiProxy, ProxyEndpoint
Jalur T/A

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 di dalam kurung kurawal { }. Jika variabel tidak ada, string kosong akan ditampilkan di output; namun, Anda dapat menentukan nilai default di template pesan (nilai yang diganti jika variabel tidak diselesaikan). Lihat Menetapkan nilai default di template pesan.

Perhatikan bahwa menyertakan seluruh string template pesan dalam tanda kutip diizinkan, 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>

Menetapkan nilai default dalam template pesan

Jika variabel template tidak dapat diselesaikan, Edge akan mengganti string kosong. Namun, Anda dapat menentukan nilai default seperti 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

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

Pada versi Edge sebelum Cloud rilis 16.08.17, Anda tidak dapat 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 masih berfungsi.

Menggunakan fungsi template pesan

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

Fungsi template pesan dijelaskan secara mendetail dalam 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, karakternya akan menjadi huruf kecil semua. Jika foo.bar tidak diselesaikan, nilai default FOO akan diganti dan dikonversi menjadi karakter huruf kecil. Contoh: 

Test header: foo

Contoh: escapeJSON()

Berikut ini 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, katakanlah Anda ingin mengembalikan pesan ini ke pemanggil klien dalam payload khusus. Cara yang biasa untuk melakukan ini adalah dengan mengekstrak pesan dari payload respons target dan menggunakan Tetapkan Pesan untuk menambahkannya ke respons proxy khusus (yaitu, mengirimkannya kembali ke klien).

Berikut adalah kebijakan Ekstrak Variabel 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>

Berikut adalah kebijakan Tetapkan Pesan 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 Ekstrak Variabel menghapus karakter kutipan yang di-escape di sekitar bagian pesan. Ini berarti bahwa respons yang dikembalikan 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 Tetapkan Pesan untuk menggunakan fungsi template pesan yang memisahkan tanda kutip dalam JSON untuk Anda. Fungsi ini, escapeJSON(), meng-escape tanda kutip atau karakter khusus lainnya yang terjadi 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 kutip tersemat, 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 dalam 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>

Topik ini menjelaskan fungsi template pesan, argumen, dan outputnya. Topik ini mengasumsikan bahwa Anda sudah memahami template pesan dan konteks yang digunakannya.

Fungsi hash

Hitung nilai hash dan tampilkan representasi string dari hash tersebut.

Fungsi hash heksadesimal

Hitung nilai hash dan tampilkan 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.

Argumen

string - Fungsi Hash mengambil 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

Hitung nilai hash dan tampilkan representasi string dari hash tersebut sebagai nilai berenkode Base64.

Sintaksis

Fungsi Deskripsi
md5Base64(string) Menghitung hash MD5 yang dinyatakan sebagai nilai berenkode 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 pemberi nilai berenkode Base64.
sha512Base64(string) Menghitung hash SHA512 yang dinyatakan sebagai nilai yang dienkode Base64.

Argumen

string - Fungsi Hash mengambil satu argumen string yang digunakan untuk menghitung algoritma hash. Argumennya 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

Menjalankan operasi pada string dalam template pesan.

Fungsi encoding Base64

Lakukan enkode dan dekode string menggunakan skema encoding Base64.

Sintaksis

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

Argumen

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

Mengonversi string menjadi huruf besar semua atau huruf kecil.

Sintaksis

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


Argumen

string - String yang akan dikonversi. Dapat berupa string literal atau variabel flow 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)

Argumen

  • str - String literal atau variabel alur 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 Ganti Semua

Menerapkan ekspresi reguler ke string, dan untuk kecocokan apa pun, menggantikan kecocokan dengan nilai pengganti.

Sintaksis

replaceAll(string,regex,value)

Argumen

  • string - String literal atau variabel alur string yang digunakan untuk melakukan penggantian.
  • regex - Ekspresi reguler.
  • nilai - Nilai yang akan menggantikan semua ekspresi reguler yang cocok dalam string.

Contoh

Untuk contoh berikut, anggap variabel flow 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 Ganti First

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

Sintaksis

replaceFirst(string,regex,value)

Argumen

  • string - String literal atau variabel alur string yang digunakan untuk melakukan penggantian.
  • regex - Ekspresi reguler.
  • nilai - Nilai yang akan menggantikan pencocokan ekspresi reguler dalam string.

Fungsi encoding dan escape karakter

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

Sintaksis

Fungsi Deskripsi
escapeJSON(string) Tanda kutip ganda untuk {i>back-slash-escape<i}.
escapeXML(string) Mengganti tanda kurung sudut, apostrof, tanda kutip ganda, dan ampersand dengan entitas XML yang bersangkutan. Gunakan untuk dokumen XML 1.0.

escapeXML11(string) Berfungsi 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 ampersand.

Argumen

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

Catatan penggunaan

XML 1.1 dapat merepresentasikan karakter kontrol tertentu, tetapi tidak dapat menyatakan byte null atau titik kode pengganti Unicode yang tidak dipasangkan, 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 variabel flow bernama food ada dengan nilai ini: "bread" & "butter". Kemudian, fungsi: 

{escapeHTML(food)}

menghasilkan:

&quot;bread&quot; &amp; &quot;butter&quot;

Fungsi format waktu

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

Sintaksis

Fungsi Deskripsi
timeFormat(format,str) Menampilkan tanggal yang diformat dalam zona waktu lokal.
timeFormatMs(format,str) Menampilkan tanggal yang diformat dalam zona waktu lokal.
timeFormatUTC(format,str) Menampilkan tanggal yang diformat dalam UTC.
timeFormatUTCMs(format,str) Menampilkan tanggal yang diformat dalam UTC.

Argumen

  • format - String format tanggal/waktu. Dapat berupa string literal atau variabel string.
  • str - Variabel aliran string atau string yang berisi nilai waktu. Nilainya dapat dalam satuan detik sejak epoch atau milidetik sejak epoch untuk timeFormatMs.

Contoh

Asumsikan nilai berikut dan anggaplah 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 untuk menghitung HMAC. Fungsi ini berguna saat melakukan penghitungan HMAC bertingkat, 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 didekodekan 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 BiddingMessage 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 membuat HMAC bertingkat yang dapat digunakan dengan proses penandatanganan AWS Signature v4. Contoh ini menggunakan kebijakan TetapkanMessage untuk menghasilkan lima level HMAC bertingkat 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 Generator Panjang Acak

    Menampilkan bilangan bulat panjang acak.

    Sintaksis

    randomLong(args)

    Argumen

    • Jika tidak ada argumen yang ditentukan, fungsi akan menampilkan bilangan bulat panjang yang 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 maksimum komputasi.

    Contoh

    {random()}

    menghasilkan sesuatu seperti ini: 

    5211338197474042880

    Generator teks ekspresi reguler

    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 nol: 

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

    Contoh hasil: 

    9857253

    Fungsi penggabungan null

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

    Sintaksis

    firstnonnull(var1,varn)

    Argumen

    var1 - Variabel konteks.

    varn - Satu atau beberapa variabel konteks. Anda dapat menetapkan argumen paling kanan ke string untuk memberikan nilai fallback (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)} 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 flow atau string yang berisi XML.

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

    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, 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(), seperti berikut:

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

    Akibat operasi ini, variabel konteks extracted_tag ditetapkan ke 250397

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

    Contoh 3: Namespace XML

    Untuk menentukan namespace, tambahkan parameter tambahan, masing-masing berupa 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().

    Anda dapat menentukan ekspresi XPath sederhana sebagai string yang dikelilingi oleh 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 tersebut 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 mengembalikan 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, hal tersebut 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 kumpulan node.

    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 flow 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, maka hanya elemen ke-nol dari array kumpulan hasil yang akan ditampilkan. Jika kumpulan hasilnya bukan sebuah 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, dalam hal ini, kumpulan hasilnya adalah elemen tunggal (bukan array elemen). Jika kumpulan hasilnya adalah array, hanya elemen ke-nol dari array 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']