Praca z mapami klucz-wartość

Wyświetlasz dokumentację Apigee Edge.
Zapoznaj się z dokumentacją Apigee X. info

Czasami chcesz przechowywać dane, aby można było je pobrać w czasie działania – dane, które nie wygasają i nie powinny być na stałe zakodowane w logice proxy interfejsu API. Do tego celu idealnie nadają się mapy klucz-wartość (KVM). KVM to niestandardowa kolekcja par klucz/wartość typu String, która może być zaszyfrowana lub nie. Poniżej przedstawiamy dwa przykłady:

Więcej informacji o innych typach trwałości znajdziesz w artykule Dodawanie buforowania i trwałości.

Scenariusze KVM

Oto kilka sytuacji, w których przełączniki KVM są przydatne:

  • Masz serwer proxy interfejsu API, który musi wywoływać jeden adres URL docelowy (lub wywołanie usługi) w środowisku testowym i inny adres URL docelowy w środowisku produkcyjnym. Zamiast na stałe kodować adresy URL w serwerze proxy, możesz sprawić, że serwer proxy będzie wykrywać środowisko, w którym działa, wykonywać powiązaną zasadę operacji na mapie par klucz-wartość i pobierać prawidłowy docelowy adres URL z jednej z utworzonych przez Ciebie map par klucz-wartość. Jeśli później zmieni się jeden z Twoich celów lub oba, po prostu zaktualizuj mapowania kluczy wartości nowymi adresami URL. Serwer proxy pobierze nowe wartości i nie będzie wymagać ponownego wdrożenia.
  • Chcesz przechowywać dane logowania, klucze prywatne lub tokeny, np. tokeny do usług zewnętrznych, dane logowania wymagane do generowania tokenów OAuth lub klucze prywatne używane w wywołaniach Java lub JavaScript do szyfrowania lub podpisywania tokenów sieciowych JSON (JWT). Zamiast przekazywać dane logowania, klucze lub tokeny w żądaniu albo kodować je na stałe w logice serwera proxy, możesz przechowywać je w mapie klucz-wartość (zawsze zaszyfrowanej) i dynamicznie pobierać w wywołaniach do miejsc docelowych, które ich wymagają.

Odkryjesz też inne sytuacje, w których przechowywanie par klucz/wartość w postaci ciągów znaków jest przydatne. Ogólnie rzecz biorąc, warto używać przełączników KVM, gdy:

  • Określone miejsca w kodzie wymagają różnych wartości w czasie działania programu.
  • Dane wrażliwe muszą być przekazywane bez zakodowania na stałe.
  • Chcesz przechowywać wartości, które nie wygasają, jak w przypadku pamięci podręcznej.

KVM mają zakres

Zakres oznacza „gdzie jest dostępny KVM”. Mapy kluczy mogą być tworzone w tych zakresach: organization, environment i apiproxy.

Jeśli na przykład tylko jeden serwer proxy interfejsu API wymaga danych w mapie klucz-wartość, możesz utworzyć mapę klucz-wartość w zakresie apiproxy, w którym tylko ten serwer proxy interfejsu API będzie miał dostęp do danych.

Możesz też chcieć, aby wszystkie serwery proxy interfejsu API w środowisku testowym miały dostęp do mapy klucz-wartość. W takim przypadku utwórz mapę klucz-wartość w zakresie środowiska. Serwery proxy wdrożone w środowisku „prod” nie mają dostępu do maszyn KVM w zakresie środowiska „test”. Jeśli chcesz, aby te same klucze KVM były dostępne w środowisku produkcyjnym, utwórz równoległy klucz KVM ograniczony do środowiska „prod”.

Jeśli chcesz, aby wszystkie serwery proxy we wszystkich środowiskach miały dostęp do tej samej mapy klucz-wartość, utwórz ją w zakresie organization.

Informacje o zaszyfrowanych przełącznikach KVM

Zaszyfrowane mapy klucz-wartość są szyfrowane za pomocą klucza szyfrującego AES-128 wygenerowanego przez Apigee. Klucz używany do szyfrowania mapy klucz-wartość jest przechowywany w zakresie mapy klucz-wartość. Na przykład w organizacji wszystkie zaszyfrowane maszyny wirtualne KVM utworzone w zakresie środowiska są tworzone przy użyciu tego samego klucza w zakresie środowiska.

Edge obsługuje wyświetlanie zaszyfrowanych wartości w następujący sposób: (Informacje o tworzeniu zaszyfrowanych map klucz-wartość znajdziesz w artykule Zarządzanie mapami klucz-wartość i korzystanie z nich).

Interfejs Edge

Zaszyfrowane mapy klucz-wartość wyświetlają w interfejsie wartości zamaskowane gwiazdkami (*****). Przykład:

interfejs API zarządzania Google Analytics

W interfejsie Management API zaszyfrowane wartości są zwracane w postaci zamaskowanej. Poniżej znajdziesz przykładową odpowiedź interfejsu API zarządzania na wywołanie Get encrypted KVM:

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}

Śledzenie i debugowanie

Gdy używasz zasad operacji na mapie wartości klucza do pobierania zaszyfrowanych wartości KVM, podajesz nazwę zmiennej, w której ma być przechowywana wartość. Aby uzyskać zaszyfrowaną wartość, musisz dodać prefiks „private.” do nazwy zmiennej, co zapobiega wyświetlaniu kluczy i wartości KVM w sesjach śledzenia i debugowania.

Limity

W organizacjach, w których włączono usługi trwałości podstawowej (CPS):

  • W nazwie lub identyfikatorze KVM rozróżniana jest wielkość liter.
  • Rozmiar klucza jest ograniczony do 2 KB.
  • Rozmiar wartości jest ograniczony do 10 KB.

W przypadku Apigee Edge for Private Cloud rozmiar każdej mapy wartości klucza nie powinien przekraczać 15 MB (jest to łączny rozmiar kluczy i wartości). Jeśli przekroczysz ten limit, Apigee Edge for Private Cloud zwróci błąd. Aby określić rozmiar maszyn KVM, możesz użyć polecenia nodetool cfstats.

Większe przełączniki KVM mogą obniżać wydajność. W rezultacie duże, monolityczne maszyny KVM należy podzielić na mniejsze, aby zwiększyć wydajność.

Zarządzanie przełącznikami KVM i korzystanie z nich

KVM możesz tworzyć, zarządzać nimi i używać ich na wiele sposobów. W tej sekcji opisujemy różne opcje tworzenia, a następnie pobierania zarówno zaszyfrowanych, jak i niezaszyfrowanych maszyn wirtualnych KVM.

Tworzenie i aktualizowanie map kluczy wartości

Mapy kluczy wartości możesz tworzyć i aktualizować na te sposoby:

  • Polityka operacji na mapie par klucz-wartość (bez szyfrowania)

    Do tworzenia i aktualizowania map klucz-wartość w czasie działania przez serwery proxy interfejsu API używaj zasady operacji na mapach klucz-wartość. (W zasadach podajesz nazwę mapy kluczy w atrybucie mapIdentifier elementu nadrzędnego).

    Element <InitialEntries> umożliwia utworzenie i wypełnienie podstawowego zestawu wpisów w nowej mapie klucz-wartość natychmiast po zapisaniu zasad w interfejsie lub wdrożeniu serwera proxy interfejsu API (jeśli został on opracowany offline). Jeśli wartości w zasadach ulegną zmianie, dotychczasowe wartości zostaną zastąpione. Wszystkie nowe klucze i wartości są dodawane do istniejącego KVM wraz z dotychczasowymi kluczami i wartościami.

    Element <Put> tworzy nową parę klucz-wartość, jeśli jeszcze nie istnieje, i tworzy klucz z co najmniej 1 wartością. Jeśli KVM już istnieje, klucze i wartości są dodawane (lub aktualizowane, jeśli klucz już istnieje). W zasadach KVM możesz używać wielu elementów <Put>.

  • Management API

    Interfejs Management API służy do pracy z mapami wartości klucza jako administrator, a nie w czasie działania w proxy interfejsu API. Możesz na przykład mieć wewnętrzny skrypt, który używa interfejsu Management API do usuwania i ponownego tworzenia map klucz-wartość w środowisku testowym. Możesz też zresetować wartość klucza na mapie klucz-wartość, aby wszystkie serwery proxy mogły ją pobrać. (Aby manipulować mapami klucz-wartość w czasie działania, użyj w swoich serwerach proxy zasad operacji na mapach klucz-wartość).

    Interfejs API do zarządzania mapami klucz-wartość umożliwia tworzenie, aktualizowanie i usuwanie zaszyfrowanych map klucz-wartość oraz kluczy i wartości we wszystkich zakresach (organizacja, środowisko i apiproxy).

    Aby utworzyć zaszyfrowany KVM za pomocą interfejsu Management API, dodaj "encrypted" : "true" do ładunku JSON. Mapy wartości klucza możesz zaszyfrować tylko podczas ich tworzenia. Nie możesz zaszyfrować istniejącego KVM.

  • Interfejs zarządzania

    W interfejsie zarządzania Edge możesz tworzyć i aktualizować zakresy środowiska KVM, które są jedynym zakresem KVM wyświetlanym w interfejsie. Interfejs zarządzania to dobry sposób na ręczne administrowanie danymi KVM w przypadku serwerów proxy interfejsu API w czasie działania. Więcej informacji znajdziesz w artykule Tworzenie i edytowanie map klucz-wartość w środowisku.

Pobieranie KVM

Zaszyfrowane i niezaszyfrowane mapy klucz-wartość pobiera się w ten sam sposób, z jednym niewielkim wyjątkiem podczas pobierania za pomocą zasad dotyczących operacji na mapach klucz-wartość.

  • Zasady: użyj elementu <Get> w zasadach operacji na mapie par klucz-wartość, aby pobrać zaszyfrowane i niezaszyfrowane mapy par klucz-wartość. Jedyna niewielka różnica polega na pobieraniu zaszyfrowanych wartości za pomocą zasady. W tym przypadku musisz dodać prefiks „private.” do nazwy zmiennej, która będzie zawierać pobraną wartość, zgodnie z opisem w sekcji operacji Get w temacie referencyjnym. Ten prefiks ukrywa wartość w sesjach Śledzenie i debugowanie podczas debugowania serwerów proxy interfejsu API.
  • Management API: do celów administracyjnych możesz używać tworzenia i edytowania map wartości kluczy środowiska, aby pobierać mapy wartości kluczy i klucze/wartości. Jeśli na przykład chcesz utworzyć kopię zapasową map kluczy wartości (KVM) przez pobranie i zapisanie definicji JSON, użyj interfejsu Management API. Pamiętaj jednak, że zaszyfrowane wartości są wyświetlane w odpowiedzi interfejsu API jako *****.
  • Interfejs zarządzania: możesz wyświetlić mapy klucz-wartość w zakresie środowiska w interfejsie zarządzania, klikając Interfejsy API > Konfiguracja środowiska > Mapy klucz-wartość (klasyczna wersja Edge) lub Administracja > Środowiska > Mapy klucz-wartość (nowa wersja Edge).

Przykład KVM

Przykład użycia KVM do wypełniania wartości w adresie URL znajdziesz w artykule Tworzenie szablonu docelowego adresu URL za pomocą KVM według środowiska.