Udostępnianie usługi SOAP jako serwera proxy interfejsu API

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

W tym temacie objaśniono sposób tworzenia serwerów proxy interfejsów API dla usług internetowych opartych na protokole SOAP. W Edge możesz utworzyć dwa rodzaje serwerów proxy SOAP. Pierwszy z nich generuje interfejs REST do usługi SOAP backendu, a drugi wykonuje przekazywanie komunikatu SOAP do backendu. W tym temacie opisano obie metody.

Ten film przedstawia kompleksową prezentację przekształcania usługi SOAP w usługę REST za pomocą Apigee Edge za pomocą kreatora proxy interfejsu API. Jeśli jednak chcesz mieć większą kontrolę nad przekształceniem SOAP w REST, możesz utworzyć serwer proxy z użyciem zasad. Więcej informacji znajdziesz w samouczku: ręczna konstrukcja serwera proxy interfejsu SOAP-to-REST API w Apigee Edge.

Tworzenie serwera proxy interfejsu API typu REST dla usługi opartej na SOAP

Ta sekcja wyjaśnia, jak utworzyć serwer proxy interfejsu REST API SOAP przy użyciu opcji REST to SOAP to REST w kreatorze tworzenia serwera proxy.

Opis

Opcja REST to SOAP to REST przetwarza WSDL w celu wygenerowania serwera proxy interfejsu API REST. Edge określa na podstawie WSDL obsługiwane operacje, parametry wejściowe usługi itd. Edge „zgaduje”, której metody HTTP należy użyć w przypadku każdej operacji. Zwykle Edge tłumaczy operacje na żądania GET, które mają tę zaletę, że można je buforować. Edge konfiguruje też docelowy punkt końcowy backendu, który może się różnić w zależności od operacji SOAP.

W przypadku serwera proxy tego typu Edge automatycznie generuje specyfikację OpenAPI, której możesz użyć do utworzenia dokumentacji API.

Podstawowe czynności

Edge

Aby utworzyć serwer proxy interfejsu API REST do usługi opartej na SOAP za pomocą interfejsu Edge:

  1. Zaloguj się na stronie apigee.com/edge.
  2. Na pasku nawigacyjnym po lewej stronie wybierz Programowanie > Proxies API.
  3. Kliknij +Serwer proxy.
  4. Kliknij Usługa SOAP.
  5. Na stronie Szczegóły serwera proxy podaj plik WSDL.
    Pole Opis
    Prześlij plik WSDL

    Wybierz źródło pliku WSDL.

    • Z adresu internetowego (URL) – wpisz lub wklej adres URL WSDL.
    • Z mojego komputera – prześlij plik WSDL z katalogu lokalnego. Jeśli występują zależności, możesz przesłać wiele plików.
  6. Kliknij Validate (Weryfikuj), aby sprawdzić poprawność WSDL.
  7. Wpisz te szczegóły serwera proxy:
    Pole Opis
    Nazwa Nazwa wyświetlana dla Twojego interfejsu API. Możesz podać znaki alfanumeryczne, łącznik (-) lub podkreślenia (_).
    Ścieżka podstawowa

    Fragment identyfikatora URI, który pojawia się po adresie http(s)://[host] serwera proxy interfejsu API. Edge używa identyfikatora URI ścieżki podstawowej, aby dopasowywać przychodzące wiadomości żądań i kierować je do odpowiedniego serwera proxy interfejsu API.

    UWAGA: domyślna ścieżka bazowa serwera proxy interfejsu API przyjmuje wartość podaną w polu Name przekonwertowanej wyłącznie na małe litery.

    Za ścieżką bazową znajdują się wszystkie dodatkowe adresy URL zasobów. Oto pełna struktura adresów URL, których klienci będą używać do wywoływania serwera proxy interfejsu API:

    https://[host]/base_path/conditional_flow_path

    UWAGA: ścieżka bazowa musi być unikalna. Nie można wdrożyć dwóch serwerów proxy interfejsu API z tą samą ścieżką bazową. Jeśli zmienisz wdrożony serwer proxy interfejsu API i ustawisz ścieżkę bazową na tę samą wartość co ścieżka bazowa innego serwera proxy interfejsu API, Edge automatycznie cofnie wdrożenie serwera proxy interfejsu API po jego zapisaniu. Przed ponownym wdrożeniem serwera proxy interfejsu API musisz zmodyfikować ścieżkę bazową, aby była niepowtarzalna.

    Używanie symboli wieloznacznych w ścieżkach podstawowych

    Użyj co najmniej jednego symbolu wieloznacznego /*/ w ścieżkach bazowych serwera proxy interfejsu API, aby przygotować się na przyszłość. Na przykład ścieżka bazowa /team/*/members umożliwia klientom wywoływanie https://[host]/team/blue/members i https://[host]/team/green/members bez konieczności tworzenia nowych serwerów proxy interfejsu API do obsługi nowych zespołów. Pamiętaj, że właściwość /**/ nie jest obsługiwana.
    Opis (Opcjonalnie) Opis interfejsu API.
  8. Kliknij Dalej.
  9. Na stronie Typowe zasady w kreatorze skonfiguruj te ustawienia:
    • Wymagania dotyczące autoryzacji zabezpieczeń w sekcji Zabezpieczenia: autoryzacja. Zobacz Dodawanie zabezpieczeń.
    • Obsługa udostępniania zasobów między domenami (CORS) w sekcji Zabezpieczenia: przeglądarka. Zobacz Dodawanie obsługi CORS.
    • Limity, które chronią usługę backendu przed dużym ruchem. Zobacz Limity. Ta opcja jest niedostępna, jeśli wybrano opcję Autoryzacja przekazywania.
  10. Na stronie Operacje WSDL wybierz typ serwera proxy interfejsu API REST to SOAP to REST.

    Pojawi się tabela z listą operacji, które Edge „wykryło” w pliku WSDL. Możesz wybrać i skonfigurować operacje, które chcesz włączyć do serwera proxy interfejsu API. Tabela znajduje się na ilustracji poniżej.

  11. Z menu wybierz Typ portu, aby określić zestaw operacji, których chcesz użyć. W WSDL elementy typu portu definiują operacje, które można wywoływać w usłudze internetowej.
  12. Opcjonalnie zmień ścieżkę interfejsu API REST dla operacji. Ścieżka będzie używana jako nazwa zasobu w adresie URL serwera proxy interfejsu API.
  13. Opcjonalnie zmień Verb (metoda HTTP) powiązany z operacją.
  14. Kliknij Dalej.
  15. Na stronie Hosty wirtualne kreatora wybierz hosty wirtualne, z którymi serwer proxy interfejsu API powiąże się po wdrożeniu. Aby dowiedzieć się więcej, przeczytaj Informacje o hostach wirtualnych.
  16. Kliknij Dalej.
  17. Wybierz środowiska wdrożenia i kliknij Utwórz i wdróż.
    Nowy serwer proxy interfejsu API zostanie utworzony i wdrożony w wybranym środowisku.
  18. Kliknij Edytuj serwer proxy, aby wyświetlić stronę z informacjami o serwerze proxy interfejsu API.

Klasyczna wersja Edge (Private Cloud)

Aby utworzyć serwer proxy interfejsu API REST do usługi opartej na SOAP przy użyciu klasycznego interfejsu użytkownika Edge:

  1. Zaloguj się w http://ms-ip:9000, gdzie ms-ip to adres IP lub nazwa DNS węzła serwera zarządzania.
  2. Na górnym pasku nawigacyjnym wybierz Interfejsy API > Serwery proxy API.
  3. Kliknij + Serwer proxy API.
  4. W kreatorze tworzenia serwera proxy wybierz usługę SOAP.
  5. Kliknij Dalej.
  6. Wybierz odpowiednie ustawienia na stronie Szczegóły. Po wybraniu WSDL musisz kliknąć Weryfikuj.
    W tym polu wykonaj to
    WSDL

    Wybierz źródło pliku WSDL.

    • URL – wpisz adres URL WSDL, którego chcesz używać.
    • Plik – wybierz plik WSDL w systemie plików. Jeśli istnieją dodatkowe pliki zależne, możesz wybrać je wszystkie.
    • Przykładowy URL – wybierz z listy WSDL dla publicznie dostępnych usług internetowych. Są one przydatne do testowania funkcji serwera proxy SOAP/API dostępnych w Edge.
    Nazwa serwera proxy

    Jest to nazwa tworzonego serwera proxy.
    Ścieżka podstawowa serwera proxy

    Fragment identyfikatora URI, który pojawia się po adresie http(s)://[host] serwera proxy interfejsu API. Edge używa identyfikatora URI ścieżki podstawowej, aby dopasowywać przychodzące wiadomości żądań i kierować je do odpowiedniego serwera proxy interfejsu API.

    Uwaga: domyślna ścieżka bazowa serwera proxy interfejsu API przyjmuje wartość podaną w polu Name przekonwertowanej wyłącznie na małe litery.

    Za ścieżką bazową znajdują się wszystkie dodatkowe adresy URL zasobów. Oto pełna struktura adresów URL, których klienci będą używać do wywoływania serwera proxy interfejsu API:

    https://[host]/base_path/conditional_flow_path

    Uwaga: ścieżka bazowa musi być unikalna. Nie można wdrożyć dwóch serwerów proxy interfejsu API z tą samą ścieżką bazową. Jeśli zmienisz wdrożony serwer proxy interfejsu API i ustawisz ścieżkę bazową na tę samą wartość co ścieżka bazowa innego serwera proxy interfejsu API, Edge automatycznie cofnie wdrożenie serwera proxy interfejsu API po jego zapisaniu. Przed ponownym wdrożeniem serwera proxy interfejsu API musisz zmodyfikować ścieżkę bazową, aby była niepowtarzalna.

    Używanie symboli wieloznacznych w ścieżkach podstawowych

    Użyj co najmniej jednego symbolu wieloznacznego /*/ w ścieżkach bazowych serwera proxy interfejsu API, aby przygotować się na przyszłość. Na przykład ścieżka bazowa /team/*/members umożliwia klientom wywoływanie https://[host]/team/blue/members i https://[host]/team/green/members bez konieczności tworzenia nowych serwerów proxy interfejsu API do obsługi nowych zespołów. Pamiętaj, że właściwość /**/ nie jest obsługiwana.
    Opis Krótki opis serwera proxy.
  7. Kliknij Dalej.
  8. Na stronie WSDL wybierz typ serwera proxy interfejsu API REST to SOAP to REST.

    Pojawi się tabela z listą operacji, które Edge „wykryło” w pliku WSDL. Możesz wybrać i skonfigurować operacje, które chcesz włączyć do serwera proxy interfejsu API. Tabela znajduje się na ilustracji poniżej.

    Na stronie operacji WSDL typ serwera proxy interfejsu API jest ustawiony na REST na SOAP w celu REST, a w tabeli znajduje się jeden wiersz wyników z operacją dodawania.

  9. W kolumnie Typ portu wybierz zestaw operacji, których chcesz użyć. W WSDL elementy typu portu definiują operacje, które można wywoływać w usłudze internetowej.
  10. Opcjonalnie zmień metodę HTTP powiązaną z operacją.

    Uwaga: Edge wykonuje „najlepsze przypuszczenie” do określania metody HTTP używanej w każdej operacji. Metoda GET jest ogólnie preferowana, ponieważ żądania GET mogą być przechowywane w pamięci podręcznej.
  11. Opcjonalnie zmień ścieżkę interfejsu API REST dla operacji. Ścieżka będzie używana jako nazwa zasobu w adresie URL serwera proxy interfejsu API.
  12. Przejdź przez resztę kreatora, aby dodać zabezpieczenia, wybrać hosty wirtualne i środowisko wdrożenia.
  13. Na stronie kompilacji kliknij Skompiluj i wdróż. Edge generuje i wdraża nowy serwer proxy interfejsu API na podstawie WSDL.
  14. Otwórz stronę podsumowania nowego serwera proxy interfejsu API. Zwróć uwagę, że zbiór zasobów został utworzony na podstawie operacji wykrytych w pliku WSDL.

    Na stronie Przegląd serwera proxy lista Zasoby zawiera szczegółowy opis nowego interfejsu API, jego operacji i parametrów. Możesz ją traktować jako dokumentację referencyjną interfejsu API. Edge automatycznie generuje dla Ciebie ten widok modelu API. Wystarczy rozwinąć zasób, aby zobaczyć jego opis i informacje o ścieżce.

O końcowym serwerze proxy

Gdy Edge generuje serwer proxy interfejsu API na podstawie WSDL, powstały serwer proxy jest w rzeczywistości złożonym procesem obejmującym zasady dotyczące przekształcania danych, wyodrębniania i ustawiania zmiennych, manipulowania wiadomościami oraz nie tylko. Po wygenerowaniu serwera proxy na podstawie WSDL obejrzyj wynikowy proces w widoku Programowanie interfejsu zarządzania interfejsami API. Możesz tam dokładnie sprawdzić, które zasady zostały dodane.

Na przykład po stronie żądania do ustawiania docelowego adresu URL służy zasada AssignMessage. Po stronie odpowiedzi zasady są wykonywane w celu przekształcenia odpowiedzi z XML na JSON, wyodrębnienia części treści SOAP do zmiennej i ustawienia komunikatu z odpowiedzią. Te zasady (i inne) są dodawane automatycznie podczas tworzenia serwera proxy.

Specyfikacja OpenAPI: aby wyświetlić automatycznie wygenerowaną specyfikację OpenAPI dla tego serwera proxy, otwórz http(s)://[proxy_domain]/[proxy_base_path]/openapi.json. Jednak konwersja nie zawsze jest dokładna, ponieważ nie wszystkie reguły schematu XML można uwzględnić w specyfikacji OpenAPI.

Tworzenie przekazującego serwera proxy do usługi opartej na SOAP

Ta sekcja wyjaśnia, jak utworzyć przekazujący serwer proxy za pomocą opcji Serwer proxy przekazywania w oknie Utwórz nowy serwer proxy.

Opis

Opcja przekazywania serwera proxy umożliwia utworzenie serwera proxy, który przekazuje wiadomość SOAP w żądaniu do usługi backendu „nietknięty”, co bardzo ułatwia utworzenie serwera proxy dla usługi internetowej opartej na SOAP. Za kulisami Edge automatycznie wykonuje wszystkie przekształcenia i inne działania związane z przepływem. Jeśli na przykład żądanie jest w formacie JSON, przed wysłaniem go do usługi Edge podejmuje odpowiednie kroki, aby przekonwertować je na prawidłowy komunikat XML SOAP z prawidłowymi przestrzeniami nazw. Podobnie, gdy usługa zwraca odpowiedź SOAP opartą na XML, Edge konwertuje ją z powrotem na JSON, a następnie zwraca klientowi. Dodatkowo Edge konfiguruje docelowy punkt końcowy backendu, który może się różnić w zależności od operacji SOAP.

W przypadku tego typu serwera proxy Edge hostuje WSDL i tworzy przepływ na serwerze proxy, aby umożliwić Ci dostęp do niego. Adres tego hostowanego na serwerach brzegowych WSDL (http(s)://[proxy_domain]/[proxy_base_path]?wsdl) staje się nowym adresem URL punktu końcowego usługi dla klientów wywołujących usługę SOAP przez serwer proxy.

Podstawowe czynności

Edge

Aby utworzyć przekazujący serwer proxy do usługi opartej na SOAP za pomocą interfejsu Edge:

  1. Zaloguj się na stronie apigee.com/edge.
  2. Na pasku nawigacyjnym po lewej stronie wybierz Programowanie > Proxies API.
  3. Kliknij +Serwer proxy.
  4. Kliknij Usługa SOAP.
  5. Na stronie Szczegóły serwera proxy podaj szczegółowe informacje o WSDL.
    Pole Opis
    WSDL

    Wybierz źródło pliku WSDL.

    • Z adresu internetowego (URL) – wpisz lub wklej adres URL WSDL.
    • Z mojego komputera – prześlij plik WSDL z katalogu lokalnego. Jeśli występują zależności, możesz przesłać wiele plików.
    Nazwa

    Nazwa serwera proxy interfejsu API.
    Ścieżka podstawowa

    Fragment identyfikatora URI po adresie http(s)://[host] serwera proxy interfejsu API. Edge używa identyfikatora URI ścieżki podstawowej, aby dopasowywać przychodzące wiadomości żądań i kierować je do odpowiedniego 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.

    Po ścieżce bazowej znajdują się dodatkowe adresy URL zasobów. Oto pełna struktura adresów URL, których klienci będą używać do wywoływania serwera proxy interfejsu API:

    https://[host]/base_path/conditional_flow_path

    Uwaga: ścieżka bazowa musi być unikalna. Jeśli później zmienisz ten serwer proxy i ustawisz jego ścieżkę bazową na taką samą jak inny serwer proxy interfejsu API, po zapisaniu tego serwera proxy interfejsu API zostanie automatycznie wycofany. Przed ponownym wdrożeniem musisz zmodyfikować ścieżkę podstawową.

    Używanie symbolu wieloznacznego w ścieżkach podstawowych

    W ścieżkach bazowych serwera proxy interfejsu API możesz użyć co najmniej jednego symbolu wieloznacznego /*/, aby zabezpieczyć serwery proxy na przyszłość. Na przykład ścieżka bazowa /team/*/members umożliwia klientom wywoływanie https://[host]/team/blue/members i https://[host]/team/green/members bez konieczności tworzenia nowych serwerów proxy interfejsu API do obsługi nowych zespołów. Pamiętaj, że /**/ nie jest obsługiwana.

    Uwaga: domyślna ścieżka bazowa serwera proxy interfejsu API przyjmuje wartość podaną w polu Nazwa przekonwertowanej wyłącznie na małe litery, chyba że zmienisz treść w polu Ścieżka bazowa.
    Opis (Opcjonalnie) Opis interfejsu API.
  6. Kliknij Dalej.
  7. Na stronie Typowe zasady w kreatorze skonfiguruj te ustawienia:
  8. Na stronie WSDL wybierz typ serwera proxy interfejsu API Pass-Through SOAP.

  9. Z menu wybierz Typ portu, aby określić zestaw operacji, których chcesz użyć. W WSDL elementy typu portu definiują operacje, które można wywoływać w usłudze internetowej.
  10. Kliknij Dalej.
  11. Na stronie Hosty wirtualne kreatora wybierz hosty wirtualne, z którymi serwer proxy interfejsu API powiąże się po wdrożeniu. Więcej informacji znajdziesz w artykule o hostach wirtualnych.
  12. Wybierz środowiska wdrożenia i kliknij Utwórz i wdróż.
    Nowy serwer proxy interfejsu API zostanie utworzony i wdrożony w wybranym środowisku.
  13. Kliknij Edytuj serwer proxy, aby wyświetlić stronę z informacjami o serwerze proxy interfejsu API.

Klasyczna wersja Edge (Private Cloud)

Aby utworzyć przekazujący serwer proxy do usługi opartej na SOAP za pomocą klasycznego interfejsu użytkownika Edge:

  1. Zaloguj się w http://ms-ip:9000, gdzie ms-ip to adres IP lub nazwa DNS węzła serwera zarządzania.
  2. Na górnym pasku nawigacyjnym wybierz Interfejsy API > Serwery proxy API.
  3. Kliknij + Serwer proxy API.
  4. W kreatorze tworzenia serwera proxy wybierz usługę SOAP.
  5. Kliknij Dalej.
  6. Wybierz odpowiednie ustawienia na stronie Szczegóły. Po wybraniu WSDL musisz kliknąć Weryfikuj.
    W tym polu wykonaj to
    WSDL

    Wybierz źródło pliku WSDL.

    • URL – wpisz adres URL WSDL, którego chcesz używać.
    • Plik – wybierz plik WSDL w systemie plików. W przypadku dodatkowych plików zależnych możesz wybrać je wszystkie.
    • Przykładowy URL – wybierz z listy WSDL dla publicznie dostępnych usług internetowych. Są one przydatne do testowania funkcji serwera proxy SOAP/API dostępnych w Edge.
    Nazwa serwera proxy

    Jest to nazwa tworzonego serwera proxy.
    Ścieżka podstawowa serwera proxy Ścieżka podstawowa serwera proxy to fragment identyfikatora URI, który jednoznacznie identyfikuje interfejs API ujawniany przez ten serwer proxy interfejsu API. Usługi API korzystają z identyfikatora URI ścieżki podstawowej w celu dopasowywania przychodzących komunikatów żądań i kierowania ich do odpowiedniego serwera proxy interfejsu API. Ścieżka podstawowa jest dołączana do domeny interfejsu API, która jest generowana automatycznie na podstawie nazwy organizacji i środowiska, w którym został wdrożony serwer proxy interfejsu API. Najlepiej jest podać w nazwie projektu numer wersji, np. /v1/delayedstockquote. Określa sposób wywoływania interfejsu API przez aplikacje konsumenckie.

    Uwaga: domyślnie ścieżka bazowa serwera proxy przyjmuje wartość podaną w polu Nazwa serwera proxy przekonwertowanego wyłącznie na małe litery, chyba że zmienisz treść w polu Ścieżka bazowa serwera proxy.
    Opis Krótki opis serwera proxy.

  8. Kliknij Dalej.
  9. Na stronie WSDL wybierz typ serwera proxy interfejsu API Pass-Through SOAP.

    Uwaga: pojawi się tabela z listą operacji WSDL i odpowiadających im ładunkom SOAP. Jest to ładunek, który jest „przekazywany” do usługi SOAP backendu.

    Na stronie WSDL typ serwera proxy interfejsu API jest ustawiony na Pass-Through SOAP, a lista operacji, takich jak Getcite, jest uporządkowana według typu portu.
  10. W kolumnie Typ portu wybierz zestaw operacji, których chcesz użyć. W WSDL elementy typu portu definiują operacje, które można wywoływać w usłudze internetowej.
  11. Przejdź przez resztę kreatora, aby dodać zabezpieczenia, wybrać hosty wirtualne i środowisko wdrożenia.
  12. Na stronie kompilacji kliknij Skompiluj i wdróż. Edge generuje i wdraża nowy serwer proxy interfejsu API na podstawie WSDL.

O końcowym serwerze proxy

Gdy Edge generuje przekazujący serwer proxy, powstały serwer proxy jest w rzeczywistości złożonym procesem obejmującym zasady dotyczące przekształcania danych, wyodrębniania i ustawiania zmiennych, manipulowania wiadomościami oraz nie tylko. Po wygenerowaniu przekazującego serwera proxy przejrzyj wynikowy przepływ w widoku Programowanie interfejsu zarządzania interfejsem API. Możesz tam dokładnie sprawdzić, które zasady zostały dodane.

Na przykład ten rysunek przedstawia część wstępnego przepływu docelowego punktu końcowego w przekazywanym serwerze proxy. Po stronie żądania do ustawiania docelowego adresu URL używana jest zasada AssignMessage. Po stronie odpowiedzi zasady są wykonywane w celu przekształcenia odpowiedzi z XML na JSON, wyodrębnienia części treści SOAP do zmiennej i ustawienia komunikatu z odpowiedzią. Te zasady (i inne) są dodawane automatycznie podczas tworzenia serwera proxy.

W widoku Programowanie na panelu procesu strzałki przedstawiają przepływ od żądania do odpowiedzi, a ikony – zasady.

WSDL hostowany na brzegu: aby zobaczyć hostowany na serwerach brzegowy plik WSDL wygenerowany dla tego typu serwera proxy, otwórz http(s)://[proxy_domain]/[proxy_base_path]?wsdl.

Zaawansowane tworzenie serwerów proxy SOAP do REST

W poprzednich sekcjach omówiliśmy tworzenie serwera proxy interfejsu SOAP-to-REST API za pomocą kreatora serwerów proxy interfejsów API w przeglądarce Edge. Jeśli jednak chcesz mieć większą kontrolę nad przekształceniem SOAP w REST, możesz pominąć automatyzację oferowaną przez kreatora i utworzyć serwer proxy przez ręczne dodawanie i konfigurowanie zasad w celu osiągnięcia pożądanego działania. Więcej informacji znajdziesz w samouczku: ręczna konstrukcja serwera proxy interfejsu SOAP-to-REST API w Apigee Edge.