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

Z tego samouczka dowiesz się, jak utworzyć serwer proxy interfejsu API Edge na podstawie specyfikacji OpenAPI za pomocą interfejsu zarządzania Apigee Edge. Gdy wywołasz serwer proxy interfejsu API za pomocą klienta HTTP, np. cURL, serwer proxy interfejsu API wyśle żądanie do usługi docelowej Apigee.

Informacje o inicjatywie Open API

"Inicjatywa Open API (OAI) koncentruje się na tworzeniu, rozwijaniu i promowaniu niezależnego od dostawcy formatu opisu interfejsu API opartego na specyfikacji Swagger Specyfikacja." Więcej informacji o inicjatywie Open API znajdziesz na stronie https://openapis.org.

Specyfikacja OpenAPI używa standardowego formatu do opisywania interfejsu API RESTful. Specyfikacja OpenAPI, napisana w formacie JSON lub YAML, jest czytelna dla komputera, ale jest też łatwa do odczytania i zrozumienia dla ludzi. Specyfikacja opisuje takie elementy interfejsu API jak ścieżka podstawowa, ścieżki i czasowniki, nagłówki, parametry zapytania, operacje, typy treści, opisy odpowiedzi i inne. Specyfikacja OpenAPI jest też często używana do generowania dokumentacji API.

Informacje o usłudze docelowej Apigee

Usługa docelowa Apigee używana w tym samouczku jest hostowana w Apigee i zwraca proste dane. Nie wymaga klucza interfejsu API ani tokena dostępu. Dostęp do niej można uzyskać w przeglądarce. Wypróbuj, klikając 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ę docelową, kliknij ten link:

http://mocktarget.apigee.net/help

Czego potrzebujesz

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

Tworzenie serwera proxy interfejsu API

Edge

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

Zaloguj się na https://apigee.com/edge.
W głównym oknie kliknij API Proxies (Proxy interfejsów API).
Możesz też wybrać Develop (Tworzenie) > API Proxies (Proxy interfejsów API) na pasku nawigacji po lewej stronie.
Kliknij + Proxy.
W kreatorze Create Proxy (Tworzenie proxy) kliknij Use OpenAPI Spec (Użyj specyfikacji OpenAPI) w przypadku szablonu Reverse proxy (most common) (Odwrotny serwer proxy – najczęstszy).
Kliknij Import from URL (Importuj z adresu URL) i wpisz te informacje:
- Adres URL specyfikacji OpenAPI: ścieżka do nieprzetworzonej treści w GitHubie w przypadku specyfikacji OpenAPI w polu URL:
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- Spec name (Nazwa specyfikacji): nazwa specyfikacji OpenAPI, np. Mock Target.
  Ta nazwa służy do przechowywania specyfikacji OpenAPI w magazynie specyfikacji. Zobacz Zarządzanie specyfikacjami.

Kliknij Import.

Wyświetli się strona z informacjami w kreatorze Create Proxy (Tworzenie proxy). Pola są wstępnie wypełnione wartościami zdefiniowanymi w specyfikacji OpenAPI, jak pokazano poniżej.

W tej tabeli opisujemy wartości domyślne, które są wstępnie wypełniane za pomocą właściwości w specyfikacji OpenAPI. Po tabeli znajduje się fragment specyfikacji OpenAPI ilustrujący używane właściwości.

Pole	Opis	Domyślny
Name (Nazwa)	Nazwa serwera proxy interfejsu API. Na przykład: `Mock-Target-API`.	Właściwość `title` ze specyfikacji OpenAPI, w której spacje zostały zastąpione myślnikami.
Base path (Ścieżka podstawowa)	Składnik ścieżki, który jednoznacznie identyfikuje ten serwer proxy interfejsu API w organizacji. Publiczny adres URL tego serwera proxy interfejsu API składa się z nazwy organizacji, środowiska, w którym jest wdrożony, i tej ścieżki podstawowej. Na przykład: `http://myorg-test.apigee.net/mock-target-api`	Zawartość pola Name (Nazwa) przekonwertowana na małe litery.
Description (Opis)	Opis serwera proxy interfejsu API.	Właściwość `description` ze specyfikacji OpenAPI.
Target (Existing API) (Cel – istniejący interfejs API)	Docelowy adres URL wywoływany w imieniu tego serwera proxy interfejsu API. Można użyć dowolnego adresu URL, który jest dostępny w otwartym internecie. Na przykład: `http://mocktarget.apigee.net`	Właściwość `servers` ze specyfikacji OpenAPI.

Poniżej znajduje się fragment specyfikacji OpenAPI, który pokazuje 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
...

Edytuj pole Description (Opis) w ten sposób: API proxy for the Apigee mock target service endpoint.
Kliknij Next (Dalej).
Na stronie Common policies (Typowe zasady) w sekcji Security: Authorization (Zabezpieczenia: autoryzacja) upewnij się, że wybrana jest opcja Pass through (no authorization) (Przekazywanie – bez autoryzacji), i kliknij Next (Dalej):
Na stronie Flows (Przepływy) upewnij się, że wybrane są wszystkie operacje.
Wskazówka: przepływy warunkowe są generowane automatycznie na podstawie operacji zdefiniowanych w obiekcie paths w specyfikacji OpenAPI. Przepływy warunkowe informują Edge: „Gdy zobaczysz to, wykonaj tę logikę”. Na przykład, gdy wywołanie interfejsu API jest GET na zasobie /xml (warunek), przekształć odpowiedź na JSON (za pomocą zasady dołączonej do przepływu warunkowego). W ramach transakcji wykonywany jest tylko 1 przepływ – pierwszy, którego warunek przyjmuje wartość true.
Kliknij Next (Dalej).
Na stronie Virtual hosts (Hosty wirtualne) wybierz default (domyślny) i secure (bezpieczny), a następnie kliknij Next (Dalej).
Na stronie Summary (Podsumowanie) upewnij się, że w sekcji Optional Deployment (Opcjonalne wdrożenie) wybrane jest środowisko Test (Testowanie), a następnie kliknij Create and deploy (Utwórz i wdróż):

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

Classic Edge (Private Cloud)

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

Zaloguj się na https://apigee.com/edge.
W głównym oknie kliknij API Proxies (Proxy interfejsów API).
Możesz też wybrać Develop (Tworzenie) > API Proxies (Proxy interfejsów API) na pasku nawigacji po lewej stronie.
Kliknij + Proxy.
W kreatorze Create Proxy (Tworzenie proxy) wybierz Reverse proxy (most common) (Odwrotny serwer proxy – najczęstszy) i kliknij Use OpenAPI (Użyj OpenAPI).
Kliknij Import from a URL (Importuj z adresu URL), wpisz nazwę specyfikacji OpenAPI i w polu URL wpisz ścieżkę do nieprzetworzonej treści w GitHubie w przypadku specyfikacji OpenAPI:

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

Kliknij Next (Dalej).

Wyświetli się strona z informacjami w kreatorze Create Proxy (Tworzenie proxy). Pola są wstępnie wypełnione wartościami zdefiniowanymi w specyfikacji OpenAPI, jak pokazano na ilustracji poniżej.

W tej tabeli opisujemy wartości domyślne, które są wstępnie wypełniane za pomocą właściwości w specyfikacji OpenAPI. Po tabeli znajduje się fragment specyfikacji OpenAPI ilustrujący używane właściwości.

Pole	Opis	Domyślny
Proxy Name (Nazwa serwera proxy)	Nazwa serwera proxy interfejsu API. Na przykład: `Mock-Target-API`.	Właściwość `title` ze specyfikacji OpenAPI, w której spacje zostały zastąpione myślnikami.
Proxy Base Path (Podstawowa ścieżka serwera proxy)	Składnik ścieżki, który jednoznacznie identyfikuje ten serwer proxy interfejsu API w organizacji. Publiczny adres URL tego serwera proxy interfejsu API składa się z nazwy organizacji, środowiska, w którym jest wdrożony, i tej ścieżki podstawowej. Na przykład: `http://myorg-test.apigee.net/mock-target-api`	Zawartość pola Name (Nazwa) przekonwertowana na małe litery.
Existing API (Istniejący interfejs API)	Docelowy adres URL wywoływany w imieniu tego serwera proxy interfejsu API. Można użyć dowolnego adresu URL, który jest dostępny w otwartym internecie. Na przykład: `http://mocktarget.apigee.net`	Właściwość `servers` ze specyfikacji OpenAPI.
Description (Opis)	Opis serwera proxy interfejsu API.	Właściwość `description` ze specyfikacji OpenAPI.

Poniżej znajduje się fragment specyfikacji OpenAPI, który pokazuje 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
...

Edytuj pole Description (Opis) w ten sposób: API proxy for the Apigee mock target service endpoint.
Kliknij Next (Dalej).
Na stronie Flows (Przepływy) upewnij się, że wybrane są wszystkie operacje.
Wskazówka: przepływy warunkowe są generowane automatycznie na podstawie operacji zdefiniowanych w obiekcie paths w specyfikacji OpenAPI. Przepływy warunkowe informują Edge: „Gdy zobaczysz to, wykonaj tę logikę”. Na przykład, gdy wywołanie interfejsu API jest GET na zasobie /xml (warunek), przekształć odpowiedź na JSON (za pomocą zasady dołączonej do przepływu warunkowego). W ramach transakcji wykonywany jest tylko 1 przepływ – pierwszy, którego warunek przyjmuje wartość true.
Kliknij Next (Dalej).
Na stronie Security (Zabezpieczenia) jako opcję zabezpieczeń wybierz Pass through (none) (Przekazywanie – brak) i kliknij Next (Dalej).
Na stronie Virtual Hosts (Hosty wirtualne) upewnij się, że wybrane są wszystkie hosty wirtualne, i kliknij Next (Dalej).
Na stronie Build (Kompilacja) upewnij się, że wybrane jest środowisko test (testowanie), a następnie kliknij Build and Deploy (Kompiluj i wdróż).
Na stronie Summary (Podsumowanie) zobaczysz potwierdzenie, że nowy serwer proxy interfejsu API został utworzony pomyślnie i wdrożony w środowisku testowym.
Kliknij Mock-Target-API , aby wyświetlić stronę Overview (Przegląd) serwera proxy interfejsu API.

Gratulacje! Serwer proxy interfejsu API został utworzony na podstawie specyfikacji OpenAPI. Teraz przetestujesz go, aby sprawdzić, jak działa.

Testowanie serwera proxy interfejsu API

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

W oknie terminala uruchom to polecenie cURL. W adresie URL zastąp nazwę organizacji.

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

Odpowiedź

Powinna pojawić się taka odpowiedź:

Hello, Guest!

Doskonale! Utworzono prosty serwer proxy interfejsu API na podstawie specyfikacji OpenAPI i przetestowano go.

Dodawanie zasady XML do JSON

Następnie dodasz zasadę XML do JSON do przepływu warunkowego View XML Response, który został wygenerowany automatycznie podczas tworzenia serwera proxy interfejsu API na podstawie specyfikacji OpenAPI. Zasada przekonwertuje odpowiedź XML usługi docelowej na odpowiedź JSON.

Najpierw wywołaj interfejs API, aby móc porównać wyniki z tymi, które otrzymasz po dodaniu zasady. W oknie terminala wykonaj to polecenie cURL. Wywołujesz zasób /xml usługi docelowej, który natywnie zwraca prosty blok XML. W adresie URL zastąp 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 zróbmy coś, co przekonwertuje odpowiedź XML na JSON. Dodaj zasadę XML do JSON do przepływu warunkowego View XML Response (Wyświetl odpowiedź XML) w serwerze proxy interfejsu API.

W prawym górnym rogu strony Overview (Przegląd) serwera proxy Mock-Target-API w interfejsie Edge kliknij kartę Develop (Tworzenie).
W panelu nawigacji po lewej stronie w sekcji Proxy Endpoints (Punkty końcowe serwera proxy) > default (domyślny) kliknij przepływ warunkowy View XML Response (Wyświetl odpowiedź XML).
Kliknij dolny przycisk +Step odpowiadający Response w przepływie.

Otworzy się okno Add Step (Dodaj krok), w którym wyświetli się podzielona na kategorie lista wszystkich zasad, które możesz dodać.
Przewiń do kategorii Mediation (Mediacja) i wybierz XML to JSON (XML do JSON).
Zachowaj wartości domyślne w polach Display Name i Name.
Kliknij Add (Dodaj). Zasada XML do JSON jest stosowana do odpowiedzi.
Kliknij Save (Zapisz).

Gdy dodasz zasadę, ponownie wywołaj interfejs API za pomocą cURL. Zauważ, że nadal wywołujesz ten sam /xml zasób. Usługa docelowa nadal zwraca swój blok XML, ale teraz zasada w serwerze proxy interfejsu API przekonwertuje odpowiedź na JSON. Wykonaj to wywołanie:

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

Zwróć uwagę, że odpowiedź XML jest przekształcana na JSON:

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

Gratulacje! Pomyślnie przetestowano wykonanie zasady dodanej do przepływu warunkowego.