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 mẫu thông báo trong proxy API và cung cấp tệp tham chiếu hàm.

Mẫu thông báo là gì?

Mẫu thông báo cho phép bạ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 chuỗi động khi một proxy thực thi.

Bạn có thể thêm bất kỳ tổ hợp tham chiếu biến luồng nào và văn bản cố định 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.

Hãy xem thêm phần Bạn có thể sử dụng mẫu tin nhắn ở đâu?

Ví dụ:

Ví dụ: chính sách Chỉ định tin nhắn cho phép bạn sử dụng mẫu thông báo bên 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ẽ đượ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ả thông điệp đầu ra trong tải trọng sẽ là: You entered an invalid username: jdoe. Nếu biến không phân giải được thì sẽ có một chuỗi trống.

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 dùng cùng với "quy tắc lỗi" để cung cấp kết quả nhằm cung cấp cho phương thức 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 để tự động điền thông tin hạn mức vào 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 phần tử <Set> hỗ trợ việc tạo mẫu thông báo:

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

Một lần nữa, xin lưu ý 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:

Các phần tử Tiêu đề nhận giá trị của các biến luồng đã 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 động).
Trạng thái và Lý do 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 tạo mẫu thông báo nếu bạn muốn sử dụng nó.

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, các biến luồng trong dấu ngoặc nhọn đượ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ử nhất định được dùng trong cấu hình TargetEndpoint.

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

Chính sách	Các phần tử và phần tử con hỗ trợ mẫu tin nhắn
Chính sách AccessControl	`<SourceAddress>`, cho thuộc tính `mask` và địa chỉ IP.
Chính sáchassignMessage	`<Set>` các phần tử con: Payload, ContentType, Verb, Version, Path, StatusCode, Gradle, Headers, QueryParams, formParams `<Add>` các phần tử con: Tiêu đề, QueryParams, formParams `<AssignVariable>` phần tử con: `<Template>`
Chính sách về chú thích cho phần mở rộng	`<Input>`
Chính sách về ExtractVariables	`<JsonPath>` Mẫu tin nhắn không được chấp nhận cho `<XMLPath>`.
Generate JWS policy Chính sáchVerifyJWS	`<Payload>` (chỉ dành cho Tạo chính sách JWS) `<AdditionalHeaders><Claim>` * Các phần tử này chỉ hỗ trợ mẫu thông báo khi type=map.
GenerateJWT chính sách 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 về việc ghi nhật ký thư	`<Syslog><Message>` `<File><Message>`
Chính sách xác thực OASValidation	Phần tử `<OASResource>`
Chính sách của RaiseFault	Các phần tử `<Set>`: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonP, Headers, QueryParams, formParams Các thành phần `<Add>`: Tiêu đề, QueryParams, formParams
Chính sách xác nhận SAML	`<Template>` * Chỉ khi chữ ký chính sách là `<GenerateSAMLAssertion>`
Chính sách về chú thích dịch vụ	Các thành phần `<Set>`: Payload, ContentType, Verb, Version, Path, StatusCode, reasonP, /Headers, QueryParams, formParams Các thành phần `<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.

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

Phần tử HTTPTargetConnection	Các 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 bạn phải tuân theo để sử dụng mẫu tin nhắn.

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, thì một 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 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 thông báo.

Lưu ý rằng bạn có thể đặt toàn bộ chuỗi mẫu thông bá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 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 một 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 phân giải được thì giá trị của biến đó sẽ được thay thế bằng Unknown. Ví dụ:

Test message. id = Unknown

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

Dấu cách không được phép ở bất kỳ vị trí nào trong biểu thức hàm mẫu tin nhắn. 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 các 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 tệp tham chiếu biến trong các 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 các ký tự phân tách và sử dụng các thuộc tính đó để 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 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ũ hơn 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 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 của mẫu thông báo được mô tả chi tiết trong Tài liệu tham khảo về hàm của mẫu thông báo.

Ví dụ: toLowCase()

Dùng hàm toLowerCase() tích hợp sẵn để chuyển đổi một 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 được phân giải, thì tất cả các ký tự của biến đó sẽ đều là chữ thường. Nếu foo.bar không được giải quyết, 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()

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 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 chỉ định thông báo để thêm thông báo đó vào một phản hồi proxy tuỳ chỉnh (tức là gửi thông báo lại cho máy khách).

Sau đây là chính sách Trích xuất biến giúp trích xuất thông tin user_message thành một biến 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, sau đây là chính sách Chỉ định thông báo hoàn toàn hợp lệ. Chính sách này sẽ 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 Trích xuất biến đã xoá các ký tự trong 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 trả về cho ứng dụng khách có định dạng JSON không hợp lệ. Đây rõ ràng không phải là điều bạn mong đợi!

{
    "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ư để dùng hàm mẫu tin nhắn có tính năng thoát dấu ngoặc kép trong JSON cho bạn. Hàm escapeJSON() này giúp 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 thoát khỏi 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ẫ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 nhất định và trong các định nghĩa TargetEndpoint. Hàm 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 composeMessage sau, 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 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 đó.

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

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

Hàm băm

Tính toán giá trị hàm băm rồi trả về giá trị thể hiện 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ề chuỗi đại diện của hàm băm đó dưới dạng số thập lục phân.

Cú pháp

Hàm	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 – Các hàm băm lấy một đối số chuỗi đơn để tính toán thuật toán băm. Đối số có thể là một chuỗi cố định hoặc một 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ị hàm băm và trả về giá trị thể hiện chuỗi của hàm băm đó dưới dạng giá trị được mã hoá Base64.

Cú pháp

Hàm	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 – Các hàm băm lấy một đối số chuỗi đơn để tính toán thuật toán băm. Đối số có thể là một chuỗi cố định hoặc một 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 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

Hàm	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` giữ `abc`, hàm sẽ trả về chuỗi: `YWJj`
`decodeBase64(string)`	Giải mã một chuỗi được mã hoá Base64. Ví dụ: `decodeBase64(value)` khi `value` giữ `aGVsbG8sIHdvcmxk`, hàm sẽ trả về chuỗi `hello, world`.

Đối số

chuỗi – Chuỗi cần mã hoá hoặc giải mã. Có thể là một chuỗi giá trị 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 cách viết hoa

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

Cú pháp

Hàm	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à một chuỗi giá trị 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ự giữa chỉ mục bắt đầu và kết thúc của chuỗi được chỉ định.

Cú pháp

substring(str,start_index,end_index)

Đối số

str – Biến chuỗi giá trị cố định hoặc biến luồng 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 sẽ là điểm cuối của chuỗi.

Ví dụ

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

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 một 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, kết quả sẽ được thay thế bằng một giá trị thay thế.

Cú pháp

replaceAll(string,regex,value)

Đối số

string – Một chuỗi giá trị cố định hoặc biến luồng chuỗi dùng để thay thế.
biểu thức chính quy – Biểu thức chính quy.
value – Giá trị để thay thế tất cả cá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ác biến luồng sau:

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 giá trị cố định hoặc biến luồng chuỗi dùng để thay thế.
biểu thức chính quy – 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.

Các 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

Hàm	Mô tả
escapeJSON(chuỗi)	Dấu ngoặc kép thoát dấu gạch chéo ngược.
escapeXML(chuỗi)	Thay thế dấu ngoặc nhọn, dấu nháy đơn, dấu ngoặc kép và ký hiệu "&" bằng các thực thể XML tương ứng. Sử dụng cho tài liệu XML 1.0. Sử dụng escapeXML cho tài liệu XML1.0 và escapeXML11 cho tài liệu XML 1.1.
escapeXML11(chuỗi)	Hoạt động giống như escapeXML, nhưng đối với các thực thể XML phiên bản 1.1. Hãy xem phần 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à một chuỗi giá trị cố định hoặc biến luồng chuỗi.

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

XML 1.1 có thể đại diện cho một số ký tự điều khiển nhất định, nhưng không thể đại diện cho byte rỗng hoặ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 nằm trong phạm vi sau:

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

Hàm escapeXML11() thoát các ký tự trong các phạm vi sau:

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

Hàm	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ố

format – 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 – Biến luồng hoặc chuỗi chứa giá trị thời gian. Giá trị có thể ở dạng mili giây-kể từ thời gian bắt đầu của hệ thống hoặc thời gian bắt đầu của hệ thống mili giây đối với thời gian bắt đầu của hệ thống đối với timeFormatMs.

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

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 toán HMAC. Các hàm này rất hữu ích khi thực hiện phép tính HMAC theo tầng, như khi dữ liệu đầu ra của một HMAC được dùng làm khoá cho HMAC thứ hai.

Cú pháp

Hàm	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 HMAC.
valueToSign – (Bắt buộc) Chỉ định nội dung cần ký. Đó phải là một chuỗi.
keycode – (Không bắt buộc) Chuỗi khoá bí mật sẽ được giải mã theo phương thức mã hoá đã chỉ định này. Giá trị hợp lệ: hex, base16, base64, utf-8. Mặc định: utf-8
outputCompile – (Không bắt buộc) Chỉ định thuật toán mã hoá cần sử dụng cho dữ liệu đầ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à các từ đồng nghĩa. Mặc định: base64

Ví dụ

Ví dụ này sử dụng chính sách AttributionMessage để tính toán HMAC-256 và chỉ định HMAC-256 cho 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 phân tầng có thể 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áchassignMessage để tạo 5 cấp độ HMAC xếp tầng được dùng để tính toán chữ ký cho Chữ ký AWS phiên bản 4:

<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ột mã nhận dạng duy nhất (UUID).

Cú pháp

createUuid()

Đối số

Không nội dung nào.

Ví dụ:

{createUuid()}

Kết quả mẫu:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Hàm trình tạo 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 sẽ trả về một số nguyên dài ngẫu nhiên, như được tính toán bằng lớp Java SecureRandom.
Nếu có một đối số, đối số đó được coi là giá trị nhỏ nhất của phép tính.
Nếu có đối số thứ hai, đối số đó sẽ được coi là giá trị lớn nhất của phép tính.

Ví dụ:

{random()}

sẽ mang lại 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 nhất định.

Cú pháp

xeger(regex)

Đối số

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

Ví dụ:

Ví dụ sau sẽ 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:

Hàm hợp nhất giá trị rỗng

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

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

Ví dụ

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

Template	Var1	Var2	Var3	Kết quả
`{firstnonnull(var1,var2)}`	Không đặt	`foo`	Không áp dụng	`foo`
`{firstnonnull(var1,var2)}`	`foo`	`bar`	Không áp dụng	`foo`
`{firstnonnull(var1,var2)}`	`foo`	Không đặt	Không áp dụng	`foo`
`{firstnonnull(var1,var2,var3)}`	`foo`	`bar`	`baz`	`foo`
`{firstnonnull(var1,var2,var3)}`	Không đặt	`bar`	`baz`	`bar`
`{firstnonnull(var1,var2,var3)}`	Không đặt	Không đặt	`baz`	`baz`
`{firstnonnull(var1,var2,var3)}`	Không đặt	Không đặt	Không đặt	`null`
`{firstnonnull(var1)}`	Không đặt	Không áp dụng	Không có câu trả lời thích hợp	`null`
`{firstnonnull(var1)}`	`foo`	Không có câu trả lời thích hợp	Không có câu trả lời thích hợp	`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 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 luồng hoặc chuỗi chứa XML.

datatype – (Không bắt buộc) Chỉ định kiểu dữ liệu trả về mong muốn của truy vấn. Đó có thể là tập hợp nút, 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 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 composeMessage, 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ó tên là extracted_tag.

Ví dụ 2

Nếu bạn chỉ muốn nhậ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() sẽ là tất cả cá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 giống như prefix:namespaceuri. Ví dụ: một 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 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 là một chuỗi được đặt trong dấu ngoặc đơn:

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

Nếu biểu thức XPath 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 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 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 kiểu 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 giá trị 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 hiểu là đối số không gian tên. Nếu không thì đây đượ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ệ (không phân biệt chữ hoa chữ thường), 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 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 thông số này được đặt thành 'true' và nếu kết quả đạt được 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 thành bất kỳ giá trị nào khác hoặc nếu tham số này bị bỏ qua, thì chỉ có phần tử thứ 0 của mảng nhóm 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 thông báo:

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

Ví dụ 2

Nếu đây là mẫu thông báo:

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