Как предоставить доступ к сервису SOAP через прокси API

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

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

В этом видео показано комплексное преобразование сервиса SOAP в сервис REST с помощью Apigee Edge и мастера прокси-сервера API. Однако, если вы хотите более детально контролировать преобразование SOAP в REST, вы можете создать прокси-сервер с помощью правил. Подробнее о создании прокси API SOAP-to-REST в Apigee Edge…

Создание прокси-сервера API RESTful для сервиса на основе 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.

Основные действия

Edge

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

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

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

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

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

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

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

    https://[host]/base_path/conditional_flow_path

    NOTE Базовый путь должен быть уникальным. Нельзя развернуть два прокси API с одинаковым базовым путем. Если вы измените развернутый прокси API и зададите для базового пути то же значение, что и для базового пути другого прокси API, Edge автоматически отменит развертывание прокси API при сохранении. Чтобы повторно развернуть прокси API, необходимо изменить базовый путь, чтобы он стал уникальным.

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

    Используйте один или несколько подстановочных знаков /*/ в базовых путях прокси-сервера API, чтобы обеспечить совместимость прокси-сервера API с будущими версиями. Например, если базовый путь – /team/*/members, клиенты смогут вызывать https://[host]/team/blue/members и https://[host]/team/green/members, и вам не придется создавать новые прокси API для поддержки новых команд. Обратите внимание, что /**/ не поддерживается.
    Описание Описание API (необязательно).
  8. Нажмите Далее.
  9. На странице Распространенные правила мастера настройте следующие параметры:
    • Требования к авторизации в разделе Безопасность: авторизация. Подробнее о защите аккаунта…
    • Поддержка совместного использования ресурсов между разными источниками (CORS) в разделе Безопасность: браузер. Подробнее о добавлении поддержки CORS…
    • Квоты для защиты бэкенд-службы от высокого трафика в разделе Quota. Подробнее о квотах… (Недоступно, если выбран вариант "Сквозная авторизация".)
  10. На странице WSDL operations (Операции WSDL) выберите тип прокси-сервера API REST to SOAP to REST (REST в SOAP в REST).

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

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

Классическая версия Edge (частное облако)

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

  1. Войдите в http://ms-ip:9000, где ms-ip – это IP-адрес или DNS-имя узла сервера управления.
  2. На панели навигации вверху страницы выберите API > Прокси API.
  3. Нажмите + API Proxy (Прокси API).
  4. В мастере создания прокси-сервера выберите сервис SOAP.
  5. Нажмите Далее.
  6. На странице "Подробности" выберите следующие варианты: После выбора WSDL-файла необходимо нажать Validate (Проверить).
    В этом поле выполните следующие действия
    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 to SOAP to REST (REST – SOAP – REST), а в таблице показана одна строка результатов с операцией add.

  9. В столбце "Тип порта" выберите набор операций, которые вы хотите использовать. В WSDL элементы portType определяют операции, которые можно вызывать в веб-сервисе.
  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. Адрес WSDL, размещенного на Edge, http(s)://[proxy_domain]/[proxy_base_path]?wsdlстановится новым URL конечной точки сервиса для клиентов, вызывающих сервис SOAP через прокси-сервер.

Основные действия

Edge

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

  1. Войдите в аккаунт на сайте apigee.com/edge.
  2. На панели навигации слева выберите Develop > API Proxies (Разработка > Прокси 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 элементы portType определяют операции, которые можно вызывать в веб-сервисе.
  10. Нажмите Далее.
  11. На странице Virtual hosts (Виртуальные хосты) мастера выберите виртуальные хосты, с которыми будет связан прокси-сервер API при развертывании. Подробнее о виртуальных хостах…
  12. Выберите среду развертывания и нажмите Создать и развернуть
    Новый прокси-сервер API будет создан и развернут в выбранной среде.
  13. Нажмите Изменить прокси, чтобы открыть страницу с информацией о прокси API.

Классическая версия Edge (частное облако)

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

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

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

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

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

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

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

    Примечание. Появится таблица со списком операций WSDL и соответствующих полезных нагрузок SOAP. Это полезная нагрузка, которая "передается" в серверную службу SOAP.

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

О конечном прокси-сервере

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

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

В режиме разработки на панели Flow стрелки показывают путь от запроса к ответу, а значки обозначают правила.

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

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

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