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

Wyświetlasz dokumentację Apigee Edge.
Zapoznaj się z dokumentacją Apigee X. info

Z tego artykułu dowiesz się, jak tworzyć proxy interfejsu API dla usług internetowych opartych na protokole SOAP. W Edge możesz utworzyć 2 rodzaje serwerów proxy SOAP. Jeden generuje interfejs RESTful dla usługi SOAP backendu, a drugi wykonuje „przekazywanie” komunikatu SOAP do backendu. Obie techniki opisano w tym temacie.

Ten film zawiera kompleksową prezentację przekształcania usługi SOAP w usługę REST za pomocą Apigee Edge przy użyciu kreatora serwera proxy interfejsu API. Jeśli jednak chcesz mieć większą kontrolę nad przekształcaniem SOAP na REST, możesz utworzyć serwer proxy za pomocą zasad. Więcej informacji znajdziesz w  tym samouczku.

Tworzenie proxy interfejsu API RESTful dla usługi opartej na protokole SOAP

W tej sekcji dowiesz się, jak utworzyć serwer proxy interfejsu API SOAP RESTful za pomocą opcji REST to SOAP to REST w kreatorze tworzenia serwera proxy.

Przegląd

Opcja REST to SOAP to REST przetwarza plik WSDL, aby wygenerować serwer proxy interfejsu API RESTful. Edge określa na podstawie pliku WSDL obsługiwane operacje usługi, parametry wejściowe itp. Edge „zgaduje”, której metody HTTP użyć w przypadku poszczególnych operacji. Zwykle Edge przekształca operacje w żądania GET, które można umieszczać w pamięci podręcznej. Edge konfiguruje też 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 automatycznie generuje specyfikację OpenAPI, której możesz użyć do utworzenia dokumentacji interfejsu API.

Podstawowe czynności

Edge

Aby utworzyć serwer proxy interfejsu API RESTful dla usługi opartej na protokole SOAP za pomocą interfejsu Edge:

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

    Wybierz źródło WSDL.

    • Z adresu internetowego (URL) – wpisz lub wklej adres URL WSDL.
    • Z komputera – prześlij plik WSDL z katalogu lokalnego. Jeśli istnieją zależności, możesz przesłać wiele plików.
  6. Aby zweryfikować plik WSDL, kliknij Validate (Sprawdź).
  7. Podaj te szczegóły serwera proxy:
    Pole Opis
    Nazwa Nazwa wyświetlana interfejsu API. Użyj znaków alfanumerycznych, myślnika (-) lub podkreślenia (_).
    Ścieżka podstawowa

    Fragment URI, który pojawia się po adresie http(s)://[host] serwera proxy interfejsu API. Edge używa identyfikatora URI ścieżki podstawowej do dopasowywania i kierowania przychodzących żądań do odpowiedniego serwera proxy interfejsu API.

    NOTE ścieżka podstawowa serwera proxy interfejsu API domyślnie przyjmuje wartość podaną w polu Name przekształconą na małe litery.

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

    https://[host]/base_path/conditional_flow_path

    NOTE ścieżka podstawowa musi być unikalna. Nie możesz wdrożyć 2 serwerów proxy interfejsu API z tą samą ścieżką podstawową. Jeśli edytujesz wdrożony serwer proxy interfejsu API i ustawisz ścieżkę podstawową na taką samą wartość jak ścieżka podstawowa innego serwera proxy interfejsu API, Edge automatycznie wycofa wdrożenie serwera proxy interfejsu API po jego zapisaniu. Zanim ponownie wdrożysz serwer proxy interfejsu API, musisz edytować ścieżkę podstawową, aby była unikalna.

    Używanie symboli wieloznacznych w ścieżkach podstawowych

    Używaj co najmniej 1 symbolu wieloznacznego /*/ w ścieżkach podstawowych serwera proxy interfejsu API, aby zapewnić zgodność serwerów proxy interfejsu API z przyszłymi zmianami. Na przykład ścieżka podstawowa /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 na potrzeby nowych zespołów. Pamiętaj, że /**/ nie jest obsługiwany.
    Opis (Opcjonalnie) Opis interfejsu API.
  8. Kliknij Dalej.
  9. Na stronie Common policies (Zasady wspólne) kreatora skonfiguruj te ustawienia:
    • Wymagania dotyczące autoryzacji zabezpieczeń w sekcji Zabezpieczenia: autoryzacja. Zobacz Dodawanie zabezpieczeń.
    • Obsługa współdzielenia zasobów pomiędzy serwerami z różnych domen (CORS) w sekcji Bezpieczeństwo: przeglądarka. Zobacz Dodawanie obsługi CORS.
    • Limity, które chronią usługę backendu przed dużym ruchem w sekcji Quota. Zobacz Limity. (Niedostępne, jeśli wybrano autoryzację przekazywaną).
  10. Na stronie WSDL operations (Operacje WSDL) wybierz typ proxy interfejsu API REST to SOAP to REST (REST do SOAP do REST).

    Pojawi się tabela z listą operacji, które Edge „wykrył” w pliku WSDL. Możesz wybrać i skonfigurować operacje, które chcesz uwzględnić w proxy interfejsu API. Tabela jest widoczna na tym rysunku.

  11. Wybierz Typ portu z menu, aby określić, którego zestawu operacji chcesz użyć. W języku WSDL elementy typu portu definiują operacje, które można wywołać w usłudze internetowej.
  12. Opcjonalnie możesz zmienić ś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ń czasownik (metodę HTTP) powiązany z operacją.
  14. Kliknij Dalej.
  15. Na stronie Wirtualni hostowie kreatora wybierz wirtualnych hostów, z którymi serwer proxy interfejsu API będzie powiązany po wdrożeniu. Więcej informacji znajdziesz w artykule Informacje o hostach wirtualnych.
  16. Kliknij Dalej.
  17. Wybierz środowiska wdrażania i kliknij Utwórz i wdroż
    . Nowy serwer proxy interfejsu API zostanie utworzony i wdrożony w wybranym środowisku.
  18. Kliknij Edytuj serwer proxy, aby wyświetlić stronę szczegółów serwera proxy interfejsu API.

Classic Edge (Private Cloud)

Aby utworzyć serwer proxy interfejsu API RESTful dla usługi opartej na protokole SOAP za pomocą klasycznego interfejsu Edge:

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

    Wybierz źródło WSDL.

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

    To nazwa tworzonego przez Ciebie serwera proxy.
    Podstawowa ścieżka serwera proxy

    Fragment URI, który pojawia się po adresie http(s)://[host] serwera proxy interfejsu API. Edge używa identyfikatora URI ścieżki podstawowej do dopasowywania i kierowania przychodzących żądań do odpowiedniego serwera proxy interfejsu API.

    Uwaga: domyślna ścieżka podstawowa serwera proxy interfejsu API to wartość określona w polu Name przekonwertowana na małe litery.

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

    https://[host]/base_path/conditional_flow_path

    Uwaga: ścieżka podstawowa musi być unikalna. Nie można wdrożyć 2 proxy interfejsu API z tą samą ścieżką podstawową. Jeśli edytujesz wdrożony serwer proxy interfejsu API i ustawisz ścieżkę podstawową na taką samą wartość jak ścieżka podstawowa innego serwera proxy interfejsu API, Edge automatycznie wycofa wdrożenie serwera proxy interfejsu API po jego zapisaniu. Zanim ponownie wdrożysz serwer proxy interfejsu API, musisz edytować ścieżkę podstawową, aby była unikalna.

    Używanie symboli wieloznacznych w ścieżkach podstawowych

    Używaj co najmniej 1 symbolu wieloznacznego /*/ w ścieżkach podstawowych serwera proxy interfejsu API, aby zapewnić zgodność serwerów proxy interfejsu API z przyszłymi zmianami. Na przykład ścieżka podstawowa /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 na potrzeby nowych zespołów. Pamiętaj, że /**/ nie jest obsługiwany.
    Opis Krótki opis serwera proxy.
  7. Kliknij Dalej.
  8. Na stronie WSDL wybierz typ proxy interfejsu API REST to SOAP to REST (REST na SOAP na REST).

    Pojawi się tabela z listą operacji, które Edge „wykrył” w pliku WSDL. Możesz wybrać i skonfigurować operacje, które chcesz uwzględnić w proxy interfejsu API. Tabela jest widoczna na tym rysunku.

    Na stronie operacji WSDL typ proxy interfejsu API jest ustawiony na REST to SOAP to REST, a tabela zawiera 1 wiersz wyników z operacją dodawania.

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

    Uwaga: Edge „zgaduje”, jakiej metody HTTP użyć w przypadku każdej operacji. Metoda GET jest zwykle preferowana, ponieważ żądania GET można przechowywać 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. Wykonaj pozostałe kroki kreatora, aby dodać zabezpieczenia, wybrać hosty wirtualne i środowisko wdrażania.
  13. Na stronie Kompilacja kliknij Kompilacja i wdrożenie. Edge generuje i wdraża nowy serwer proxy interfejsu API na podstawie pliku WSDL.
  14. Otwórz stronę podsumowania nowego serwera proxy interfejsu API. Zwróć uwagę, że na podstawie operacji wykrytych w pliku WSDL utworzono zestaw zasobów.

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

Informacje o końcowym serwerze proxy

Gdy Edge generuje serwer proxy interfejsu API na podstawie pliku WSDL, wynikowy serwer proxy jest w rzeczywistości złożonym przepływem, który obejmuje zasady przekształcania danych, wyodrębniania i ustawiania zmiennych, manipulowania wiadomościami i nie tylko. Po wygenerowaniu serwera proxy na podstawie pliku WSDL sprawdź wynikowy przepływ w widoku Develop (Tworzenie) interfejsu zarządzania interfejsem API. Tam możesz sprawdzić, które zasady zostały dodane.

Na przykład po stronie żądania zasada AssignMessage służy do ustawiania docelowego adresu URL. Po stronie odpowiedzi zasady są wykonywane w celu przekształcenia odpowiedzi z XML na JSON, wyodrębnienia części treści SOAP odpowiedzi do zmiennej i ustawienia komunikatu 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. Konwersja nie zawsze jest jednak dokładna, ponieważ nie wszystkie reguły schematu XML można przedstawić w specyfikacji OpenAPI.

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

Z tej sekcji dowiesz się, jak utworzyć serwer proxy typu pass-through za pomocą opcji Serwer proxy typu pass-through w oknie Utwórz nowy serwer proxy.

Przegląd

Opcja Pass-Through Proxy umożliwia utworzenie serwera proxy, który przekazuje komunikat SOAP w żądaniu do usługi backendu „bez zmian”, co bardzo ułatwia utworzenie serwera proxy dla usługi internetowej opartej na protokole SOAP. W tle Edge automatycznie obsługuje wszystkie przekształcenia i inne działania związane z przepływem. Jeśli na przykład żądanie jest w formacie JSON, Edge podejmuje kroki, aby przekonwertować je na prawidłową wiadomość SOAP w formacie XML z prawidłowymi przestrzeniami nazw przed wysłaniem jej do usługi za pomocą metody POST. Podobnie, gdy usługa zwraca odpowiedź SOAP opartą na XML, Edge tłumaczy ją z powrotem na JSON, zanim zwróci ją do klienta. 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 plik WSDL i tworzy w serwerze proxy przepływ, który umożliwia dostęp do tego pliku. Adres tego pliku WSDL hostowanego na platformie Edge, 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 za pomocą serwera proxy.

Podstawowe czynności

Edge

Aby utworzyć serwer proxy typu pass-through dla usługi opartej na protokole SOAP za pomocą interfejsu Edge:

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

    Wybierz źródło WSDL.

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

    Nazwa proxy interfejsu API.
    Ścieżka podstawowa

    Fragment URI po adresie http(s)://[host] serwera proxy interfejsu API. Edge używa identyfikatora URI ścieżki podstawowej do dopasowywania i kierowania przychodzących żądań do odpowiedniego serwera proxy interfejsu API.

    Uwaga: zalecenia Apigee dotyczące określania wersji interfejsu API znajdziesz w rozdziale Określanie wersji w e-booku Web API Design: The Missing Link.

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

    https://[host]/base_path/conditional_flow_path

    Uwaga: ścieżka podstawowa musi być unikalna. Jeśli później edytujesz ten serwer proxy i ustawisz jego ścieżkę podstawową taką samą jak w przypadku innego serwera proxy interfejsu API, ten serwer proxy interfejsu API zostanie automatycznie wycofany po zapisaniu. Aby ponownie wdrożyć ścieżkę podstawową, musisz ją edytować.

    Używanie symbolu wieloznacznego w ścieżkach podstawowych

    W ścieżkach podstawowych serwera proxy interfejsu API możesz używać co najmniej 1 symbolu wieloznacznego /*/, aby zabezpieczyć serwery proxy na przyszłość. Na przykład ścieżka podstawowa /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 na potrzeby nowych zespołów. Pamiętaj, że /**/ nie jest obsługiwane.

    Uwaga: domyślna ścieżka podstawowa serwera proxy interfejsu API to wartość określona w polu Nazwa przekształcona na małe litery, chyba że wyraźnie edytujesz zawartość pola Ścieżka podstawowa.
    Opis (Opcjonalnie) Opis interfejsu API.
  6. Kliknij Dalej.
  7. Na stronie Common policies (Zasady wspólne) kreatora skonfiguruj te ustawienia:
  8. Na stronie WSDL wybierz typ proxy interfejsu API Pass-Through SOAP.

  9. Wybierz Typ portu z menu, aby określić, którego zestawu operacji chcesz użyć. W języku WSDL elementy typu portu definiują operacje, które można wywołać w usłudze internetowej.
  10. Kliknij Dalej.
  11. Na stronie Wirtualni hostowie kreatora wybierz wirtualnych hostów, z którymi serwer proxy interfejsu API będzie powiązany po wdrożeniu. Więcej informacji znajdziesz w artykule Informacje o hostach wirtualnych.
  12. Wybierz środowiska wdrażania i kliknij Utwórz i wdroż
    . Nowy serwer proxy interfejsu API zostanie utworzony i wdrożony w wybranym środowisku.
  13. Kliknij Edytuj serwer proxy, aby wyświetlić stronę szczegółów serwera proxy interfejsu API.

Classic Edge (Private Cloud)

Aby utworzyć serwer proxy typu pass-through dla usługi opartej na protokole SOAP za pomocą klasycznego interfejsu Edge:

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

    Wybierz źródło WSDL.

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

    To nazwa tworzonego przez Ciebie serwera proxy.
    Podstawowa ścieżka serwera proxy Podstawowa ścieżka proxy to fragment URI, który jednoznacznie identyfikuje interfejs API udostępniany przez ten serwer proxy interfejsu API. Usługi API używają podstawowego adresu URI ścieżki do dopasowywania i kierowania przychodzących wiadomości z żądaniami 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 jest wdrażany serwer proxy interfejsu API). Zalecamy uwzględnienie w nazwie projektu numeru wersji, np. /v1/delayedstockquote. Określi to sposób wywoływania interfejsu API przez aplikacje konsumenckie.

    Uwaga: domyślna wartość podstawowej ścieżki serwera proxy to nazwa serwera proxy zapisana małymi literami, chyba że w polu Podstawowa ścieżka serwera proxy wpiszesz inną wartość.
    Opis Krótki opis serwera proxy.

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

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

    Na stronie WSDL typ proxy interfejsu API jest ustawiony na Pass-Through SOAP, a lista operacji, takich jak GetQuote, jest uporządkowana według typu portu.
  10. W kolumnie „Typ portu” wybierz zestaw operacji, których chcesz użyć. W języku WSDL elementy typu portu definiują operacje, które można wywołać w usłudze internetowej.
  11. Wykonaj pozostałe kroki kreatora, aby dodać zabezpieczenia, wybrać hosty wirtualne i środowisko wdrażania.
  12. Na stronie Kompilacja kliknij Kompilacja i wdrożenie. Edge generuje i wdraża nowy serwer proxy interfejsu API na podstawie pliku WSDL.

Informacje o końcowym serwerze proxy

Gdy Edge generuje serwer proxy typu pass-through, wynikowy serwer proxy jest w rzeczywistości złożonym przepływem, który obejmuje zasady przekształcania danych, wyodrębniania i ustawiania zmiennych, manipulowania wiadomościami i nie tylko. Po wygenerowaniu serwera proxy typu pass-through sprawdź wynikowy przepływ w widoku Develop (Tworzenie) interfejsu zarządzania interfejsami API. Tam możesz sprawdzić, które zasady zostały dodane.

Na przykład na poniższym rysunku widać część przepływu wstępnego punktu końcowego docelowego serwera proxy typu pass-through. Po stronie żądania do ustawienia 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 odpowiedzi do zmiennej i ustawienia komunikatu odpowiedzi. Te zasady (i inne) są dodawane automatycznie podczas tworzenia serwera proxy.

W widoku Develop w panelu Flow strzałki przedstawiają przepływ od żądania do odpowiedzi, a ikony przedstawiają zasady.

WSDL hostowany na serwerze brzegowym: aby wyświetlić plik WSDL hostowany na serwerze brzegowym wygenerowany dla tego typu serwera proxy, kliknij http(s)://[proxy_domain]/[proxy_base_path]?wsdl.

Zaawansowane tworzenie serwerów proxy SOAP-to-REST

W poprzednich sekcjach opisaliśmy tworzenie serwera proxy interfejsu API SOAP-to-REST za pomocą kreatora serwera proxy interfejsu API w Edge. Jeśli jednak chcesz mieć większą kontrolę nad przekształcaniem SOAP na REST, możesz pominąć automatyzację zapewnianą przez kreatora i utworzyć serwer proxy, ręcznie dodając i konfigurując zasady, aby uzyskać pożądane działanie. Więcej informacji znajdziesz w tym samouczku.