Mẫu tin nhắn

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X. thông tin

Chủ đề này thảo luận về cách sử dụng mẫu tin nhắn trong proxy API và cung cấp tài liệu tham khảo về hàm.

Mẫu tin nhắn là gì?

Mẫu thông báo cho phép bạn thực hiện thay thế chuỗi biến trong một số phần tử chính sách và TargetEndpoint nhất định. Tính năng này (nếu được hỗ trợ) cho phép bạn điền các chuỗi một cách linh động khi một proxy thực thi.

Bạn có thể đưa bất kỳ tổ hợp tham chiếu biến flow và văn bản cố định nào vào mẫu thông báo. Tên biến Flow phải được đặt trong dấu ngoặc nhọn, trong khi mọi văn bản không nằm trong dấu ngoặc nhọn sẽ được xuất dưới dạng văn bản cố định.

Xem thêm bài viết Bạn có thể sử dụng mẫu thư ở đâu?

Ví dụ:

Ví dụ: Chính sách Chỉ định thông báo cho phép bạn sử dụng mẫu thông báo trong phần tử <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>

Trong ví dụ trên, giá trị của biến flow user.name (trong dấu ngoặc nhọn) sẽ được đánh giá và thay thế vào chuỗi tải trọng trong thời gian chạy. Ví dụ: nếu user.name=jdoe, thì kết quả đầu ra của thông báo trong tải trọng sẽ là: You entered an invalid username: jdoe. Nếu không thể phân giải biến, thì một chuỗi trống sẽ được xuất ra.

Ví dụ:

Khi vượt quá hạn mức, bạn nên trả về một thông báo có ý nghĩa cho phương thức gọi. Mẫu này thường được sử dụng với "quy tắc lỗi" để cung cấp đầu ra cho người gọi thông tin về lỗi vi phạm hạn mức. Trong chính sách Chỉ định thông báo sau đây, các mẫu thông báo được dùng để điền thông tin về hạn mức một cách linh động trong một số phần tử 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>

Trong chính sách AssignMessage, các phần tử sau trong phần tử <Set> hỗ trợ tạo mẫu thông báo:

• Tiêu đề
• QueryParam
• FormParam
• PayLoad
• Phiên bản
• Động từ
• Đường dẫn
• StatusCode
• ReasonPhrase

Xin lưu ý rằng các biến flow trong mẫu tin nhắn phải được đặt trong dấu ngoặc nhọn.

Thời điểm thực thi chính sách này:

• Các phần tử Tiêu đề nhận giá trị của các biến flow được chỉ định.
• Tải trọng bao gồm văn bản cố định và biến (client_id được điền động).
• StatusCode và ReasonPhrase chỉ chứa văn bản cố định; tuy nhiên, các phần tử này cũng hỗ trợ tạo mẫu thông báo nếu bạn muốn sử dụng.

Ví dụ:

Trong định nghĩa TargetEndpoint proxy, các phần tử con của <SSLInfo> hỗ trợ tạo mẫu thông báo. Theo cùng một mẫu được sử dụng trong các chính sách, các biến flow trong dấu ngoặc nhọn sẽ được thay thế khi proxy thực thi.

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

Bạn có thể sử dụng mẫu thư ở đâu?

Mẫu thông báo được hỗ trợ trong một số chính sách cũng như một số phần tử nhất định được dùng trong cấu hình TargetEndpoint.

Chính sách chấp nhận mẫu tin nhắn

Các phần tử TargetEndpoint chấp nhận mẫu tin nhắn

Cú pháp mẫu tin nhắn

Phần này giải thích các quy tắc bạn phải tuân thủ để sử dụng mẫu thư.

Dùng dấu ngoặc nhọn để biểu thị biến

Đặt tên biến trong dấu ngoặc nhọn { }. Nếu biến không tồn tại, một chuỗi trống sẽ được trả về trong kết quả; tuy nhiên, bạn có thể chỉ định giá trị mặc định trong mẫu thông báo (giá trị được thay thế nếu biến không được phân giải). Xem phần Đặt giá trị mặc định trong mẫu tin nhắn.

Xin lưu ý rằng bạn có thể (nhưng không bắt buộc) đặt dấu ngoặc kép xung quanh toàn bộ chuỗi mẫu thư. Ví dụ: hai mẫu thông báo sau đây tương đương nhau:

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

Đặt giá trị mặc định trong mẫu tin nhắn

Nếu không thể phân giải biến mẫu, Edge sẽ thay thế bằng một chuỗi trống. Tuy nhiên, bạn có thể chỉ định giá trị mặc định như sau:

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

Trong mẫu trên, nếu không thể phân giải biến request.header.id, thì giá trị của biến này sẽ được thay thế bằng Unknown. Ví dụ:

Test message. id = Unknown

Không được dùng dấu cách trong biểu thức hàm

Không được phép có dấu cách ở bất kỳ vị trí nào trong biểu thức hàm của mẫu tin nhắn. Ví dụ:

Được phép:

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

Không được phép:

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

Cú pháp cũ cho gói dữ liệu JSON

Trong các phiên bản Edge trước bản phát hành Cloud 16.08.17, bạn không thể sử dụng dấu ngoặc nhọn để biểu thị tham chiếu biến trong tải trọng JSON. Trong các phiên bản cũ đó, bạn cần sử dụng các thuộc tính variablePrefix và variableSuffix để chỉ định ký tự phân cách và sử dụng các ký tự đó để gói tên biến, như sau:

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

Mặc dù Apigee khuyên bạn nên sử dụng cú pháp dấu ngoặc nhọn mới hơn, nhưng cú pháp cũ vẫn hoạt động.

Sử dụng các hàm mẫu tin nhắn

Edge cung cấp một tập hợp các hàm mà bạn có thể sử dụng trong mẫu thông báo để thoát, mã hoá, băm và định dạng các biến chuỗi.

Các hàm mẫu thông báo được mô tả chi tiết trong phần Tài liệu tham khảo về hàm mẫu thông báo.

Ví dụ: toLowerCase()

Sử dụng hàm toLowerCase() tích hợp sẵn để chuyển đổi biến chuỗi thành chữ thường:

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

Nếu biến flow foo.bar phân giải, thì các ký tự của biến đó sẽ đều là chữ thường. Nếu foo.bar không được phân giải, thì giá trị mặc định FOO sẽ được thay thế và chuyển đổi thành ký tự viết thường. Ví dụ:

Test header: foo

Ví dụ: escapeJSON()

Sau đây là một trường hợp sử dụng thú vị: Giả sử ứng dụng phụ trợ của bạn trả về một phản hồi JSON chứa các ký tự thoát hợp lệ. Ví dụ:

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

Sau đó, giả sử bạn muốn trả về thông báo này cho phương thức gọi ứng dụng trong một tải trọng tuỳ chỉnh. Cách thông thường để thực hiện việc này là trích xuất thông báo từ tải trọng phản hồi mục tiêu và sử dụng Assign Message (Gán thông báo) để thêm thông báo đó vào phản hồi proxy tuỳ chỉnh (tức là gửi lại thông báo đó cho ứng dụng).

Dưới đây là chính sách Trích xuất biến để trích xuất thông tin user_message vào một biến có tên là standard.systemMessage:

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

Sau đây là chính sách Assign Message (Gán thông báo) hợp lệ hoàn toàn, thêm biến đã trích xuất vào tải trọng phản hồi (phản hồi 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>

Rất tiếc, đã xảy ra sự cố. Chính sách Trích xuất biến đã xoá các ký tự dấu ngoặc kép thoát xung quanh một phần của thông báo. Điều này có nghĩa là phản hồi được trả về cho ứng dụng khách là JSON không hợp lệ. Rõ ràng là bạn không muốn điều này!

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

Để giải quyết vấn đề này, bạn có thể sửa đổi chính sách Chỉ định thông báo để sử dụng hàm mẫu thông báo giúp bạn thoát khỏi dấu ngoặc kép trong JSON. Hàm này, escapeJSON(), sẽ thoát mọi dấu ngoặc kép hoặc các ký tự đặc biệt khác xuất hiện trong biểu thức 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>

Hàm này thoát khỏi các dấu ngoặc kép được nhúng, dẫn đến JSON hợp lệ, chính xác là những gì bạn muốn:

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

Mẫu thông báo là một tính năng thay thế chuỗi động mà bạn có thể sử dụng trong một số chính sách và trong định nghĩa TargetEndpoint. Hàm của mẫu thông báo cho phép bạn thực hiện các thao tác hữu ích như băm, thao tác với chuỗi, thoát ký tự và các thao tác khác trong mẫu thông báo.

Ví dụ: trong chính sách AssignMessage sau đây, hàm toLowerCase() được dùng trong mẫu thông báo:

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

Chủ đề này mô tả các hàm mẫu thư, đối số và đầu ra của các hàm đó. Chủ đề này giả định rằng bạn đã quen thuộc với mẫu thông báo và ngữ cảnh sử dụng các mẫu đó.

Hàm băm

Tính toán giá trị băm và trả về chuỗi đại diện của giá trị băm đó.

Hàm băm thập lục phân

Tính toán giá trị băm và trả về giá trị biểu diễn chuỗi của hàm băm đó dưới dạng số thập lục phân.

Cú pháp

Đối số

string – Hàm băm nhận một đối số chuỗi duy nhất để tính toán thuật toán băm. Đối số có thể là một chuỗi cố định hoặc biến luồng chuỗi.

Ví dụ

Lệnh gọi hàm:

sha256Hex('abc')

Kết quả:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Lệnh gọi hàm:

var str = 'abc';
sha256Hex(str)

Kết quả:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Hàm băm Base64

Tính toán giá trị băm và trả về giá trị đại diện chuỗi của giá trị băm đó dưới dạng giá trị được mã hoá Base64.

Cú pháp

Đối số

string – Hàm băm nhận một đối số chuỗi duy nhất để tính toán thuật toán băm. Đối số có thể là một chuỗi cố định hoặc biến luồng chuỗi.

Ví dụ

Lệnh gọi hàm:

sha256Base64('abc')

Kết quả:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Lệnh gọi hàm:

var str = 'abc';
sha256Base64(str)

Kết quả:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Hàm chuỗi

Thực hiện các thao tác trên chuỗi trong mẫu tin nhắn.

Hàm mã hoá Base64

Mã hoá và giải mã chuỗi bằng lược đồ mã hoá Base64.

Cú pháp

Đối số

string – Chuỗi cần mã hoá hoặc giải mã. Có thể là một chuỗi cố định hoặc biến luồng chuỗi.

Ví dụ:

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

Hàm chuyển đổi chữ hoa chữ thường

Chuyển đổi một chuỗi thành toàn bộ chữ hoa hoặc toàn bộ chữ thường.

Cú pháp

Đối số

chuỗi – Chuỗi cần chuyển đổi. Có thể là một chuỗi cố định hoặc biến luồng chuỗi.

Ví dụ:

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

Hàm chuỗi con

Trả về các ký tự nằm giữa chỉ mục bắt đầu và kết thúc của chuỗi đã chỉ định.

Cú pháp

substring(str,start_index,end_index)

Đối số

• str – Chuỗi cố định hoặc biến luồng chuỗi.
• start_index – Chỉ mục bắt đầu của chuỗi.
• end_index – (Không bắt buộc) Chỉ mục kết thúc của chuỗi. Nếu không được cung cấp, chỉ mục kết thúc là cuối chuỗi.

Ví dụ

Đối với các ví dụ sau, giả sử các biến flow này tồn tại:

Sau đây là kết quả của các lệnh gọi hàm sử dụng các biến này:

Hàm Thay thế tất cả

Áp dụng một biểu thức chính quy cho một chuỗi và cho mọi kết quả trùng khớp, thay thế kết quả trùng khớp bằng một giá trị thay thế.

Cú pháp

replaceAll(string,regex,value)

Đối số

• string – Chuỗi cố định hoặc biến flow string để thay thế.
• regex – Biểu thức chính quy.
• value – Giá trị để thay thế tất cả kết quả khớp với biểu thức chính quy trong chuỗi.

Ví dụ

Đối với các ví dụ sau, giả sử các biến flow này tồn tại:

Dưới đây là kết quả của các lệnh gọi hàm sử dụng các biến này:

Thay thế hàm First

Chỉ thay thế lần xuất hiện đầu tiên của kết quả so khớp biểu thức chính quy đã chỉ định trong chuỗi.

Cú pháp

replaceFirst(string,regex,value)

Đối số

• string – Chuỗi cố định hoặc biến flow string để thay thế.
• regex – Biểu thức chính quy.
• value – Giá trị thay thế các kết quả khớp với biểu thức chính quy trong chuỗi.

Hàm mã hoá và thoát ký tự

Các hàm thoát hoặc mã hoá ký tự đặc biệt trong một chuỗi.

Cú pháp

Đối số

chuỗi – Chuỗi cần thoát. Có thể là một chuỗi cố định hoặc biến luồng chuỗi.

Lưu ý về cách sử dụng

XML 1.1 có thể biểu thị một số ký tự điều khiển nhất định, nhưng không thể biểu thị byte rỗng hoặc điểm mã đại diện Unicode chưa ghép nối, ngay cả sau khi thoát. Hàm escapeXML11() xoá các ký tự không phù hợp với các dải sau:

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

Hàm escapeXML11() thoát các ký tự trong các dải sau:

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

Ví dụ

Giả sử có một biến flow có tên là food với giá trị này: "bread" & "butter". Sau đó, hàm:

{escapeHTML(food)}

dẫn đến:

Hàm định dạng thời gian

Trả về một chuỗi đại diện cho thời gian, được định dạng theo múi giờ địa phương hoặc theo giờ UTC.

Cú pháp

Đối số

• format – Chuỗi định dạng ngày/giờ. Có thể là một chuỗi cố định hoặc biến chuỗi.
• str – Một biến chuỗi hoặc luồng chuỗi chứa giá trị thời gian. Giá trị có thể tính bằng giây kể từ thời gian bắt đầu của hệ thống hoặc mili giây kể từ thời gian bắt đầu của hệ thống cho timeFormatMs.

Ví dụ

Giả sử các giá trị sau và giả sử múi giờ địa phương là Thái Bình Dương:

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

Các hàm này trả về kết quả sau:

Chức năng	Đầu ra
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

Hàm tính toán HMAC

Các hàm tính toán HMAC cung cấp một giải pháp thay thế cho việc sử dụng chính sách HMAC để tính toán HMAC. Các hàm này rất hữu ích khi thực hiện phép tính HMAC dạng thác nước, chẳng hạn như khi đầu ra của một HMAC được dùng làm khoá cho một HMAC thứ hai.

Cú pháp

Chức năng	Nội dung mô tả
hmacSha224(key,valueToSign[,keyencoding[,outputencoding]])	Tính toán HMAC bằng hàm băm SHA-224.
hmacSha256(key,valueToSign[,keyencoding[,outputencoding]])	Mã hoá HMAC bằng hàm băm SHA-256.
hmacSha384(key,valueToSign[,keyencoding[,outputencoding]])	Mã hoá HMAC bằng hàm băm SHA-384.
hmacSha512(key,valueToSign[,keyencoding[,outputencoding]])	Mã hoá HMAC bằng hàm băm SHA-512.
hmacMd5(key,valueToSign[,keyencoding[,outputencoding]])	Mã hoá HMAC bằng hàm băm MD5.
hmacSha1(key, valueToSign [,keyencoding[,outputencoding]])	Mã hoá HMAC bằng thuật toán mã hoá SHA-1.

Đối số

• key – (Bắt buộc) Chỉ định khoá bí mật, được mã hoá dưới dạng chuỗi, dùng để tính toán HMAC.
• valueToSign – (Bắt buộc) Chỉ định thông báo cần ký. Giá trị này phải là một chuỗi.
• keyencoding – (Không bắt buộc) Chuỗi khoá bí mật sẽ được giải mã theo cách mã hoá được chỉ định này. Giá trị hợp lệ: hex, base16, base64, utf-8. Mặc định: utf-8
• outputencoding – (Không bắt buộc) Chỉ định thuật toán mã hoá để sử dụng cho đầu ra. Giá trị hợp lệ: hex, base16, base64. Các giá trị không phân biệt chữ hoa chữ thường; hex và base16 là đồng nghĩa. Mặc định: base64

Ví dụ

Ví dụ này sử dụng chính sách AssignMessage để tính toán HMAC-256 và gán hàm này cho một biến 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>

Ví dụ này minh hoạ cách tạo HMAC dạng lũy thừa có thể được sử dụng với quy trình ký Chữ ký AWS phiên bản 4. Ví dụ này sử dụng chính sách AssignMessage để tạo 5 cấp HMAC dạng thác nước dùng để tính toán chữ ký cho 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>

Các hàm khác

Tạo hàm UUID

Tạo và trả về một UUID.

Cú pháp

createUuid()

Đối số

Không có.

Ví dụ:

{createUuid()}

Kết quả mẫu:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Hàm Trình tạo số dài ngẫu nhiên

Trả về một số nguyên dài ngẫu nhiên.

Cú pháp

randomLong(args)

Đối số

• Nếu không chỉ định đối số nào, hàm này sẽ trả về một số nguyên dài ngẫu nhiên, được tính toán bằng lớp SecureRandom của Java.
• Nếu có một đối số, đối số đó sẽ được coi là giá trị tối thiểu của phép tính.
• Nếu có đối số thứ hai, đối số này sẽ được coi là giá trị tối đa của phép tính.

Ví dụ:

{random()}

sẽ dẫn đến kết quả như sau:

5211338197474042880

Trình tạo văn bản Regex

Tạo một chuỗi văn bản khớp với một biểu thức chính quy đã cho.

Cú pháp

xeger(regex)

Đối số

regex – Biểu thức chính quy.

Ví dụ:

Ví dụ này tạo một chuỗi gồm 7 chữ số không có số 0:

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

Kết quả mẫu:

9857253

Hàm hợp nhất rỗng

Hàm firstnonnull() trả về giá trị của đối số không rỗng ở ngoài cùng bên trái.

Cú pháp

firstnonnull(var1,varn)

Đối số

var1 – Biến ngữ cảnh.

var_n – Một hoặc nhiều biến ngữ cảnh. Bạn có thể đặt đối số ở ngoài cùng bên phải thành một chuỗi để cung cấp giá trị dự phòng (giá trị sẽ được đặt nếu không có đối số nào ở bên trái được đặt).

Ví dụ

Bảng sau đây minh hoạ cách sử dụng hàm:

Mẫu	Var1	Var2	Var3	Kết quả
{firstnonnull(var1,var2)}	Chưa đặt	foo	Không áp dụng	foo
{firstnonnull(var1,var2)}	foo	bar	Không áp dụng	foo
{firstnonnull(var1,var2)}	foo	Chưa đặt	Không áp dụng	foo
{firstnonnull(var1,var2,var3)}	foo	bar	baz	foo
{firstnonnull(var1,var2,var3)}	Chưa đặt	bar	baz	bar
{firstnonnull(var1,var2,var3)}	Chưa đặt	Chưa đặt	baz	baz
{firstnonnull(var1,var2,var3)}	Chưa đặt	Chưa đặt	Chưa đặt	null
{firstnonnull(var1)}	Chưa đặt	Không áp dụng	Không áp dụng	null
{firstnonnull(var1)}	foo	Không áp dụng	Không áp dụng	foo
{firstnonnull(var1,var2)}	""	bar	Không áp dụng	""
{firstnonnull(var1,var2,'fallback value')}	null	null	fallback value	fallback value

Hàm XPath

Áp dụng biểu thức XPath cho một biến XML.

Cú pháp

xpath(xpath_expression,xml_string,[datatype])

Đối số

xpath_expression – Biểu thức XPath.

xml_string – Biến flow hoặc chuỗi chứa XML.

datatype – (Không bắt buộc) Chỉ định loại dữ liệu trả về mong muốn của truy vấn. Đây có thể là tập hợp nút, nút, số, boolean, chuỗi. Giá trị mặc định là nodeset. Lựa chọn mặc định thường là lựa chọn phù hợp.

Ví dụ 1

Giả sử các biến ngữ cảnh này xác định một chuỗi XML và một biểu thức XPath:

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

Và hàm xpath() được dùng trong chính sách AssignMessage như sau:

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

Hàm này trả về giá trị <tagid>250397</tagid>. Giá trị này được đặt trong biến ngữ cảnh có tên là extracted_tag.

Ví dụ 2

Nếu bạn chỉ muốn giá trị của nút, hãy sử dụng hàm text() như sau:

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

Kết quả của thao tác này là biến ngữ cảnh extracted_tag được đặt thành 250397

Nếu bạn chọn nhiều nút, thì kết quả của xpath() là tất cả giá trị của lựa chọn, được nối với nhau bằng dấu phẩy.

Ví dụ 3: Không gian tên XML

Để chỉ định một không gian tên, hãy thêm các tham số bổ sung, mỗi tham số là một chuỗi có dạng như prefix:namespaceuri. Ví dụ: hàm xpath() chọn phần tử con của phần nội dung SOAP có thể như sau:

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

Đối với các không gian tên bổ sung, bạn có thể thêm tối đa 10 tham số bổ sung vào hàm xpath().

Bạn có thể chỉ định một biểu thức XPath đơn giản dưới dạng một chuỗi được bao quanh bằng dấu nháy đơn:

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

Nếu biểu thức XPath bao gồm tiền tố không gian tên (và dấu hai chấm), thì bạn cần gán biểu thức XPath đó cho một biến và chỉ định tên biến thay vì biểu thức trực tiếp.

{xpath(xpathexpression,xml,ns1)}

Ví dụ 4: Chỉ định loại dữ liệu trả về mong muốn

Tham số thứ ba không bắt buộc được truyền đến hàm xpath() chỉ định loại dữ liệu trả về mong muốn của truy vấn.

Một số truy vấn XPath có thể trả về giá trị số hoặc boolean. Ví dụ: hàm count() trả về một số. Đây là một truy vấn XPath hợp lệ:

count(//Record/Fields/Pair)

Truy vấn hợp lệ này trả về một boolean:

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

Trong những trường hợp đó, hãy gọi hàm xpath() bằng tham số thứ ba chỉ định loại đó:

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

Nếu tham số thứ ba chứa dấu hai chấm, thì tham số đó sẽ được diễn giải là đối số không gian tên. Nếu không, giá trị này sẽ được coi là kiểu dữ liệu trả về mong muốn. Trong trường hợp này, nếu tham số thứ ba không phải là một trong các giá trị hợp lệ (bỏ qua trường hợp), hàm xpath() sẽ mặc định trả về một tập hợp nút.

Hàm Đường dẫn JSON

Áp dụng biểu thức Đường dẫn JSON cho một biến JSON.

Cú pháp

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

Đối số

• (Bắt buộc) json-path: (Chuỗi) Biểu thức Đường dẫn JSON.
• (Bắt buộc) json-var: (Chuỗi) Biến flow hoặc chuỗi chứa JSON.
• (Không bắt buộc) want-array: (Chuỗi) Nếu tham số này được đặt thành 'true' và nếu tập hợp kết quả là một mảng, thì tất cả các phần tử mảng sẽ được trả về. Nếu bạn đặt giá trị này thành bất kỳ giá trị nào khác hoặc nếu bạn bỏ qua tham số này, thì hệ thống sẽ chỉ trả về phần tử thứ 0 của mảng tập hợp kết quả. Nếu tập hợp kết quả không phải là một mảng, thì tham số thứ ba này (nếu có) sẽ bị bỏ qua.

Ví dụ 1

Nếu đây là mẫu thư:

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

và the_json_variable chứa:

{
  "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"
    }
  ]
} 

Kết quả của hàm là:

The address is 1060 West Addison Street

Lưu ý rằng trong trường hợp này, tập hợp kết quả là một phần tử duy nhất (không phải một mảng phần tử). Nếu tập hợp kết quả là một mảng, thì chỉ phần tử thứ 0 của mảng đó mới được trả về. Để trả về toàn bộ mảng, hãy gọi hàm có 'true' làm tham số thứ ba, như trong ví dụ tiếp theo.

Ví dụ 2

Nếu đây là mẫu thư:

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

và the_json_variable chứa:

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

Kết quả của hàm là:

['A','B']