Szablony wiadomości

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

W tym temacie omawiamy korzystanie z szablonów wiadomości w interfejsach API proxy oraz podajemy przykłady funkcji.

Co to jest szablon wiadomości?

Szablon wiadomości umożliwia zastąpienie zmiennych ciągów znaków w niektórych elementach zasad i elementach typu TargetEndpoint. Ta funkcja (jeśli jest obsługiwana) umożliwia wypełnianie ciągów znaków dynamicznie podczas wykonywania serwera proxy.

W szablonie wiadomości możesz użyć dowolnej kombinacji odwołań do zmiennych przepływu i tekstu dosłownego. Nazwy zmiennych przepływu muszą być ujęte w nawiasy klamrowe, a tekst nieujęty w nawiasy klamrowe jest wyświetlany jako tekst dosłowny.

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

Przykład

Na przykład zasada przypisywania wiadomości 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 oceniona i zastąpiona w czasie działania ciągiem danych. Jeśli na przykład user.name=jdoe, wynikowy komunikat w danych będzie wyglądał tak: You entered an invalid username: jdoe. Jeśli nie uda się rozwiązać zmiennej, zostanie zwrócony pusty ciąg.

Przykład

Gdy przekroczysz limit, warto przesłać do dzwoniącego użytkownika odpowiednią wiadomość. Ten wzorzec jest często używany z „regułą domyślną”, aby zapewnić wywołującemu informacje o naruszeniu limitu. W tej polityce przypisywania wiadomości szablony wiadomości są używane do dynamicznego wypełniania informacji o limitach 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 dotyczących przypisywania wiadomości te 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.

Gdy ta zasada jest wykonywana:

• Elementy nagłówka otrzymują wartości określone w ramach zmiennych przepływu.
• Dane payload zawierają mieszankę tekstu dosłownego i zmiennych (element client_id jest wypełniany dynamicznie).
• Elementy StatusCode i ReasonPhrase zawierają tylko tekst dosłowny, ale obsługują też szablony wiadomości.

Przykład

W definicji docelowego punktu końcowego proxy elementy podrzędne elementu <SSLInfo> obsługują szablony wiadomości. Zgodnie z tym samym wzorcem co w przypadku zasad, podczas wykonywania usługi proxy zastępuje się zmienne przepływu w nawiasach klamrowych.

<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 oraz w niektórych elementach używanych w konfiguracji punktu końcowego docelowego.

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żywanie nawiasów klamrowych do oznaczania zmiennych

Zawijaj nazwy zmiennych w nawiasy klamrowe { }. Jeśli zmienna nie istnieje, zwracany jest pusty ciąg znaków. W szablonach wiadomości możesz jednak określić wartości domyślne (które są zastępowane, jeśli zmienna nie zostanie rozwiązana). Zobacz artykuł Ustawianie wartości domyślnych w szablonach wiadomości.

Pamiętaj, że otaczanie cudzysłowami całego ciągu szablonu wiadomości jest dozwolone, ale nie jest wymagane. 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 uda się rozwiązać zmiennej w szablonie, Edge wstawi 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 powyższym przykładzie, jeśli nie uda się rozwiązać 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 )}

Stara składnia ładunków JSON

W wersjach Edge poprzedzających wersję Cloud 16.08.17 nie można używać nawiasów klamrowych do oznaczania odwołań do zmiennych w ładunkach JSON. W tych starszych wersjach trzeba było używać atrybutów variablePrefix i variableSuffix, aby określać znaki rozdzielające i stosować je do otaczania nazw zmiennych, np. w ten sposób:

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

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

Korzystanie z funkcji szablonów wiadomości

Edge udostępnia zestaw funkcji, których możesz używać w szablonach wiadomości, aby uciekać, kodować, szyfrować i formatować zmienne ciągu.

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

Przykład: toLowerCase()

Aby przekształcić zmienną ciągu tekstowego w małą literę, 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 zostanie rozwiązana, jej znaki będą małymi literami. Jeśli parametr foo.bar nie zostanie rozwiązany, zostanie zastąpiony wartością domyślną FOO i przekształcony w małe litery. Na przykład:

Test header: foo

Przykład: escapeJSON()

Oto ciekawy przypadek użycia: załóżmy, że aplikacja serwera zwraca odpowiedź 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 wywołującego klienta w ramach niestandardowego ładunku. Najczęstszym sposobem jest wyodrębnienie wiadomości z docelowego ładunku odpowiedzi i dodanie jej do niestandardowej odpowiedzi pośredniczącej za pomocą polecenia przypisz wiadomość (czyli wysłanie jej z powrotem do klienta).

Oto zasada wyodrębniania 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 w pełni poprawna polityka przypisywania wiadomości, która dodaje wyekstrahowaną zmienną do odpowiedzi (odpowiedzia pośredniczącego):

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

Niestety, wystąpił problem. Zasady dotyczące wyodrębniania zmiennych usunęły znaki cudzysłowów otaczające część wiadomości. Oznacza to, że odpowiedź zwrócona do klienta jest nieprawidłowym JSON-em. To nie jest na pewno to, co zamierzasz zrobić.

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

Aby obejść ten problem, możesz zmodyfikować zasadę Przypisz wiadomość, aby używała funkcji szablonu wiadomości, która ucieka z cudzysłowów w kodzie JSON. Ta funkcja escapeJSON() powoduje uciekanie znaków 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 ucieka znaki cudzysłowów, co powoduje, że wynik jest prawidłowym ciągiem JSON, czyli dokładnie tym, czego oczekujesz:

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

Szablon wiadomości to funkcja dynamicznej zamiany ciągów znaków, której możesz używać w niektórych zasadach i definicjach punktu końcowego docelowego. Funkcje szablonu wiadomości umożliwiają wykonywanie przydatnych operacji, takich jak haszowanie, manipulowanie ciągami znaków, ucieczka znaków i inne, w ramach szablonu wiadomości.

Na przykład w poniższej polityce przypisywania wiadomości w szablonie wiadomości użyto funkcji 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 temacie opisujemy funkcje szablonu wiadomości, ich argumenty i wyjścia. W tym temacie zakładamy, że znasz szablony wiadomości i konteksty, w których są używane.

Funkcje skrótu

Oblicz wartość hasza i zwraca ciąg znaków tego hasza.

Szesnastkowe funkcje skrótu

Oblicz wartość skrótu i zwraca ciąg znaków tego skrótu jako liczba szesnastkowa.

Składnia

Argumenty

ciąg znaków – funkcje haszujące przyjmują pojedynczy argument typu ciąg znaków, na podstawie którego jest obliczany algorytm haszowania. Argument może być ciągiem znaków lub zmienną ciągu w przepływie.

Przykłady

Wywołanie funkcji:

sha256Hex('abc')

Efekt:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Wywołanie funkcji:

var str = 'abc';
sha256Hex(str)

Efekt:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Funkcje haszujące Base64

Oblicz wartość skrótu i zwróć jej ciąg znaków jako wartość zakodowana w formacie Base64.

Składnia

Argumenty

ciąg znaków – funkcje haszujące przyjmują pojedynczy argument typu ciąg znaków, na podstawie którego jest obliczany algorytm haszowania. Argument może być ciągiem znaków lub zmienną ciągu w przepływie danych.

Przykłady

Wywołanie funkcji:

sha256Base64('abc')

Efekt:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Wywołanie funkcji:

var str = 'abc';
sha256Base64(str)

Efekt:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Funkcje tekstowe

Wykonywanie operacji na ciągach znaków w szablonie wiadomości.

Funkcje kodowania Base64

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

Składnia

Argumenty

ciąg znaków – ciąg znaków do zakodowania lub odkodowania. Może to być ciąg znaków lub zmienna ciągu w przepływie.

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 ciąg znaków na wyłącznie wielkie lub małe litery.

Składnia

Argumenty

ciąg – ciąg znaków do przekonwertowania. Może to być ciąg znaków lub zmienna ciągu w przepływie.

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 substring

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

Składnia

substring(str,start_index,end_index)

Argumenty

• str – ciąg znaków lub zmienna przepływu ciągu znaków.
• start_index – indeks początkowy w ciągu.
• end_index – (opcjonalnie) indeks końcowy w łańcuchu. Jeśli nie zostanie podany, indeks końcowy będzie odpowiadał końcowi ciągu.

Przykłady

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

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

Funkcja Zastąp wszystko

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

Składnia

replaceAll(string,regex,value)

Argumenty

• string – literały lub zmienne przepływu ciągu znaków, w których mają być dokonywane zamiany.
• regex – wyrażenie regularne.
• value – wartość, która zastąpi wszystkie dopasowania wyrażenia regularnego w ciągu.

Przykłady

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

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

Zastąp funkcję Pierwsza

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

Składnia

replaceFirst(string,regex,value)

Argumenty

• string – literały lub zmienne przepływu ciągu znaków, w których mają być dokonywane zamiany.
• regex – wyrażenie regularne.
• wartość – wartość, która ma zastąpić dopasowania wyrażenia regularnego w ciągu.

Funkcje kodowania i modyfikacji znaków

Funkcje, które zmieniają znaczenie znaków specjalnych w ciągu tekstowym lub je kodują.

Składnia

Argumenty

ciąg – ciąg znaków do ucieczki. Może to być ciąg znaków lub zmienna ciągu w przepływie.

Zastosowanie

XML 1.1 może reprezentować niektóre znaki sterujące, ale nie może reprezentować bajtu null ani niesparowanych kodów zastępczych Unicode, nawet po użyciu znaku ucieczki. Funkcja escapeXML11() usuwa znaki, które nie pasują do tych zakresów:

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

Funkcja escapeXML11() powoduje zastąpienie 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)}

powoduje:

Funkcje formatu czasu

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

Składnia

Argumenty

• format – ciąg formatu daty/godziny. Może to być ciąg znaków lub zmienna tekstowa.
• str – zmienna tekstowa lub zmienna przepływu tekstowego zawierająca wartość czasową. W przypadku formatu timeFormatMs wartość może być podana w sekundach od początku epoki lub w milisekundach od początku epoki.

Przykłady

Przyjmij te wartości i załóż, że lokalny czas 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 korzystania z zasad HMAC do obliczania HMAC. Te funkcje są przydatne podczas kaskadowego obliczania HMAC, gdy wyjście jednego HMAC jest używane jako klucz 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 służy do obliczenia HMAC.
• valueToSign – (wymagany) określa wiadomość do podpisania. Musi to być ciąg znaków.
• keyencoding – (opcjonalnie) ciąg znaków klucza tajnego zostanie zdekodowany zgodnie z podanym tu kodowaniem. Prawidłowe wartości: hex, base16, base64 i utf-8. Wartość domyślna: utf-8
• outputencoding – (opcjonalnie) określa algorytm kodowania do użycia w przypadku danych wyjściowych. Prawidłowe wartości: hex, base16 i base64. Wielkość liter w wartościach nie jest rozróżniana. hex i base16 to synonimy. Wartość domyślna: base64

Przykłady

W tym przykładzie do obliczenia wartości HMAC-256 i przypisania jej do zmiennej przepływu użyto reguły przypisywania wiadomości:

<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, które są używane do obliczenia podpisu 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 losowego generatora długich ciągów

Zwraca losową liczbę całkowitą typu long.

Składnia

randomLong(args)

Argumenty

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

Przykład

{random()}

powoduje, że:

5211338197474042880

Generator tekstu z wyrażeniami regularnymi

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

Składnia

xeger(regex)

Argument

regex – wyrażenie regularne.

Przykład

W tym przykładzie generowany jest 7-cyfrowy ciąg bez zer:

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

Przykładowy wynik:

9857253

Funkcja null-coalescing

Funkcja firstnonnull() zwraca wartość najbardziej lewego argumentu, który nie jest równy wartości NULL.

Składnia

firstnonnull(var1,varn)

Argument

var1 – zmienna kontekstowa.

var_n – co najmniej 1 zmienna kontekstowa. Najbardziej prawy argument może być ustawiony na ciąg znaków, aby podać wartość zastępczą (wartość, która zostanie ustawiona, jeśli żaden z lewych argumentów nie jest ustawiony).

Przykłady

W tabeli poniżej znajdziesz instrukcje korzystania z 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 – (opcjonalnie) określa żądany typ zwracanych danych zapytania. Może to być nodeset, node, number, boolean, string. Domyślnie jest to nodeset. Domyślna opcja jest zwykle prawidłowym wyborem.

Przykład 1

Załóżmy, że te zmienne kontekstowe definiują ciąg 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 przypisywania wiadomości 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 kontekstu o nazwie extracted_tag.

Przykład 2

Jeśli interesuje Cię 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 ma wartość 250397.

Jeśli wybranych jest wiele węzłów, wynik funkcji xpath() to wszystkie wartości wybranych węzłów połączone przecinkami.

Przykład 3. Przestrzeń nazw XML

Aby określić nazwę przestrzeni nazw, dodaj dodatkowe parametry, z których każdy jest ciągiem znaków podobnym do prefix:namespaceuri. Na przykład funkcja xpath(), która wybiera element podrzędny w ciele 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.

Proste wyrażenie XPath możesz podać jako ciąg znaków otoczony pojedynczymi cudzysłowami:

{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 podać nazwę zmiennej zamiast wyrażenia bezpośrednio.

{xpath(xpathexpression,xml,ns1)}

Przykład 4. Określanie żądanego typu zwracanych danych

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

Niektóre zapytania XPath mogą zwracać wartości liczbowe lub logiczne. Na przykład funkcja count() zwraca liczbę. Poniżej znajduje się 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 traktowana jako żądany typ zwracanych danych. W tym przypadku, jeśli trzeci parametr nie jest jedną z dozwolonych wartości (ignorując wielkość liter), funkcja xpath() zwraca domyślnie zbiór węzłów.

Funkcja Ścieżka JSON

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.
• (Wymagany) json-var: (ciąg znaków) zmienna przepływu lub ciąg znaków zawierający dane w formacie 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 ustawisz go na dowolną inną wartość lub pominiesz ten parametr, zwrócony zostanie tylko element zerowy tablicy zbioru wyników. Jeśli zbiór wyników nie jest tablicą, 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 funkcji:

The address is 1060 West Addison Street

Pamiętaj, że w tym przypadku zestaw wyników to pojedynczy element (a nie tablica elementów). Jeśli zbiór wyników jest tablicą, zwrócony zostanie tylko jej pierwszy element. Aby zwrócić pełną tablicę, wywołaj funkcję, podając jako trzeci parametr wartość 'true', 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 funkcji:

['A','B']