Praca z mapami klucz-wartość

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

Czasami chcesz przechowywać dane, które można pobrać w czasie działania. Są to dane ważne, które nie powinny być zakodowane na stałe w logice serwera proxy interfejsu API. Idealnie nadają się do tego mapy klucz-wartość (KVM). KVM to niestandardowy zbiór par ciągów klucz-wartość, który jest zaszyfrowany lub niezaszyfrowany. Poniżej przedstawiamy dwa przykłady:

Informacje o innych typach trwałości znajdziesz w artykule o dodawaniu pamięci podręcznej i trwałości.

Scenariusze KVM

Oto kilka sytuacji, w których zastosowanie ma KVM:

  • Masz serwer proxy interfejsu API, który musi wywoływać jeden docelowy adres URL (lub objaśnienia usługi) w środowisku testowym i drugi w środowisku produkcyjnym. Zamiast umieszczania adresów URL na stałe w kodzie serwera proxy możesz ustawić serwer proxy, aby wykrywał środowisko, w którym się znajduje, uruchamiał powiązaną zasadę operacji mapowania par klucz-wartość i pobierał prawidłowy docelowy adres URL z jednego z utworzonych przez Ciebie KVM. Później, gdy zmieni się co najmniej jeden z tych celów, wystarczy, że zaktualizujesz te KVM, podając nowe adresy URL. Serwer proxy pobierze nowe wartości i nie będzie konieczne ponowne wdrożenie serwera proxy.
  • Chcesz przechowywać dane logowania, klucze prywatne lub tokeny, np. tokeny usług zewnętrznych, dane uwierzytelniające wymagane do wygenerowania tokenów OAuth lub klucze prywatne używane w objaśnieniach Java lub w kodzie JavaScript do szyfrowania lub podpisywania tokenów sieciowych JSON (JWT). Zamiast przekazywać dane logowania, klucze czy tokeny w żądaniu lub kodować je na stałe w logice serwera proxy, możesz je przechowywać w maszynie wirtualnej (zawsze szyfrowanej) i dynamicznie pobierać je w wywołaniach do celów, które ich wymagają.

Poznasz też inne sytuacje, w których przechowywanie par klucz/wartość jest przydatne. Ogólnie 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 kodowania na stałe.
  • Chcesz przechowywać wartości, które nie wygasają, tak jak może to być w pamięci podręcznej.

Podstawowe maszyny wirtualne mają zakres

Zakres oznacza „gdzie jest dostępna wirtualna maszyna wirtualna”. KVM można tworzyć na tych zakresach: organization, environment i apiproxy.

Jeśli na przykład tylko jeden serwer proxy interfejsu API wymaga danych w KVM, możesz utworzyć tę maszynę wirtualną w zakresie apiproxy, gdzie tylko ten serwer proxy interfejsu API ma dostęp do danych.

Możesz też chcieć, aby wszystkie serwery proxy interfejsów API w środowisku testowym miały dostęp do mapy par klucz-wartość. W takim przypadku musisz utworzyć mapę par klucz-wartość w zakresie środowiska. Serwery proxy wdrożone w środowisku „produkcyjnym” nie mają dostępu do maszyn wirtualnych w zakresie środowiska „testowego”. 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 maszyny wirtualnej, utwórz KVM w zakresie organization.

Informacje o zaszyfrowanych KVM

Zaszyfrowane KVM są szyfrowane kluczem szyfrowania AES-128 wygenerowanym przez Apigee. Klucz używany do szyfrowania KVM jest przechowywany w zakresie tej maszyny wirtualnej. Na przykład w organizacji wszystkie zaszyfrowane maszyny wirtualne tworzone przez Ciebie w zakresie środowiska są tworzone przy użyciu tego samego klucza ograniczonego do środowiska.

Edge obsługuje wyświetlanie zaszyfrowanych wartości na kilka sposobów. Więcej informacji na temat tworzenia zaszyfrowanych KVM znajdziesz w artykule Zarządzanie maszynami wirtualnymi i ich używanie.

Interfejs Edge

Zaszyfrowana wartość klucza mapuje wartości zamaskowane w interfejsie użytkownika z gwiazdkami (*****). Na 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 Pobierz zaszyfrowanej KVM:

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

Śledzenie i debugowanie

Gdy używasz zasady operacji mapy klucz-wartość do pobierania zaszyfrowanych wartości KVM, musisz podać nazwę zmiennej do przechowywania wartości. Aby uzyskać zaszyfrowaną wartość, musisz dodać do nazwy zmiennej prefiks „private.”, który zapobiega wyświetlaniu kluczy/wartości KVM w sesjach śledzenia i debugowania.

Ograniczenia

W organizacjach z włączonymi usługami Core Persistence Services (CPS):

  • Wielkość liter w nazwie/identyfikatorze KVM ma znaczenie.
  • Rozmiar klucza jest ograniczony do 2 KB.
  • Rozmiar wartości nie może przekraczać 10 KB.

W przypadku Apigee Edge dla Private Cloud każdy KVM 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 KVM, możesz użyć polecenia nodetool cfstats.

Większe KVM mogą spowodować spadek wydajności. Dlatego duże, monolityczne maszyny wirtualne należy podzielić na mniejsze, aby zwiększyć wydajność.

Zarządzanie wieloma maszynami wirtualnymi i korzystanie z nich

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

Tworzenie i aktualizowanie KVM

Możesz tworzyć i aktualizować KVM na te sposoby:

  • Zasady dotyczące operacji na mapie klucz-wartość (bez szyfrowania)

    Aby utworzyć i zaktualizować KVM w czasie działania przez serwery proxy interfejsu API, użyj zasady operacji mapowania par klucz-wartość. W zasadzie nazwę KVM określasz w atrybucie mapIdentifier elementu nadrzędnego.

    Element <InitialEntries> umożliwia utworzenie i wypełnienie bazowego zestawu wpisów w nowym KVM, gdy tylko zapiszesz zasadę w UI lub wdrożysz serwer proxy interfejsu API (jeśli został utworzony offline). Jeśli wartości w zasadzie ulegną zmianie, obecne wartości zostaną zastąpione. Wszystkie nowe pary klucz-wartość zostaną dodane do dotychczasowej KVM wraz z istniejącymi parami klucz-wartość.

    Element <Put> tworzy nową maszynę wirtualną, jeśli jeszcze nie istnieje, oraz klucz z co najmniej 1 wartością. Jeśli KVM już istnieje, zostaną dodane pary klucz-wartość (lub zaktualizowane, jeśli klucz już istnieje). W zasadzie KVM możesz używać wielu elementów <Put>.

  • Interfejs API zarządzania Google Analytics

    Interfejs API zarządzania służy do pracy z KVM jako administrator, a nie w czasie działania w ramach serwerów proxy interfejsu API. Możesz na przykład mieć wewnętrzny skrypt, który korzysta z interfejsu API zarządzania do usuwania i odtwarzania KVM w środowisku testowym, lub można zresetować wartość klucza w KVM, aby mogły być pobierane przez wszystkie serwery proxy. (Do operacji na maszynach wirtualnych w środowisku wykonawczym użyj zasady operacji mapowania par klucz-wartość na serwerach proxy).

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

    Aby utworzyć zaszyfrowaną KVM za pomocą interfejsu API zarządzania, dodaj "encrypted" : "true" do ładunku JSON. Maszyny wirtualne możesz szyfrować tylko podczas ich tworzenia. Nie możesz zaszyfrować istniejącego KVM.

  • Interfejs zarządzania

    W interfejsie zarządzania urządzeniami brzegowymi możesz tworzyć i aktualizować KVM ograniczone do środowiska, które są jedynym zakresem tych ustawień, który pojawia się w UI. Interfejs zarządzania to dobry sposób na ręczne administrowanie danymi KVM dla serwerów proxy interfejsu API w czasie działania. Więcej informacji znajdziesz w artykule na temat tworzenia i edytowania map klucz-wartość środowiska.

Pobieram KVM

Zaszyfrowane i niezaszyfrowane wartości klucza pobiera się w ten sam sposób z jedną drobną odmianą w przypadku pobierania za pomocą zasady operacji mapowania wartości kluczy.

  • Zasada: użyj elementu <Get> w zasadzie operacji mapowania klucz-wartość, aby pobrać zaszyfrowane i niezaszyfrowane KVM. Jedyna drobna różnica polega na pobieraniu zaszyfrowanych wartości za pomocą zasady. Oznacza to, że do nazwy zmiennej, która będzie zawierać pobraną wartość, należy dodać prefiks „private.”, zgodnie z opisem w sekcji pobierania operacji tematu referencyjnego. Prefiks ukrywa wartość w sesjach śledzenia i debugowania podczas debugowania serwerów proxy interfejsu API.
  • Interfejs API zarządzania Google Analytics: do pobierania maszyn wirtualnych oraz par klucz-wartość możesz użyć tworzenia i edytowania map klucz-wartość środowiska do celów administracyjnych. Jeśli na przykład chcesz tworzyć kopie zapasowe KVM, pobierając i przechowując definicje 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ć lokalne maszyny wirtualne z zakresu środowiska w interfejsie zarządzania, wybierając Interfejsy API > Konfiguracja środowiska > Mapy klucz-wartość (Klasyczna Edge) lub Administracja > Środowiska > Mapy wartości klucza (Nowa Edge).

Przykład KVM

Przykład wykorzystania KVM do wypełniania wartości w adresie URL znajdziesz na stronie https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html.