Tworzenie serwera proxy interfejsów API na podstawie specyfikacji OpenAPI | Apigee Edge

Z tego samouczka dowiesz się, jak utworzyć serwer proxy interfejsu Edge API na podstawie specyfikacji OpenAPI przy użyciu interfejsu zarządzania Apigee Edge. Gdy wywołujesz serwer proxy interfejsu API za pomocą klienta HTTP, takiego jak cURL, serwer proxy interfejsu API wysyła żądanie do próbnej usługi docelowej Apigee.

Informacje o inicjatywie Open API

„Open API Initiative (OAI) koncentruje się na tworzeniu, rozwijaniu i promowaniu formatu opisu interfejsu API neutralnego dla dostawców na podstawie specyfikacji Swagger”. Więcej informacji o inicjatywie Open API Initiative znajdziesz na stronie https://openapis.org.

Specyfikacja OpenAPI używa standardowego formatu do opisania interfejsu API typu REST. Specyfikacja OpenAPI napisana w formacie JSON lub YAML jest czytelna dla komputerów, ale jest łatwa do odczytania i zrozumienia przez człowieka. Specyfikacja opisuje takie elementy interfejsu API, m.in. ścieżkę bazową, ścieżki i czasowniki, nagłówki, parametry zapytań, operacje, typy treści i opisy odpowiedzi. Ponadto do generowania dokumentacji interfejsów API często używana jest specyfikacja OpenAPI.

Informacje o próbnej usłudze docelowej Apigee

Pozorowana usługa docelowa Apigee używana w tym samouczku jest hostowana w Apigee i zwraca proste dane. Nie wymaga ona żadnego klucza API ani tokena dostępu. W rzeczywistości jest ona dostępna w przeglądarce. Aby wypróbować tę funkcję, kliknij ten link:

http://mocktarget.apigee.net

Usługa docelowa zwraca powitanie Hello, guest!

Aby uzyskać informacje o pełnym zestawie interfejsów API obsługiwanych przez usługę próbną, kliknij ten element:

http://mocktarget.apigee.net/help

Czego potrzebujesz

konto Apigee Edge. Jeśli nie masz konta, możesz się zarejestrować, wykonując instrukcje podane na stronie Tworzenie konta Apigee Edge.
Specyfikacja OpenAPI. W tym samouczku będziesz używać mocktarget.yaml specyfikacji OpenAPI, która opisuje pozorowaną usługę docelową Apigee http://mocktarget.apigee.net. Więcej informacji: https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.
cURL zainstalowany na komputerze, aby wykonywać wywołania interfejsu API za pomocą wiersza poleceń lub przeglądarki.

Tworzenie serwera proxy interfejsu API

Edge

Aby utworzyć serwer proxy interfejsu API na podstawie specyfikacji OpenAPI za pomocą interfejsu Edge:

Zaloguj się na stronie https://apigee.com/edge.
Kliknij opcję Proxies API w oknie głównym.
Możesz też wybrać Programowanie > Proxies API na pasku nawigacyjnym po lewej stronie.
Kliknij + Serwer proxy.
W kreatorze tworzenia serwera proxy kliknij Użyj specyfikacji OpenAPI dla szablonu Odwrotny serwer proxy (najczęściej używane).
Kliknij Importuj z adresu URL i podaj te informacje:
- URL specyfikacji OpenAPI: ścieżka do nieprzetworzonej treści na GitHubie zgodna ze specyfikacją OpenAPI w polu URL:
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- Nazwa specyfikacji: nazwa specyfikacji OpenAPI, np. Przykładowy element docelowy.
  Ta nazwa służy do przechowywania specyfikacji OpenAPI w magazynie specyfikacji. Zobacz Zarządzanie specyfikacjami.

Kliknij Importuj.

Zostanie wyświetlona strona Szczegóły w kreatorze tworzenia serwera proxy. Pola są wstępnie wypełniane z użyciem wartości zdefiniowanych w specyfikacji OpenAPI, jak pokazano poniżej

W tabeli poniżej opisujemy wartości domyślne, które są wstępnie wypełniane z wykorzystaniem właściwości ze specyfikacji OpenAPI. Pod tabelą znajduje się fragment specyfikacji OpenAPI ilustrujący używane właściwości.

Pole	Opis	Domyślne
Nazwa	Nazwa serwera proxy interfejsu API. Na przykład: `Mock-Target-API`.	`title` ze specyfikacji OpenAPI ze spacjami zastąpionymi myślnikami
Ścieżka podstawowa	Komponent ścieżki, który jednoznacznie identyfikuje ten serwer proxy interfejsu API w organizacji. Dostępny publicznie URL tego serwera proxy interfejsu API składa się z nazwy organizacji, środowiska, w którym został wdrożony ten serwer proxy interfejsu API, oraz tej ścieżki podstawowej. Na przykład: `http://myorg-test.apigee.net/mock-target-api`	Zawartość pola Nazwa została przekonwertowana na małe litery
Opis	Opis serwera proxy interfejsu API.	`description` ze specyfikacji OpenAPI
Cel (istniejący interfejs API)	Docelowy URL został wywołany w imieniu tego serwera proxy interfejsu API. Można użyć dowolnego adresu URL dostępnego w otwartym internecie. Przykład: `http://mocktarget.apigee.net`	`servers` ze specyfikacji OpenAPI

Poniżej znajdziesz fragment specyfikacji OpenAPI przedstawiający właściwości używane do wstępnego wypełniania pól.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

Zmodyfikuj pole Opis w następujący sposób: API proxy for the Apigee mock target service endpoint.
Kliknij Dalej.
Na stronie Typowe zasady w sekcji Zabezpieczenia: autoryzacja sprawdź, czy jest zaznaczona opcja Przekazywanie (bez autoryzacji) i kliknij Dalej:
Upewnij się, że na stronie Przepływy są wybrane wszystkie operacje.
Wskazówka: przepływy warunkowe są generowane automatycznie na podstawie operacji zdefiniowanych w obiekcie paths w specyfikacji OpenAPI. Przepływy warunkowe informują rozszerzenie „W takim przypadku wykonaj tę logikę”. Jeśli na przykład wywołanie interfejsu API jest żądaniem GET dla zasobu /xml (warunek), przekształć odpowiedź na JSON (za pomocą zasady dołączonej do przepływu warunkowego). W każdej transakcji jest wykonywany tylko jeden proces – pierwszy przepływ, którego warunek przyjmuje wartość prawda.
Kliknij Dalej.
Na stronie Hosty wirtualne wybierz Domyślne i Bezpieczne, a następnie kliknij Dalej.
Na stronie Podsumowanie w sekcji Wdrożenie opcjonalne wybierz środowisko Testowe i kliknij Utwórz i wdróż:

Apigee utworzy nowy serwer proxy interfejsu API i wdroży go w środowisku testowym:
Kliknij Edytuj serwer proxy, aby wyświetlić stronę Przegląd dla serwera proxy interfejsu API.

Klasyczna wersja Edge (Private Cloud)

Aby utworzyć serwer proxy interfejsu API na podstawie specyfikacji OpenAPI za pomocą klasycznego interfejsu użytkownika Edge:

Zaloguj się na stronie https://apigee.com/edge.
Kliknij opcję Proxies API w oknie głównym.
Możesz też wybrać Programowanie > Proxies API na pasku nawigacyjnym po lewej stronie.
Kliknij + Serwer proxy.
W kreatorze tworzenia serwera proxy wybierz Odwrotny serwer proxy (najczęstszy) i kliknij Użyj OpenAPI.
Kliknij Import z URL (Importuj z adresu URL), wpisz nazwę specyfikacji OpenAPI, a w polu URL wpisz ścieżkę do nieprzetworzonej treści strony na GitHubie, aby wyświetlić specyfikację OpenAPI:

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
Kliknij Wybierz.

Kliknij Dalej.

Zostanie wyświetlona strona Szczegóły w kreatorze tworzenia serwera proxy. Pola są wstępnie wypełniane z użyciem wartości zdefiniowanych w specyfikacji OpenAPI, jak pokazano na poniższej ilustracji.

W tabeli poniżej opisujemy wartości domyślne, które są wstępnie wypełniane z wykorzystaniem właściwości ze specyfikacji OpenAPI. Pod tabelą znajduje się fragment specyfikacji OpenAPI ilustrujący używane właściwości.

Pole	Opis	Domyślne
Nazwa serwera proxy	Nazwa serwera proxy interfejsu API. Na przykład: `Mock-Target-API`.	`title` ze specyfikacji OpenAPI ze spacjami zastąpionymi myślnikami
Ścieżka podstawowa serwera proxy	Komponent ścieżki, który jednoznacznie identyfikuje ten serwer proxy interfejsu API w organizacji. Dostępny publicznie URL tego serwera proxy interfejsu API składa się z nazwy organizacji, środowiska, w którym został wdrożony ten serwer proxy interfejsu API, oraz tej ścieżki podstawowej. Na przykład: `http://myorg-test.apigee.net/mock-target-api`	Zawartość pola Nazwa została przekonwertowana na małe litery
Dotychczasowy interfejs API	Docelowy URL został wywołany w imieniu tego serwera proxy interfejsu API. Można użyć dowolnego adresu URL dostępnego w otwartym internecie. Przykład: `http://mocktarget.apigee.net`	`servers` ze specyfikacji OpenAPI
Opis	Opis serwera proxy interfejsu API.	`description` ze specyfikacji OpenAPI

Poniżej znajdziesz fragment specyfikacji OpenAPI przedstawiający właściwości używane do wstępnego wypełniania pól.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

Zmodyfikuj pole Opis w następujący sposób: API proxy for the Apigee mock target service endpoint.
Kliknij Dalej.
Upewnij się, że na stronie Przepływy są wybrane wszystkie operacje.
Wskazówka: przepływy warunkowe są generowane automatycznie na podstawie operacji zdefiniowanych w obiekcie paths w specyfikacji OpenAPI. Przepływy warunkowe informują rozszerzenie „W takim przypadku wykonaj tę logikę”. Jeśli na przykład wywołanie interfejsu API jest żądaniem GET dla zasobu /xml (warunek), przekształć odpowiedź na JSON (za pomocą zasady dołączonej do przepływu warunkowego). W każdej transakcji jest wykonywany tylko jeden proces – pierwszy przepływ, którego warunek przyjmuje wartość prawda.
Kliknij Dalej.
Na stronie Zabezpieczenia wybierz Przekazywanie (brak) i kliknij Dalej.
Na stronie Virtual Hosts (Hosty wirtualne) sprawdź, czy są wybrane wszystkie hosty wirtualne, i kliknij Dalej.
Na stronie kompilacji wybierz środowisko testowe, a następnie kliknij Skompiluj i wdróż.
Na stronie Podsumowanie zobaczysz potwierdzenie, że nowy serwer proxy interfejsu API został utworzony i wdrożony w środowisku testowym.
Kliknij Mock-Target-API (Mock-Target-API), aby wyświetlić stronę Przegląd dla serwera proxy interfejsu API.

Gratulacje! Udało Ci się utworzyć serwer proxy interfejsu API na podstawie specyfikacji OpenAPI. Następnie przetestuj tę funkcję, aby zobaczyć, jak działa.

Testowanie serwera proxy interfejsu API

Interfejs API Mock-Target-API możesz przetestować za pomocą cURL lub przeglądarki.

W oknie terminala uruchom podane niżej polecenie cURL. Zastąp w adresie URL nazwę organizacji.

curl http://<org_name>-test.apigee.net/mock-target-api

Odpowiedź

Powinna pojawić się taka odpowiedź:

Hello, Guest!

Doskonale! Udało Ci się utworzyć prosty serwer proxy interfejsu API na podstawie specyfikacji OpenAPI i go przetestować.

Dodaj plik XML do zasady JSON

Następnie dodaj zasadę XML do procesu warunkowego Wyświetl odpowiedź XML, który został wygenerowany automatycznie podczas tworzenia serwera proxy interfejsu API na podstawie specyfikacji OpenAPI. Zasada konwertuje odpowiedź XML środowiska docelowego na odpowiedź JSON.

Najpierw wywołaj interfejs API, aby porównać wyniki z wynikami otrzymanymi po dodaniu zasady. W oknie terminala wykonaj poniższe polecenie cURL. Wywołujesz zasób /xml usługi docelowej, który natywnie zwraca prosty blok kodu XML. Zastąp w adresie URL nazwę organizacji.

curl http://<org_name>-test.apigee.net/mock-target-api/xml

Odpowiedź

Powinna pojawić się taka odpowiedź:

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

Teraz wypróbujmy działanie powodujące konwersję odpowiedzi XML na format JSON. Dodaj zasadę XML do pliku JSON do procesu warunkowego wyświetlania odpowiedzi XML na serwerze proxy interfejsu API.

Kliknij kartę Develop (Programowanie) w prawym górnym rogu strony Podglądu interfejsu API Edge w interfejsie Edge.
W panelu nawigacji po lewej stronie, w sekcji Punkty końcowe serwera proxy > Domyślnie, kliknij przepływ warunkowy Wyświetl odpowiedź XML.
Kliknij dolny przycisk +Krok obok odpowiedzi dotyczącej przepływu.

Otworzy się okno Dodaj krok, w którym znajdziesz listę wszystkich zasad, które można dodać, pogrupowaną według kategorii.
Przewiń do kategorii Zapośredniczenie i wybierz XML to JSON.
Zachowaj wartości domyślne w polach Nazwa wyświetlana i Nazwa.
Kliknij Dodaj. Zasada XML na JSON jest stosowana do odpowiedzi.
Kliknij Zapisz.

Po dodaniu zasady ponownie wywołaj interfejs API, używając narzędzia cURL. Zwróć uwagę, że nadal wywołujesz ten sam zasób /xml. Usługa docelowa nadal zwraca swój blok kodu XML, ale teraz zasada w serwerze proxy interfejsu API konwertuje odpowiedź na format JSON. Wywołaj to:

curl http://<org_name>-test.apigee.net/mock-target-api/xml

Pamiętaj, że odpowiedź XML jest konwertowana na format JSON:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

Gratulacje! Udało Ci się przetestować wykonanie zasady dodanej do przepływu warunkowego.