Создайте простой API-прокси

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

Apigee Edge позволяет быстро предоставлять доступ к серверным сервисам в виде API. Для этого создается API-прокси, который предоставляет фасад для серверного сервиса, который вы хотите сделать доступным. Вам нужно лишь указать сетевой адрес серверного сервиса, а также некоторую информацию, которую Edge использует для создания API-прокси, доступного разработчикам.

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

Посмотрите это видео, чтобы получить общее представление о процессе создания API-прокси.

Создание API-прокси с помощью пользовательского интерфейса

Самый простой способ создать API-прокси — использовать мастер создания прокси.

Край

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

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

Мастер создания прокси отображает и пошагово объясняет процесс создания и добавления минимального набора функций к API-прокси.

На первой странице мастера создания прокси-сервера вам предлагается выбрать обратный прокси, службу SOAP, «Без цели» или «Пакет прокси» для настройки процесса работы мастера.

Классический Edge (частное облако)

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

  1. Войдите в систему по http:// ms-ip :9000 , где ms-ip — это IP-адрес или DNS-имя узла сервера управления.
  2. В верхней панели навигации выберите API > API-прокси .
  3. Нажмите + API-прокси .

Мастер создания прокси отображает и пошагово объясняет процесс создания и добавления минимального набора функций к API-прокси.

На первой странице мастера создания прокси-сервера вам предлагается выбрать обратный прокси, службу SOAP, «Без цели» или «Пакет прокси» для настройки процесса работы мастера.

На первой странице мастера можно создать API-прокси из следующих источников:

Тип Описание
Обратный прокси (наиболее распространенный вариант)

API-прокси, который перенаправляет входящие запросы к существующим HTTP-сервисам. Может быть JSON или XML API. См. раздел «Создание обратного прокси для HTTP-сервиса» далее в этом разделе.

Нажмите «Использовать спецификацию OpenAPI» , чтобы сгенерировать прокси на основе действительной спецификации OpenAPI. Дополнительную информацию об этой опции см. в разделе «Использование спецификаций OpenAPI для генерации прокси» далее в этом разделе.

SOAP-сервис API-прокси, сгенерированный из WSDL-файла. См. раздел «Предоставление доступа к веб-сервису на основе SOAP в качестве API-прокси» .
Цель отсутствует

API-прокси без бэкэнда API («без цели»). Аналогично созданию обратного прокси для HTTP-сервиса, описанному ранее, за исключением того, что при определении параметров API-прокси вам не нужно указывать существующий API.

Нажмите «Использовать спецификацию OpenAPI» , чтобы сгенерировать прокси на основе допустимой спецификации OpenAPI. Дополнительную информацию об этой опции см. в разделе «Использование спецификаций OpenAPI для генерации прокси» далее в этом разделе.

Размещенный целевой объект

API-прокси, который перенаправляет запросы к приложению Node.js, развернутому в среде Hosted Targets. См. обзор Hosted Targets .

Загрузка пакета прокси Существующий пакет API-прокси (например, один из примеров API-прокси, доступных на GitHub). См. раздел «Импорт API-прокси из пакета API-прокси» .

В следующих разделах описано, как создать API-прокси, используя каждый из источников.

Создание обратного прокси для HTTP-сервиса

Edge генерирует обратные прокси-серверы на основе двух элементов информации:

  • URL серверной службы
  • URI-путь, однозначно идентифицирующий API, который будет предоставляться API-прокси приложениям-потребителям.

URL-адрес серверной части обычно представляет собой приложение, поддерживающее данную службу и принадлежащее вашей организации. Он также может указывать на общедоступный API. API или служба могут находиться под вашим контролем (например, внутреннее приложение для управления персоналом или приложение Rails в облаке) или это может быть сторонний API или служба (например, Twitter или Instagram).

Край

  1. Воспользуйтесь мастером создания прокси-сервера, как описано в разделе «Создание API-прокси с помощью пользовательского интерфейса» ранее в этом разделе.
  2. В мастере создания прокси-сервера нажмите «Обратный прокси (наиболее распространенный вариант)» . Чтобы сгенерировать прокси-сервер на основе существующей действительной спецификации OpenAPI, нажмите « Использовать спецификацию OpenAPI ». Подробную информацию об этом параметре см. в разделе «Использование спецификаций OpenAPI для генерации прокси-серверов» ниже.
  3. На странице «Подробности» мастера введите следующую информацию.
    Поле Описание
    Имя Название, отображаемое для вашего 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.
    Целевой объект (существующий API) URL-адрес серверной части, которую вызывает этот API-прокси.
  4. На странице «Общие политики» мастера настройте следующие параметры:
  5. На странице «Виртуальные хосты» мастера выберите виртуальные хосты, к которым будет привязываться API-прокси после развертывания. Дополнительную информацию см. в разделе «О виртуальных хостах» .
  6. На странице «Сводка» выберите среду(ы) развертывания (при необходимости) и нажмите «Создать и развернуть» .

    Ваш новый API-прокси создан и развернут в выбранной среде.

  7. Нажмите «Редактировать прокси» , чтобы отобразить страницу с подробной информацией о прокси-сервере API.

Классический Edge (частное облако)

  1. Воспользуйтесь мастером создания прокси-сервера, как описано в разделе «Создание API-прокси с помощью пользовательского интерфейса» ранее в этом разделе.
  2. В мастере создания прокси выберите «Обратный прокси» (наиболее распространенный вариант) . Чтобы сгенерировать прокси на основе существующей действительной спецификации OpenAPI, нажмите « Использовать OpenAPI» . Подробную информацию об этом параметре см. в разделе «Использование спецификаций OpenAPI для генерации прокси» ниже.
  3. Нажмите «Далее» .
  4. На странице «Подробности» мастера введите следующую информацию.
    Поле Описание
    Имя прокси Название, отображаемое для вашего 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 URL-адрес, который платформа API вызывает от имени приложений, обращающихся к вашему API через URL-адрес прокси-сервера API.
    Описание Описание API.
  5. На странице «Безопасность » мастера настройте следующие параметры:
  6. На странице «Виртуальные хосты» мастера выберите виртуальные хосты, к которым будет привязываться API-прокси после развертывания. Дополнительную информацию см. в разделе «О виртуальных хостах» .
  7. Выберите среду(ы) развертывания и нажмите «Создать и развернуть».
    Вам будет отправлено подтверждение о том, что ваш новый API-прокси был успешно создан и развернут в выбранной среде.
  8. Нажмите кнопку «Просмотреть прокси <имя прокси>» в редакторе , чтобы отобразить страницу с подробными сведениями о прокси API.

Импорт API-прокси из пакета API-прокси

Часто API-прокси определяются как набор XML-файлов, а также любых других вспомогательных файлов. Определив API-прокси как набор файлов, внешних по отношению к Edge, вы можете поддерживать их в системе контроля версий, а затем импортировать в Edge для тестирования и развертывания.

Посмотрите это видео, чтобы узнать, как создать и импортировать API-прокси из пакета API-прокси.

Край

Для импорта API-прокси из пакета API-прокси:

  1. Воспользуйтесь мастером создания прокси-сервера, как описано в разделе «Создание API-прокси с помощью пользовательского интерфейса» ранее в этом разделе.
  2. Нажмите «Загрузить пакет прокси» .
  3. На странице «Загрузка пакета прокси» в мастере настройки прокси введите следующую информацию.

    Поле Описание
    ZIP-архив ZIP-архив, содержащий конфигурацию API-прокси. Перетащите файл или щелкните по нему, чтобы перейти к нужному файлу.
    Имя Отображаемое имя для вашего API. По умолчанию используется имя ZIP-файла без расширения.
  4. Нажмите «Далее» .
  5. На странице «Сводка» выберите среду(ы) развертывания (при необходимости) и нажмите «Создать и развернуть».
    Отображается подтверждение того, что ваш новый API-прокси был успешно создан.
  6. Нажмите «Редактировать прокси» , чтобы отобразить страницу с подробной информацией о прокси-сервере API.

Классический Edge (частное облако)

  1. Воспользуйтесь мастером создания прокси-сервера, как описано в разделе «Создание API-прокси с помощью пользовательского интерфейса» ранее в этом разделе.
  2. В мастере создания прокси-сервера выберите «Пакет прокси» .
  3. Нажмите «Далее» .
  4. На странице «Подробности» в мастере настройки прокси-сервера введите следующую информацию.

    Поле Описание
    ZIP-архив Нажмите «Выбрать файл» и найдите ZIP-архив, содержащий конфигурацию API-прокси.
    Имя прокси Название, отображаемое для вашего API.
  5. Просмотрите информацию о сборке и нажмите «Собрать».
    В случае успеха отобразится сообщение, и Edge автоматически развернет импортированный API-прокси в выбранной среде вашей организации. API, предоставляемый API-прокси, станет доступен для вызова.
  6. Нажмите кнопку «Просмотреть прокси <имя прокси>» в редакторе, чтобы отобразить страницу с подробными сведениями о прокси API.
  7. Для развертывания прокси-сервера щелкните раскрывающийся список «Развертывание» , выберите среду, в которую хотите выполнить развертывание, и ответьте на запрос.

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

В мастере создания прокси-сервера щелкните «Сервис SOAP» и следуйте инструкциям мастера, чтобы создать сквозной или REST-прокси для сервиса SOAP. Подробности см. в разделе «Предоставление доступа к сервису SOAP в качестве API-прокси» .

Повышение безопасности

На странице «Общие политики» (Edge) или «Безопасность» (Classic Edge) мастера создания прокси-сервера выберите тип авторизации безопасности, который вы хотите добавить. В следующей таблице приведено краткое описание доступных вариантов:

Авторизация безопасности Описание
Ключ API Добавляет простую проверку ключа API к определяемому вами API-прокси. В ответ платформа API добавляет к вашему API-прокси политику VerifyAPIKey и политику AssignMessage. Политика VerifyAPIKey проверяет ключи API, предоставляемые запрашивающими приложениями. Политика AssignMessage удаляет ключ API, предоставленный в вызове API в качестве параметра запроса, из запроса, перенаправляемого на бэкэнд-сервер.
OAuth 2.0 Добавляет аутентификацию на основе OAuth 2.0 к вашему API-прокси. Apigee Edge автоматически добавляет две политики к вашему API-прокси: одну политику для проверки токена доступа и другую политику для удаления токена доступа из сообщения перед его пересылкой в ​​ваш бэкэнд-сервис. Чтобы узнать, как получить токен доступа, см. OAuth .
Проезд без разрешения Авторизация не требуется. Запросы передаются на бэкэнд без каких-либо проверок безопасности в Apigee Edge.

Добавлена ​​поддержка CORS.

CORS (Cross-origin resource sharing) — это стандартный механизм, позволяющий веб-браузеру отправлять прямые запросы к другому домену. Стандарт CORS определяет набор HTTP-заголовков, которые веб-браузеры и серверы используют для реализации междоменной связи.

Добавить поддержку CORS в ваш API можно, выбрав «Добавить заголовки CORS» на странице «Общие политики» (Edge) или «Безопасность» (Classic Edge) мастера создания прокси.

Для получения более подробной информации о поддержке CORS, включая добавление поддержки CORS-проверки к прокси-серверу, см. раздел «Добавление поддержки CORS к API-прокси» .

Использование спецификаций OpenAPI для генерации прокси.

В этом разделе обсуждается опция «Использовать OpenAPI», доступная для генерации из спецификации OpenAPI следующих типов API-прокси: обратный, Node.js или без целевого объекта.

Что такое спецификация OpenAPI?

Логотип Open API Initiative «Инициатива Open API (OAI) сосредоточена на создании, развитии и продвижении независимого от поставщиков формата описания API, основанного на спецификации Swagger». Для получения дополнительной информации об инициативе Open API см. https://openapis.org .

Спецификация OpenAPI использует стандартный формат для описания RESTful API. Написанная в формате JSON или YAML, спецификация OpenAPI является машиночитаемой, но при этом легко читается и понимается человеком. Спецификация описывает такие элементы API, как его базовый путь, пути и глаголы, заголовки, параметры запроса, операции, типы контента, описания ответов и многое другое. Кроме того, спецификация OpenAPI часто используется для генерации документации API.

Вот фрагмент спецификации OpenAPI, описывающий сервис имитации целевых объектов Apigee: http://mocktarget.apigee.net . Более подробную информацию можно найти по ссылке : https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi .

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
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

С помощью мастера создания прокси вы можете импортировать спецификацию OpenAPI и использовать ее для генерации API-прокси. После генерации прокси вы можете использовать пользовательский интерфейс Edge для его дальнейшей разработки, добавляя политики, реализуя пользовательский код и так далее — как и любой другой прокси Edge.

Создание API-прокси на основе спецификации OpenAPI

Создавайте API-прокси на основе спецификации OpenAPI. Всего за несколько кликов вы получите API-прокси с автоматически сгенерированными путями, параметрами, условными потоками и целевыми конечными точками. Затем вы можете добавить такие функции, как безопасность OAuth, ограничение скорости запросов и кэширование.

В мастере создания прокси нажмите «Использовать спецификацию OpenAPI» и следуйте инструкциям мастера, чтобы создать обратный прокси или прокси без целевого объекта на основе спецификации OpenAPI. Подробности см. в разделе «Создание прокси API на основе спецификации OpenAPI» .

Посмотрите это видео, чтобы узнать, как создать API-прокси на основе спецификации OpenAPI.

Обновление потоков в API-прокси с использованием спецификации OpenAPI.

После создания API-прокси на основе спецификации OpenAPI, если вы измените спецификацию, добавив дополнительные пути к ресурсам, вы сможете использовать спецификацию для добавления соответствующих условных потоков к API-прокси.

Для обновления потоков в API-прокси с использованием спецификации OpenAPI:

  1. Добавьте новые пути к ресурсам в спецификацию OpenAPI. См. раздел «Редактирование существующей спецификации OpenAPI» .
  2. Откройте API-прокси в пользовательском интерфейсе и перейдите на вкладку «Разработка» .
  3. В окне навигатора нажмите кнопку «+» рядом с конечной точкой прокси, которую вы хотите обновить.
    Открывается диалоговое окно «Новый условный поток».
  4. Нажмите « Из OpenAPI», если этот пункт еще не выбран.
    Если в спецификации OpenAPI есть ресурсы, для которых в прокси-сервере API отсутствует соответствующий условный поток, они отображаются в диалоговом окне, как показано на следующем рисунке. Ресурсы, которые не представлены в виде потоков в текущем API-прокси. В этом примере указаны /loveapis, /ip, /json и /xml.
  5. Выберите каждый из ресурсов, для которых вы хотите добавить условный поток.
  6. Нажмите «Добавить» .

Условные потоки добавляются в ваш API-прокси.

Создание новой версии API-прокси

Создайте новую версию API-прокси, как описано ниже.

Край

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

  1. Войдите на сайт apigee.com/edge .
  2. В левой панели навигации выберите «Разработка» > «API-прокси» .
  3. Щелкните по нужному API-прокси в списке и выберите тот, который хотите скопировать.
  4. Выберите проект > Сохранить как новую редакцию .

Классический Edge (частное облако)

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

  1. Войдите в систему по http:// ms-ip :9000 , где ms-ip — это IP-адрес или DNS-имя узла сервера управления.
  2. В верхней панели навигации выберите API > API-прокси .
  3. Щелкните по нужному API-прокси в списке и выберите тот, который хотите скопировать.
  4. Выберите проект > Сохранить как новую редакцию .

Копирование API-прокси

Скопируйте существующий API-прокси в новый API-прокси, как описано ниже.

Край

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

  1. Войдите на сайт apigee.com/edge .
  2. В левой панели навигации выберите «Разработка» > «API-прокси» .
  3. Щелкните по нужному API-прокси в списке и выберите тот, который хотите скопировать.
  4. Выберите проект > Сохранить как новый API-прокси .
  5. В диалоговом окне «Сохранить как новый прокси» введите имя нового API-прокси.
  6. Нажмите «Добавить» .

Классический Edge (частное облако)

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

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

Резервное копирование API-прокси

Вы можете создать резервную копию существующего API-прокси в виде набора XML-файлов в пакете API-прокси. После экспорта в пакет вы можете импортировать API-прокси в новый прокси, как описано в разделе «Импорт API-прокси из пакета API-прокси» ранее в этом разделе. Для получения дополнительной информации см. раздел «Загрузка API-прокси» .

Создание API-прокси с использованием API

Чтобы создать прокси API с помощью API, см. раздел «Прокси API» .