Trang này được dịch bởi Cloud Translation API.

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 cách sử dụng các mẫu tin nhắn trong proxy API và cung cấp một hàm tham chiếu.

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

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

Bạn có thể thêm bất kỳ tổ hợp tham chiếu biến luồng và văn bản cố định nào vào mẫu thông báo. Bạn phải đặt tên biến luồng trong dấu ngoặc nhọn, còn 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.

Hãy xem thêm bài viết Bạn có thể sử dụng mẫu tin nhắn ở đâ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 luồng user.name (trong dấu ngoặc nhọn) sẽ là được đánh giá và thay thế vào chuỗi tải trọng trong thời gian chạy. Vì vậy, ví dụ: nếu user.name=jdoe, thì kết quả đầu ra 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ì kết quả sẽ là một chuỗi trống.

Ví dụ:

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

Tiêu đề
QueryParam
FormParam
PayLoad
Phiên bản
Động từ
Đường dẫn
StatusCode
ReasonPhrase

Xin nhắc lại rằng các biến luồng trong mẫu thông báo phải được đặt trong dấu ngoặc nhọn.

Khi chính sách này thực thi:

Phần tử Tiêu đề nhận giá trị của các biến luồng được chỉ định.
Tải trọng bao gồm sự kết hợp giữa văn bản cố định và các biến (client_id được điền tự động).
Trạng thái StatusCode và ReasonCluster chỉ bao gồm văn bản cố định; tuy nhiên, các phần tử này cũng hỗ trợ việc soạn mẫu 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ợ việc tạo mẫu thông báo. Theo cùng một mẫu dùng trong các chính sách, biến luồng 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ể dùng mẫu tin nhắn ở đâ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ử dùng trong cấu hình TargetEndpoint.

Chính sách chấp nhận mẫu thông báo

Policy	Các phần tử và phần tử con hỗ trợ mẫu thông báo
Chính sách AccessControl	`<SourceAddress>` cho thuộc tính `mask` và Địa chỉ IP.
Chính sách assignMessage	Các phần tử con `<Set>`: Tải trọng, ContentType, Động từ, Phiên bản, Đường dẫn, Mã trạng thái, ReasonCluster, Tiêu đề, QueryParams, FormParams Các phần tử con `<Add>`: Tiêu đề, QueryParams, FormParams Phần tử con `<AssignVariable>`: `<Template>`
Chính sách về chú thích tiện ích	`<Input>`
Chính sách ExtractVariables	`<JsonPath>` Mẫu tin nhắn không được chấp nhận cho `<XMLPath>`.
Chính sáchGenerateJWS Chính sáchVerifyJWS	`<Payload>` (chỉ dành cho chính sáchGenerateJWS) `<AdditionalHeaders><Claim>` * Các phần tử này chỉ hỗ trợ mẫu thông báo khi type=map.
Chính sáchGenerateJWT Chính sáchVerifyJWT	`<AdditionalClaims><Claim>` `<AdditionalHeaders><Claim>` * Các phần tử này chỉ hỗ trợ mẫu thông báo khi type=map.
Chính sách LDAP	`<SearchQuery>`
Chính sách Ghi nhật ký tin nhắn	`<Syslog><Message>` `<File><Message>`
Chính sách OASValidation	`<OASResource>` phần tử
Chính sách củaRaiseFault	Các phần tử `<Set>`: Tải trọng, ContentType, Động từ, Phiên bản, Đường dẫn, StatusCode, ReasonCluster, Tiêu đề, QueryParams, FormParams Các phần tử `<Add>`: Tiêu đề, QueryParams, FormParams
Chính sách Xác nhận SAML	`<Template>` * Chỉ khi chữ ký của chính sách là `<GenerateSAMLAssertion>`
Chính sách về Chú thích dịch vụ	Các phần tử `<Set>`: Tải trọng, ContentType, Động từ, Phiên bản, Đường dẫn, StatusCode, ReasonCluster, /Headers, QueryParams, FormParams Các phần tử `<Add>`: Tiêu đề, QueryParams, FormParams `<HTTPTargetConnection>/<URL>`: Lưu ý rằng phần đầu tiên của chuỗi phải là http hoặc https.

Các phần tử TargetEndpoint chấp nhận mẫu thông báo

Các phần tử HTTPTargetConnection	Phần tử con hỗ trợ mẫu thông báo
SSLInfo	Đã bật, KeyAlias, KeyStore, TrustStore, ClientAuthEnabled, CLRStore
LocalTargetConnection	ApiProxy, ProxyEndpoint
Đường dẫn	Không áp dụng

Cú pháp mẫu thông báo

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

Sử 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, chuỗi trống sẽ được trả về trong kết quả; tuy nhiên, bạn có thể chỉ định các giá trị mặc định trong thông báo mẫu (các giá trị được thay thế nếu biến không được giải quyết). Xem Đặt giá trị mặc định trong mẫu tin nhắn.

Lưu ý rằng bạn được phép đưa toàn bộ chuỗi mẫu thông báo vào trong dấu ngoặc kép, nhưng không bắt buộc. Ví dụ: 2 mẫu thông báo sau đây là tương đương với 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 phân giải được biến theo mẫu, Edge sẽ thay thế 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 biến request.header.id không thể được phân giải thì giá trị của biến đó đượ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 dùng dấu cách ở bất cứ đâu trong biểu thức hàm mẫu thông báo. Ví dụ:

Cho 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 tải trọng JSON

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

Edge cung cấp một tập hợp các hàm mà bạn có thể sử dụng trong các mẫu tin nhắn để 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 Mẫu thông báo tham chiếu hàm.

Ví dụ: toBottomCase()

Dùng hàm toLowerCase() tích hợp sẵn để biế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 luồng foo.bar phân giải thì các ký tự của biến đó sẽ là chữ thường. Nếu foo.bar chưa được giải quyết thì giá trị mặc định FOO sẽ được thay thế và được chuyển đổi sang ký tự viết thường. Ví dụ:

Test header: foo

Ví dụ: escapeJSON()

Dưới đâ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ề 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ề tin nhắn này cho phương thức gọi ứng dụng khách 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 tin nhắn từ tải trọng phản hồi mục tiêu và sử dụng Chỉ định tin nhắn để thêm tin nhắn đó vào phản hồi proxy tuỳ chỉnh (tức là gửi lại tin nhắn cho máy khách).

Dưới đây là chính sách Trích xuất biến trích xuất thông tin user_message thành 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>

Hiện tại, đây là chính sách Chỉ định tin nhắn hoàn toàn hợp lệ, giúp thêm biến được 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 về Trích xuất đã xoá các ký tự trích dẫn 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 là JSON không hợp lệ. Đây rõ ràng không phải là điều bạn mong muốn!

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

Để khắc phục 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 thoát khỏi dấu ngoặc kép trong JSON cho bạn. Hàm escapeJSON() này thoát mọi dấu ngoặc kép hoặ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ệ, đúng như bạn muốn:

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

Một thông báo mẫu 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. Các hàm mẫu tin nhắn cho phép bạn thực hiện các thao tác hữu ích chẳng hạn như băm, thao tác chuỗi, thoát ký tự và các tính năng khác trong mẫu thông báo.

Ví dụ: trong chính sách FindMessage sau đây, hàm toLowerCase() được dùng trong một 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ông báo, đối số và kết quả của các hàm đó. Chủ đề này giả định mà bạn quen thuộc với thông báo mẫu và bối cảnh sử dụng mẫu.

Không thể lồng các lệnh gọi hàm. Ví dụ như bạn không thể làm những việc sau:

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

Các hàm băm

Tính toán một giá trị hàm băm và trả về giá trị biểu diễn dạng chuỗi của hàm băm đó.

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

Tính toán giá trị hàm 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

Chức năng	Nội dung mô tả
`md5Hex(string)`	Tính toán hàm băm MD5 được biểu thị dưới dạng số thập lục phân.
`sha1Hex(string)`	Tính toán hàm băm SHA1 được biểu thị dưới dạng số thập lục phân.
`sha256Hex(string)`	Tính toán hàm băm SHA256 được biểu thị dưới dạng số thập lục phân.
`sha384Hex(string)`	Tính toán hàm băm SHA384 được biểu thị dưới dạng số thập lục phân.
`sha512Hex(string)`	Tính toán hàm băm SHA512 được biểu thị dưới dạng số thập lục phân.

Đối số

chuỗi – Hàm băm lấy một đối số chuỗi đơn dựa trên mà thuật toán băm sẽ được tính toán. Đối số có thể là một chuỗi cố định hoặc một biến luồng dữ liệu.

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

Các hàm băm Base64

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

Cú pháp

Chức năng	Nội dung mô tả
`md5Base64(string)`	Tính toán hàm băm MD5 được biểu thị dưới dạng giá trị được mã hoá Base64.
`sha1Base64(string)`	Tính toán hàm băm SHA1 được biểu thị dưới dạng giá trị được mã hoá Base64.
`sha256Base64(string)`	Tính toán hàm băm SHA256 được biểu thị dưới dạng giá trị được mã hoá Base64.
`sha384Base64(string)`	Tính toán hàm băm SHA384 được biểu thị dưới dạng giá trị được mã hoá Base64.
`sha512Base64(string)`	Tính toán hàm băm SHA512 được biểu thị dưới dạng giá trị được mã hoá Base64.

Đối số

chuỗi – Hàm băm lấy một đối số chuỗi đơn dựa trên mà thuật toán băm sẽ được tính toán. Đối số có thể là một chuỗi cố định hoặc một chuỗi biến.

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 các chuỗi trong một mẫu thông báo.

Hàm mã hoá Base64

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

Cú pháp

Chức năng	Nội dung mô tả
`encodeBase64(string)`	Mã hoá một chuỗi bằng phương thức mã hoá Base64. Ví dụ: `encodeBase64(value)`, khi `value` lưu giữ `abc`, hàm sẽ trả về chuỗi: `YWJj`
`decodeBase64(string)`	Giải mã chuỗi được mã hoá Base64. Ví dụ: `decodeBase64(value)` khi `value` lưu giữ `aGVsbG8sIHdvcmxk`, hàm sẽ trả về chuỗi `hello, world`.

Đối số

chuỗi – Chuỗi để mã hoá hoặc giải mã. Có thể là chuỗi ký tự 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

Chức năng	Nội dung mô tả
`toUpperCase(string)`	Chuyển đổi một chuỗi thành chữ hoa.
`toLowerCase(string)`	Chuyển đổi một chuỗi thành chữ thường.

Đối số

chuỗi – Chuỗi cần chuyển đổi. Có thể là chuỗi ký tự 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ự giữa chỉ mục bắt đầu và chỉ mục kết thúc của chuỗi đã chỉ định.

Cú pháp

substring(str,start_index,end_index)

Đối số

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

Ví dụ

Trong các ví dụ sau, giả sử tồn tại các biến luồng này:

Tên biến	Giá trị
`alpha`	ABCDEFGHIJKLMNOPQRSTUVWXYZ
`seven`	7

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:

Biểu thức mẫu thông báo	Kết quả
`{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`

Thay thế tất cả hàm

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

Cú pháp

replaceAll(string,regex,value)

Đối số

string – Một chuỗi bằng chữ hoặc biến luồng chuỗi cần thay thế.
regex – Biểu thức chính quy.
value – Giá trị để thay thế tất cả các kết quả trùng khớp của biểu thức chính quy trong chuỗi.

Ví dụ

Trong các ví dụ sau, giả sử tồn tại các biến luồng này:

Tên biến	Giá trị
`header`	`Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993`
`regex1`	`"^Bearer "`
`replacement`	`"TOKEN: "`

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:

Biểu thức mẫu thông báo	Kết quả
`{replaceAll(header,"9993",'')}`	`Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-`
`{replaceAll(header,regex1,'')}`	`ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993`
`{replaceAll(header,regex1,replacement)}`	`TOKEN: ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993`

Thay thế hàm đầu tiên

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

Cú pháp

replaceFirst(string,regex,value)

Đối số

string – Một chuỗi bằng chữ hoặc biến luồng chuỗi cần thay thế.
regex – Biểu thức chính quy.
value – Giá trị để thay thế các kết quả khớp của biểu thức chính quy trong chuỗi.

Các hàm thoát và mã hoá ký tự

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

Cú pháp

Chức năng	Nội dung mô tả
EscapeJSON(chuỗi)	Dấu gạch chéo ngược thoát trong dấu ngoặc kép.
escapeXML(chuỗi)	Thay thế dấu ngoặc góc, dấu nháy đơn, dấu ngoặc kép và dấu "&" bằng các thực thể XML tương ứng. Sử dụng cho các tài liệu XML 1.0. Sử dụng EscapeXML cho các tài liệu XML1.0 và EscapeXML11 cho các tài liệu XML 1.1.
escapeXML11(chuỗi)	Hoạt động tương tự như escapeXML, nhưng dành cho các thực thể XML phiên bản 1.1. Hãy xem Ghi chú về cách sử dụng ở bên dưới.
mã hoáHTML(chuỗi)	Mã hoá dấu nháy đơn, dấu ngoặc nhọn và ký hiệu "&".

Đối số

chuỗi – Chuỗi cần thoát. Có thể là chuỗi ký tự hoặc biến luồng chuỗi.

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

XML 1.1 có thể biểu thị các ký tự điều khiển nhất định, nhưng nó không thể biểu thị các byte rỗng hoặc các điểm mã thay thế 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 trong các phạm vi sau:

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

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

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

Ví dụ

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

{escapeHTML(food)}

kết quả trong:

"bread" & "butter"

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

Chức năng	Nội dung mô tả
`timeFormat(format,str)`	Trả về ngày được định dạng theo múi giờ địa phương.
`timeFormatMs(format,str)`	Trả về ngày được định dạng theo múi giờ địa phương.
`timeFormatUTC(format,str)`	Trả về ngày theo định dạng UTC.
`timeFormatUTCMs(format,str)`	Trả về ngày theo định dạng UTC.

Đối số

định dạng – Chuỗi định dạng ngày/giờ. Có thể là một chuỗi cố định hoặc một biến chuỗi.
str – Một chuỗi hoặc biến luồng chuỗi có chứa giá trị thời gian. Đối với timeFormatMs, giá trị có thể ở dạng mili giây 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.

Ví dụ

Giả sử các giá trị sau đây và giả định 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 trả về kết quả như 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`

Các hàm tính toán HMAC

Các hàm tính toán HMAC cung cấp một phương án thay thế cho việc sử dụng chính sách HMAC để tính một HMAC. Các hàm này rất tiện dụng khi thực hiện phép tính HMAC theo tầng, như khi đầu ra của một HMAC được sử dụng làm khoá cho 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ố

khoá – (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.
mã hoá khoá – (Không bắt buộc) Chuỗi khoá bí mật sẽ được giải mã theo cách này mã hoá đã chỉ định. Các giá trị hợp lệ: hex, base16, base64, utf-8. Mặc định: utf-8
mã hoá đầu ra – (Không bắt buộc) Chỉ định thuật toán mã hoá để sử dụng cho đầu ra. Các 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à từ đồng nghĩa. Mặc định: base64

Ví dụ

Ví dụ này sử dụng chính sách Ấn Độ để tính toán HMAC-256 và gán HMAC-256 cho một biến luồng:

<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 nhiều tầng có thể sử dụng với Quá trình ký AWS Signature v4. Ví dụ này sử dụng chính sách AttributionMessage để tạo năm cấp HMAC nhiều tầng được sử dụng để tính toán chữ ký cho Chữ ký AWS 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>

Hàm khác

Tạo hàm UUID

Tạo và trả về mã nhận dạng duy nhấ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 tạo ngẫu nhiên dài

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

Cú pháp

randomLong(args)

Đối số

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

Ví dụ:

{random()}

kết quả sẽ có dạng như sau:

5211338197474042880

Trình tạo văn bản biểu thức chính quy

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ụ sau tạo ra một chuỗi có 7 chữ số không có số 0:

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

Ví dụ về kết quả:

Hàm kết hợp rỗng

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

Cú pháp

firstnonnull(var1,var_n)

Đố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 góc ngoài cùng bên phải đối số cho một chuỗi để cung cấp giá trị dự phòng (một giá trị sẽ được đặt nếu không có giá trị nào trong số đối số 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`

Chức năng q

Áp dụng một biểu thức quyết định cho một biến XML.

Cú pháp

xpath(xpath_expression,xml_string,[datatype])

Đối số

xpath_expression – Một biểu thức vai trò.

xml_string – Một biến luồng 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. Nó có thể lànodeset, nút, số, boolean, chuỗi. Thuộc tính này mặc định là tập hợp nút. 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 sau xác định một chuỗi XML và một biểu thức vai trò chuyện:

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 sử dụng trong chính sách AttributionMessage như sau:

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

Hàm trả về giá trị <tagid>250397</tagid>. Giá trị này được đặt trong biến ngữ cảnh được gọi 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>

Nhờ thao tác này, biến ngữ cảnh extracted_tag được đặt thành 250397

Nếu chọn nhiều nút, kết quả của xpath() là tất cả giá trị của lựa chọn, được nối 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 trông giống như prefix:namespaceuri. Ví dụ: hàm xpath() chọn phần tử con của nội dung SOAP có thể có dạng 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 khác, bạn có thể thêm tối đa 10 tham số bổ sung vào xpath() .

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

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

Nếu biểu thức NETWORK bao gồm các tiền tố không gian tên (và dấu hai chấm) thì bạn cần chỉ định biểu thức Wi-Fi đó 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 kiểu 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 giá trị trả về mong muốn của truy vấn.

Một số truy vấn quyết định có thể trả về giá trị số hoặc giá trị boolean. Ví dụ: hàm count() sẽ trả về một số. Đây là một truy vấn vai trò 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() với tham số thứ ba chỉ định kiểu đó:

{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 hiểu là đối số không gian tên. Nếu không, thì thuộc tính này sẽ được coi là loại 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ệ (không phân biệt chữ hoa chữ thường), theo mặc định, hàm xpath() sẽ 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 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 luồng hoặc chuỗi có chứa JSON.
(Không bắt buộc) want-array: (Chuỗi) Nếu thuộc tính này tham số đượ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 đều được bị trả lại. Nếu được đặt thành bất kỳ giá trị nào khác hoặc nếu giá trị này tham số sẽ bị bỏ qua, khi đó chỉ phần tử thứ 0 của một mảng tập hợp kết quả được trả về. 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 tin nhắn:

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, nhóm kết quả là một phần tử đơn lẻ (không phải một mảng các 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 được trả về. Cần trả lại toàn bộ mảng, hãy gọi hàm có 'true' là tham số thứ ba, như minh hoạ trong ví dụ tiếp theo.

Ví dụ 2

Nếu đây là mẫu tin nhắn:

{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']