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 otwarciu 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.
  4. Pole Wartość
    Nazwa httpbin-product
    Wyświetlana nazwa httpbin product
    Środowisko your_environment

    Ustaw w tym miejscu środowisko używane podczas udostępniania adaptera Apigee dla Envoy.

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

    Zobacz też Limit.

  5. W sekcji Zdalne cele usługi Apigee kliknij Dodaj zdalny cel usługi Apigee.
  6. 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.
    Ścieżka Wpisz ścieżkę zasobu w usłudze, która ma być dopasowywana. Na przykład: /headers. Ś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.
  7. 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.
  5. Następnie dodaj do aplikacji usługę API:
    1. W sekcji Dane logowania kliknij + Dodaj usługę i wybierz skonfigurowaną usługę: httpbin-product.
    2. Kliknij Utwórz.
    3. W sekcji Dane logowania kliknij Pokaż obok opcji Klucz.
    4. 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ż 1 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ń:

    $CLI_HOME/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-token/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

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

    lub

    $CLI_HOME/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 kanałów stdout i 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.

    Obsługa środowiska wielu najemców

    Możesz teraz włączyć adapter, aby umożliwić obsługę wielu środowisk w organizacji Apigee. Ta funkcja pozwala na obsługę wielu środowisk za pomocą jednego adaptera Apigee dla Envoy powiązanego z jedną organizacją Apigee. Przed tą zmianą 1 adapter był zawsze powiązany z jednym środowiskiem Apigee.

    Aby skonfigurować obsługę wielu środowisk, zmień wartość tenant:env_name na * w pliku config.yaml. Na przykład:

    1. Otwórz plik config.yaml w edytorze.
    2. Zmień wartość tenant.env_name na *. Przykład:
      apiVersion: v1
      kind: ConfigMap
      metadata:
        name: apigee-remote-service-envoy
        namespace: apigee
      data:
        config.yaml: |
          tenant:
            remote_service_api: https://myorg-myenv.apigee.net/remote-service
            org_name: apigee-docs-hybrid-a
            env_name: *
            allow_unverified_ssl_cert: true
          analytics:
            collection_interval: 10s
          auth:
            jwt_provider_key: https://myorg-myenv.apigee.net.net/remote-token/token
    3. Zapisz plik.
    4. Zastosuj plik:
      kubectl apply -f $CLI_HOME/config.yaml

    Konfigurując tryb wielu środowisk, musisz też skonfigurować Envoy tak, aby wysyłała do adaptera odpowiednią wartość środowiska. W tym celu należy dodać poniższe metadane w sekcji virtual_hosts:routes pliku envoy-config.yaml. Na przykład:

    1. Wygeneruj plik envoy-config.yaml za pomocą interfejsu wiersza poleceń. Przykład:
      $CLI_HOME/apigee-remote-service-cli samples create \
        -t envoy-1.16 -c ./config.yaml --out myconfigs
    2. Otwórz wygenerowany plik (o nazwie envoy-config.yaml).
    3. Dodaj te metadane w sekcji virtual_host lub routes pliku:
      typed_per_filter_config:
        envoy.filters.http.ext_authz:
          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
          check_settings:
            context_extensions:
              apigee_environment: test

      Poniższy przykład pokazuje konfigurację virtual_host ze zdefiniowanymi wieloma trasami, w których każda trasa kieruje ruch do określonego środowiska:

      filter_chains:
          - filters:
            - name: envoy.filters.network.http_connection_manager
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                stat_prefix: ingress_http
                route_config:
                  virtual_hosts:
                  - name: default
                    domains: "*"
                    routes:
                    - match: { prefix: /test }
                      route:
                        cluster: httpbin
                      typed_per_filter_config:
                        envoy.filters.http.ext_authz:
                          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                          check_settings:
                            context_extensions:
                               apigee_environment: test
                    - match: { prefix: /prod }
                      route:
                        cluster: httpbin
                      typed_per_filter_config:
                        envoy.filters.http.ext_authz:
                          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                          check_settings:
                            context_extensions:
                               apigee_environment: prod
    4. Powtórz ostatni krok, aby w razie potrzeby dodać kolejne środowiska.
    5. Zapisz plik i zastosuj go.

    Konfigurowanie mTLS między adapterem a środowiskem wykonawczym Apigee

    Certyfikaty TLS po stronie klienta możesz podać w sekcji tenant pliku config.yaml adaptera, aby używać mTLS między adapterem a środowiskiem wykonawczym Apigee. Ta zmiana dotyczy wszystkich obsługiwanych platform Apigee. Umożliwia też analizę mTLS dla platformy Apigee Edge dla Private Cloud. Na przykład:

    tenant:
      tls:
        ca_file: path/ca.pem
        cert_file: path/cert.pem
        key_file: path/key.pem
        allow_unverified_ssl_cert: false