Zasada KeyValueMapOperations

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

Co

Daje oparty na zasadach dostęp do magazynu mapy klucz-wartość (KVM) dostępnego w Apigee Edge. Pary klucz-wartość można przechowywać, pobierać i usuwać z nazwanych istniejących map przez skonfigurowanie zasad KeyValueMapOperations, które określają operacje PUT, GET lub DELETE. (Zasada musi wykonać co najmniej 1 z tych operacji).

Filmy

Aby dowiedzieć się więcej o KVM, obejrzyj te filmy.

Sample

<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

Dokumentacja elementów 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>

Ten przykład pokazuje atrybuty w tagu <KeyValueMapOperations>:

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

W tabeli poniżej znajdziesz opis atrybutów charakterystycznych dla tagu <KeyValueMapOperations>:

Tabela poniżej zawiera opis atrybutów wspólnych dla wszystkich elementów nadrzędnych zasad:

Element <DisplayName>

Użyj oprócz atrybutu name, aby oznaczyć zasadę w edytorze serwera proxy interfejsu zarządzania inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

Element <Delete>

Usuwa określoną parę klucz-wartość. Należy użyć co najmniej 1 z tych elementó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 wyjściowe dla map klucz-wartość, które są wypełniane w mapie par klucz-wartość po jej zainicjowaniu.

W przypadku Edge dla chmury publicznej 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ść z pamięci podręcznej określonego KVM.

Wartość 0 lub -1 albo jego wykluczenie oznacza, że używana jest wartość domyślna 300 sekund. Na przykład:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

KVM to mechanizm długoterminowego przechowywania danych, który przechowuje klucze i wartości w bazie danych NoSQL. Z tego powodu odczyt z maszyny wirtualnej w czasie działania może potencjalnie spowolnić serwer proxy. Aby zwiększyć wydajność, Edge ma wbudowany mechanizm buforowania kluczy/wartości KVM w pamięci podczas działania. Ta zasada operacji KVM zawsze odczytuje dane z pamięci podręcznej w przypadku operacji GET.

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

GET – przy pierwszym wykonaniu operacji GET żądane klucze/wartości z KVM (której nazwa jest określona w atrybucie głównym zasad mapIdentifier) są ładowane do pamięci podręcznej, gdzie pozostają przy kolejnych operacjach GET, dopóki nie wystąpi jedna z tych sytuacji:

• Liczba sekund podana w polu <ExpiryTimeInSecs> wygasa.
  lub
• Operacja PUT w zasadzie KVM zastępuje istniejące wartości (objaśnione poniżej).

PUT – operacja PUT zapisuje klucze/wartości w określonym KVM. Jeśli PUT zapisuje klucz w kluczu, który już istnieje w pamięci podręcznej, ta pamięć podręczna jest natychmiast odświeżana i teraz zachowuje nową wartość dla liczby sekund określonej w elemencie <ExpiryTimeInSecs> zasady.

Przykład: zapisywanie KVM w pamięci podręcznej

1. Operacja GET pobiera wartość „rating”, która dodaje wartość „10” do pamięci podręcznej. <ExpiryTimeInSecs> w zasadzie ma wartość 60.
2. Po 30 sekundach zasada GET jest uruchamiana ponownie i pobiera z pamięci podręcznej wartość „10”.
3. 5 sekund później zasada PUT aktualizuje wartość „rating” na „8”, a <ExpiryTimeInSecs> w zasadzie PUT ma wartość 20. Pamięć podręczna jest natychmiast odświeżana przy użyciu nowej wartości, która obecnie jest ustawiona tak, aby pozostawała w pamięci podręcznej przez 20 sekund. (Gdyby PUT nie wystąpiło, pamięć podręczna wypełniona pierwotnie przez pierwsze GET dalej będzie istnieć przez kolejne 30 sekund.
4. 15 sekund później wykonuje się kolejna metoda GET, która pobiera wartość „8”.

Element <Get>

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

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

Aby pobierać wiele elementów z KVM, możesz uwzględnić w zasadzie wiele bloków Get.

Pobieranie pojedynczego produktu z maszyny wirtualnej

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

Pobieranie wielu elementów z maszyny wirtualnej

W przykładzie poniżej przyjmijmy, że kluczowa jest maszyna wirtualna z podanymi niżej kluczami i wartościami. Oprócz magazynu najpopularniejszych filmów wszech czasów, KVM przechowuje również imię i nazwisko reżysera wszystkich popularnych filmów.

Oto konfiguracja zasad KVM, dzięki której możemy pobrać obecnie najpopularniejszy film i imię i nazwisko 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>

Po wywołaniu serwera proxy interfejsu API Edge tworzy te zmienne, których możesz używać w procesie obsługi serwera proxy interfejsu API:

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

Atrybuty

Tabela poniżej zawiera opis atrybutów elementu <Get>:

<Get assignTo="private.myvar">

Element <InitialEntries>

Wartości wyjściowe w przypadku map par klucz-wartość, które są wypełniane w mapie par klucz-wartość po jej zainicjowaniu. Pamiętaj, aby podać 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 zapiszesz zasadę w interfejsie zarządzania na wdrożonej wersji serwera proxy lub wdrożysz pakiet proxy interfejsu API zawierający zasadę z tym elementem, klucze zostaną automatycznie utworzone w KVM (jako niezaszyfrowane). Jeśli wartości w zasadzie różnią się od wartości w KVM, po wdrożeniu serwera proxy wartości w KVM są zastępowane. Wszystkie nowe pary klucz-wartość zostaną dodane do istniejącej klucza maszyny wirtualnej razem z dotychczasowymi parami.

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

Rozmiar klucza jest ograniczony do 2 KB zarówno w przypadku Edge dla chmury publicznej, jak i Edge dla Private mogła. Wartość KVM jest ograniczona do 2 KB.

Aby utworzyć zaszyfrowaną maszynę wirtualną, 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 w celu utworzenia klucza 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>

Szczegółowe informacje o ustawianiu nazwy klucza znajdziesz w elemencie <Parameter>.

W przypadku Edge dla chmury publicznej rozmiar klucza jest ograniczony do 2 KB. Więcej informacji znajdziesz w artykule o różnicach między interfejsem Edge for Public Cloud API a interfejsem Private Cloud API.

Element <Parametr>

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ł

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

• Zmienna do pobrania w czasie działania 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, ciąg znaków skutecznego klucza to połączenie wartości każdego parametru połączone podwójnym podkreśleniem. Na przykład w powyższym przykładzie, jeśli zmienna apiproxy.name ma wartość „abc1”, skutecznym kluczem jest targeturl__abc1__weight.

Niezależnie od tego, czy pobierasz, aktualizujesz czy usuwasz wpis klucz-wartość, nazwa klucza musi być taka sama jak nazwa klucza na mapie par klucz-wartość. Wskazówki znajdziesz w sekcji Określanie i pobieranie nazw kluczy.

Atrybuty

Tabela poniżej zawiera opis atrybutów elementu <Parameter>:

Element <Put>

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

Aby utworzyć zaszyfrowaną mapę par klucz-wartość, użyj interfejsu API zarządzania kluczami i wartościami map. Możesz też zapoznać się z informacjami w sekcji Tworzenie i edytowanie map wartości kluczy środowiska, co pozwoli Ci utworzyć w interfejsie zaszyfrowane KVM w zakresie środowiska.

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

Atrybuty

Tabela poniżej zawiera opis atrybutów elementu <Put>:

Element <Scope>

Określa granicę ułatwień dostępu na mapach klucz-wartość. Domyślnym zakresem jest environment, co oznacza, że wpisy map są domyślnie wspólne przez wszystkie serwery proxy interfejsu API działające w środowisku (na przykład testowe lub produkcyjne). Jeśli ustawisz zakres na apiproxy, wpisy w mapie par klucz-wartość będą dostępne tylko przez serwer proxy interfejsu API, który zapisuje wartości na mapie.

Pamiętaj, że podczas uzyskiwania dostępu do wpisu o mapie lub mapie 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, przy pobieraniu jej wartości, wprowadzaniu zmian lub usuwaniu wpisów musisz używać zakresu apiproxy.

<Scope>environment</Scope>

Element <Value>

Określa wartość klucza. Możesz podać wartość jako ciąg literału lub za pomocą atrybutu ref jako zmienną do pobierania 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ć wiele elementów <Value>, aby określić wieloczęściową wartość. Wartości są łączone w czasie działania.

W tym przykładzie do KVM zostały dodane 2 klucze:

• Klucz k1 o wartościach v1,v2
• Klucz k2 o wartościach 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 poniższym przykładzie tworzony jest 1 klucz z 2 wartościami. Załóżmy, że nazwa organizacji to foo_org, nazwa serwera proxy interfejsu API to bar, a środowisko to test:

• Klucz foo_org o wartościach bar,test

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

Atrybuty

Tabela poniżej zawiera opis atrybutów elementu <Value>:

Informacje o błędach

Błędy zwracane z zasad Edge mają spójny format opisany w Informacjach na temat 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ść (w języku angielskim).

Magazyn mapy par klucz-wartość zapewnia prosty mechanizm trwałości danych sformatowanych jako pary klucz/wartość. Możesz uzyskać do nich dostęp w czasie działania 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 w mapie par klucz-wartość. Mapa par klucz-wartość może zawierać wiele wpisów.

Oto przykład użycia map klucz-wartość. Załóżmy, że chcesz 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 plik 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 w celu wymuszania umieszczania adresów IP na liście dozwolonych lub odrzuconych, aby dynamicznie wybierać docelowy adres backendu itp. Zwykle zasada KeyValueMapOperations służy do przechowywania lub pobierania długotrwałych informacji, których należy używać ponownie w wielu transakcjach żądań i odpowiedzi.

Mapami klucz-wartość można manipulować za pomocą zasady KeyValueMapOperations lub bezpośrednio przez interfejs Apigee Edge Management API. Więcej informacji o interfejsie API map klucz-wartość organizacji znajdziesz w dokumentacji interfejsu Management API. Za pomocą interfejsu API możesz na przykład przesyłać duże zbiory danych do magazynu par klucz-wartość lub tworzyć skrypty do zarządzania wpisami z mapami par klucz-wartość. Zanim uzyskasz dostęp do mapy 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 podać wartość literałową (gdzie wartość znajduje się między tagiem otwierającym i zamykającym) lub użyć atrybutu ref, aby określić nazwę zmiennej, której wartość należy używać w czasie działania.

Warto wspomnieć o elemencie Parametr, ponieważ określa on nazwę utworzonego klucza oraz nazwę klucza, który chcesz pobrać lub usunąć. Poniżej przedstawiliśmy 2 przykłady. Pierwszy określa dosłownie nazwę klucza, a drugi – nazwę klucza za pomocą zmiennej. Załóżmy, że do tworzenia kluczy w KVM:

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

W pierwszej instancji wartość literałowa „key_name_literal” jest przechowywana w KVM jako nazwa klucza. W drugim instancji każda wartość znajdująca się w key.name.variable staje się nazwą klucza w KVM. Jeśli np. key.name.variable zawiera wartość foo, klucz będzie miał nazwę „foo”.

Jeśli chcesz pobrać klucz i wartość klucza za pomocą operacji GET (lub usunąć za pomocą operacji DELETE), ustawienie <Parametr> musi być zgodne z nazwą klucza w KVM. Jeśli na przykład nazwa klucza w KVM to „foo”, możesz podać literał za pomocą <Parameter>foo</Parameter> lub określić 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