Szablony wiadomości

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

W tym artykule omawiamy, jak używać szablonów wiadomości w proxy interfejsu API, i podajemy odniesienie do funkcji.

Co to jest szablon wiadomości?

Szablon wiadomości umożliwia zastępowanie ciągów zmiennych w określonych elementach zasad i elementach TargetEndpoint. Ta funkcja, jeśli jest obsługiwana, umożliwia dynamiczne wypełnianie ciągów znaków podczas wykonywania serwera proxy.

W szablonie wiadomości możesz umieścić dowolną kombinację odwołań do zmiennych przepływu i tekstu dosłownego. Nazwy zmiennych przepływu muszą być ujęte w nawiasy klamrowe, a tekst, który nie jest w nich ujęty, jest wyświetlany jako tekst dosłowny.

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

Przykład

Na przykład zasada Assign Message umożliwia użycie 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) zostanie obliczona i podstawiona do ciągu ładunku w czasie działania. Jeśli na przykład user.name=jdoe, to wynikowa wiadomość 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.

Przykład

Po przekroczeniu limitu warto zwrócić dzwoniącemu odpowiedni komunikat. Ten wzorzec jest często używany z „regułą błędu”, aby przekazywać dane wyjściowe, które informują wywołującego o naruszeniu limitu. W tej zasadzie 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 zasadach AssignMessage te elementy w elemencie <Set> obsługują tworzenie szablonów 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.

Gdy ta zasada jest wykonywana:

• Elementy nagłówka otrzymują wartości określonych zmiennych przepływu.
• Ładunek zawiera połączenie tekstu dosłownego i zmiennych (client_id jest wypełniana dynamicznie).
• Elementy StatusCode i ReasonPhrase zawierają tylko tekst dosłowny, ale obsługują też tworzenie szablonów wiadomości, jeśli chcesz z nich korzystać.

Przykład

W definicji docelowego punktu końcowego serwera proxy elementy podrzędne <SSLInfo> obsługują tworzenie szablonów wiadomości. Zgodnie z wzorcem używanym w zasadach zmienne przepływu w nawiasach klamrowych są zastępowane podczas wykonywania serwera 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 w kilku zasadach, a także w określonych elementach używanych w konfiguracji TargetEndpoint.

Zasady, które akceptują szablony wiadomości

Elementy TargetEndpoint, które akceptują szablony wiadomości

Składnia szablonu wiadomości

W tej sekcji znajdziesz zasady, których musisz przestrzegać, aby korzystać z szablonów wiadomości.

Używaj nawiasów klamrowych do oznaczania zmiennych

Nazwy zmiennych umieszczaj w nawiasach klamrowych {}. 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 (wartości, które są zastępowane, jeśli zmienna nie zostanie rozpoznana). Zobacz Ustawianie wartości domyślnych w szablonach wiadomości.

Pamiętaj, że umieszczenie całego ciągu szablonu wiadomości w cudzysłowie 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 rozwiązać zmiennej szablonowej, Edge zastępuje ją pustym ciągiem. 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 powyższym przykładzie, jeśli nie można rozpoznać zmiennej request.header.id, jej wartość zostanie zastąpiona wartością Unknown. Na przykład:

Test message. id = Unknown

W wyrażeniach funkcji nie można używać spacji

W wyrażeniach funkcji szablonu wiadomości nie można używać spacji. 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 Edge przed wersją Cloud 16.08.17 nie można było używać nawiasów klamrowych do oznaczania odwołań do zmiennych w ładunkach JSON. W starszych wersjach do określania znaków rozdzielających trzeba było używać atrybutów variablePrefix i variableSuffix, a nazwy zmiennych trzeba było umieszczać w tych znakach, np.:

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

Apigee zaleca używanie nowszej składni z nawiasami klamrowymi, ale starsza składnia nadal działa.

Korzystanie z funkcji szablonu wiadomości

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

Funkcje szablonu wiadomości są szczegółowo opisane w dokumentacji funkcji szablonu wiadomości.

Przykład: toLowerCase()

Użyj wbudowanej funkcji toLowerCase(), aby przekształcić zmienną tekstową na małe litery:

<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 zostanie rozpoznana, wszystkie jej znaki będą pisane małymi literami. Jeśli wartość foo.bar nie zostanie rozpoznana, zostanie zastąpiona wartością domyślną FOO i przekonwertowana na małe litery. Na przykład:

Test header: foo

Przykład: escapeJSON()

Oto ciekawy przypadek użycia: załóżmy, że aplikacja backendu zwraca odpowiedź w formacie JSON, która zawiera prawidłowe znaki ucieczki. Na przykład:

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

Załóżmy, że chcesz zwrócić tę wiadomość do klienta w niestandardowym ładunku. Zwykle polega to na wyodrębnieniu wiadomości z ładunku odpowiedzi docelowej i użyciu funkcji Assign Message (Przypisz wiadomość), aby dodać ją do niestandardowej odpowiedzi serwera proxy (czyli odesłać ją do klienta).

Oto zasady Extract Variables, które wyodrębniają 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 prawidłowa zasada Assign Message, która dodaje wyodrębnioną zmienną do ładunku odpowiedzi (odpowiedzi 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 Extract Variables usunęła znaki cudzysłowu z części wiadomości. Oznacza to, że odpowiedź zwrócona do klienta jest nieprawidłowym formatem JSON. Z pewnością nie o to Ci chodziło.

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

Aby obejść ten problem, możesz zmodyfikować zasadę Assign Message (Przypisz wiadomość), tak aby używała funkcji szablonu wiadomości, która usuwa cudzysłowy w formacie 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 zagnieżdżonych cudzysłowów, co daje prawidłowy kod JSON, czyli dokładnie to, o co Ci chodziło:

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

Szablon wiadomości to dynamiczna funkcja zastępowania ciągów znaków, której możesz używać w niektórych zasadach i definicjach TargetEndpoint. Funkcje szablonu wiadomości umożliwiają wykonywanie przydatnych operacji, takich jak haszowanie, manipulowanie ciągami znaków, usuwanie znaków specjalnych i inne, w ramach szablonu wiadomości.

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

<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 artykule opisujemy funkcje szablonu wiadomości, ich argumenty i dane wyjściowe. W tym artykule zakładamy, że znasz szablony wiadomości i konteksty, w których są one używane.

Funkcje skrótu

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

Szesnastkowe funkcje skrótu

Oblicza wartość skrótu i zwraca jej reprezentację w postaci ciągu jako liczbę szesnastkową.

Składnia

Argumenty

string – funkcje haszujące przyjmują jeden argument w postaci ciągu znaków, na podstawie którego obliczany jest algorytm haszujący. Argument może być ciągiem znaków lub zmienną przepływu ciągu znaków.

Przykłady

Wywołanie funkcji:

sha256Hex('abc')

Wynik:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Wywołanie funkcji:

var str = 'abc';
sha256Hex(str)

Wynik:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Funkcje skrótu Base64

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

Składnia

Argumenty

string – funkcje haszujące przyjmują jeden argument w postaci ciągu znaków, na podstawie którego obliczany jest algorytm haszujący. Argument może być ciągiem znaków lub zmienną przepływu ciągu znaków.

Przykłady

Wywołanie funkcji:

sha256Base64('abc')

Wynik:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Wywołanie funkcji:

var str = 'abc';
sha256Base64(str)

Wynik:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Funkcje ciągów znaków

wykonywać operacje na ciągach w szablonie wiadomości,

Funkcje kodowania Base64

Kodowanie i dekodowanie ciągów tekstowych za pomocą schematu kodowania Base64.

Składnia

Argumenty

string – ciąg znaków do zakodowania lub zdekodowania. Może to być ciąg dosłowny lub zmienna 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 zmiany wielkości liter

Konwertowanie ciągu znaków na wielkie lub małe litery.

Składnia

Argumenty

string – ciąg znaków do przekonwertowania. Może to być ciąg dosłowny lub zmienna 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 między indeksem początkowym a końcowym określonego ciągu.

Składnia

substring(str,start_index,end_index)

Argumenty

• str – literał tekstowy lub zmienna przepływu tekstu.
• start_index – indeks początkowy w ciągu znaków.
• end_index – (opcjonalny) indeks końcowy w ciągu. Jeśli nie zostanie podany, indeks końcowy będzie oznaczał koniec ciągu.

Przykłady

Załóżmy, że w przypadku tych przykładów istnieją te zmienne przepływu:

Oto wyniki wywołań funkcji, które używają tych zmiennych:

Funkcja Zastąp wszystkie

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

Składnia

replaceAll(string,regex,value)

Argumenty

• string – ciąg literału lub zmienna przepływu ciągu, w której mają być dokonywane zamiany.
• regex – wyrażenie regularne.
• value – wartość, którą należy zastąpić wszystkie dopasowania wyrażenia regularnego w ciągu.

Przykłady

Załóżmy, że w przypadku poniższych przykładów istnieją te zmienne przepływu:

Oto wyniki wywołań funkcji, które używają tych zmiennych:

Funkcja ZASTĄP.PIERWSZY

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

Składnia

replaceFirst(string,regex,value)

Argumenty

• string – ciąg literału lub zmienna przepływu ciągu, w której mają być dokonywane zamiany.
• regex – wyrażenie regularne.
• value – wartość, która ma zastąpić dopasowania wyrażenia regularnego w ciągu.

Funkcje zmiany znaczenia znaków i kodowania

Funkcje, które zmieniają znaczenie lub kodują znaki specjalne w ciągu tekstowym.

Składnia

Argumenty

ciąg – ciąg znaków do zmiany. Może to być ciąg dosłowny lub zmienna przepływu ciągu.

Zastosowanie

XML 1.1 może reprezentować niektóre znaki kontrolne, ale nie może reprezentować bajtu zerowego ani nieparzystych punktów kodowych Unicode, nawet po zastosowaniu sekwencji ucieczki. Funkcja escapeXML11() usuwa znaki, które nie mieszczą się w tych zakresach:

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

Funkcja escapeXML11() używa symboli zmieniających znaczenie w przypadku 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 food o wartości "bread" & "butter". Następnie funkcja:

{escapeHTML(food)}

Wynik:

Funkcje formatu czasu

Zwraca ciąg znaków reprezentujący czas sformatowany w lokalnej strefie czasowej lub w czasie UTC.

Składnia

Argumenty

• format – ciąg tekstowy formatu daty i godziny. Może to być ciąg tekstowy lub zmienna tekstowa.
• str – ciąg lub zmienna przepływu ciągu zawierająca wartość czasu. Wartość może być podana w sekundach od początku epoki lub w milisekundach od początku epoki w przypadku parametru timeFormatMs.

Przykłady

Załóż, że obowiązują te wartości, a lokalna strefa czasowa to czas pacyficzny:

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

Funkcje zwracają te 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 obliczania HMAC

Funkcje obliczania HMAC stanowią alternatywę dla zasad HMAC przy obliczaniu HMAC. Funkcje te są przydatne podczas wykonywania kaskadowych obliczeń HMAC, np. gdy dane wyjściowe jednego HMAC są używane jako klucz do 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 za pomocą algorytmu szyfrowania SHA-1.

Argumenty

• key – (wymagany) określa klucz tajny zakodowany jako ciąg znaków, który jest używany do obliczania HMAC.
• valueToSign – (wymagany) określa wiadomość do podpisania. Powinien to być ciąg znaków.
• keyencoding – (Opcjonalnie) Ciąg klucza obiektu tajnego zostanie zdekodowany zgodnie z tym określonym kodowaniem. Prawidłowe wartości: hex, base16, base64, utf-8. Domyślnie: utf-8
• outputencoding – (opcjonalny) określa algorytm kodowania, który ma być używany w przypadku danych wyjściowych. Prawidłowe wartości: hex, base16, base64. Wartości nie uwzględniają wielkości liter. hex i base16 są synonimami. Domyślnie: base64

Przykłady

W tym przykładzie użyto zasady AssignMessage do obliczenia HMAC-256 i przypisania go do zmiennej przepływu:

<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óry można wykorzystać w procesie podpisywania AWS Signature v4. W przykładzie użyto zasady AssignMessage do wygenerowania 5 poziomów kaskadowego HMAC używanego do obliczania podpisu dla AWS Signature w wersji 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>

Inne funkcje

Tworzenie funkcji UUID

Generuje i zwraca identyfikator UUID.

Składnia

createUuid()

Argumenty

Brak.

Przykład

{createUuid()}

Przykładowy wynik:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Funkcja Random Long Generator

Zwraca losową długą liczbę całkowitą.

Składnia

randomLong(args)

Argumenty

• Jeśli nie podasz żadnych argumentów, funkcja zwróci losową liczbę całkowitą długiego formatu obliczoną przez klasę Java SecureRandom.
• Jeśli występuje 1 argument, jest on traktowany jako wartość minimalna obliczeń.
• Jeśli występuje drugi argument, jest on traktowany jako maksymalna wartość obliczeń.

Przykład

{random()}

spowoduje wyświetlenie czegoś takiego:

5211338197474042880

Generator tekstu z wyrażeniami regularnymi

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

Składnia

xeger(regex)

Argument

regex – wyrażenie regularne.

Przykład

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

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

Przykładowy wynik:

9857253

Funkcja łączenia z wartością null

Funkcja firstnonnull() zwraca wartość argumentu znajdującego się najbardziej po lewej stronie, który nie jest wartością null.

Składnia

firstnonnull(var1,varnn>)

Argument

var1 – zmienna kontekstowa.

var_n – co najmniej 1 zmienna kontekstowa. Argument right-most możesz ustawić na ciąg znaków, aby podać wartość domyślną (wartość, która zostanie ustawiona, jeśli żaden z argumentów po lewej stronie nie jest ustawiony).

Przykłady

W tabeli poniżej pokazujemy, 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 XML.

datatype – (Opcjonalnie) określa żądany zwracany typ zapytania. Może to być zbiór węzłów, węzeł, liczba, wartość logiczna lub ciąg znaków. Domyślnie jest to nodeset. Domyślne ustawienie jest zwykle najlepszym wyborem.

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 zasadach 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 uzyskać 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 przyjmuje wartość 250397

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

Przykład 3. Przestrzenie nazw XML

Aby określić przestrzeń nazw, dołącz dodatkowe parametry, z których każdy jest ciągiem znaków w formacie prefix:namespaceuri. Na przykład xpath() funkcja, 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 możesz dodać do funkcji xpath() maksymalnie 10 dodatkowych parametrów.

Możesz określić proste wyrażenie XPath jako ciąg znaków ujęty w apostrofy:

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

Jeśli wyrażenie XPath zawiera prefiksy przestrzeni nazw (i dwukropki), musisz przypisać to wyrażenie XPath do zmiennej i określić nazwę zmiennej zamiast samego wyrażenia.

{xpath(xpathexpression,xml,ns1)}

Przykład 4. Określanie żądanego typu zwracanej wartości

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

Niektóre zapytania XPath mogą zwracać wartości liczbowe lub 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 interpretowany jako argument przestrzeni nazw. W przeciwnym razie jest traktowany jako oczekiwany typ zwracany. W takim przypadku, jeśli trzeci parametr nie jest jedną z prawidłowych wartości (z ignorowaniem wielkości liter), funkcja xpath() domyślnie zwraca zbiór węzłów.

Funkcja ścieżki JSON

Stosuje wyrażenie JSONPath do zmiennej JSON.

Składnia

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

Argumenty

• (Wymagany) json-path: (String) Wyrażenie JSONPath.
• (Wymagany) json-var: (String) zmienna przepływu lub ciąg znaków zawierający JSON.
• (Opcjonalnie) want-array: (String) Jeśli ten parametr ma wartość 'true' i zestaw wyników jest tablicą, zwracane są wszystkie elementy tablicy. Jeśli ustawisz inną wartość lub pominiesz ten parametr, zwracany będzie tylko zerowy element tablicy 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 szablon wiadomości wygląda tak:

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 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 byłby tablicą, zwrócony zostałby tylko element zerowy tablicy. Aby zwrócić całą tablicę, wywołaj funkcję z parametrem 'true' jako trzecim argumentem, jak pokazano w przykładzie poniżej.

Przykład 2

Jeśli szablon wiadomości wygląda tak:

{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 funkcji to:

['A','B']