Tworzenie serwera proxy interfejsów API na podstawie specyfikacji OpenAPI

Oglądasz dokumentację Apigee Edge.
Wyświetl dokumentację Apigee X.

Czego się nauczysz

Z tego samouczka dowiesz się, jak:

  • utworzyć serwer proxy Edge API na podstawie specyfikacji OpenAPI;
  • Wywołaj serwer proxy interfejsu API przy użyciu cURL.
  • Dodaj zasadę do przepływu warunkowego.
  • Przetestuj wywołanie zasady za pomocą cURL.

Z tego samouczka dowiesz się, jak utworzyć serwer proxy Edge API na podstawie specyfikacji OpenAPI za pomocą interfejsu zarządzania Apigee Edge. Po wywołaniu serwera proxy interfejsu API za pomocą klienta HTTP, takiego jak cURL, serwer proxy interfejsu API wysyła żądanie do makiety Apigee.

Informacje o inicjatywie Open API

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

Specyfikacja OpenAPI używa standardowego formatu RESTowego API. Specyfikacja OpenAPI napisana w formacie JSON lub YAML jest czytelna dla komputera, ale zrozumiała dla człowieka. Specyfikacja opisuje takie elementy interfejsu API jako ścieżkę podstawową, ścieżki i czasowniki, nagłówki, parametry zapytania, operacje, typy treści, opisy odpowiedzi itd. Dodatkowo do tworzenia dokumentacji API często używa się specyfikacji OpenAPI.

Informacje o przykładowej usłudze Apigee

Pozorowana usługa Apigee używana w tym samouczku jest hostowana w Apigee i zwraca proste dane. Nie wymaga klucza interfejsu API ani tokena dostępu. Możesz uzyskać do niego dostęp w przeglądarce. Kliknij, aby wypróbować:

http://mocktarget.apigee.net

Usługa docelowa zwraca powitanie Hello, guest!

Aby uzyskać informacje o pełnym zestawie interfejsów API obsługiwanych przez przykładową usługę docelową, kliknij te elementy:

http://mocktarget.apigee.net/help

Czego potrzebujesz

  • Konto Apigee Edge. Jeśli nie masz konta, możesz się zarejestrować, postępując zgodnie z instrukcjami zawartymi w artykule Tworzenie konta Apigee Edge.
  • Specyfikacja OpenAPI. W tym samouczku będziesz używać mocktarget.yamlspecyfikacji OpenAPI opisującej pozorowaną usługę Apigee http://mocktarget.apigee.net. Więcej informacji: https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.
  • cURL zainstalowany na Twoim komputerze, aby wykonywać wywołania interfejsu API z poziomu wiersza poleceń lub przeglądarki.

Tworzenie serwera proxy interfejsu API

Edge

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

  1. Zaloguj się na https://apigee.com/edge.
  2. W głównym oknie kliknij „Protokoły API”.

    Możesz też wybrać Develop (Program) > API Proxies (Serwery interfejsów API) na pasku nawigacyjnym po lewej stronie.

    Kliknij interfejs API interfejsów API na stronie docelowej

  3. Kliknij + Serwer proxy.
    Dodaj serwer proxy interfejsu API
  4. W kreatorze tworzenia proxy kliknij Użyj specyfikacji OpenAPI, aby wyświetlić szablon Odwrotnego serwera proxy (najczęstszy).
    Tworzenie typu serwera proxy
  5. Kliknij Importuj z adresu URL i podaj te informacje:
    • Adres URL specyfikacji OpenAPI: ścieżka do nieprzetworzonej treści z GitHuba dla specyfikacji 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ładowa strona docelowa.

      Ta nazwa służy do przechowywania specyfikacji OpenAPI w magazynie specyfikacji. Zobacz Zarządzanie specyfikacjami.

  6. Kliknij Importuj.

    Pojawi się strona Details (Szczegóły) w kreatorze tworzenia serwera proxy. Pola są wstępnie wypełniane na podstawie wartości zdefiniowanych w specyfikacji OpenAPI, jak pokazano poniżej

    W tabeli poniżej znajdziesz domyślne wartości wstępnie uzupełniane za pomocą właściwości w specyfikacji OpenAPI. Fragment specyfikacji OpenAPI ilustrujący używane właściwości jest widoczny pod tabelą.

    Pole Opis Domyślna
    Nazwa Nazwa serwera proxy interfejsu API. Przykład: Mock-Target-API. Właściwość title ze specyfikacji OpenAPI ze spacjami zastąpionymi myślnikami
    Ścieżka podstawowa Komponent ścieżki jednoznacznie identyfikujący ten serwer proxy interfejsu API w organizacji. Publiczny adres URL tego serwera proxy interfejsów API składa się z nazwy Twojej organizacji, środowiska, w którym ten serwer proxy interfejsu API jest wdrożony, oraz z tej ścieżki podstawowej. Na przykład: http://myorg-test.apigee.net/mock-target-api Treść pola Nazwa została zamieniona na małe litery
    Description Opis serwera proxy interfejsu API. Właściwość description ze specyfikacji OpenAPI
    Kierowanie (istniejący interfejs API) Docelowy URL wywoływany w imieniu tego serwera proxy interfejsu API. Można użyć dowolnego adresu URL, który jest dostępny przez otwarty internet. Na przykład: http://mocktarget.apigee.net Właściwość servers ze specyfikacji OpenAPI

    Poniżej znajdziesz fragment specyfikacji OpenAPI zawierający właściwości służące 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
    ...
    
  7. Edytuj pole Opis w ten sposób: API proxy for the Apigee mock target service endpoint.
  8. Kliknij Dalej.
  9. Na stronie Wspólne zasady w sekcji Zabezpieczenia: autoryzacja wybierz opcję Powodzenie (brak autoryzacji) i kliknij Dalej:

    Przejdź (bez autoryzacji) na stronie z często używanymi zasadami

  10. Na stronie Flows (Procesy) wybierz wszystkie operacje. Tworzenie przepływów proxy
  11. Kliknij Dalej.
  12. Na stronie Hosty wirtualne wybierz domyślne i bezpieczne, a następnie kliknij Dalej.
    Domyślne i bezpieczne wybrane na stronie Wirtualne hosty
  13. Na stronie Podsumowanie w sekcji Opcjonalne wdrożenie wybierz środowisko Testowe i kliknij Utwórz i wdróż:

    Apigee tworzy nowy serwer proxy interfejsu API i wdraża go w środowisku testowym:

  14. Kliknij Edytuj serwer proxy, aby wyświetlić stronę Przegląd informacji o serwerze proxy interfejsu API.
    Podsumowanie serwera proxy interfejsu API pozornego kierowania

Classic Edge (prywatna w chmurze)

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

  1. Zaloguj się na https://apigee.com/edge.
  2. W głównym oknie kliknij „Protokoły API”.

    Możesz też wybrać Develop (Program) > API Proxies (Serwery interfejsów API) na pasku nawigacyjnym po lewej stronie.

  3. Kliknij + Serwer proxy.
    Dodaj serwer proxy interfejsu API
  4. W kreatorze tworzenia proxy wybierz Odwrotny serwer proxy (najczęstszy) i kliknij Użyj OpenAPI.
    Tworzenie typu serwera proxy
  5. Kliknij Importuj z adresu URL, w polu URL wpisz nazwę specyfikacji OpenAPI i w polu URL wpisz ścieżkę do nieprzetworzonej treści dla specyfikacji OpenAPI:

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

    Pojawi się strona Details (Szczegóły) w kreatorze tworzenia serwera proxy. Pola są wstępnie wypełniane na podstawie wartości zdefiniowanych w specyfikacji OpenAPI, jak widać na tym rysunku.

    Szczegóły serwera proxy

    W tabeli poniżej znajdziesz domyślne wartości wstępnie uzupełniane za pomocą właściwości w specyfikacji OpenAPI. Fragment specyfikacji OpenAPI ilustrujący używane właściwości jest widoczny pod tabelą.

    Pole Opis Domyślna
    Nazwa serwera proxy Nazwa serwera proxy interfejsu API. Przykład: Mock-Target-API. Właściwość title ze specyfikacji OpenAPI ze spacjami zastąpionymi myślnikami
    Ścieżka bazowa serwera proxy Komponent ścieżki jednoznacznie identyfikujący ten serwer proxy interfejsu API w organizacji. Publiczny adres URL tego serwera proxy interfejsów API składa się z nazwy Twojej organizacji, środowiska, w którym ten serwer proxy interfejsu API jest wdrożony, oraz z tej ścieżki podstawowej. Na przykład: http://myorg-test.apigee.net/mock-target-api Treść pola Nazwa została zamieniona na małe litery
    Istniejący interfejs API Docelowy URL wywoływany w imieniu tego serwera proxy interfejsu API. Można użyć dowolnego adresu URL, który jest dostępny przez otwarty internet. Na przykład: http://mocktarget.apigee.net Właściwość servers ze specyfikacji OpenAPI
    Description Opis serwera proxy interfejsu API. Właściwość description ze specyfikacji OpenAPI

    Poniżej znajdziesz fragment specyfikacji OpenAPI zawierający właściwości służące 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
    ...
    
  8. Edytuj pole Opis w ten sposób: API proxy for the Apigee mock target service endpoint.
  9. Kliknij Dalej.
  10. Na stronie Flows (Procesy) wybierz wszystkie operacje. Tworzenie przepływów proxy
  11. Kliknij Dalej.
  12. Na stronie Bezpieczeństwo wybierz Brak przekazywania jako opcję zabezpieczeń i kliknij Dalej.
  13. Na stronie Wirtualne hosty upewnij się, że wszystkie hosty wirtualne są wybrane, a następnie kliknij Dalej.
  14. Na stronie kompilacji wybierz środowisko testowe i kliknij Utwórz i wdróż.
  15. Na stronie Podsumowanie zobaczysz potwierdzenie, że nowy serwer proxy interfejsu API został utworzony i wdrożony w środowisku testowym.
    Podsumowanie serwera proxy
  16. Kliknij Wersja robocza interfejsu API, aby wyświetlić stronę Przegląd dotyczącą serwera proxy interfejsu API.
    Podsumowanie serwera proxy interfejsu API pozornego kierowania

Gratulacje! Serwer proxy interfejsu API został utworzony na podstawie specyfikacji OpenAPI. Następnie przetestuj, jak to 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 to polecenie cURL. Zastąp nazwę swojej organizacji w adresie URL.

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 ze specyfikacji OpenAPI i przetestować go.

Dodaj zasadę XML do JSON

Następnie dodaj zasadę XML do JSON do przepływu warunkowego Wyświetl odpowiedź XML wygenerowanego automatycznie podczas tworzenia serwera proxy interfejsu API ze specyfikacji OpenAPI. Zasada konwertuje odpowiedź XML docelowego na kod JSON.

Najpierw wywołaj interfejs API, aby móc porównywać wyniki z tymi uzyskanymi po dodaniu zasady. W oknie terminalu uruchom to polecenie cURL. Wywołujesz zasób /xml usługi docelowej, który natywnie zwraca prosty blok XML. Zastąp nazwę swojej organizacji w adresie URL.

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 zrobimy coś, co spowoduje konwersję odpowiedzi XML na JSON. Dodaj zasadę XML do JSON do przepływu warunkowego wyświetlania odpowiedzi XML na serwerze proxy interfejsu API.

  1. W prawym górnym rogu strony Przegląd Mock-Target-API kliknij kartę Programowanie w interfejsie Edge.
    Karta Deweloper
  2. W panelu po lewej stronie Navigator > Endpoint Endpoints ( Punkty końcowe serwera proxy) > kliknij domyślny przepływ Wyświetl odpowiedź XML.
    Wybierz opcję Wyświetl odpowiedź XML.
  3. Kliknij dolny przycisk +Krok odpowiadający odpowiedzi przepływu.
    Wybierz +krok
    Otworzy się okno Dodaj krok, aby wyświetlić listę wszystkich zasad, które możesz dodać.
  4. Przewiń do kategorii Zapośredniczenie i kliknij XML do JSON.
    Okno Dodaj krok
  5. Zachowaj wartości domyślne w polach Nazwa wyświetlana i Nazwa.
  6. Kliknij Dodaj. Zasada XML do JSON jest stosowana do odpowiedzi.Zasada XML do JSON w przepływie
  7. Kliknij Zapisz.

Po dodaniu zasad wywołaj ponownie interfejs API przy użyciu cURL. Zwróć uwagę, że nadal wywołujesz ten sam zasób /xml. Usługa docelowa zwraca blok kodu XML, ale zasada w proxy interfejsu API przekonwertuje odpowiedź na kod JSON. Wywołaj to:

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

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

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

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