Przewodnik po korzystaniu

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

Jak uzyskać klucz interfejsu API

Poniższy przykład wyjaśnia, jak uzyskać klucz interfejsu API, za pomocą którego można zweryfikować wywołania interfejsu API usługi docelowej przez serwer proxy Apigee dla Envoy.

1. Zaloguj się w Apigee

  1. Otwórz interfejs Apigee w przeglądarce.
  2. Po przejściu do interfejsu wybierz tę samą organizację, która została użyta do skonfigurowania adaptera Apigee dla Envoy.

2. Tworzenie programisty

Możesz w tym celu skorzystać z dotychczasowego dewelopera lub utworzyć nowego w ten sposób:

  1. W bocznym menu nawigacyjnym wybierz Opublikuj > Programiści.
  2. Kliknij + Deweloper.
  3. Wypełnij okno, aby utworzyć nowego dewelopera. Możesz użyć dowolnej nazwy lub adresu e-mail dewelopera.

3. Tworzenie usługi API

Skorzystaj z podanego niżej przykładu tworzenia produktu. Zapoznaj się też z informacjami o konfiguracji usługi przez interfejs API.

  1. W bocznym menu nawigacyjnym wybierz Opublikuj > Usługi API.
  2. Kliknij + Usługa API.
  3. Wypełnij stronę Szczegóły produktu w następujący sposób. Nie klikaj Zapisz, dopóki nie pojawi się taka prośba.
    4. Pole Wartość
    Nazwa httpbin-product
    Wyświetlana nazwa httpbin product
    Środowisko your_environment

    Ustaw jako środowisko używane podczas udostępniania adaptera Apigee dla Envoy za pomocą apigee-remote-service-cli.

    Dostęp Private
    Limit 5 żądań co minutę

    Zobacz też Omówienie limitów.

  4. W sekcji Zdalne cele usługi Apigee kliknij Dodaj zdalny cel usługi Apigee.
  5. W oknie celu usługi zdalnej Apigee dodaj te wartości:
    Atrybut Wartość Opis
    Nazwa elementu docelowego Wpisz nazwę usługi docelowej. np.: httpbin.org Docelowy punkt końcowy, z którym poprzedza serwer proxy Envoy.
    Serwer proxy interfejsu API remote-service Serwer proxy remote-service udostępniony w Apigee podczas instalacji adaptera Envoy.
    Ścieżka Wpisz /resource_path, aby pasował do określonej ścieżki. Na przykład: /httpbin. Ścieżka żądania do dopasowania w docelowym punkcie końcowym. Wywołania serwera proxy interfejsu API powiązane z tą ścieżką będą zgodne z tą usługą API.

    Edge Public or Private Cloud: poniższy zrzut ekranu przedstawia prawidłowo skonfigurowane ustawienia okna docelowego httpbin.org oraz odpowiednią konfigurację Apigee Edge w chmurze publicznej lub prywatnej.

  6. Kliknij Zapisz.

4. Tworzenie aplikacji związanej z programistą

  1. W bocznym menu nawigacyjnym wybierz Opublikuj > Aplikacje.
  2. Kliknij + Aplikacja.
  3. Wypełnij stronę aplikacji dewelopera w ten sposób. Nie zapisuj operacji, dopóki nie pojawi się taka instrukcja.
    4. Nazwa httpbin-app
    Wyświetlana nazwa httpbin app
    Deweloper Wybierz wcześniej utworzonego dewelopera lub dowolnego z nich z listy.
  4. Następnie dodaj do aplikacji 2 usługi:
    1. Najpierw w sekcji Dane logowania kliknij + Dodaj usługę i wybierz skonfigurowaną usługę: httpbin-product.
    2. Następnie dodaj usługę usługa zdalna. Ta usługa została utworzona automatycznie podczas udostępniania Apigee.
  5. Kliknij Utwórz.
  6. W sekcji Dane logowania kliknij Pokaż obok opcji Klucz.
  7. Skopiuj wartość klucza klienta. Ta wartość to klucz interfejsu API, którego będziesz używać do wykonywania wywołań interfejsu API w usłudze httpbin.

Usługi interfejsu API

Usługi interfejsu API to główny punkt kontrolny usługi zdalnej Apigee. Tworząc usługę API i powiązując ją z usługą docelową, tworzysz zasadę, która będzie stosowana do wszystkich żądań skonfigurowanych przez adapter Apigee dla Envoy.

Definicja usługi API

Gdy zdefiniujesz usługę API w Apigee, możesz ustawić liczbę parametrów, które będą używane do oceny żądań:

  • Cel
  • Ścieżka żądania
  • Limit
  • Zakresy protokołu OAuth

Zdalne cele usług

Definicja usługi API będzie miała zastosowanie do żądania, jeśli żądanie pasuje zarówno do powiązania docelowego (np. httpbin.org), jak i do ścieżki żądania (np. /httpbin). Lista potencjalnych celów jest przechowywana jako atrybut w usłudze API.

Domyślnie usługa zdalna Apigee sprawdza specjalny nagłówek :authority (host) Envoy pod kątem listy celów, ale można ją skonfigurować tak, by używała innych nagłówków.

Ścieżka zasobów interfejsu API

Wpisana ścieżka jest dopasowana do następujących reguł:

  • Pojedynczy ukośnik (/) pasuje do dowolnej ścieżki.
  • Funkcja * jest poprawna wszędzie i pasuje w obrębie segmentu (między ukośnikami).
  • ** ma prawidłową wartość na końcu i pasuje do wszystkiego, co znajduje się na końcu wiersza.

Limit

Limit określa liczbę wiadomości z żądaniami, które aplikacja może przesłać do interfejsu API w ciągu godziny, dnia, tygodnia lub miesiąca. Po osiągnięciu limitu przez aplikację kolejne wywołania interfejsu API są odrzucane.

Przypadki użycia limitów

Limity pozwalają na egzekwowanie liczby żądań, które klient może wysłać do usługi w określonym czasie. Limity są często używane do egzekwowania umów biznesowych lub gwarancji jakości usług z deweloperami i partnerami, a nie do operacyjnego zarządzania ruchem. Limit może na przykład służyć do ograniczenia ruchu w bezpłatnej usłudze przy jednoczesnym zapewnieniu pełnego dostępu klientom płacącym.

Limit jest zdefiniowany w usłudze API

Parametry limitu są konfigurowane w usługach API. Podczas tworzenia usługi API na przykład możesz ustawić dozwolony limit, jednostkę czasu i interwał.

Klucze interfejsu API są mapowane z powrotem na usługi API, dlatego przy każdej weryfikacji klucza interfejsu API można zmniejszyć odpowiedni licznik limitu (jeśli w powiązanej usłudze został zdefiniowany limit).

W przeciwieństwie do środowiska wykonawczego Apigee limity podane w definicji usługi są automatycznie egzekwowane przez usługę zdalną Apigee. Jeśli żądanie jest autoryzowane, jest wliczane do dozwolonego limitu.

Gdzie są zachowywane limity

Limity są utrzymywane i sprawdzane lokalnie przez proces usługi zdalnej, a zarządzanie nimi asynchronicznie za pomocą środowiska wykonawczego Apigee. Oznacza to, że limity nie są precyzyjne i prawdopodobnie zostaną przekroczone, jeśli masz więcej niż jedną usługę zdalną, która je utrzymuje. Jeśli połączenie ze środowiskiem wykonawczym Apigee zostanie zakłócone, limit lokalny pozostanie samodzielnym limitem, dopóki nie odzyska on połączenia ze środowiskiem wykonawczym Apigee.

Zakresy OAuth

Jeśli używasz tokenów JWT, możesz ograniczyć tokeny do podzbiorów dozwolonych zakresów OAuth. Zakresy przypisane do wystawionego tokena JWT zostaną sprawdzone pod kątem zakresów usługi API.

Informacje o aplikacjach dla deweloperów

Po skonfigurowaniu usług interfejsu API utwórz aplikację powiązaną z deweloperem. Aplikacja umożliwia klientowi dostęp do powiązanych usług API za pomocą klucza interfejsu API lub tokena JWT.

Korzystanie z uwierzytelniania opartego na JWT

Zamiast używać klucza interfejsu API do wykonywania uwierzytelnionych wywołań serwera proxy interfejsu API, możesz użyć tokena JWT. W tej sekcji dowiesz się, jak używać polecenia apigee-remote-service-cli token do tworzenia, sprawdzania i rotacji tokenów JWT.

Opis

Weryfikacja i uwierzytelnianie JWT jest obsługiwane przez Envoy przy użyciu filtra uwierzytelniania JWT.

Po uwierzytelnieniu filtr Envoy ext-authz wysyła nagłówki żądań i token JWT do apigee-remote-service-envoy. Jest zgodny z deklaracjami api_product_list i scope tokena JWT wobec usług Apigee API, aby autoryzować je względem miejsca docelowego żądania.

Tworzenie tokenów JWT Apigee

Tokeny JWT Apigee można tworzyć za pomocą interfejsu wiersza poleceń:

apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

Możesz też użyć standardowego punktu końcowego tokena OAuth. Przykład zwinięcia:

curl https://org-env.apigee.net/remote-service/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

Korzystanie z tokena JWT

Po otrzymaniu tokena przekaż go do Envoy w nagłówku Authorization. Przykład:

curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

Błąd tokena JWT

Odrzucenie zaproszenia

Jeśli aplikacja Envoy odrzuci token, możesz zobaczyć taki komunikat:

Jwks remote fetch is failed

Jeśli tak, upewnij się, że konfiguracja Envoy zawiera w sekcji remote_jwks prawidłowy identyfikator URI, aby był on osiągalny przez Envoy, oraz że podczas instalowania serwera proxy Apigee zostały prawidłowo ustawione certyfikaty. Powinno być możliwe bezpośrednie wywołanie identyfikatora URI za pomocą wywołania GET i otrzymanie prawidłowej odpowiedzi JSON.

Przykład:

curl https://myorg-eval-test.apigee.net/remote-service/certs

Inne wiadomości od Envoy mogą wyglądać tak:

  • „Listy odbiorców w JWT są niedozwolone”
  • „Wystawca JWT nie został skonfigurowany”

Pochodzą one z wymagań w konfiguracji Envoy, które być może musisz zmienić.

Sprawdzanie tokena

Aby sprawdzić token, możesz użyć interfejsu wiersza poleceń. Przykład

apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

lub 

apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

Debugowanie

Patrz: Błąd prawidłowego klucza interfejsu API.

Logowanie

Poziom rejestrowania możesz dostosować w usłudze $REMOTE_SERVICE_Home/apigee-remote-service-envoy. Logowanie jest wysyłane do systemu stderr.

Element Wymagane Opis
-l, --log-level Prawidłowe poziomy: debugowanie, informacje, ostrzeżenie, błąd. Dostosowuje poziom rejestrowania. Domyślnie: info
-j, --json-log Przekazuje dane wyjściowe logu w postaci rekordów JSON.

Envoy zapewnia logowanie. Więcej informacji znajdziesz, klikając te linki do dokumentacji Envoy:

Korzystanie z sieciowego serwera proxy

Serwer proxy HTTP można wstawić przy użyciu zmiennych środowiskowych HTTP_PROXY i HTTPS_PROXY w środowisku pliku binarnego apigee-remote-service-envoy. Podczas używania zmiennej środowiskowej NO_PROXY można też wykluczać wysyłanie określonych hostów przez serwer proxy.

HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
NO_PROXY=127.0.0.1,localhost

Pamiętaj, że serwer proxy musi być osiągalny z poziomu apigee-remote-service-envoy.

Informacje o danych i statystykach

Punkt końcowy wskaźników Prometheus jest dostępny pod adresem :5001/metrics. Ten numer portu możesz skonfigurować. Zobacz Plik konfiguracji.

Analityka Envoy

Informacje o uzyskiwaniu danych analitycznych serwera proxy Envoy znajdziesz w tych linkach:

Analityka Istio

Informacje o uzyskiwaniu danych analitycznych serwera proxy Envoy znajdziesz w tych linkach:

Statystyki Apigee

Usługa zdalna Apigee dla Envoy wysyła do Apigee statystyki żądań w celu ich przetworzenia. Apigee raportuje te żądania pod nazwą powiązanej usługi API.

Więcej informacji o usłudze Apigee znajdziesz w artykule Omówienie usług Analytics.