Praca z mapami klucz-wartość

Wyświetlasz dokumentację Apigee Edge.
Przejdź do dokumentacji Apigee X. info

Czasami trzeba przechowywać dane, aby można było je pobrać w czasie działania. Są to dane, które nie wygasają i nie powinny być zakodowane na stałe w logice serwera proxy interfejsu API. Mapy klucz-wartość (KVM) są do tego idealne. KVM to niestandardowy zbiór par klucz-wartość typu String, który może być zaszyfrowany lub niezaszyfrowany. Poniżej przedstawiamy 2 przykłady:

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

Scenariusze użycia KVM

Oto kilka sytuacji, w których KVM mogą się przydać:

  • Masz serwer proxy interfejsu API, który musi wywoływać jeden docelowy adres URL (lub wywołanie usługi) w środowisku testowym i inny docelowy adres URL w środowisku produkcyjnym. Zamiast zakodować na stałe adresy URL w serwerze proxy, możesz skonfigurować serwer proxy tak, aby wykrywał, w jakim środowisku się znajduje, wykonywał powiązaną zasadę operacji na mapach klucz-wartość i pobierał prawidłowy docelowy adres URL z jednej z utworzonych map KVM. Jeśli później jeden lub oba cele ulegną zmianie, wystarczy zaktualizować mapy KVM o nowe adresy URL. Serwer proxy pobierze nowe wartości i nie będzie trzeba ponownie wdrażać serwera proxy.
  • Chcesz przechowywać dane logowania, klucze prywatne lub tokeny, np. tokeny usług zewnętrznych usług, dane logowania wymagane do generowania tokenów OAuth lub klucze prywatne używane w wywołaniach Java Callout lub JavaScript do szyfrowania lub podpisywania tokenów internetowych JSON (JWT). Zamiast przekazywać dane logowania, klucze lub tokeny w żądaniu albo zakodować je na stałe w logice serwera proxy, możesz przechowywać je w mapie KVM (zawsze zaszyfrowanej) i dynamicznie pobierać je w wywołaniach do celów, które ich wymagają.

Odkryjesz inne sytuacje, w których przechowywanie par klucz-wartość typu String jest przydatne. Ogólnie rzecz biorąc, rozważ użycie KVM, gdy:

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

KVM mają zakres

Zakres oznacza „miejsce, w którym jest dostępna mapa KVM”. Mapy KVM można tworzyć w tych zakresach: organization, environment i apiproxy.

Jeśli na przykład tylko 1 serwer proxy interfejsu API wymaga danych w mapie KVM, możesz utworzyć mapę KVM w zakresie apiproxy , w którym tylko ten serwer proxy interfejsu API może uzyskać 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 map KVM w zakresie środowiska "test". Jeśli chcesz, aby te same klucze KVM były dostępne w środowisku produkcyjnym, utwórz równoległą mapę KVM w zakresie środowiska "prod".

Jeśli chcesz, aby wszystkie serwery proxy we wszystkich środowiskach miały dostęp do tej samej mapy KVM, utwórz mapę KVM w zakresie organization.

Informacje o zaszyfrowanych mapach KVM

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

Edge wyświetla zaszyfrowane wartości w ten sposób. (Więcej informacji o tworzeniu zaszyfrowanych map KVM znajdziesz w artykule Zarządzanie mapami KVM i korzystanie z nich).

Interfejs Edge

W interfejsie zaszyfrowane mapy klucz-wartość wyświetlają wartości zamaskowane gwiazdkami (*****). Przykładowo:

Interfejs API zarządzania Google Analytics

W interfejsie API zarządzania zaszyfrowane wartości są zwracane zamaskowane. 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 zasady operacji na mapach klucz-wartość do pobierania zaszyfrowanych wartości KVM, podajesz nazwę zmiennej, w której ma być przechowywana wartość. Aby uzyskać zaszyfrowaną wartość, musisz dodać do nazwy zmiennej prefiks „private.”, co uniemożliwi wyświetlanie kluczy i wartości KVM w sesjach śledzenia i debugowania.

Limity

W organizacjach, w których włączone są podstawowe usługi trwałości (CPS):

  • W nazwie/identyfikatorze KVM jest rozróżniana wielkość liter.
  • Maksymalny rozmiar klucza to 2 KB.
  • Maksymalny rozmiar wartości to 10 KB.

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

Większe mapy KVM mogą powodować spadek wydajności. Dlatego, aby poprawić wydajność, należy podzielić duże, monolityczne mapy KVM na mniejsze.

Zarządzanie mapami KVM i korzystanie z nich

Mapy KVM możesz tworzyć, zarządzać nimi i używać ich na różne sposoby. W tej sekcji opisujemy różne opcje tworzenia, a następnie pobierania zaszyfrowanych i niezaszyfrowanych map KVM.

Tworzenie i aktualizowanie map KVM

Mapy KVM możesz tworzyć i aktualizować na te sposoby:

  • Zasada operacji na mapach klucz-wartość (bez szyfrowania)

    Aby serwery proxy interfejsu API mogły tworzyć i aktualizować mapy KVM w czasie działania, użyj zasady operacji na mapach klucz-wartość . (W zasadzie podajesz nazwę mapy KVM w atrybucie mapIdentifier elementu nadrzędnego ).

    Element <InitialEntries> umożliwia utworzenie i wypełnienie podstawowego zestawu wpisów w nowej mapie KVM od razu po zapisaniu zasady w interfejsie lub wdrożeniu serwera proxy interfejsu API (jeśli został on opracowany offline). Jeśli wartości w zasadzie ulegną zmianie, dotychczasowe wartości zostaną zastąpione. Wszystkie nowe klucze i wartości są dodawane do istniejącej mapy KVM obok dotychczasowych kluczy i wartości.

    Element <Put> tworzy nową mapę KVM, jeśli jeszcze nie istnieje, oraz klucz z jedną lub kilkoma wartościami. Jeśli mapa KVM już istnieje, klucze i wartości są dodawane (lub aktualizowane, jeśli klucz już istnieje). W zasadzie KVM możesz użyć kilku elementów <Put>.

  • Interfejs API zarządzania Google Analytics

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

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

    Aby utworzyć zaszyfrowaną mapę KVM za pomocą interfejsu API zarządzania, dodaj "encrypted" : "true" do ładunku JSON. Mapy KVM można szyfrować tylko podczas ich tworzenia. Nie można zaszyfrować istniejącej mapy KVM.

  • Interfejs zarządzania

    W interfejsie zarządzania Edge możesz tworzyć i aktualizować mapy KVM w zakresie środowiska, które są jedynym zakresem map 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 map KVM

Zaszyfrowane i niezaszyfrowane mapy klucz-wartość pobierasz w ten sam sposób, z niewielką różnicą podczas pobierania za pomocą zasady operacji na mapach klucz-wartość.

  • Zasada: aby pobrać zaszyfrowane i niezaszyfrowane mapy KVM, użyj elementu <Get> w zasadzie operacji na mapach klucz-wartość. Jedyna niewielka różnica polega na pobieraniu zaszyfrowanych wartości za pomocą zasady. Musisz dodać prefiks "private." do nazwy zmiennej, która będzie zawierać pobraną wartość, jak opisano w sekcji operacji Get artykułu referencyjnego. Ten prefiks ukrywa wartość w sesjach śledzenia i debugowania podczas debugowania serwerów proxy interfejsu API.
  • Interfejs API zarządzania Google Analytics: do celów administracyjnych możesz użyć artykułu Tworzenie i edytowanie map klucz-wartość w środowisku, aby pobrać mapy KVM oraz klucze i wartości. Jeśli na przykład chcesz utworzyć kopię zapasową map KVM, pobierając i przechowując definicje JSON, użyj interfejsu API zarządzania. Pamiętaj jednak, że zaszyfrowane wartości są wyświetlane w odpowiedzi interfejsu API jako *****.
  • Interfejs zarządzania: mapy KVM w zakresie środowiska możesz wyświetlić w interfejsie zarządzania, klikając Interfejsy API > Konfiguracja środowiska > Mapy klucz-wartość (Classic Edge) lub Administracja > Środowiska > Mapy klucz-wartość (New Edge).

Przykład KVM

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