Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje
Czego się nauczysz
Z tego samouczka dowiesz się, jak:
- Utwórz serwer proxy interfejsu API, który wymaga klucza interfejsu API.
- Dodaj usługę API.
- Dodaj dewelopera i zarejestruj aplikację.
- Wywołaj swój interfejs API za pomocą klucza interfejsu API.
Jest to istotne, aby chronić interfejs API przed nieuprawnionym dostępem. Możesz to zrobić na przykład za pomocą kluczy interfejsu API (nazywanych też kluczami publicznymi, kluczami klienta lub kluczami aplikacji).
Gdy aplikacja wysyła żądanie do interfejsu API, musi dostarczyć prawidłowy klucz. W czasie działania zasada Weryfikacja klucza interfejsu API sprawdza, czy dostarczony klucz interfejsu API:
- Jest prawidłowe
- Nie zostało unieważnione
- Pasuje do klucza interfejsu API usługi API, która ujawnia żądane zasoby
Jeśli klucz jest prawidłowy, żądanie jest dozwolone. Jeśli klucz jest nieprawidłowy, żądanie kończy się niepowodzeniem autoryzacji.
W tym samouczku utworzysz serwer proxy interfejsu API, który wymaga prawidłowego klucza interfejsu API, aby uzyskać do niego dostęp.
Czego potrzebujesz
- konto Apigee Edge. Jeśli nie masz jeszcze konta Apigee Edge, możesz się zarejestrować, postępując zgodnie z instrukcjami podanymi w artykule Tworzenie konta Apigee Edge.
- Przeglądarka do wywołania interfejsu API.
- (Nie jest wymagana sekcja z dodatkowymi środkami) – na komputerze zainstalowany jest program cURL, aby wykonywać wywołania interfejsu API z poziomu wiersza poleceń.
Tworzenie serwera proxy interfejsu API
- Otwórz stronę https://apigee.com/edge i zaloguj się.
Przełącz się na odpowiednią organizację, klikając nazwę użytkownika u góry bocznego paska nawigacyjnego, aby wyświetlić menu profilu użytkownika, a następnie wybierz organizację z listy.
-
Kliknij Serwery proxy API na stronie docelowej, aby wyświetlić listę serwerów proxy API.
- Kliknij + Serwer proxy.
- Na stronie Utwórz serwer proxy wybierz Odwrotny serwer proxy (najczęstszy).
- Na stronie Szczegóły serwera proxy skonfiguruj serwer proxy w następujący sposób:
W tym polu wykonaj to Nazwa serwera proxy Wpisz: helloworld_apikey
Ścieżka bazowa projektu Zmień na:
/helloapikey
Ścieżka podstawowa projektu jest częścią adresu URL używanego do wysyłania żądań do serwera proxy interfejsu API.
Uwaga: zalecenia Apigee dotyczące obsługi wersji interfejsu API znajdziesz w sekcji Obsługa wersji w e-booku Web API Design: The Missing Link.
Dotychczasowy interfejs API Wpisz:
http://mocktarget.apigee.net
Określa docelowy adres URL, który Apigee Edge wywołuje w odpowiedzi na żądanie wysyłane do serwera proxy interfejsu API.
Opis Wpisz: hello world protected by API key
- Kliknij Dalej.
- Na stronie Typowe zasady w sekcji Zabezpieczenia: autoryzacja wybierz Klucz interfejsu API i kliknij Dalej. Spowoduje to dodanie 2 zasad do serwera proxy interfejsu API.
- Na stronie Hosty wirtualne wybierz default i secure, a następnie kliknij Dalej. Wybranie opcji domyślne umożliwia wywoływanie interfejsu API za pomocą polecenia
http://
. Wybranie opcji secure umożliwia wywoływanie interfejsu API za pomocąhttps://
. - Na stronie Podsumowanie wybierz testowe środowisko wdrożenia, a następnie kliknij Utwórz i wdróż.
- Zobaczysz potwierdzenie, że nowy serwer proxy interfejsu API i usługa API zostały utworzone, a serwer proxy interfejsu API został wdrożony w środowisku testowym.
- Kliknij Edytuj serwer proxy, aby wyświetlić stronę Przegląd serwera proxy interfejsu API.
Wyświetl zasady
- W edytorze proxy interfejsu API kliknij kartę Develop (Programuj). Zobaczysz, że do przepływu żądań serwera proxy interfejsu API dodano 2 zasady:
- Zweryfikuj klucz interfejsu API: sprawdza wywołanie interfejsu API, aby upewnić się, że jest obecny prawidłowy klucz interfejsu API (wysłany jako parametr zapytania).
- Usuń klucz apikey zapytania: zasada AssignMessage, która usuwa klucz interfejsu API po sprawdzeniu, aby nie był przekazywany i ujawniany niepotrzebnie.
-
Kliknij ikonę zasady weryfikacji klucza interfejsu API w widoku procesu i sprawdź konfigurację XML zasady w dolnym widoku kodu. Element
<APIKey>
informuje zasadę, gdzie powinna szukać klucza interfejsu API podczas wykonywania wywołania. Domyślnie szuka klucza jako parametru zapytania o nazwieapikey
w żądaniu HTTP:<APIKey ref="request.queryparam.apikey" />
Nazwa
apikey
jest dowolna i może być dowolną właściwością zawierającą klucz interfejsu API.
Spróbuj wywołać interfejs API
W tym kroku wykonasz skuteczne wywołanie interfejsu API bezpośrednio do usługi docelowej, a następnie wykonasz nieudane wywołanie do serwera proxy interfejsu API, aby sprawdzić, jak jest chroniony przez zasady.
-
Sukces
W przeglądarce otwórz ten adres. To jest usługa docelowa, do której serwer proxy interfejsu API ma przekazywać żądanie, ale na razie korzystasz z niej bezpośrednio:
http://mocktarget.apigee.net
Powinna wyświetlić się ta odpowiedź:
Hello, Guest!
-
Błąd
Teraz spróbuj wywołać serwer proxy interfejsu API:
http://ORG_NAME-test.apigee.net/helloapikey
Zastąp
ORG_NAME
nazwą organizacji Edge.Bez zasady Zweryfikuj klucz interfejsu API to wywołanie zwróci tę samą odpowiedź co poprzednie. W takim przypadku powinien wyświetlić się jednak taki komunikat o błędzie:
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
co oznacza, że nie został przekazany prawidłowy klucz interfejsu API (jako parametr zapytania).
W następnych krokach dodasz usługę API.
Dodaj usługę API
Aby dodać usługę API za pomocą interfejsu Apigee:
- Wybierz Opublikuj > Usługi API.
- Kliknij + Usługa API.
Podaj Szczegóły produktu w interfejsie API.
Pole Opis Nazwa Wewnętrzna nazwa usługi API. Nie określaj w niej znaków specjalnych.
Uwaga: po utworzeniu usługi API nie można edytować nazwy. Na przykład:helloworld_apikey-Product
.Wyświetlana nazwa Wyświetlana nazwa usługi API. Wyświetlana nazwa jest używana w interfejsie użytkownika i możesz ją w każdej chwili edytować. Jeśli nie podasz wartości, zostanie użyta wartość Nazwa. To pole jest automatycznie wypełniane wartością Nazwa. Możesz edytować i usuwać jego zawartość. Wyświetlana nazwa może zawierać znaki specjalne. Na przykład: helloworld_apikey-Product
.Opis Opis usługi API. Na przykład: Test product for tutorial
.Środowisko Środowiska, do których produkt API ma dostęp. Na przykład test
lubprod
.Dostęp Wybierz Publiczne. Automatyczne zatwierdzanie próśb o dostęp Włącz automatyczne zatwierdzanie żądań kluczy dla tej usługi interfejsu API z dowolnej aplikacji. Limit Zignoruj w tym samouczku. Dozwolone zakresy protokołu OAuth Zignoruj w tym samouczku. - W sekcji zasobów interfejsu API wybierz utworzony przed chwilą serwer proxy interfejsu API. Na przykład:
helloworld_apikey
. - Kliknij Dodaj.
- W sekcji Ścieżki dodaj ścieżkę „/”.
- Kliknij Dodaj.
- Kliknij Zapisz.
W następnych krokach otrzymasz wymagany klucz interfejsu API.
Dodawanie dewelopera i aplikacji do organizacji
Następnie będziemy symulować przepływ pracy programisty rejestrującego się w celu korzystania z Twoich interfejsów API. Deweloper będzie mieć co najmniej jedną aplikację, która będzie wywoływać Twoje interfejsy API, a każda aplikacja otrzyma unikalny klucz interfejsu API. Dzięki temu jako dostawca interfejsu API masz bardziej szczegółową kontrolę nad dostępem do interfejsów API i bardziej szczegółowe raporty o ruchu API według aplikacji.
Tworzenie programisty
Aby utworzyć dewelopera:
- W menu kliknij Opublikuj > Programiści.
- Kliknij + Deweloper.
W oknie nowego programisty wpisz te informacje:
W tym polu Enter Imię Keyser
Nazwisko Soze
Nazwa użytkownika keyser
Napisz e-maila keyser@example.com
- Kliknij Utwórz.
Zarejestruj aplikację
Aby zarejestrować aplikację dewelopera:
- Wybierz Opublikuj > Aplikacje.
- Kliknij + Aplikacja.
W oknie Nowa aplikacja wpisz:
pW tym polu wykonaj to Name (Nazwa) i Display Name (Nazwa wyświetlana) Wpisz: keyser_app
Firma / deweloper Wybierz: Developer
Deweloper Wybierz: Keyser Soze (keyser@example.com)
Callback URL (URL wywołania zwrotnego) i Notes (Uwagi) Zostaw puste - W sekcji Dane logowania z menu Wygaśnięcie wybierz Nigdy. Dane logowania do tej aplikacji nigdy nie wygasną.
- W sekcji Produkty kliknij Dodaj produkt.
- Wybierz helloworld_apikey-Product.
- Kliknij Dodaj.
- Aby zapisać zmiany, kliknij Utwórz powyżej i po prawej stronie sekcji Szczegóły aplikacji.
Uzyskiwanie klucza interfejsu API
Aby uzyskać klucz interfejsu API:
- Na stronie Aplikacje (Publikowanie > Aplikacje) kliknij keyser_app.
Na stronie keyser_app kliknij Pokaż obok pozycji Klucz w sekcji Dane logowania. Zwróć uwagę, że w sekcji Product klucz jest powiązany z helloworld_apikey.
.- Zaznacz i skopiuj Klucz. Użyjesz go w następnym kroku.
Wywoływanie interfejsu API za pomocą klucza
Gdy masz już klucz interfejsu API, możesz go użyć do wywołania serwera proxy interfejsu API. Wpisz w przeglądarce te polecenia. Zastąp nazwę organizacji Edge w ORG_NAME, a klucz interfejsu API w API_KEY. Upewnij się, że w parametrze zapytania nie ma dodatkowych spacji.
http://ORG_NAME-test.apigee.net/helloapikey?apikey=API_KEY
Teraz po wywołaniu serwera proxy interfejsu API powinna pojawić się ta odpowiedź: Hello, Guest!
Gratulacje! Serwer proxy interfejsu API został przez Ciebie utworzony i zabezpieczony przez wymaganie umieszczenia w wywołaniu prawidłowego klucza interfejsu API.
Pamiętaj, że przekazywanie klucza interfejsu API jako parametru zapytania nie jest zalecane. Zamiast tego rozważ przekazanie go w nagłówku HTTP.
Sprawdzona metoda: przekazywanie klucza w nagłówku HTTP
W tym kroku zmodyfikujesz serwer proxy tak, aby szukał klucza interfejsu API w nagłówku o nazwie x-apikey
.
- Edytuj serwer proxy interfejsu API. Wybierz Programowanie > Serwery proxy interfejsu API > helloworld_apikey i przejdź do widoku Develop.
-
Wybierz zasadę Zweryfikuj klucz interfejsu API i zmodyfikuj kod XML zasad, aby wskazać, że zasada ma sprawdzać się w
header
, a nie wqueryparam
:<APIKey ref="request.header.x-apikey"/>
- Zapisz serwer proxy interfejsu API, aby wdrożyć zmianę.
-
Wykonaj poniższe wywołanie interfejsu API za pomocą cURL, by przekazać klucz interfejsu API jako nagłówek o nazwie
x-apikey
. Nie zapomnij zastąpić nazwy organizacji.curl -v -H "x-apikey: API_KEY" http://ORG_NAME-test.apigee.net/helloapikey
Pamiętaj, że aby dokończyć zmianę, musisz też skonfigurować zasadęAssignMessage tak, aby usuwała nagłówek zamiast parametru zapytania. Na przykład:
<Remove> <Headers> <Header name="x-apikey"/> </Headers> </Remove>
Powiązane artykuły
Oto niektóre tematy, które są bezpośrednio związane z tym samouczkiem:
- Zarządzaj usługami API
- Klucze interfejsu API
- Zarejestruj deweloperów aplikacji
- Rejestrowanie aplikacji i zarządzanie kluczami interfejsu API
- Zasada weryfikacji VerAPIKey
- Zasada AssignMessage
Ochrona interfejsów API za pomocą kluczy interfejsu API to tylko część materiału. Ochrona interfejsu API często obejmuje dodatkowe zabezpieczenia, takie jak OAuth.
OAuth to otwarty protokół, który w skrócie wymienia dane logowania (takie jak nazwa użytkownika i hasło) na potrzeby tokenów dostępu. Tokeny dostępu to długie, losowe ciągi, które mogą być przekazywane w obrębie potoku wiadomości, nawet z jednej aplikacji do aplikacji bez naruszania oryginalnych danych logowania. Tokeny dostępu często mają krótki czas życia, więc zawsze są generowane nowe.