Szablony wiadomości

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

W tym temacie opisujemy, jak używać szablonów wiadomości w serwerach proxy interfejsu API, oraz podajemy odwołanie do funkcji.

Czym jest szablon wiadomości?

Szablon wiadomości umożliwia zastępowanie ciągu zmiennych w określonych zasadach i elementach TargetEndpoint. Ta funkcja (o ile jest obsługiwana) umożliwia dynamiczne wypełnianie ciągów znaków podczas działania serwera proxy.

W szablonie wiadomości możesz umieścić dowolną kombinację odwołań do zmiennych przepływu i tekstu literału. Nazwy zmiennych przepływu muszą być ujęte w nawiasy klamrowe, a tekst, który nie jest w nawiasach klamrowych, jest zapisywany jako tekst literał.

Zobacz też Gdzie można używać szablonów wiadomości?

Przykład

Na przykład zasada Przypisz wiadomość pozwala używać szablonu wiadomości w elemencie <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>

W powyższym przykładzie wartość zmiennej przepływu user.name (w nawiasach klamrowych) jest oceniana i podmieniana w ciągu ładunku w czasie działania. Jeśli na przykład jeśli wybierzesz user.name=jdoe, wynikowy komunikat w ładunku będzie wyglądać tak: You entered an invalid username: jdoe. Jeśli zmiennej nie można rozpoznać, zwracany jest pusty ciąg znaków.

Przykład

Po przekroczeniu limitu warto zwrócić uwagę rozmówcy na istotną wiadomość. Ten wzorzec jest zwykle używany z „regułą błędu”, aby dostarczyć dane wyjściowe przekazujące informacje wywołujące o naruszeniu limitu. W poniższych zasadach przypisywania wiadomości szablony wiadomości są używane do dynamicznego wypełniania informacji o limicie w kilku elementach 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>

W zasadzie AssignMessage następujące elementy elementu <Set> obsługują szablony wiadomości:

• Nagłówek
• QueryParam
• FormParam
• PayLoad
• Wersja
• Czasownik
• Ścieżka
• StatusCode
• ReasonPhrase

Pamiętaj, że zmienne przepływu w szablonie wiadomości muszą być ujęte w nawiasy klamrowe.

Po wykonaniu tej zasady:

• Elementy Header (nagłówek) otrzymują wartości określonych zmiennych przepływu.
• Ładunek zawiera kombinację tekstu literału i zmiennych (element client_id jest wypełniany dynamicznie).
• Kolumny StatusCode i ReasonPhrase obejmują tylko literał. Jednak elementy te obsługują również szablony wiadomości, jeśli chcesz ich użyć.

Przykład

W definicji elementu docelowego punktu końcowego serwera proxy elementy podrzędne <SSLInfo> obsługują szablony wiadomości. Zgodnie z tym samym wzorcem co w zasadach, zmienne przepływu w nawiasach klamrowych są zastępowane podczas wykonywania działań przez serwer proxy.

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

Gdzie można używać szablonów wiadomości?

Szablony wiadomości są obsługiwane przez kilka zasad, a także niektóre elementy używane w konfiguracji docelowego punktu końcowego.

Zasady, które akceptują szablony wiadomości

Zasady	Elementy i elementy podrzędne, które obsługują szablony wiadomości
Zasada AccessControl	<SourceAddress> dla atrybutu mask i adresu IP.
zasada AssignMessage;	<Set> elementów podrzędnych: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams Elementy podrzędne <Add>: Headers, QueryParams, FormParams <AssignVariable> element podrzędny: <Template>
Zasady dotyczące ExtensionCallout	<Input>
Zasada ExtractVariables	<JsonPath>
Zasada WygenerujJWS Zweryfikuj zasadę JWS	<Payload> (tylko zasada WygenerujJWS) <AdditionalHeaders><Claim> Te elementy obsługują szablon wiadomości tylko wtedy, gdy parametr type=map.
Wygeneruj zasadę JWT Zweryfikuj zasadę JWT	<AdditionalClaims><Claim> <AdditionalHeaders><Claim> Te elementy obsługują szablon wiadomości tylko wtedy, gdy parametr type=map.
Zasada LDAP	<SearchQuery>
Zasada MessageLogging	<Syslog><Message> <File><Message>
Zasady OASValidation	Element <OASResource>
Zasady dotyczące GrowFault	Elementy <Set>: Ładunek, ContentType, Czasownik, Wersja, Ścieżka, Kod stanu, Przyczyna, Nagłówki, QueryParams, FormParams Elementy <Add>: Headers, QueryParams, FormParams
Zasady SAMLAssertion	<Template> * Tylko wtedy, gdy podpis zasad to <GenerateSAMLAssertion>
Zasady dotyczące wywołania usługi	Elementy <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, /Headers, QueryParams, FormParams Elementy <Add>: Headers, QueryParams, FormParams <HTTPTargetConnection>/<URL>: pamiętaj, że pierwszą częścią ciągu musi być http lub https.

Elementy docelowego punktu końcowego, które akceptują szablony wiadomości

Elementy HTTPTargetConnection	Elementy podrzędne, które obsługują szablony wiadomości
SSLInfo	Włączono, KeyAlias, KeyStore, TrustStore, ClientAuthEnabled, CLRStore
LocalTargetConnection	Proxy API, ProxyEndpoint
Ścieżka	Nie dotyczy

Składnia szablonu wiadomości

W tej sekcji opisano reguły, których należy przestrzegać, aby używać szablonów wiadomości.

Oznaczanie zmiennych za pomocą nawiasów klamrowych

Nazwy zmiennych ujmij w nawiasy klamrowe { }. Jeśli zmienna nie istnieje, w danych wyjściowych zwracany jest pusty ciąg znaków. W szablonach wiadomości możesz jednak określić wartości domyślne w szablonach wiadomości (wartości, które są zastępowane, jeśli zmienna jest nierozstrzygnięta). Zobacz Ustawianie wartości domyślnych w szablonach wiadomości.

Pamiętaj, że umieszczanie w cudzysłowie całego ciągu szablonu wiadomości jest dozwolone, ale opcjonalne. Na przykład te 2 szablony wiadomości są równoważne:

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

Ustawianie wartości domyślnych w szablonach wiadomości

Jeśli nie można znaleźć zmiennej opartej na szablonie, Edge zastępuje pusty ciąg. Możesz jednak określić wartość domyślną w ten sposób:

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

W przykładzie powyżej, jeśli nie można znaleźć zmiennej request.header.id, jej wartość jest zastępowana przez Unknown. Na przykład:

Test message. id = Unknown

Spacje są niedozwolone w wyrażeniach funkcji

Spacje nie są dozwolone nigdzie w wyrażeniach funkcji szablonu wiadomości. Na przykład:

Dozwolone:

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

Niedozwolone:

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

Starsza składnia ładunków JSON

W wersjach brzegowych przed opublikowaniem Cloud 16.08.17 nie można używać nawiasów klamrowych do oznaczania odwołań do zmiennych w ładunkach JSON. W starszych wersjach musisz używać atrybutów variablePrefix i variableSuffix, aby określać znaki separatora, a potem zawijać ich nazwy w ten sposób:

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

Apigee zaleca używanie nowszej składni nawiasów klamrowych, jednak starsza składnia nadal działa.

Korzystanie z funkcji szablonów wiadomości

Edge udostępnia zestaw funkcji, których można używać w szablonach wiadomości do zmiany znaczenia, kodowania, haszowania i formatowania zmiennych ciągu znaków.

Funkcje szablonów wiadomości zostały szczegółowo opisane w artykule z informacjami o funkcjach szablonu wiadomości.

Przykład: toLowerCase()

Aby przekształcić zmienną ciągu znaków na małe litery, użyj wbudowanej funkcji toLowerCase():

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

Jeśli zmienna przepływu foo.bar się rozwiąże, jej znaki będą się składać tylko z małych liter. Jeśli foo.bar nie jest rozwiązany, wartość domyślna FOO zostanie zastąpiona i przekształcona na małe litery. Na przykład:

Test header: foo

Przykład: escapeJSON()

Oto ciekawy przypadek użycia: załóżmy, że Twoja aplikacja backendu zwraca odpowiedź JSON zawierającą prawidłowe znaki zmiany znaczenia. Na przykład:

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

Załóżmy, że chcesz zwrócić tę wiadomość w niestandardowym ładunku do elementu wywołującego klienta. Zazwyczaj jest to wyodrębnione z ładunku docelowego ładunku odpowiedzi i użycie funkcji Przypisz wiadomość w celu dodania jej do niestandardowej odpowiedzi serwera proxy (czyli odesłania jej z powrotem do klienta).

Oto zasada Wyodrębnianie zmiennych, która wyodrębnia informacje user_message do zmiennej o nazwie standard.systemMessage:

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

Oto całkowicie prawidłowa zasada przypisywania wiadomości, która dodaje wyodrębnioną zmienną do ładunku odpowiedzi (odpowiedź serwera 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>

Wystąpił problem. Zasada Wyodrębnianie zmiennych usuwała znaki cudzysłowu ze znakami zmiany znaczenia w obrębie części wiadomości. Oznacza to, że odpowiedź zwrócona klientowi ma nieprawidłowy format JSON. To wyraźnie nie o to Ci chodziło!

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

Aby obejść ten problem, możesz zmodyfikować zasadę przypisywania wiadomości, używając funkcji szablonu wiadomości, która zmienia znaczenie cudzysłowów w pliku JSON. Ta funkcja (escapeJSON()) zmienia znaczenie cudzysłowów i innych znaków specjalnych występujących w wyrażeniu 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>

Funkcja zmienia znaczenie osadzonego cudzysłowu, co skutkuje poprawnym plikiem JSON, o co Ci chodziło:

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

Szablon wiadomości to funkcja zastępowania ciągów dynamicznych, której można używać w określonych zasadach i definicjach docelowych punktów końcowych. Funkcje szablonu wiadomości umożliwiają wykonywanie w szablonie wiadomości przydatnych operacji, takich jak haszowanie, modyfikowanie ciągów znaków czy zmienianie znaczenia znaków.

Na przykład w poniższej zasadzie AssignMessage funkcja toLowerCase() jest używana w szablonie wiadomości:

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

W tym temacie opisujemy funkcje szablonów wiadomości, ich argumenty i wyniki. W tym temacie zakładamy, że znasz szablony wiadomości i ich konteksty.

Funkcje haszujące

Oblicza wartość skrótu i zwraca jego reprezentację w postaci ciągu znaków.

Szesnastkowe funkcje skrótu

Oblicza wartość skrótu i zwraca ciąg znaków reprezentujący tę wartość w postaci liczby szesnastkowej.

Składnia

Funkcja	Opis
md5Hex(string)	Oblicza hasz MD5 wyrażony w postaci liczby szesnastkowej.
sha1Hex(string)	Oblicza hasz SHA1 wyrażony w postaci liczby szesnastkowej.
sha256Hex(string)	Oblicza hasz SHA256 wyrażony w postaci liczby szesnastkowej.
sha384Hex(string)	Oblicza hasz SHA384 wyrażony w postaci liczby szesnastkowej.
sha512Hex(string)	Oblicza hasz SHA512 wyrażony w postaci liczby szesnastkowej.

Argumenty

ciąg znaków – funkcje haszujące przyjmują pojedynczy argument w postaci ciągu, dla którego obliczany jest algorytm szyfrowania. Ten argument może być literałem lub zmienną przepływu ciągu.

Przykłady

Wywołanie funkcji:

sha256Hex('abc')

Efekt:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Wywołanie funkcji:

var str = 'abc';
sha256Hex(str)

Efekt:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Funkcje skrótu Base64

Oblicza wartość skrótu, a następnie zwraca reprezentowany przez nią ciąg znaków w postaci wartości zakodowanej w formacie Base64.

Składnia

Funkcja	Opis
md5Base64(string)	Oblicza hasz MD5 wyrażony jako wartość zakodowaną w formacie Base64.
sha1Base64(string)	Oblicza hasz SHA1 wyrażony jako wartość zakodowaną w formacie Base64.
sha256Base64(string)	Oblicza hasz SHA256 wyrażony jako wartość zakodowaną w formacie Base64.
sha384Base64(string)	Oblicza hasz SHA384 wyrażony jako wartość zakodowaną w formacie Base64.
sha512Base64(string)	Oblicza hasz SHA512 wyrażony jako wartość zakodowaną w formacie Base64.

Argumenty

ciąg znaków – funkcje haszujące przyjmują pojedynczy argument w postaci ciągu, dla którego obliczany jest algorytm szyfrowania. Argumentem może być ciąg literału lub zmienna przepływu ciągu znaków.

Przykłady

Wywołanie funkcji:

sha256Base64('abc')

Efekt:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Wywołanie funkcji:

var str = 'abc';
sha256Base64(str)

Efekt:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Funkcje z ciągami znaków

Wykonywanie operacji na ciągach tekstowych w szablonie wiadomości.

Funkcje kodowania Base64

Koduj i dekoduj ciągi znaków za pomocą schematu kodowania Base64.

Składnia

Funkcja	Opis
encodeBase64(string)	Koduje ciąg znaków za pomocą kodowania Base64. Przykład: encodeBase64(value), gdy value zawiera ciąg abc, funkcja zwraca ciąg znaków: YWJj
decodeBase64(string)	Dekoduje ciąg zakodowany w standardzie Base64. Przykład: decodeBase64(value), gdy value zawiera aGVsbG8sIHdvcmxk, funkcja zwraca ciąg hello, world.

Argumenty

ciąg znaków – ciąg do zakodowania lub dekodowania. Może być literałem lub zmienną przepływu ciągu.

Przykład

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

Funkcje konwersji wielkości liter

Konwertuje tekst na wielkie lub małe litery.

Składnia

Funkcja	Opis
toUpperCase(string)	Zamień ciąg znaków na wielkie litery.
toLowerCase(string)	Zmień pisownię ciągu na małe litery.

Argumenty

ciąg znaków – ciąg do przekonwertowania. Może być literałem lub zmienną przepływu ciągu.

Przykład

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

Funkcja podłańcucha

Zwraca znaki występujące między indeksem początkowym a końcowym określonego ciągu.

Składnia

substring(str,start_index,end_index)

Argumenty

• str – ciąg literału lub zmienna przepływu ciągu znaków.
• start_index – indeks początkowy do ciągu znaków.
• end_index – (opcjonalny) indeks końcowy do ciągu znaków. Jeśli indeks końcowy nie zostanie podany, to koniec ciągu znaków.

Przykłady

W podanych niżej przykładach załóżmy, że istnieją zmienne przepływu:

Nazwa zmiennej	Wartość
alpha	AĄBCĆDEĘFGHIJKLŁMNŃOÓPRSŚTUWYZŹŻ
seven	7

Oto wyniki wywołań funkcji, które korzystają z tych zmiennych:

Wyrażenie szablonu wiadomości	Wynik
{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

Zastąp wszystkie funkcje

Stosuje wyrażenie regularne do ciągu znaków i w przypadku każdego dopasowania zastępuje dopasowanie wartością zastępczą.

Składnia

replaceAll(string,regex,value)

Argumenty

• ciąg znaków – ciąg literału lub zmienna przepływu ciągu znaków, w której przypadku zostaną zastąpione.
• regex (wyrażenie regularne) – wyrażenie regularne.
• wartość – wartość, która ma zastąpić wszystkie wyrażenia regularne pasujące do ciągu.

Przykłady

W tych przykładach załóżmy, że zmienne przepływu występują:

Nazwa zmiennej	Wartość
header	Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
regex1	"^Bearer "
replacement	"TOKEN: "

Oto wyniki wywołań funkcji, które korzystają z tych zmiennych:

Wyrażenie szablonu wiadomości	Wynik
{replaceAll(header,"9993",'')}	Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-
{replaceAll(header,regex1,'')}	ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
{replaceAll(header,regex1,replacement)}	TOKEN: ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993

Zastąp pierwszą funkcję

Zastępuje tylko pierwsze wystąpienie określonego wyrażenia regularnego w ciągu znaków.

Składnia

replaceFirst(string,regex,value)

Argumenty

• ciąg znaków – ciąg literału lub zmienna przepływu ciągu znaków, w której przypadku zostaną zastąpione.
• regex (wyrażenie regularne) – wyrażenie regularne.
• wartość – wartość, która ma zastąpić wyrażenie regularne, pasuje do ciągu.

Funkcje zmiany znaczenia znaków i kodowania

Funkcje, których kodowanie zmienia znaczenie znaków specjalnych w ciągu znaków.

Składnia

Funkcja	Opis
escapeJSON(ciąg)	Podwójny ukośnik lewy albo cudzysłów.
escapeXML(ciąg)	Zastępuje nawiasy kątowe, apostrof, cudzysłów podwójny i znaki ampersand odpowiednimi elementami XML. Używaj w przypadku dokumentów XML 1.0.
escapeXML11(ciąg)	Działa tak samo jak escapeXML, ale w przypadku elementów XML w wersji 1.1. Zastosowanie znajduje się poniżej.
encodeHTML(ciąg znaków)	Koduje apostrof, nawiasy kątowe i ampersand.

Argumenty

ciąg znaków – ciąg znaków, którego zmianę chcesz zmienić. Może być literałem lub zmienną przepływu ciągu.

Zastosowanie

XML 1.1 może reprezentować niektóre znaki kontrolne, ale nie może reprezentować zerowego bajta ani niesparowanych zastępczego bajta Unicode, nawet po zmianie znaczenia. Funkcja escapeXML11() usuwa znaki, które nie pasują do tych zakresów:

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

Funkcja escapeXML11() zmienia znaczenie znaków z tych zakresów:

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

Przykłady

Załóżmy, że istnieje zmienna przepływu o nazwie jedzenie o wartości: "bread" & "butter". Następnie funkcja:

{escapeHTML(food)}

daje:

"bread" & "butter"

Funkcje formatu godziny

Zwraca ciąg znaków reprezentujący godzinę w lokalnej strefie czasowej lub w strefie czasowej UTC.

Składnia

Funkcja	Opis
timeFormat(format,str)	Zwraca datę sformatowaną w lokalnej strefie czasowej.
timeFormatMs(format,str)	Zwraca datę sformatowaną w lokalnej strefie czasowej.
timeFormatUTC(format,str)	Zwraca datę sformatowaną w strefie czasowej UTC.
timeFormatUTCMs(format,str)	Zwraca datę sformatowaną w strefie czasowej UTC.

Argumenty

• format – ciąg w formacie daty/godziny. Może to być literałowy ciąg znaków lub zmienna ciągu znaków.
• str – ciąg tekstowy lub zmienna przepływu ciągu zawierająca wartość czasu. W przypadku parametru timeFormatMs wartość może być wyrażona w sekundach od początku epoki lub w milisekundach od początku epoki.

Przykłady

Przyjmijmy podane niżej wartości i załóżmy, że lokalna strefa czasowa to pacyficzny:

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

Funkcje zwracają takie wyniki:

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

Funkcje obliczeniowe HMAC

Funkcje obliczeniowe HMAC stanowią alternatywę dla zasady HMAC do obliczania HMAC. Funkcje te są przydatne podczas wykonywania kaskadowych obliczeń HMAC, na przykład gdy dane wyjściowe jednego kodu HMAC są używane jako klucz dla drugiego HMAC.

Składnia

Funkcja	Opis
hmacSha224(key,valueToSign[,keyencoding[,outputencoding]])	Oblicza HMAC za pomocą funkcji skrótu SHA-224.
hmacSha256(key,valueToSign[,keyencoding[,outputencoding]])	Koduje HMAC za pomocą funkcji skrótu SHA-256.
hmacSha384(key,valueToSign[,keyencoding[,outputencoding]])	Koduje HMAC za pomocą funkcji skrótu SHA-384.
hmacSha512(key,valueToSign[,keyencoding[,outputencoding]])	Koduje HMAC za pomocą funkcji skrótu SHA-512.
hmacMd5(key,valueToSign[,keyencoding[,outputencoding]])	Koduje HMAC za pomocą funkcji skrótu MD5.
hmacSha1(key, valueToSign [,keyencoding[,outputencoding]])	Koduje HMAC algorytmem szyfrowania SHA-1.

Argumenty

• klucz – (wymagany) określa tajny klucz zakodowany jako ciąg znaków, który jest używany do obliczenia HMAC.
• valueToSign – (wymagany) określa wiadomość do podpisania. Powinien to być ciąg znaków.
• keyencoding – (opcjonalny) ciąg tajny klucza zostanie dekodowany zgodnie z określonym kodowaniem. Prawidłowe wartości: hex, base16, base64, utf-8. Domyślnie: utf-8
• outputencoding – (opcjonalny) określa algorytm kodowania używany na potrzeby danych wyjściowych. Prawidłowe wartości: hex, base16, base64. Wielkość liter w wartościach nie jest rozróżniana. hex i base16 to synonimy. Domyślnie: base64

Przykłady

W tym przykładzie do obliczenia HMAC-256 i przypisania jej do zmiennej przepływu służy zasada AssignMessage:

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

Ten przykład pokazuje, jak wygenerować kaskadowy kod HMAC, którego można używać z procesem podpisywania AWS Signature v4. W tym przykładzie do generowania 5 poziomów kaskadowych HMAC używanych do obliczania podpisu dla podpisu AWS w wersji 4 użyto zasady AssignMessage:

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

Inne funkcje

Utwórz funkcję UUID

Generuje i zwraca identyfikator UUID.

Składnia

createUuid()

Argumenty

Brak.

Przykład

{createUuid()}

Przykładowy wynik:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Funkcja losowego długiego generatora

Zwraca losową liczbę całkowitą.

Składnia

randomLong(args)

Argumenty

• Jeśli nie określono żadnych argumentów, funkcja zwraca losową liczbę całkowitą określoną przez klasę Java SecureRandom.
• Jeśli podany jest 1 argument, jest on traktowany jako minimalna wartość obliczenia.
• Jeśli podany jest drugi argument, jest on traktowany jako maksymalna wartość obliczeń.

Przykład

{random()}

daje wynik podobny do tego:

5211338197474042880

Generator tekstu wyrażenia regularnego

Wygeneruj ciąg tekstowy pasujący do danego wyrażenia regularnego.

Składnia

xeger(regex)

Argument

regex (wyrażenie regularne) – wyrażenie regularne.

Przykład

Ten przykład generuje 7-cyfrowy ciąg bez zer:

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

Przykładowy wynik:

9857253

Funkcja scalania o wartości null

Funkcja firstnonnull() zwraca wartość niepustego argumentu, który znajduje się najbardziej po lewej stronie.

Składnia

firstnonnull(var1,varn)

Argument

var1 – zmienna kontekstowa.

var_n – co najmniej jedna zmienna kontekstowa. Argument najdalej z prawej strony możesz ustawić na ciąg znaków, aby podać wartość zastępczą (wartość, która zostanie ustawiona, jeśli nie zostanie ustawiony żaden z argumentów po lewej stronie).

Przykłady

Tabela poniżej pokazuje, jak używać tej funkcji:

Szablon	Var1	Var2	Var3	Wynik
{firstnonnull(var1,var2)}	Nie ustawiono	foo	Nie dotyczy	foo
{firstnonnull(var1,var2)}	foo	bar	Nie dotyczy	foo
{firstnonnull(var1,var2)}	foo	Nie ustawiono	Nie dotyczy	foo
{firstnonnull(var1,var2,var3)}	foo	bar	baz	foo
{firstnonnull(var1,var2,var3)}	Nie ustawiono	bar	baz	bar
{firstnonnull(var1,var2,var3)}	Nie ustawiono	Nie ustawiono	baz	baz
{firstnonnull(var1,var2,var3)}	Nie ustawiono	Nie ustawiono	Nie ustawiono	null
{firstnonnull(var1)}	Nie ustawiono	Nie dotyczy	Nie dotyczy	null
{firstnonnull(var1)}	foo	Nie dotyczy	Nie dotyczy	foo
{firstnonnull(var1,var2)}	""	bar	Nie dotyczy	""
{firstnonnull(var1,var2,'fallback value')}	null	null	fallback value	fallback value

Funkcja XPath

Stosuje wyrażenie XPath do zmiennej XML.

Składnia

xpath(xpath_expression,xml_string,[datatype])

Argumenty

xpath_expression – wyrażenie XPath.

xml_string – zmienna przepływu lub ciąg znaków zawierający kod XML.

datatype – (opcjonalny) określa pożądany zwracany typ zapytania. Może to być zbiór węzłów, węzeł, liczba, wartość logiczna i ciąg. Domyślnie jest to zbiór węzłów. Zazwyczaj jest to odpowiedni wybór.

Przykład 1

Załóżmy, że te zmienne kontekstowe definiują ciąg znaków XML i wyrażenie XPath:

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

Funkcja xpath() jest używana w zasadzie AssignMessage w ten sposób:

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

Funkcja zwraca wartość <tagid>250397</tagid>. Ta wartość jest umieszczana w zmiennej kontekstowej o nazwie extracted_tag.

Przykład 2

Jeśli chcesz poznać tylko wartość węzła, użyj funkcji text() w ten sposób:

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

W wyniku tej operacji zmienna kontekstowa extracted_tag jest ustawiona na 250397.

Jeśli wybierzesz wiele węzłów, wynikiem xpath() będą wszystkie wartości wyboru połączone przecinkiem.

Przykład 3. Przestrzenie nazw XML

Aby określić przestrzeń nazw, dołącz dodatkowe parametry, każdy z nich jako ciąg znaków w postaci prefix:namespaceuri. Na przykład funkcja xpath(), która wybiera element podrzędny treści SOAP, może wyglądać tak:

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

W przypadku dodatkowych przestrzeni nazw do funkcji xpath() możesz dodać maksymalnie 10 dodatkowych parametrów.

Proste wyrażenie XPath możesz podać jako ciąg znaków w cudzysłowie prostym:

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

Jeśli wyrażenie XPath zawiera prefiksy (i dwukropki) przestrzeni nazw, musisz przypisać to wyrażenie do zmiennej i podać bezpośrednio nazwę zmiennej, a nie wyrażenie.

{xpath(xpathexpression,xml,ns1)}

Przykład 4: określanie odpowiedniego typu zwracanego produktu

Opcjonalny trzeci parametr przekazywany do funkcji xpath() określa pożądany zwracany typ zapytania.

Niektóre zapytania XPath mogą zwracać wartości liczbowe lub wartości logiczne. Na przykład funkcja count() zwraca liczbę. To jest prawidłowe zapytanie XPath:

count(//Record/Fields/Pair)

To prawidłowe zapytanie zwraca wartość logiczną:

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

W takich przypadkach wywołaj funkcję xpath() z trzecim parametrem określającym ten typ:

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

Jeśli trzeci parametr zawiera dwukropek, jest on interpretowany jako argument przestrzeni nazw. Jeśli nie jest, jest traktowany jako wymagany typ zwracany. W tym przypadku, jeśli trzeci parametr nie jest jedną z prawidłowych wartości (ignoruje wielkość liter), funkcja xpath() domyślnie zwraca zbiór węzłów.

Funkcja JSON Path

Stosuje wyrażenie ścieżki JSON do zmiennej JSON.

Składnia

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

Argumenty

• (Wymagane) json-path: (ciąg znaków) wyrażenie ścieżki JSON.
• (Wymagane) json-var: (ciąg znaków) zmienna przepływu lub ciąg znaków zawierający plik JSON.
• (Opcjonalnie) want-array: (ciąg znaków) jeśli ten parametr ma wartość 'true', a zbiór wyników jest tablicą, zwracane są wszystkie elementy tablicy. Jeśli jest ustawiony na dowolną inną wartość lub ten parametr jest pominięty, zwracany jest tylko zerowy element tablicy zbioru wyników. Jeśli zbiór wyników nie jest tablicą, ten trzeci parametr (jeśli występuje) jest ignorowany.

Przykład 1

Jeśli to jest szablon wiadomości:

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

i the_json_variable zawiera:

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

Wynik tej funkcji to:

The address is 1060 West Addison Street

Pamiętaj, że w tym przypadku zbiór wyników to pojedynczy element (a nie tablica elementów). Jeśli zbiór wyników jest tablicą, zwrócony zostanie tylko zerowy element tablicy. Aby zwrócić pełną tablicę, wywołaj funkcję z 'true' jako trzecim parametrem, jak pokazano w następnym przykładzie.

Przykład 2

Jeśli to jest szablon wiadomości:

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

i the_json_variable zawiera:

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

Wynik tej funkcji to:

['A','B']