Предоставление службы SOAP в качестве прокси-сервера API

Вы просматриваете документацию Apigee Edge .
Перейти к документации Apigee X. info

В этом разделе объясняется, как создавать прокси-серверы API для веб-сервисов на основе SOAP. В Edge можно создать два типа прокси-серверов SOAP. Один из них генерирует RESTful-интерфейс для бэкенд-сервиса SOAP, а другой осуществляет «сквозную» передачу SOAP-сообщений бэкенду. В этом разделе описаны оба метода.

В этом видео представлена ​​полная демонстрация преобразования SOAP-сервиса в REST-сервис с помощью Apigee Edge с помощью мастера API-прокси. Однако, если вам нужен более полный контроль над преобразованием SOAP в REST, вы можете создать прокси с помощью политик. Подробнее см. в разделе «Руководство: ручное создание API-прокси SOAP в REST в Apigee Edge» .

Создание RESTful API-прокси для службы на основе SOAP

В этом разделе объясняется, как создать прокси-сервер RESTful SOAP API с помощью параметра REST to SOAP to REST в мастере создания прокси-сервера.

Обзор

Функция REST to SOAP to REST обрабатывает WSDL для создания прокси-сервера RESTful API. Edge определяет на основе WSDL поддерживаемые сервисом операции, входные параметры и т. д. Edge «угадывает», какой HTTP-метод использовать для каждой операции. Обычно Edge преобразует операции в GET-запросы, преимущество которых заключается в возможности кэширования. Edge также устанавливает целевую конечную точку бэкенда, которая может меняться для каждой операции SOAP.

Для этого типа прокси Edge автоматически генерирует спецификацию OpenAPI , которую можно использовать для создания документации API.

Основные шаги

Край

Чтобы создать прокси-сервер RESTful API для службы на основе SOAP с помощью Edge UI:

  1. Войдите на сайт apigee.com/edge .
  2. Выберите «Разработка» > «Прокси API» на левой панели навигации.
  3. Нажмите +Прокси .
  4. Нажмите «Служба SOAP» .
  5. На странице сведений о прокси-сервере укажите файл WSDL.
    Поле Описание
    Предоставить WSDL-файл

    Выберите источник WSDL.

    • С веб-адреса (URL) — введите или вставьте URL-адрес WSDL.
    • С моего компьютера — загрузите WSDL-файл из локального каталога. Вы можете загрузить несколько файлов, если есть зависимости.
  6. Нажмите «Проверить» , чтобы проверить WSDL.
  7. Введите следующие данные прокси:
    Поле Описание
    Имя Имя, отображаемое для вашего API. Укажите буквы, цифры, дефис (-) или подчёркивание (_).
    Базовый путь

    Фрагмент URI, который появляется после адреса http(s)://[host] вашего API-прокси. Edge использует базовый URI пути для сопоставления и маршрутизации входящих запросов к соответствующему API-прокси.

    ПРИМЕЧАНИЕ . Базовый путь прокси-API по умолчанию соответствует значению, указанному в поле Name , преобразованному в строчные буквы.

    После базового пути следуют URL-адреса всех дополнительных ресурсов. Вот полная структура URL-адресов, которую клиенты будут использовать для вызова вашего API-прокси:

    https://[host]/ base_path / conditional_flow_path

    ПРИМЕЧАНИЕ : Базовый путь должен быть уникальным; невозможно развернуть два прокси-сервера API с одним и тем же базовым путем. Если вы редактируете развёрнутый прокси-сервер API и задаёте базовый путь, совпадающий с базовым путём другого прокси-сервера API, Edge автоматически отменяет развёртывание прокси-сервера API при его сохранении. Перед повторным развёртыванием прокси-сервера API необходимо отредактировать базовый путь, сделав его уникальным.

    Используйте подстановочные знаки в базовых путях

    Используйте один или несколько подстановочных знаков /*/ в базовых путях прокси-API, чтобы ваши прокси-API не теряли актуальности в будущем. Например, базовый путь /team/*/members позволяет клиентам вызывать https://[host]/team/ blue /members и https://[host]/team/ green /members без необходимости создания новых прокси-API для поддержки новых команд. Обратите внимание, что /**/ не поддерживается.

    Описание (Необязательно) Описание API.
  8. Нажмите кнопку «Далее» .
  9. На странице Общие политики мастера настройте следующее:
  10. На странице операций WSDL выберите тип прокси API REST to SOAP to REST .

    Появится таблица со списком операций, которые Edge «обнаружил» в WSDL-файле. Вы можете выбрать и настроить операции, которые хотите включить в свой API-прокси. Таблица показана на следующем рисунке.

  11. Выберите тип порта из раскрывающегося списка, чтобы указать, какой набор операций вы хотите использовать. В WSDL элементы типа порта определяют операции, которые можно вызывать в веб-службе.
  12. При необходимости измените путь к REST API для операции. Этот путь будет использоваться в качестве имени ресурса в URL-адресе прокси-сервера API.
  13. При желании можно изменить метод HTTP ( Verb ), связанный с операцией.
  14. Нажмите кнопку «Далее» .
  15. На странице мастера «Виртуальные хосты» выберите виртуальные хосты, к которым будет привязан прокси-сервер API при развертывании. Подробнее см. в разделе «О виртуальных хостах» .
  16. Нажмите кнопку «Далее» .
  17. Выберите среду(ы) развертывания и нажмите «Создать и развернуть».
    Ваш новый API-прокси создан и развернут в выбранной среде.
  18. Нажмите «Изменить прокси» , чтобы отобразить страницу сведений о прокси-сервере API.

Classic Edge (частное облако)

Чтобы создать прокси-сервер RESTful API для службы на основе SOAP с использованием пользовательского интерфейса Classic Edge:

  1. Войдите в систему по http:// ms-ip :9000 , где ms-ip — это IP-адрес или DNS-имя узла сервера управления.
  2. Выберите API > API-прокси в верхней панели навигации.
  3. Нажмите + API Proxy .
  4. В мастере создания прокси-сервера выберите службу SOAP.
  5. Нажмите кнопку «Далее» .
  6. На странице «Подробности» выберите следующие параметры. После выбора WSDL необходимо нажать кнопку «Проверить» .
    В этой области сделай это
    WSDL

    Выберите источник WSDL.

    • URL — введите URL WSDL, который вы хотите использовать.
    • Файл — выберите WSDL-файл в вашей файловой системе. Если есть дополнительные зависимые файлы, вы можете выбрать их все.
    • Пример URL — выберите из списка WSDL-файлов для общедоступных веб-сервисов. Они удобны для тестирования функций SOAP/API-прокси в Edge.
    Имя прокси

    Это имя прокси-сервера, который вы создаете.

    Базовый путь прокси-сервера

    Фрагмент URI, который появляется после адреса http(s)://[host] вашего API-прокси. Edge использует базовый URI пути для сопоставления и маршрутизации входящих запросов к соответствующему API-прокси.

    Примечание : Базовый путь прокси-API по умолчанию соответствует значению, указанному в поле Name , преобразованному в строчные буквы.

    После базового пути следуют URL-адреса всех дополнительных ресурсов. Вот полная структура URL-адресов, которую клиенты будут использовать для вызова вашего API-прокси:

    https://[host]/ base_path / conditional_flow_path

    Примечание : Базовый путь должен быть уникальным; невозможно развернуть два прокси-сервера API с одним и тем же базовым путем. Если вы редактируете развёрнутый прокси-сервер API и задаёте базовый путь, совпадающий с базовым путём другого прокси-сервера API, Edge автоматически отменяет развёртывание прокси-сервера API при его сохранении. Перед повторным развёртыванием прокси-сервера API необходимо отредактировать базовый путь, сделав его уникальным.

    Используйте подстановочные знаки в базовых путях

    Используйте один или несколько подстановочных знаков /*/ в базовых путях прокси-API, чтобы ваши прокси-API не теряли актуальности в будущем. Например, базовый путь /team/*/members позволяет клиентам вызывать https://[host]/team/ blue /members и https://[host]/team/ green /members без необходимости создания новых прокси-API для поддержки новых команд. Обратите внимание, что /**/ не поддерживается.

    Описание Краткое описание прокси.
  7. Нажмите кнопку «Далее» .
  8. На странице WSDL выберите тип прокси API REST to SOAP to REST .

    Появится таблица со списком операций, которые Edge «обнаружил» в WSDL-файле. Вы можете выбрать и настроить операции, которые хотите включить в свой API-прокси. Таблица показана на следующем рисунке.

    На странице операций WSDL тип прокси API установлен на REST-SOAP-REST, а таблица показывает одну строку результатов с операцией добавления.

  9. В столбце «Тип порта» выберите набор операций, которые вы хотите использовать. В WSDL элементы типа порта определяют операции, которые можно вызывать в веб-службе.
  10. При желании можно изменить HTTP-метод, связанный с операцией.

    Примечание: Edge делает «наилучшее предположение» при определении HTTP-метода для каждой операции. GET обычно предпочтительнее, поскольку GET-запросы можно кэшировать.
  11. При необходимости измените путь к REST API для операции. Этот путь будет использоваться в качестве имени ресурса в URL-адресе прокси-сервера API.
  12. Пройдите остальную часть мастера, чтобы добавить безопасность, выбрать виртуальные хосты и среду развертывания.
  13. На странице «Сборка» нажмите «Сборка и развертывание» . Edge сгенерирует и развернет новый API-прокси на основе WSDL.
  14. Перейдите на страницу со сводкой по новому API-прокси. Обратите внимание, что набор ресурсов был создан на основе операций, обнаруженных в WSDL-файле.

    На странице обзора прокси-сервера список ресурсов содержит подробное описание нового API, его операций и параметров. Это представление можно рассматривать как справочную документацию по API. Edge автоматически генерирует это представление модели API. Просто разверните ресурс, чтобы увидеть его описание и путь к нему.

О последнем прокси

Когда Edge генерирует API-прокси на основе WSDL, результирующий прокси фактически представляет собой сложный поток, включающий политики для преобразования данных, извлечения и установки переменных, обработки сообщений и т. д. После создания прокси на основе WSDL взгляните на полученный поток в представлении «Разработка» интерфейса управления API. Там вы можете увидеть, какие именно политики были добавлены.

Например, на стороне запроса политика AssignMessage используется для задания целевого URL. На стороне ответа политики преобразуют ответ из XML в JSON, извлекают SOAP-часть тела ответа в переменную и задают ответное сообщение. Эти (и другие) политики добавляются автоматически при создании прокси-сервера.

Спецификация OpenAPI : Чтобы просмотреть автоматически сгенерированную спецификацию OpenAPI для этого прокси-сервера, посетите http(s)://[proxy_domain]/[proxy_base_path]/openapi.json . Однако преобразование не всегда точное, поскольку не все правила XML-схемы могут быть представлены в спецификации OpenAPI.

Создание сквозного прокси-сервера для службы на основе SOAP

В этом разделе объясняется, как создать сквозной прокси-сервер с помощью параметра «Сквозной прокси-сервер» в диалоговом окне «Создать новый прокси-сервер».

Обзор

Параметр «Pass-Through Proxy» позволяет создать прокси-сервер, который передаёт SOAP-сообщение в запросе к бэкенд-сервису «без изменений», что значительно упрощает создание прокси для веб-сервиса на основе SOAP. Edge автоматически выполняет все преобразования и другие действия, связанные с потоком данных. Например, если запрос представлен в формате JSON, Edge преобразует его в корректное XML-сообщение SOAP с правильными пространствами имен перед отправкой его сервису методом POST. Аналогично, когда сервис возвращает ответ SOAP на основе XML, Edge преобразует его обратно в JSON перед возвратом клиенту. Кроме того, Edge настраивает целевую конечную точку бэкенда, которая может меняться в зависимости от операции SOAP.

Для этого типа прокси-сервера Edge размещает WSDL-файл и создаёт поток в прокси-сервере для доступа к нему. Адрес этого WSDL-файла, размещенного на Edge, http(s)://[proxy_domain]/[proxy_base_path]?wsdl , становится новым URL-адресом конечной точки сервиса для клиентов, вызывающих SOAP-сервис через прокси-сервер.

Основные шаги

Край

Чтобы создать сквозной прокси-сервер для службы на основе SOAP с помощью Edge UI:

  1. Войдите на сайт apigee.com/edge .
  2. Выберите «Разработка» > «Прокси API» на левой панели навигации.
  3. Нажмите +Прокси .
  4. Нажмите «Служба SOAP» .
  5. На странице сведений о прокси-сервере укажите данные WSDL.
    Поле Описание
    WSDL

    Выберите источник WSDL.

    • С веб-адреса (URL) — введите или вставьте URL-адрес WSDL.
    • С моего компьютера — загрузите WSDL-файл из локального каталога. Вы можете загрузить несколько файлов, если есть зависимости.
    Имя

    Имя API-прокси.

    Базовый путь

    Фрагмент URI после адреса http(s)://[host] вашего API-прокси. Edge использует базовый URI пути для сопоставления и маршрутизации входящих запросов на соответствующий API-прокси.

    Примечание : рекомендации Apigee по управлению версиями API см. в разделе «Управление версиями» электронной книги «Проектирование веб-API: недостающее звено ».

    После базового пути указаны URL-адреса всех дополнительных ресурсов. Вот полная структура URL-адресов, которую клиенты будут использовать для вызова вашего API-прокси:

    https://[host]/ base_path /conditional_flow_path

    Примечание : Базовый путь должен быть уникальным. Если вы позже отредактируете этот прокси-сервер и установите его базовый путь таким же, как у другого прокси-сервера API, этот прокси-сервер API будет автоматически отменён при сохранении. Перед повторным развёртыванием необходимо отредактировать базовый путь.

    Использование подстановочных знаков в базовых путях

    Вы можете использовать один или несколько подстановочных знаков /*/ в базовых путях прокси-API для обеспечения совместимости с будущими потребностями. Например, базовый путь /team/*/members позволяет клиентам вызывать https://[host]/team/ blue /members и https://[host]/team/ green /members без необходимости создания новых прокси-API для поддержки новых команд. Обратите внимание, что /**/ не поддерживается.

    Примечание : Базовый путь прокси-API по умолчанию соответствует значению, указанному в поле «Имя», преобразованному в строчные буквы, если только вы явно не отредактируете содержимое поля «Базовый путь».

    Описание (Необязательно) Описание API.
  6. Нажмите кнопку «Далее» .
  7. На странице Общие политики мастера настройте следующее:
  8. На странице WSDL выберите тип прокси API Pass-Through SOAP .

  9. Выберите тип порта из раскрывающегося списка, чтобы указать, какой набор операций вы хотите использовать. В WSDL элементы типа порта определяют операции, которые можно вызывать в веб-службе.
  10. Нажмите кнопку «Далее» .
  11. На странице мастера «Виртуальные хосты» выберите виртуальные хосты, к которым будет привязан прокси-сервер API при развертывании. Подробнее см. в разделе «О виртуальных хостах» .
  12. Выберите среду(ы) развертывания и нажмите «Создать и развернуть».
    Ваш новый API-прокси создан и развернут в выбранной среде.
  13. Нажмите «Изменить прокси» , чтобы отобразить страницу сведений о прокси-сервере API.

Classic Edge (частное облако)

Чтобы создать сквозной прокси-сервер для службы на основе SOAP с помощью пользовательского интерфейса Classic Edge:

  1. Войдите в систему по http:// ms-ip :9000 , где ms-ip — это IP-адрес или DNS-имя узла сервера управления.
  2. Выберите API > API-прокси в верхней панели навигации.
  3. Нажмите + API Proxy .
  4. В мастере создания прокси-сервера выберите службу SOAP.
  5. Нажмите кнопку «Далее» .
  6. На странице «Подробности» выберите следующие параметры. После выбора WSDL необходимо нажать кнопку «Проверить» .
    В этой области сделай это
    WSDL

    Выберите источник WSDL.

    • URL — введите URL WSDL, который вы хотите использовать.
    • Файл — выберите WSDL-файл в вашей файловой системе. Если есть дополнительные зависимые файлы, вы можете выбрать их все.
    • Пример URL — выберите из списка WSDL-файлов для общедоступных веб-сервисов. Они удобны для тестирования функций SOAP/API-прокси в Edge.
    Имя прокси

    Это имя прокси-сервера, который вы создаете.

    Базовый путь прокси-сервера Базовый путь прокси-сервера — это фрагмент URI, который однозначно идентифицирует API, предоставляемый этим прокси-сервером API. API Services использует URI базового пути для сопоставления и маршрутизации входящих запросов к соответствующему прокси-серверу API. (Базовый путь добавляется к домену API, который автоматически генерируется на основе названия вашей организации и среды , в которой развёрнут прокси-сервер API.) Рекомендуется включать номер версии в имя проекта, например, /v1/delayedstockquote . Это определит, как ваш API будет вызываться потребительскими приложениями.

    Примечание : Базовый путь прокси-сервера по умолчанию соответствует значению, указанному для имени прокси-сервера, преобразованному в строчные буквы, если только вы явно не отредактируете содержимое в поле Базовый путь прокси-сервера.

    Описание Краткое описание прокси.

  8. Нажмите кнопку «Далее» .
  9. На странице WSDL выберите тип прокси-сервера API Pass-Through SOAP .

    Примечание: В таблице перечислены все операции WSDL и соответствующие им полезные данные SOAP. Это полезные данные, которые «передаются» в серверную службу SOAP.

    На странице WSDL тип прокси-сервера API установлен на сквозной SOAP, а список операций, таких как GetQuote, организован по типу порта.
  10. В столбце «Тип порта» выберите набор операций, которые вы хотите использовать. В WSDL элементы типа порта определяют операции, которые можно вызывать в веб-службе.
  11. Пройдите остальную часть мастера, чтобы добавить безопасность, выбрать виртуальные хосты и среду развертывания.
  12. На странице «Сборка» нажмите «Сборка и развертывание» . Edge сгенерирует и развернет новый API-прокси на основе WSDL.

О последнем прокси

Когда Edge генерирует сквозной прокси-сервер, результирующий прокси-сервер фактически представляет собой сложный поток, включающий политики для преобразования данных, извлечения и установки переменных, обработки сообщений и т. д. После создания сквозного прокси-сервера взгляните на полученный поток в представлении «Разработка» интерфейса управления API. Там вы можете увидеть, какие именно политики были добавлены.

Например, на следующем рисунке показана часть Target Endpoint Preflow сквозного прокси-сервера. На стороне запроса политика AssignMessage используется для задания целевого URL-адреса. На стороне ответа выполняются политики для преобразования ответа из XML в JSON, извлечения SOAP-части тела ответа в переменную и задания сообщения ответа. Эти (и другие) политики добавляются автоматически при создании прокси-сервера.

В представлении «Разработка» на панели «Поток» стрелки отображают поток от запроса до ответа, а значки — политики.

Edge-hosted WSDL : чтобы увидеть Edge-hosted WSDL, сгенерированный для этого типа прокси-сервера, перейдите по адресу http(s)://[proxy_domain]/[proxy_base_path] ?wsdl .

Расширенная разработка прокси-сервера SOAP-to-REST

В предыдущих разделах рассматривалось создание прокси-сервера API SOAP-to-REST с помощью мастера прокси-сервера API в Edge. Однако, если вам нужен более тонкий контроль над преобразованием SOAP-to-REST, вы можете обойти автоматизацию, предоставляемую мастером, и создать прокси-сервер вручную, добавляя и настраивая политики для достижения желаемого поведения. Подробнее см. в разделе «Руководство: ручное создание прокси-сервера API SOAP-to-REST в Apigee Edge» .