Zasada KeyValueMapOperations

Przeglądasz dokumentację Apigee Edge.
Przejdź do Dokumentacja Apigee X. informacje.

Co

Zapewnia 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 po skonfigurowaniu Zasady KeyValueMapOperations, które określają operacje PUT, GET i DELETE. (Co najmniej jedna z te operacje muszą być wykonywane przez zasadę).

Filmy

Aby dowiedzieć się więcej o maszynach wirtualnych (KVM), obejrzyj te 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 obiektu KeyValueMapOperations zasady:

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

<KeyValueMapOperations> atrybuty

Ten 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 znajdziesz atrybuty właściwe dla tagu <KeyValueMapOperations>:

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

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

<Delete> element

Usuwa określoną parę klucz-wartość. Co najmniej jeden z tych elementów (<Get>), Należy użyć wartości <Put> lub <Delete>.

Pamiętaj, aby podać nazwę KVM z atrybutem mapIdentifier w elemencie nadrzędnym. Na przykład:

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

<Entry> element

Wartości wyjściowe w przypadku map klucz-wartość, które są wypełniane w mapie par klucz-wartość, gdy jest ona zainicjowano.

W przypadku Edge dla Cloud Public Cloud 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>

<ExclusiveCache> element

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

<ExpiryTimeInSecs> element

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

Wartość 0 lub -1 albo wykluczenie tego elementu oznacza, że domyślna wartość 300 sekund to . Na przykład:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

KVM to mechanizm długoterminowej trwałości, który przechowuje klucze i wartości w bazie danych NoSQL. Z tego powodu odczyt z KVM w czasie działania może spowolnić serwer proxy. Poprawa wyników Edge ma wbudowany mechanizm buforowania kluczy i wartości KVM w pamięci podczas działania. Ta zasada operacji KVM zawsze odczytuje z pamięci podręcznej w przypadku operacji GET.

Element <ExpiryTimeInSecs> pozwala kontrolować czas trwania par klucz-wartość używane w tej zasadzie, są przechowywane w pamięci podręcznej, zanim zostaną ponownie odświeżone przez KVM. Pamiętaj jednak: Istnieją 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 KVM GET żądane klucze/wartości z maszyny wirtualnej (o nazwie określonej w katalogu głównym mapIdentifier zasady) ) są wczytywane do pamięci podręcznej, gdzie pozostają przy kolejnych operacjach GET do momentu zachodzi taka sytuacja:

• Liczba sekund podana w polu <ExpiryTimeInSecs> wygasa.
  lub
• Operacja PUT w zasadzie KVM powoduje zastąpienie istniejących wartości (co zostało wyjaśnione poniżej).

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

Przykład: przechowywanie w pamięci podręcznej maszyny wirtualnej

1. Operacja GET pobiera wartość „rating”, który dodaje wartość „10” do pamięci podręcznej. <ExpiryTimeInSecs> w przypadku tej zasady ma wartość 60.
2. 30 sekund później zasada GET uruchamia się ponownie i pobiera wartość „10”. z pamięci podręcznej.
3. 5 sekund później zasada PUT aktualizuje wartość „rating”. do „8”, a <ExpiryTimeInSecs> w zasadzie PUT to 20. Pamięć podręczna jest od razu odświeżany z nową wartością, która jest teraz ustawiona na pozostawanie w pamięci podręcznej przez 20 sekund. (Jeśli funkcja PUT gdyby nie wystąpiła, pamięć podręczna pierwotnie zapełniona przez pierwsze żądanie GET wciąż istniała dla innego 30 sekund (pozostałe 60 sekund w porównaniu z oryginalnymi 60 sekundami).
4. 15 sekund później wykonuje się inne żądanie GET i pobiera wartość „8”.

<Get> element

Pobiera wartość określonego klucza. Co najmniej jeden z tych elementów (<Get>), Należy użyć wartości <Put> lub <Delete>.

Pamiętaj, aby podać nazwę KVM z atrybutem mapIdentifier w nadrzędnym.

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

Uzyskiwanie pojedynczego elementu z maszyny wirtualnej

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

Pobieranie wielu elementów z maszyny wirtualnej

W poniższym przykładzie załóżmy, że maszyna wirtualna jest zgodna z poniższymi kluczami i wartościami. Dodatkowo do przechowywania bieżącej listy najpopularniejszych filmów wszech czasów, w sklepach KVM reżysera wszystkich największych filmów.

Oto konfiguracja zasad KVM, za pomocą której możemy pobrać najpopularniejszy film oraz imię i nazwisko jego dyrektora:

<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 , których można używać w procesie serwera proxy interfejsu API:

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

Atrybuty

W tej tabeli opisano atrybuty elementu <Get>:

<Get assignTo="private.myvar">

<InitialEntries> element

Wartości wyjściowe dla map klucz-wartość, które są wypełniane w mapie wartości klucza podczas jej zainicjowania. Pamiętaj, aby podać nazwę KVM z włączonym atrybutem mapIdentifier do elementu nadrzędnego. np.:

<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 zasadę w interfejsie zarządzania we wdrożonej wersji serwera proxy lub wdrożyć pakiet serwera proxy API zawierający zasadę z tym elementem, kluczami są automatycznie tworzone w KVM (w postaci niezaszyfrowanej). Jeśli wartości w zasadach są różne niż wartości w maszynie wirtualnej, wartości w niej są zastępowane po wdrożeniu serwera proxy. Dowolne nowe klucze/wartości są dodawane do istniejącej KVM obok dotychczasowych par.

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

Rozmiar klucza jest ograniczony do 2 KB w przypadku Edge dla chmury publicznej oraz Krawędź dla prywatnego zasobu. Wartość KVM nie może być większa niż 2 KB.

Aby utworzyć szyfrowaną maszynę wirtualną, użyj interfejsu API do zarządzania mapami kluczy i wartości.

<Key> element

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

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

Aby dowiedzieć się, jak<Parameter> ustaw nazwę klucza.

W przypadku Edge dla Cloud Public Cloud rozmiar klucza jest ograniczony do 2 KB. Więcej informacji znajdziesz w sekcji Różnice między interfejsem Edge for Public Cloud API a interfejsem Private Cloud API.

<Parameter> element

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

Nazwę możesz podać w ten sposób:

• Ciąg literału

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

• Zmienna, która ma być pobierana w czasie działania przy użyciu atrybutu ref

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

• kombinacji 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 Parametr, skutecznym ciągiem znaków jest konkatenacji wartości każdego parametru połączonych podwójnym podkreśleniem. Na przykład w polu powyższego przykładu, jeśli zmienna apiproxy.name ma wartość „abc1”, to będzie tym kluczem: targeturl__abc1__weight.

Niezależnie od tego, czy pobierasz, aktualizujesz czy usuwasz wpis w parze klucz-wartość, nazwa klucza musi pasować do i nazwy klucza w mapie par klucz-wartość. Patrz sekcja Określanie i pobierania nazw kluczy na potrzeby wytycznych.

Atrybuty

W tej tabeli opisano atrybuty elementu <Parameter>:

<Put> element

Zapisuje parę klucz-wartość w mapie wartości klucza niezależnie od tego, czy mapa jest szyfrowana, niezaszyfrowane. Jeśli mapa par klucz-wartość określona w atrybucie mapIdentifier w atrybucie element nadrzędny nie istnieje, mapa jest tworzona automatycznie (w postaci niezaszyfrowanej). Jeśli wartość klucza Jeśli mapa już istnieje, zostanie do niej dodany klucz/wartość.

Aby utworzyć zaszyfrowaną mapę wartości klucza, użyj funkcji interfejs API do zarządzania mapami kluczy/wartości, lub zapoznaj się z artykułem Tworzenie i edytowanie map klucz-wartość środowiska. , aby tworzyć zaszyfrowane maszyny wirtualne o zakresie na poziomie środowiska w interfejsie użytkownika.

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

Atrybuty

W tej tabeli opisano atrybuty elementu <Put>:

<Scope> element

Określa granicę ułatwień dostępu dla map klucz-wartość. Domyślny zakres to environment, co oznacza, że domyślnie wpisy map są współużytkowane przez wszystkie serwery proxy interfejsów API działające w środowisku (na przykład testowym lub produkcyjnym). Jeśli ustawisz zakres na apiproxy, wpisy w mapie par klucz-wartość są dostępne tylko dla serwera proxy interfejsu API, który zapisuje wartości na mapie.

Pamiętaj, że gdy uzyskujesz dostęp do mapy lub wpisu mapy, musisz podać taką samą wartość zakresu, jaka została przez Ciebie użyta od momentu utworzenia mapy. Jeśli na przykład mapa została utworzona z zakresem apiproxy, przy pobieraniu jego wartości musisz używać zakresu apiproxy, wprowadzanie zmian lub usuwanie wpisów.

<Scope>environment</Scope>

<Value> element

Określa wartość klucza. Wartość możesz określić w postaci ciągu literału lub za pomocą funkcji atrybutu ref jako zmiennej pobieranej 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ż uwzględnić wiele elementów <Value>, aby określić wieloczęściowy . Wartości są łączone w czasie działania.

W tym przykładzie do KVM zostaną dodane 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 przykładzie poniżej tworzony jest 1 klucz z 2 wartościami. Załóżmy, że organizacja nazwa to foo_org, nazwa serwera 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 tej tabeli opisano atrybuty elementu <Value>:

Informacje o błędzie

Błędy zwracane przez zasady Edge mają spójny format opisany w dokumentacji kodu 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 par klucz-wartość znajdziesz w artykule Korzystanie z map klucz-wartość.

Magazyn map z par klucz-wartość zapewnia prosty mechanizm trwałości dla danych sformatowanych jako par 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 także 127.0.0.1 jest wartością. Każda para klucz-wartość jest przechowywana jako wpis w kluczu map wartości. Mapa klucz-wartość może przechowywać wiele wpisów.

Oto przykład użycia map par klucz-wartość. Załóżmy, że musisz przechowywać listę adresów IP powiązane z różnymi backendami w różnych środowiskach. Możesz utworzyć mapę par klucz-wartość o nazwie ipAddresses, która zawiera z listą par klucz/wartość jako wpisów. 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, aby utworzyć magazyn adresów IP, które mogą być używane przez zasady w czasie działania, aby wymuszać umieszczanie adresów IP na liście dozwolonych lub odrzuconych, aby dynamicznie wybierać cel backendu adresu i tak dalej. Zwykle zasada KeyValueMapOperations jest używana do przechowywania lub pobierania długotrwałe informacje, których trzeba ponownie użyć w wielu transakcjach dotyczących żądań/odpowiedzi.

Mapami klucz-wartość można manipulować za pomocą zasady KeyValueMapOperations lub bezpośrednio za pomocą Interfejs Apigee Edge Management API. Więcej informacji o interfejsie API map klucz-wartość organizacji znajdziesz w dokumentacji interfejsu API do zarządzania. Można używać tego interfejsu API do: Można na przykład przesyłać duże zbiory danych do magazynu par klucz-wartość lub tworzyć skrypty do zarządzania parami klucz-wartość wpisów na mapie. Przed uzyskaniem dostępu do mapy klucz-wartość za pomocą interfejsu API musisz utworzyć mapę klucz-wartość za pomocą Zasada KeyValueMapOperations.

Określanie i pobieranie nazw kluczy

Dzięki elementom <Parameter> i <Value> możesz: określ wartość literału (gdzie znajduje się między tagiem otwierającym a zamykającym) albo użyj wartości w atrybucie ref do określenia nazwy zmiennej, której wartości należy użyć w w środowisku wykonawczym.

Element Parametr zasługuje na specjalną wzmiankę, ponieważ określa nazwę klucza, który oraz nazwa klucza, który chcesz pobrać lub usunąć. Poniżej przedstawiamy 2 przykłady. Pierwszy określa dosłownie nazwę klucza, a drugi – nazwę klucza za pomocą zmiennej. Załóżmy, że do tworzenia kluczy w maszynie wirtualnej KVM używane są:

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

W pierwszej instancji jest to literał „key_name_literal”. jest przechowywany w KVM jako klucz imię i nazwisko. W drugim przypadku dowolna wartość znajdujący się w elemencie key.name.variable staje się jego nazwy w KVM. Jeśli na przykład obiekt key.name.variable zawiera parametr wartość foo, klucz miałby nazwę „foo”.

Gdy chcesz pobrać klucz i ich wartość za pomocą operacji GET (lub usuń ją za pomocą DELETE), parametr <Parametr> musi być zgodne z nazwą klucza w KVM. Dla: Jeśli na przykład nazwa klucza w maszynie wirtualnej to „foo”, możesz określić wartość literału w <Parameter>foo</Parameter> lub określ zmienną, która zawiera dokładne „foo”, na przykład: <Parameter ref="variable.containing.foo"/>.

Powiązane artykuły

• Interfejs API map klucz-wartość organizacji