Развертывание прокси-серверов API с помощью API

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

У каждой организации свой уникальный жизненный цикл разработки программного обеспечения (SDLC). Зачастую необходимо синхронизировать и согласовать развертывание API-прокси с процессами, используемыми для бэкэнд-сервисов.

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

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

Для получения полной информации см. Edge API .

Для использования Edge API необходимо пройти аутентификацию при выполнении запросов. Это можно сделать одним из следующих способов:

• OAuth2 (только для публичного облака)
• SAML (публичное и частное облако)
• Базовая аутентификация (не рекомендуется; публичные и частные облачные сервисы)

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

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

Взаимодействие с API

Следующие шаги продемонстрируют вам простые способы взаимодействия с API.

Перечислите API в вашей организации

Для начала можно составить список всех API-прокси в вашей организации. (Не забудьте заменить поля EMAIL:PASSWORD и ORG_NAME . Инструкции см. в разделе «Использование Edge API» ).

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis

Пример ответа:

[ "weatherapi" ]

Получить API

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

curl -u EMAIL:PASSWORD -H "Accept: application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi

Пример ответа:

{
  "name" : "weatherapi",
  "revision" : [ "1" ]
}

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

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

Получить версию API

Версия API (например, api.company.com/v1 ) должна меняться очень редко. Увеличение версии API сигнализирует разработчикам о существенных изменениях в сигнатуре внешнего интерфейса, предоставляемого API.

Номер ревизии API-прокси — это увеличивающийся номер, связанный с конфигурацией API-прокси. API Services поддерживает ревизии ваших конфигураций, чтобы вы могли отменить конфигурацию, если что-то пошло не так. По умолчанию номер ревизии API-прокси автоматически увеличивается каждый раз, когда вы импортируете API-прокси с помощью API «Импорт API-прокси» . Если вы не хотите увеличивать номер ревизии API-прокси, используйте API «Обновить номер ревизии API-прокси» . Если вы используете Maven для развертывания, используйте параметры clean или update , как описано в файле README плагина Maven .

Например, вы можете вызвать метод GET для API-прокси версии 1, чтобы получить подробную информацию.

curl -u EMAIL:PASSWORD -H "Accept:application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1

Пример ответа

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1343178905169,
  "createdBy" : "andrew@apigee.com",
  "lastModifiedAt" : 1343178905169,
  "lastModifiedBy" : "andrew@apigee.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

Эти элементы конфигурации API-прокси подробно описаны в справочнике по конфигурации API-прокси .

Развертывание API в среде

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

API-прокси нельзя вызвать, пока он не будет развернут в рабочей среде. После развертывания версии API-прокси в продакшене вы можете опубликовать URL-адрес prod для внешних разработчиков.

Как составить список сред

В Apigee Edge каждая организация имеет как минимум две среды: test и prod . Это различие условно. Цель состоит в том, чтобы предоставить вам область для проверки корректной работы вашего API-прокси, прежде чем вы откроете его для сторонних разработчиков.

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

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

Просмотр условий работы в организации

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments

Пример ответа

[ "test", "prod" ]

Изучите варианты развертывания.

Развертывание — это версия API-прокси, развернутого в определенной среде. API-прокси в развернутом состоянии доступен по сети по адресам, определенным в элементе <VirtualHost> для данной среды.

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

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

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

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

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

curl -X DELETE \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Затем разверните новую версию. Новая версия API-прокси уже должна существовать:

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Бесперебойное развертывание (нулевое время простоя)

Чтобы свести к минимуму потенциальные простои во время развертывания, используйте параметр override в методе развертывания и установите для него значение true .

Нельзя развернуть одну версию API-прокси поверх другой. Первая версия всегда должна быть удалена. Установив override в true , вы указываете, что одна версия API-прокси должна быть развернута поверх текущей развернутой версии. В результате последовательность развертывания меняется на обратную — развертывается новая версия, а после завершения развертывания уже развернутая версия удаляется.

В следующем примере значение override устанавливается путем передачи его в качестве параметра формы:

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments" \
  -d "override=true" \
  -u EMAIL:PASSWORD

Дополнительно оптимизировать развертывание можно, установив параметр delay . Параметр delay задает временной интервал в секундах, до истечения которого предыдущая версия должна быть удалена. В результате у незавершенных транзакций есть временной интервал, в течение которого они должны завершиться, прежде чем API-прокси, обрабатывающий их транзакцию, будет удален. Ниже показано, что происходит при override=true и установленном параметре delay :

• Первая версия обрабатывает запросы.
• Вторая версия внедряется параллельно.
• После полного развертывания версии 2 новый трафик будет направляться на версию 2. На версию 1 новый трафик не будет направляться.
• Однако, версия 1 может все еще обрабатывать существующие транзакции. Установив параметр delay (например, 15 секунд), вы даете версии 1 15 секунд на завершение обработки существующих транзакций.
• По истечении указанного периода задержки версия 1 отменяется.

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments?delay=15" \
  -d "override=true" \
  -u EMAIL:PASSWORD

При использовании override=true вместе с delay можно исключить ответы HTTP 5XX во время развертывания. Это связано с тем, что обе версии API-прокси будут развернуты одновременно, при этом более старая версия будет удалена после истечения задержки.

Посмотреть все развертывания версии API

Иногда возникает необходимость получить список всех развернутых в данный момент версий API-прокси.

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1/deployments \
  -u EMAIL:PASSWORD

{
  "aPIProxy" : "weatherapi",
  "environment" : [ {
    "configuration" : {
      "basePath" : "",
      "steps" : [ ]
    },
    "name" : "test",
    "server" : [ {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "90096dd1-1019-406b-9f42-fbb80cd01200"
    }, {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "7d6e2eb1-581a-4db0-8045-20d9c3306549"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "1619e2d7-c822-45e0-9f97-63882fb6a805"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "8a5f3d5f-46f8-4e99-b4cc-955875c8a8c8"
    } ],
    "state" : "deployed"
  } ],
  "name" : "1",
  "organization" : "org_name"
}

Приведённый выше ответ содержит множество параметров, специфичных для внутренней инфраструктуры Apigee Edge. Если вы не используете Apigee Edge в локальной среде, изменить эти настройки невозможно.

Важные свойства, содержащиеся в ответе, — это organization , environment , aPIProxy , name и state . Проверив значения этих свойств, вы можете убедиться, что в среде развернута конкретная версия API-прокси.

Посмотреть все развертывания в тестовой среде

Также вы можете получить статус развертывания для конкретной среды (включая номер ревизии текущего развернутого API-прокси), используя следующий вызов:

curl -u EMAIL:PASSWORD
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/test/deployments

Это даёт тот же результат, что и выше, для каждого API, развёрнутого в тестовой среде.

Просмотрите все развертывания в вашей организации.

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

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/deployments \
  -u EMAIL:PASSWORD

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

Поскольку API является RESTful, вы можете просто использовать метод POST вместе с полезной нагрузкой в ​​формате JSON или XML для обращения к тому же ресурсу, чтобы создать прокси-сервер API.

Для вашего API-прокси создан профиль. По умолчанию API-прокси представлен в формате JSON (JavaScript Object Notation). Ниже приведён стандартный JSON-ответ на приведённый выше POST запрос, который создал API-прокси с именем weatherapi . Далее следует описание каждого элемента профиля:

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1357172145444,
  "createdBy" : "you@yourcompany.com",
  "displayName" : "weatherapi",
  "lastModifiedAt" : 1357172145444,
  "lastModifiedBy" : "you@yourcompany.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

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

• APIProxy revision : Последовательно пронумерованная итерация конфигурации API-прокси, поддерживаемая службами API.
• APIProxy name : уникальное имя API-прокси.
• ConfigurationVersion : Версия API-сервисов, которой соответствует конфигурация API-прокси.
• CreatedAt : Время создания API-прокси, отформатированное в формате UNIX.
• CreatedBy : Адрес электронной почты пользователя Apigee Edge, создавшего API-прокси.
• DisplayName : Удобное для пользователя имя для API-прокси.
• LastModifiedAt : Время создания API-прокси, отформатированное в формате UNIX.
• LastModifiedBy : Адрес электронной почты пользователя Apigee Edge, создавшего API-прокси.
• Policies : Список политик, добавленных к этому API-прокси.
• ProxyEndpoints : Список именованных ProxyEndpoints
• Resources : Список ресурсов (JavaScript, Python, Java, XSLT), доступных для выполнения в этом API-прокси.
• TargetServers : Список именованных целевых серверов (которые можно создать с помощью API управления), используемых в расширенных конфигурациях для балансировки нагрузки.
• TargetEndpoints : Список именованных целевых конечных точек.

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

Также вы можете ознакомиться с информацией об этих элементах конфигурации в справочнике по настройке API-прокси .

Создание скриптов для работы с API

Примеры API-прокси , доступные на GitHub, содержат скрипты оболочки, которые инкапсулируют инструмент развертывания Apigee. Если по какой-либо причине вы не можете использовать инструмент развертывания на Python, вы можете вызвать API напрямую. Оба подхода продемонстрированы в приведенных ниже примерах скриптов.

Обертывание инструмента развертывания

Во-первых, убедитесь, что инструмент развертывания Python доступен в вашей локальной среде.

Затем создайте файл для хранения ваших учетных данных. Написанные вами скрипты развертывания импортируют эти настройки, что поможет вам централизованно управлять учетными данными для вашей учетной записи. В примере API Platform этот файл называется setenv.sh .

#!/bin/bash

org="Your ORG on enterprise.apigee.com"
username="Your USERNAME on enterprise.apigee.com"

# While testing, it's not necessary to change the setting below
env="test"
# Change the value below only if you have an on-premise deployment
url="https://api.enterprise.apigee.com"
# Change the value below only if you have a custom domain
api_domain="apigee.net"

export org=$org
export username=$username
export env=$env
export url=$url
export api_domain=$api_domain

Приведённый выше файл делает все ваши настройки доступными для скриптов оболочки, которые являются оболочкой инструмента развертывания.

Теперь создайте скрипт оболочки, который импортирует эти настройки и использует их для вызова инструмента развертывания. (Пример можно найти в примерах платформы API Apigee .)

#!/bin/bash

source path/to/setenv.sh

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Deploying $proxy to $env on $url using $username and $org

path/to/deploy.py -n {api_name} -u $username:$password -o $org -h $url -e $env -p / -d path/to/apiproxy

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

#!/bin/bash

echo Using org and environment configured in /setup/setenv.sh

source /path/to/setenv.sh

set -x

curl "http://$org-$env.apigee.net/{api_basepath}"

Прямой вызов API

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

Приведённый ниже скрипт напрямую вызывает API управления. Он удаляет существующую версию обновляемого вами API-прокси, создаёт ZIP-файл из каталога /apiproxy , содержащий файлы конфигурации прокси, а затем загружает, импортирует и развертывает конфигурацию.

#!/bin/bash

#This sets the name of the API proxy and the basepath where the API will be available
api=api

source /path/to/setenv.sh

echo Delete the DS_store file on OSX

echo find . -name .DS_Store -print0 | xargs -0 rm -rf
find . -name .DS_Store -print0 | xargs -0 rm -rf

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Undeploy and delete the previous revision

# Note that you need to explicitly update the revision to be undeployed.
# One benefit of the Python deploy tool is that it manages this for you.

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X DELETE

curl -k -u $username:$password -X DELETE "$url/v1/o/$org/apis/$api/revisions/1"

rm -rf $api.zip

echo Create the API proxy bundle and deploy

zip -r $api.zip apiproxy

echo Import the new revision to $env environment 

curl -k -v -u $username:$password "$url/v1/o/$org/apis?action=import&name=$api" -T $api.zip -H "Content-Type: application/octet-stream" -X POST

echo Deploy the new revision to $env environment 

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X POST