Halaman ini diterjemahkan oleh Cloud Translation API.

Template pesan

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

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 substitusi 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 alur harus diapit tanda kurung kurawal, sedangkan teks apa pun yang tidak berada dalam tanda kurung kurawal akan ditampilkan sebagai teks literal.

Lihat juga Di mana Anda dapat menggunakan template pesan?

Contoh

Misalnya, kebijakan AssignMessage memungkinkan Anda menggunakan template pesan dalam elemen <Payload>:

<AssignMessage name="AM-set-payload-with-dynamic-content">
  <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, maka output pesan yang dihasilkan dalam payload adalah: You entered an invalid username: jdoe. Jika variabel tidak dapat diselesaikan, string kosong akan ditampilkan.

Contoh

Jika kuota terlampaui, sebaiknya tampilkan pesan yang bermakna kepada pemanggil. Pola ini biasanya digunakan dengan "aturan kesalahan" untuk memberikan output guna memberikan informasi kepada pemanggil tentang pelanggaran kuota. Dalam kebijakan AssignMessage 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>
  </Set>
</AssignMessage>

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

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

Sekali lagi, perhatikan bahwa variabel alur dalam template pesan harus diapit 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> 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 pembuatan template pesan. 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.

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

Kebijakan yang menerima template pesan

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

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

`<TargetEndpoint>` elemen yang menerima template pesan

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

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 mengapit seluruh string template pesan dalam tanda petik diizinkan, tetapi bersifat opsional. Misalnya, dua template pesan berikut bersifat setara:

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

Spasi tidak diizinkan dalam ekspresi fungsi

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

Diizinkan:

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

Tidak Diizinkan:

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

Fungsi bertingkat tidak didukung

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

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

Sertakan literal string dalam fungsi template dalam tanda kutip tunggal

Saat memberikan literal string dalam fungsi, sertakan dalam tanda kutip tunggal, bukan tanda kutip ganda.

Misalnya,

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

Hindari penggunaan karakter khusus dalam literal string

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

Menetapkan nilai default dalam template pesan

Jika variabel ber-template tidak dapat diselesaikan, Apigee 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>

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

Test message. id = Unknown

Pembuatan template URL

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

Contoh ini menunjukkan URL yang dibuat menggunakan variabel:

<URL>{targeturl}</URL>

Contoh ini menunjukkan nilai default untuk protokol:

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

Sintaksis lama untuk payload JSON

Pada versi Apigee sebelum rilis Cloud 16.08.17, Anda tidak dapat menggunakan tanda 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 membungkus 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 yang lebih lama masih berfungsi.

Menggunakan fungsi template pesan

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

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

Test header: foo

Contoh: escapeJSON()

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

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

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

Sekarang, berikut adalah kebijakan AssignMessage yang sepenuhnya 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>response</AssignTo>
</AssignMessage>

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

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

Untuk mengatasi masalah ini, Anda dapat mengubah kebijakan AssignMessage untuk menggunakan fungsi template pesan yang meng-escape tanda petik dalam JSON untuk Anda. Fungsi ini, escapeJSON(), akan mengganti karakter 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>response</AssignTo>
</AssignMessage>

Fungsi ini akan mengganti karakter kutipan 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, penghindaran karakter, dan lainnya dalam template pesan.

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

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

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

Fungsi hash

Hitung nilai hash dan tampilkan representasi string dari hash tersebut.

Fungsi hash heksadesimal

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

Sintaks

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 (diapit dalam tanda kutip tunggal) atau variabel aliran 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.

Sintaks

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

Argumen

string: Fungsi Hash mengambil satu argumen string yang digunakan untuk menghitung algoritma hash. Argumen dapat berupa string literal (diapit dalam tanda kutip tunggal) atau variabel aliran string.

Contoh

Panggilan fungsi:

sha256Base64('abc')

Hasil:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Panggilan fungsi:

var str = 'abc';
sha256Base64(str)

Hasil:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Fungsi string

Lakukan operasi pada string dalam template pesan.

Fungsi encoding Base64

Enkode dan dekode string menggunakan skema encoding Base64.

Sintaks

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

Argumen

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

Contoh

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

Fungsi konversi huruf

Mengonversi string menjadi semua huruf besar atau semua huruf kecil.

Sintaks

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 (diapit dalam tanda kutip tunggal) atau variabel alur string.

Contoh

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

Fungsi substring

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

Sintaks

substring(str,start_index,end_index)

Argumen

str: String literal (diapit dalam tanda kutip tunggal) 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 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 setiap kecocokan, mengganti kecocokan dengan nilai pengganti.

Sintaks

replaceAll(string,regex,value)

Argumen

string - String literal (diapit dalam tanda kutip tunggal) atau variabel alur string tempat penggantian akan dilakukan.
regex - Ekspresi reguler.
value - Nilai untuk mengganti semua kecocokan regex dalam string.

Contoh

Untuk contoh berikut, asumsikan variabel alur ini ada:

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

Berikut adalah hasil panggilan fungsi yang menggunakan variabel ini:

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

Replace First function

Mengganti hanya kecocokan ekspresi reguler yang ditentukan pertama dalam string.

Sintaks

replaceFirst(string,regex,value)

Argumen

string: String literal (diapit dalam tanda kutip tunggal) atau variabel alur string tempat penggantian akan dilakukan.
regex: Ekspresi reguler.
value: Nilai untuk mengganti kecocokan regex dalam string.

Fungsi encoding dan escape karakter

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

Sintaks

Fungsi	Deskripsi
`escapeJSON(string)`	Meng-escape tanda kutip ganda dengan garis miring terbalik.
`escapeXML(string)`	Mengganti tanda kurung sudut, apostrof, tanda petik ganda, dan ampersand dengan entitas XML masing-masing. Digunakan untuk dokumen XML 1.0. Gunakan escapeXML untuk dokumen XML1.0 dan escapeXML11 untuk dokumen XML 1.1.
`escapeXML11(string)`	Berfungsi 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 (diapit dalam tanda kutip tunggal) atau variabel alur string.

Catatan penggunaan

XML 1.1 dapat merepresentasikan karakter kontrol tertentu, tetapi tidak dapat merepresentasikan byte null atau titik kode pengganti Unicode yang tidak berpasangan, bahkan setelah melakukan 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 alur 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, yang diformat dalam UTC.

Sintaks

Fungsi	Deskripsi
`timeFormat(format,str)`	Menampilkan tanggal yang diformat dalam UTC. `DEPRECATED`: Menampilkan tanggal yang diformat dalam zona waktu lokal.
`timeFormatMs(format,str)`	Menampilkan tanggal yang diformat dalam UTC. `DEPRECATED`: 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 (diapit dalam tanda kutip tunggal) atau variabel string. Gunakan variabel, bukan literal, jika format menyertakan titik dua. Lihat catatan sebelumnya di bagian ini.
str: Variabel string atau string flow 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 bertingkat, seperti saat output satu HMAC digunakan sebagai kunci untuk HMAC kedua.

Sintaks

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

Sintaks

createUuid()

Argumen

Tidak ada.

Contoh

{createUuid()}

Contoh hasil:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Fungsi Random Long Generator

Menampilkan bilangan bulat panjang acak.

Sintaks

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

Contoh

{randomLong()}

Hasilnya akan seperti ini:

5211338197474042880

Pembuat teks ekspresi reguler

Buat string teks yang cocok dengan ekspresi reguler tertentu.

Sintaks

xeger(regex)

Argumen

regex: Ekspresi reguler.

Contoh

Contoh ini menghasilkan string tujuh digit tanpa angka nol:

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

Contoh hasil:

Fungsi penggabungan null

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

Sintaks

firstnonnull(var1,var_n)

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 menggambarkan cara menggunakan fungsi ini:

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

Fungsi XPath

Menerapkan ekspresi XPath ke variabel XML.

Sintaks

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 yang diinginkan untuk kueri. Nilai yang valid adalah nodeset, node, number, boolean, atau string. Nilai defaultnya adalah nodeset. 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"

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: Namespace XML

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

Daripada menentukan ekspresi XPath dengan karakter khusus sebagai literal string, gunakan variabel untuk menyertakan string tersebut dalam fungsi. Lihat Hindari penggunaan karakter khusus dalam literal string untuk mengetahui detailnya.

{xpath(xpathexpression,xml,ns1)}

Contoh 3: Menentukan jenis nilai yang ditampilkan yang diinginkan

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

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, maka parameter tersebut ditafsirkan sebagai argumen namespace. Jika tidak, maka 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() secara default akan menampilkan nodeset.

Fungsi Jalur JSON

Mengevaluasi ekspresi JSON Path terhadap variabel JSON.

Sintaks

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

Argumen

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

Anda dapat menggunakan variabel untuk argumen apa pun. Jika Anda menggunakan string tetap, sertakan dalam tanda kutip tunggal.

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

The address is 1060 West Addison Street

Nilai yang ditampilkan untuk kueri jsonPath ini akan berupa array yang berisi satu elemen. Fungsi jsonPath di Apigee secara default mengasumsikan Anda menginginkan satu nilai, untuk digunakan dalam interpolasi string. Oleh karena itu, Apigee hanya menampilkan elemen ke-nol dari array. Untuk meminta seluruh array, 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:

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

Hasil fungsi adalah:

["A","B"]

Dalam hal ini, parameter ketiga fungsi ditetapkan ke true, sehingga fungsi jsonPath menampilkan array lengkap, dalam sintaksis array JSON, bukan elemen nol.

Contoh 3

Jika the_json_variable berisi:

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

dan the_query berisi:

$.config.quota[?(@.operation=="ManageOrder")].appname

Hasil template pesan: {jsonPath(the_query,the_json_variable,true)} adalah ["A","B"]

Dengan menggunakan variabel untuk kueri, Anda dapat membuat kueri saat runtime, menggunakan data dinamis. Anda dapat melakukannya dengan elemen <AssignVariable> dalam kebijakan AssignMessage.

Misalnya, jika variabel operationname berisi nilai ManageOrder, kebijakan berikut akan menetapkan the_query ke kueri yang ditampilkan di atas.

<AssignMessage>
    <AssignVariable>
      <Name>the_query</Name>
      <Template>$.config.quota[?(@.operation=="{operationname}")].appname</Template>
    </AssignVariable>
  </AssignMessage>

Template pesan Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Apa yang dimaksud dengan template pesan?

Contoh

Contoh

Contoh

Di mana Anda dapat menggunakan template pesan?

Kebijakan yang menerima template pesan

<TargetEndpoint> elemen yang menerima template pesan

Sintaksis template pesan

Menggunakan kurung kurawal untuk menunjukkan variabel

Spasi tidak diizinkan dalam ekspresi fungsi

Fungsi bertingkat tidak didukung

Sertakan literal string dalam fungsi template dalam tanda kutip tunggal

Hindari penggunaan karakter khusus dalam literal string

Menetapkan nilai default dalam template pesan

Pembuatan template URL

Sintaksis lama untuk payload JSON

Menggunakan fungsi template pesan

Contoh: toLowerCase()

Contoh: escapeJSON()

Fungsi hash

Fungsi hash heksadesimal

Sintaks

Argumen

Contoh

Fungsi hash Base64

Sintaks

Argumen

Contoh

Fungsi string

Fungsi encoding Base64

Sintaks

Argumen

Contoh

Fungsi konversi huruf

Sintaks

Argumen

Contoh

Fungsi substring

Sintaks

Argumen

Contoh

Fungsi Ganti Semua

Sintaks

Argumen

Contoh

Replace First function

Sintaks

Argumen

Fungsi encoding dan escape karakter

Sintaks

Argumen

Catatan penggunaan

Contoh

Fungsi format waktu

Sintaks

Argumen

Contoh

Fungsi penghitungan HMAC

Sintaks

Argumen

Contoh

Fungsi lainnya

Membuat fungsi UUID

Sintaks

Argumen

Contoh

Fungsi Random Long Generator

Sintaks

Argumen

Contoh

Pembuat teks ekspresi reguler

Sintaks

Argumen

Contoh

Fungsi penggabungan null

Sintaks

Argumen

Contoh

Fungsi XPath

Template pesan

`<TargetEndpoint>` elemen yang menerima template pesan