Template pesan

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

Topik ini membahas cara menggunakan template pesan dalam proxy API dan menyediakan fungsi alamat IP internal.

Apa itu template pesan?

Template pesan memungkinkan Anda melakukan substitusi string variabel dalam kebijakan dan elemen 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 yang tidak dalam tanda kurung kurawal output 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 flow user.name (dalam tanda kurung kurawal) akan menjadi dievaluasi dan diganti ke dalam string payload saat runtime. Jadi, misalnya, jika user.name=jdoe, maka output pesan yang dihasilkan dalam payload akan menjadi: You entered an invalid username: jdoe. Jika variabel tidak dapat diselesaikan, string kosong akan dihasilkan.

Contoh

Jika kuota terlampaui, sebaiknya tampilkan pesan yang berarti kepada pemanggil. Ini pola ini biasanya digunakan dengan "aturan kesalahan" untuk memberikan output guna memberikan informasi kepada pemanggil 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 MenetapkanMessage, elemen berikut di <Set> pembuatan template pesan dukungan elemen:

• 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 dijalankan:

• Elemen Header menerima nilai dari variabel alur yang ditentukan.
• Payload mencakup campuran teks literal dan variabel (client_id diisi secara dinamis).
• StatusCode dan Penyebab Frasa hanya mencakup 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 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 di 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 dengan Alamat IP tertentu
Kebijakan TetapkanMessage	Elemen turunan <Set>: Payload, ContentType, Verb, Versi, Path, StatusCode, Restriction error, Header, QueryParams, FormParams Elemen turunan <Add>: Header, QueryParams, FormParams Elemen turunan <AssignVariable>: <Template>
Kebijakan ExtensionExtension	<Input>
Kebijakan ExtractVariables	<JsonPath>
Kebijakan GenerateJWS Verifikasi kebijakan JWS	<Payload> (khusus kebijakan GenerateJWS) <AdditionalHeaders><Claim> * Elemen ini hanya mendukung template pesan jika type=map.
Kebijakan GenerateJWT Verifikasi kebijakan JWT	<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, Versi, Path, StatusCode, Alasan Frasa, Header, QueryParams, FormParams Elemen <Add>: Header, QueryParams, FormParams
Kebijakan SAMLAssertion	<Template> * Hanya jika tanda tangan kebijakan adalah <GenerateSAMLAssertion>
Kebijakan ServiceInfo	Elemen <Set>: Payload, ContentType, Verb, Versi, Path, StatusCode, reasonDifference, /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 dalam tanda kurung kurawal { }. Jika variabel tidak ada, string kosong dikembalikan dalam {i>output<i}; Namun, Anda dapat menentukan nilai default dalam pesan template (nilai yang diganti jika variabel tidak terselesaikan). Lihat Menetapkan nilai default dalam template pesan.

Perlu diketahui bahwa menyertakan seluruh string template pesan dalam tanda kutip diizinkan, tetapi bersifat opsional. Misalnya, dua template pesan berikut adalah 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 menggantikan 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, maka nilainya 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 Cloud merilis 16.08.17, Anda tidak dapat gunakan tanda kurung kurawal untuk menunjukkan referensi variabel dalam payload JSON. Di versi lama tersebut, Anda perlu menggunakan atribut variablePrefix dan variableSuffix untuk menentukan karakter pembatas, dan menggunakannya untuk menggabungkan nama variabel, seperti:

<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, melakukan hashing, dan memformat variabel {i>string<i}.

Fungsi template pesan dijelaskan secara mendetail di Template pesan referensi fungsi.

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 diganti dan dikonversi menjadi karakter huruf kecil. Contoh:

Test header: foo

Contoh: escapeJSON()

Berikut ini kasus penggunaan yang menarik: Misalkan 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 menampilkan pesan ini ke pemanggil klien dalam payload kustom. Cara biasa untuk melakukannya adalah dengan mengekstrak pesan dari payload respons target dan menggunakan Tetapkan Pesan untuk menambahkannya ke respons proxy kustom (yaitu, mengirimkannya kembali ke klien).

Berikut ini 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 dan 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 kutipan yang di-escape di sekitar bagian pesan. Artinya, respons yang ditampilkan ke klien adalah JSON yang tidak valid. Ini jelas tidak seperti yang Anda maksudkan!

{
    "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(), meng-escape setiap 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 yang disematkan, sehingga menghasilkan JSON yang valid, persis seperti yang Anda inginkan:

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

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

Misalnya, dalam kebijakan MenetapkanMessage 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 yang Anda ketahui tentang pesan template dan konteks penggunaannya.

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 argumen string tunggal di mana algoritma {i>hash<i} dihitung. Argumen bisa berupa string literal atau variabel aliran 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 berenkode Base64.
sha256Base64(string)	Menghitung hash SHA256 yang dinyatakan sebagai nilai berenkode Base64.
sha384Base64(string)	Menghitung hash SHA384 yang dinyatakan sebagai penilai berenkode Base64.
sha512Base64(string)	Menghitung hash SHA512 yang dinyatakan sebagai nilai berenkode Base64.

Argumen

string - Fungsi hash mengambil argumen string tunggal di mana algoritma {i>hash<i} dihitung. Argumen bisa berupa string literal atau alur string variabel.

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

Melakukan enkode dan dekode string menggunakan skema encoding Base64.

Sintaksis

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

Argumen

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

Sintaksis

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

Argumen

string - String yang akan dikonversi. Dapat berupa string literal atau variabel aliran 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 aliran string.
• start_index - Indeks awal ke string.
• end_index - (Opsional) Indeks akhir ke dalam string. Jika tidak disediakan, indeks akhir adalah akhir {i>string<i}.

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

Ganti Semua fungsi

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

Sintaksis

replaceAll(string,regex,value)

Argumen

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

Contoh

Untuk contoh berikut, anggaplah ada variabel alur ini:

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

Ganti fungsi Pertama

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

Sintaksis

replaceFirst(string,regex,value)

Argumen

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

Fungsi escape dan encoding karakter

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

Sintaksis

Fungsi	Deskripsi
escapeJSON(string)	Garis miring terbalik - escape tanda kutip ganda.
escapeXML(string)	Ganti tanda kurung sudut, apostrof, kutip ganda, dan ampersan dengan entitas XML masing-masing. Gunakan untuk dokumen XML 1.0.
escapeXML11(string)	Bekerja dengan cara yang sama seperti escapeXML, tetapi untuk entity XML v1.1. Lihat Catatan penggunaan di bawah.
encodeHTML(string)	Mengenkode apostrof, tanda kurung sudut, dan ampersan.

Argumen

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

Catatan penggunaan

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

{escapeHTML(food)}

menghasilkan:

"bread" & "butter"

Fungsi format waktu

Menampilkan representasi string dari waktu, yang 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 - String atau variabel aliran string yang berisi nilai waktu. Nilainya bisa dalam seconds-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 tersebut 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 perhitungan HMAC berjenjang, seperti ketika 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. Nilainya harus berupa string.
• keyencoding - (Opsional) String kunci rahasia akan didekode sesuai dengan hal ini encoding yang ditentukan. 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 MenetapkanMessage 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 menggambarkan cara menghasilkan HMAC beruntun yang dapat digunakan dengan Proses penandatanganan AWS Signature v4. Contoh ini menggunakan kebijakan MenetapkanMessage untuk menghasilkan lima tingkat HMAC berjenjang yang digunakan untuk menghitung tanda tangan 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

Membuat 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 yang acak.

Sintaksis

randomLong(args)

Argumen

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

Contoh

{random()}

menghasilkan sesuatu seperti ini:

5211338197474042880

Pembuat 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.

var_n - Satu atau beberapa variabel konteks. Anda dapat mengatur ke string untuk memberikan nilai fallback (nilai yang akan ditetapkan jika tidak ada argumen sebelah kiri 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 - String atau variabel alur yang berisi XML.

datatype - (Opsional) Menentukan jenis nilai yang ditampilkan dari kueri yang diinginkan. Dapat berupa nodeset, node, angka, boolean, string. Nilai defaultnya adalah nodeset. Pilihan default biasanya adalah 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 MenetapkanMessage, 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 kolom 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>

Sebagai hasil dari operasi ini, variabel konteks extracted_tag disetel menjadi 250397

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

Contoh 3: Namespace XML

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

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

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

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

{xpath(xpathexpression,xml,ns1)}

Contoh 4: Menentukan jenis nilai yang diinginkan

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

Beberapa kueri XPath dapat menampilkan nilai numerik atau boolean. Misalnya, fungsi count() menghasilkan 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, parameter tersebut akan ditafsirkan sebagai argumen namespace. Jika tidak, jenis nilai yang ditampilkan tersebut akan diperlakukan sebagai jenis nilai yang diinginkan. Dalam hal ini, jika parameter ketiga tidak salah satu nilai yang valid (dengan mengabaikan huruf besar/kecil), fungsi xpath() secara default menampilkan 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) String atau variabel alur yang berisi JSON.
• (Opsional) want-array: (String) Jika disetel ke 'true' dan jika set hasilnya adalah array, maka semua elemen array dikembalikan. Jika ditetapkan ke nilai lain atau jika dihilangkan, maka hanya elemen nol dari larik set hasil dimunculkan. Jika rangkaian hasil bukan berupa himpunan (array), maka 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 fungsi tersebut adalah:

The address is 1060 West Addison Street

Perhatikan bahwa dalam kasus ini, set hasilnya adalah elemen tunggal (bukan array elemen). Jika rangkaian hasilnya adalah himpunan (array), kemudian hanya elemen ke-nol dari array yang akan dikembalikan. Untuk mengembalikan array lengkap, panggil fungsi dengan 'true' sebagai parameter ketiga, seperti yang ditunjukkan di 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 fungsi tersebut adalah:

['A','B']