Zasada KeyValueMapOperations

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

Co

Umożliwia dostęp do sklepu map klucz-wartość (KVM) w Apigee Edge na podstawie zasad. Pary klucz-wartość można przechowywać, pobierać i usuwać z nazwanych istniejących map, konfigurując zasady KeyValueMapOperations, które określają operacje PUT, GET lub DELETE. (Co najmniej 1 z tych działań musi być wykonywane przez zasadę).

Filmy

Aby dowiedzieć się więcej o KVM, obejrzyj poniższe filmy.

Przykłady

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="FooKVM" mapIdentifier="FooKVM">
  <DisplayName>FooKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Put>
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
    <Value>foo</Value>
    <Value>bar</Value>
  </Put>
</KeyValueMapOperations>

<KeyValueMapOperations mapIdentifier="FooKVM" async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

<KeyValueMapOperations name="putUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Put override="true">
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/>
      </Key>
      <Value ref="urlencoding.longurl.encoded"/>
      <Value ref="request.queryparam.url"/>
   </Put>
</KeyValueMapOperations>

{
    "entry" :[
        {
            "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
            "value" : "http://tinyurl.com/38lwmlr,http://apigee.com"
        }
    ],
    "name" : "urlMapper"
}

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Get assignTo="urlencoding.shorturl" index='1'>
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/>
      </Key>
   </Get>
</KeyValueMapOperations>

<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map">
   <Scope>apiproxy</Scope>
   <Get assignTo="private.encryptedVar" index='1'>
      <Key>
         <Parameter>foo</Parameter>
      </Key>
   </Get>
</KeyValueMapOperations>

Odwołanie do elementu

Odwołanie do elementu opisuje elementy i atrybuty zasady KeyValueMapOperations:

<KeyValueMapOperations async="false" continueOnError="false"
    enabled="true" name="Key-Value-Map-Operations-1"
    mapIdentifier="urlMapper" >
   <DisplayName>Key Value Map Operations 1</DisplayName>
   <Scope>environment</Scope>
   <ExpiryTimeInSecs>300</ExpiryTimeInSecs>
   <InitialEntries>
      <Entry>
         <Key>
            <Parameter>key_name_literal</Parameter>
         </Key>
         <Value>value_literal</Value>
      </Entry>
      <Entry>
         <Key>
            <Parameter>variable_name</Parameter>
         </Key>
         <Value>value_1_literal</Value>
         <Value>value_2_literal</Value>
      </Entry>
   </InitialEntries>
   <Put override="false">
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value ref="variable_name"/>
   </Put>
   <Get assignTo="myvar" index="1">
      <Key>
         <Parameter ref="variable_name"/>
      </Key>
   </Get>
   <Delete>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
   </Delete>
</KeyValueMapOperations>

Atrybuty <KeyValueMapOperations>

Poniższy przykład pokazuje atrybuty tagu <KeyValueMapOperations>:

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">

W tabeli poniżej opisano atrybuty specyficzne dla tagu <KeyValueMapOperations>:

W tej tabeli opisano atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:

&lt;DisplayName&gt; element

Używaj oprócz atrybutu name do oznaczania zasady w edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

Element <Delete>

Usuwa określoną parę klucz/wartość. Musisz użyć co najmniej jednego z tych atrybutów: <Get>, <Put> lub <Delete>.

Pamiętaj, aby podać nazwę KVM za pomocą atrybutu mapIdentifier w elemencie nadrzędnym. Na przykład:

<Delete>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Delete>

Element <Entry>

Wartości początkowe map klucz-wartość, które są wypełniane w mapie klucz-wartość podczas jej inicjowania.

W przypadku Edge na chmurę publiczną rozmiar klucza jest ograniczony do 2 KB. Na przykład:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

Element <ExclusiveCache>

Rola wycofana. Zamiast tego użyj elementu <Scope>.

Element <ExpiryTimeInSecs>

Określa czas w sekundach, po którym Edge odświeża wartość w pamięci podręcznej z określonego KVM.

Wartość 0 lub -1 albo pominięcie tego elementu oznacza, że używana jest wartość domyślna, czyli 300 sekund. Na przykład:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

KVM to mechanizm długoterminowego przechowywania danych, który zapisuje klucze i wartości w bazie danych NoSQL. Z tego powodu odczytywanie danych z KVM w czasie działania może spowolnić działanie serwera proxy. Aby zwiększyć wydajność, Edge ma wbudowany mechanizm buforowania kluczy i wartości KVM w pamięci w czasie działania. W przypadku operacji GET ta zasada KVM Operations zawsze odczytuje dane z pamięci podręcznej.

Element <ExpiryTimeInSecs> pozwala określić, jak długo klucze i wartości używane w zasadach są przechowywane w pamięci podręcznej, zanim zostaną ponownie odświeżone z KVM. Istnieją jednak pewne różnice w tym, jak operacje GET i PUT wpływają na wygasanie pamięci podręcznej.

GET – gdy operacja GET KVM jest wykonywana po raz pierwszy, żądane klucze/wartości z KVM (którego nazwa jest określona w atrybucie głównym mapIdentifier zasad) są ładowane do pamięci podręcznej, gdzie pozostają w przypadku kolejnych operacji GET, dopóki nie nastąpi jedno z tych zdarzeń:

• Upłynie liczba sekund określona w parametrze <ExpiryTimeInSecs>.
  lub
• Operacja PUT w przypadku zasad KVM zastępuje istniejące wartości (wyjaśnienie poniżej).

PUT – operacja PUT zapisuje klucze i wartości w określonym KVM. Jeśli żądanie PUT zapisuje dane w kluczu, który już istnieje w pamięci podręcznej, pamięć podręczna jest natychmiast odświeżana i zawiera nową wartość przez liczbę sekund określoną w elemencie <ExpiryTimeInSecs> zasad.

Przykład – buforowanie KVM

1. Operacja GET pobiera wartość „rating”, która dodaje do pamięci podręcznej wartość „10”. Wartość <ExpiryTimeInSecs> w zasadach wynosi 60.
2. 30 sekund później zasada GET jest wykonywana ponownie i pobiera z pamięci podręcznej wartość „10”.
3. 5 sekund później zasada PUT aktualizuje wartość „rating” na „8”, a wartość <ExpiryTimeInSecs> w zasadzie PUT wynosi 20. Pamięć podręczna jest natychmiast odświeżana nową wartością, która ma być przechowywana w pamięci podręcznej przez 20 sekund. (Gdyby żądanie PUT nie zostało wysłane, pamięć podręczna pierwotnie wypełniona przez pierwsze żądanie GET istniałaby jeszcze przez 30 sekund, czyli pozostałe 30 sekund z pierwotnych 60 sekund).
4. 15 sekund później wykonuje się kolejne żądanie GET, które pobiera wartość „8”.

Element <Get>

Pobiera wartość określonego klucza. Musisz użyć co najmniej jednego z tych atrybutów: <Get>, <Put> lub <Delete>.

Pamiętaj, aby podać nazwę KVM za pomocą atrybutu mapIdentifier w elemencie nadrzędnym.

W zasadach możesz umieścić kilka bloków Get, aby pobrać z KVM wiele elementów.

Pobieranie pojedynczego elementu z KVM

<Get assignTo="myvar" index="1">
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Get>

Pobieranie wielu elementów z KVM

W poniższym przykładzie załóżmy, że mapa klucz-wartość ma te klucze i wartości: Oprócz przechowywania listy najpopularniejszych filmów wszech czasów KVM przechowuje nazwiska reżyserów wszystkich ważnych filmów.

Oto konfiguracja zasad KVM, której możemy użyć do pobrania aktualnie najpopularniejszego filmu i imienia jego reżysera:

<Get assignTo="top.movie.pick" index="1">
   <Key>
      <Parameter>top_movies</Parameter>
   </Key>
</Get>
<Get assignTo="movie.director">
   <Key>
      <Parameter ref="top.movie.pick"/>
   </Key>
</Get>

Gdy wywoływany jest serwer proxy interfejsu API, Edge tworzy te zmienne, których możesz używać w przepływie serwera proxy interfejsu API:

• top.movie.pick=Princess Bride
• movie.director=Rob Reiner

Atrybuty

W tabeli poniżej opisano atrybuty elementu <Get>:

<Get assignTo="private.myvar">

Element <InitialEntries>

Wartości początkowe map klucz-wartość, które są wypełniane w mapie klucz-wartość podczas jej inicjowania. Pamiętaj, aby określić nazwę KVM za pomocą atrybutu mapIdentifier w elemencie nadrzędnym. Na przykład:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

Gdy używasz tego elementu i zapisujesz zasady w interfejsie zarządzania w przypadku wdrożonej wersji proxy lub wdrażasz pakiet proxy interfejsu API zawierający zasady z tym elementem, klucze są automatycznie tworzone w mapie wartości klucza (jako niezaszyfrowane). Jeśli wartości w zasadach różnią się od wartości w mapie wartości kluczy, po wdrożeniu serwera proxy wartości w mapie wartości kluczy zostaną zastąpione. Wszystkie nowe klucze i wartości są dodawane do istniejącego KVM wraz z dotychczasowymi kluczami i wartościami.

Klucze i wartości wypełniane przez ten element muszą być literałami. Na przykład w tym elemencie nie jest obsługiwany tag <Parameter ref="request.queryparam.key">.

Rozmiar klucza jest ograniczony do 2 KB zarówno w przypadku Edge w chmurze publicznej, jak i Edge w chmurze prywatnej. Wartość KVM jest ograniczona do 2 KB.

Aby utworzyć zaszyfrowaną mapę KVM, użyj interfejsu Key/Value Maps Management API.

Element <Key>

Określa klucz we wpisie mapy klucz-wartość. Klucz może być złożony, co oznacza, że do jego utworzenia można dołączyć więcej niż 1 parametr. Na przykład userID i role można połączyć, aby utworzyć key. Na przykład:

<Key>
    <Parameter>key_name_literal</Parameter>
</Key>

Więcej informacji o tym, jak ustawić nazwę klucza, znajdziesz w elemencie <Parameter>.

W przypadku Edge na chmurę publiczną rozmiar klucza jest ograniczony do 2 KB. Więcej informacji znajdziesz w artykule Różnice między interfejsami Edge API dla chmury publicznej i chmury prywatnej.

Element <Parameter>

Określa klucz w parze klucz/wartość. Ten element określa nazwę podczas tworzenia, umieszczania, pobierania lub usuwania pary klucz/wartość.

Nazwę możesz określić za pomocą:

• literał ciągu znaków;

  <Key>
    <Parameter>literal</Parameter>
  </Key>

• Zmienna, która ma zostać pobrana w czasie działania programu, przy użyciu atrybutu ref

  <Key>
    <Parameter ref="variable_name"/>
  </Key>

• Kombinacja literałów i odwołań do zmiennych

  <Key>
    <Parameter>targeturl</Parameter>
    <Parameter ref="apiproxy.name"/>
    <Parameter>weight</Parameter>
  </Key>

Jeśli element Key zawiera wiele elementów Parameter, efektywny ciąg klucza jest konkatenacją wartości każdego parametru połączonych podwójnym podkreśleniem. Jeśli na przykład w powyższym przykładzie zmienna apiproxy.name ma wartość „abc1”, efektywny klucz będzie miał wartość targeturl__abc1__weight.

Niezależnie od tego, czy pobierasz, aktualizujesz czy usuwasz wpis klucz-wartość, nazwa klucza musi być zgodna z nazwą klucza na mapie klucz-wartość. Wskazówki znajdziesz w artykule Określanie i pobieranie nazw kluczy.

Atrybuty

W tabeli poniżej opisano atrybuty elementu <Parameter>:

Element <Put>

Zapisuje parę klucz-wartość na mapie klucz-wartość, niezależnie od tego, czy jest ona zaszyfrowana czy nie. Jeśli mapa par klucz-wartość określona w atrybucie mapIdentifier elementu nadrzędnego nie istnieje, jest ona automatycznie tworzona (jako niezaszyfrowana). Jeśli mapa klucz-wartość już istnieje, klucz i wartość zostaną do niej dodane.

Aby utworzyć zaszyfrowaną mapę klucz-wartość, użyj interfejsu API do zarządzania mapami klucz-wartość lub zapoznaj się z artykułem Tworzenie i edytowanie map klucz-wartość środowiska, aby utworzyć zaszyfrowane mapy klucz-wartość o zakresie środowiska w interfejsie.

<Put override="false">
   <Key>
      <Parameter ref="mykeyvar"/>
   </Key>
   <Value ref="myvalvar1"/>
</Put>

Atrybuty

W tabeli poniżej opisano atrybuty elementu <Put>:

Element <Scope>

Określa granicę dostępności map wartości klucza. Domyślny zakres to environment, co oznacza, że domyślnie wpisy map są współdzielone przez wszystkie proxy interfejsu API działające w środowisku (np. testowym lub produkcyjnym). Jeśli ustawisz zakres na apiproxy, wpisy na mapie klucz-wartość będą dostępne tylko dla serwera proxy interfejsu API, który zapisuje wartości na mapie.

Pamiętaj, że podczas uzyskiwania dostępu do mapy lub wpisu mapy musisz podać tę samą wartość zakresu, która została użyta podczas tworzenia mapy. Jeśli na przykład mapa została utworzona z zakresem apiproxy, podczas pobierania jej wartości, wprowadzania zmian lub usuwania wpisów musisz użyć zakresu apiproxy.

<Scope>environment</Scope>

Element <Value>

Określa wartość klucza. Wartość możesz podać jako ciąg dosłowny lub za pomocą atrybutu ref jako zmienną, która ma być pobierana w czasie działania:

<!-- Specify a literal value -->
<Value>literal<Value>

lub

<!-- Specify the name of variable value to be populated at run time. -->
<Value ref="variable_name"/>

Możesz też dodać kilka elementów <Value>, aby określić wartość wieloczęściową. Wartości są łączone w czasie działania.

W poniższym przykładzie do KVM dodawane są 2 klucze:

• Klucz k1 z wartościami v1,v2
• Klucz k2 z wartościami v3,v4

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>k1</Parameter>
      </Key>
      <Value>v1</Value>
      <Value>v2</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>k2</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

W tym przykładzie tworzony jest jeden klucz z 2 wartościami. Załóżmy, że nazwa organizacji to foo_org, nazwa proxy interfejsu API to bar, a środowisko to test:

• Klucz foo_org z wartościami bar,test

<Put>
    <Key>
        <Parameter ref="organization.name"/>
    </Key>
    <Value ref="apiproxy.name"/>
    <Value ref="environment.name"/>
</Put>

Atrybuty

W tabeli poniżej opisano atrybuty elementu <Value>:

Odwołanie do błędu

Błędy zwracane przez zasady Edge mają spójny format opisany w dokumentacji kodów błędów.

W tej sekcji opisujemy kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wywołuje błąd. Te informacje są ważne, jeśli opracowujesz reguły dotyczące błędów do obsługi takich błędów. Więcej informacji znajdziesz w sekcjach Co musisz wiedzieć o błędach zasad i Postępowanie w przypadku błędów.

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Błędy wdrażania

Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego te zasady.

Schematy

Zastosowanie

Omówienie map klucz-wartość znajdziesz w artykule Praca z mapami klucz-wartość.

Magazyn map klucz-wartość zapewnia prosty mechanizm utrwalania danych sformatowanych jako pary klucz-wartość. Możesz uzyskać do nich dostęp w czasie działania programu za pomocą zasad lub kodu. Mapa zawiera dowolne dane w formacie key=value.

Na przykład localhost=127.0.0.1, zip_code=94110 lub first_name=felix. W pierwszym przykładzie localhost to klucz, a 127.0.0.1 to wartość. Każda para klucz/wartość jest przechowywana jako wpis na mapie klucz-wartość. Mapa klucz-wartość może przechowywać wiele wpisów.

Oto przykład użycia map wartości klucza. Załóżmy, że musisz przechowywać listę adresów IP powiązanych z różnymi środowiskami backendu. Możesz utworzyć mapę klucz-wartość o nazwie ipAddresses, która zawiera listę par klucz-wartość jako wpisy. Na przykład ten kod JSON może reprezentować taką mapę:

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

Możesz użyć tej struktury do utworzenia magazynu adresów IP, które mogą być używane przez zasady w czasie działania do wymuszania listy dozwolonych lub zabronionych adresów IP, do dynamicznego wybierania docelowego adresu backendu itp. Zasady KeyValueMapOperations są zwykle używane do przechowywania lub pobierania długoterminowych informacji, które muszą być ponownie wykorzystywane w wielu transakcjach żądanie/odpowiedź.

Mapami klucz-wartość można manipulować za pomocą zasady KeyValueMapOperations lub bezpośrednio za pomocą interfejsu API zarządzania Apigee Edge. Szczegółowe informacje o interfejsie Organization key/value maps API znajdziesz w dokumentacji API zarządzania. Za pomocą interfejsu API możesz na przykład przesyłać duże zbiory danych do magazynu klucz/wartość lub tworzyć skrypty do zarządzania wpisami w mapie klucz/wartość. Przed uzyskaniem dostępu do mapy klucz/wartość za pomocą zasady KeyValueMapOperations musisz utworzyć ją za pomocą interfejsu API.

Określanie i pobieranie nazw kluczy

Za pomocą elementów <Parameter> i <Value> możesz określić wartość dosłowną (wartość między tagami otwierającym i zamykającym) lub użyć atrybutu ref, aby określić nazwę zmiennej, której wartość ma być używana w czasie działania programu.

Element Parameter zasługuje na szczególną uwagę, ponieważ określa nazwę tworzonego klucza, a także nazwę klucza, który chcesz pobrać lub usunąć. Poniżej znajdziesz 2 przykłady. Pierwszy określa nazwę klucza dosłownie, a drugi – za pomocą zmiennej. Załóżmy, że do tworzenia kluczy w KVM używane są te elementy:

<Parameter>key_name_literal</Parameter>
<Parameter ref="key.name.variable"/>

W pierwszym przypadku w KVM jako nazwa klucza jest przechowywana wartość literalna „key_name_literal”. W drugim przypadku wartość w key.name.variable staje się nazwą klucza w KVM. Jeśli na przykład parametr key.name.variable zawierał wartość foo, klucz miałby nazwę „foo”.

Jeśli chcesz pobrać klucz i jego wartość za pomocą operacji GET (lub usunąć za pomocą operacji DELETE), ustawienie <Parameter> musi być zgodne z nazwą klucza w KVM. Jeśli na przykład nazwa klucza w mapie wartości klucza to „foo”, możesz podać wartość dosłowną za pomocą <Parameter>foo</Parameter> lub zmienną, która zawiera dokładną wartość „foo”, w ten sposób: <Parameter ref="variable.containing.foo"/>.

Powiązane artykuły

• Interfejs API map klucz-wartość organizacji