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

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

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

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

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

Полную информацию см. в разделе API Edge .

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

В этом разделе основное внимание уделяется набору 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 поддерживают версии ваших конфигураций, чтобы вы могли восстановить конфигурацию, если что-то пойдет не так. По умолчанию версия прокси-сервера API автоматически увеличивается каждый раз, когда вы импортируете прокси-сервер API с помощью API-интерфейса импорта прокси-сервера API . Если вы не хотите увеличивать версию прокси-сервера API, используйте API версии прокси-сервера API . Если вы используете Maven для развертывания, используйте параметры clean или update , как описано в файле сведений о плагине 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 , а затем, когда все готово, переводите версию прокси-сервера API в prod . Часто вы обнаружите, что у вас гораздо больше версий прокси-сервера API в тестовой среде, в первую очередь потому, что вы будете выполнять гораздо меньше итераций в рабочей среде.

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

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

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

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

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

Просмотр сред в организации

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

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

[ "test", "prod" ]

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

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

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

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

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

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

Сначала отмените развертывание существующей версии. Укажите имя среды и номер версии прокси-сервера 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 :

  • Версия 1 предназначена для обработки запросов.
  • Версия 2 развертывается параллельно.
  • Когда версия 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

По умолчанию установлено значение false (обычное поведение при развертывании: существующая редакция не развертывается, затем развертывается новая редакция).

Установите значение true , чтобы переопределить обычное поведение развертывания и обеспечить плавное развертывание. Существующая версия остается развернутой, в то время как новая версия также развертывается. При развертывании новой версии старая версия не развертывается. Используйте вместе с параметром delay , чтобы контролировать возникновение отмены развертывания.

delay

Чтобы обработка транзакции могла завершиться в существующей версии до того, как она будет отменена, а также исключить вероятность ошибок 502 Bad Gateway или 504 Gateway Timeout errors , установите для этого параметра значение в секундах, на которое вы хотите отложить развертывание. Ограничений на количество секунд, которые вы можете установить, нет, и установка большого количества секунд не влияет на производительность. Во время задержки новый трафик на старую ревизию не отправляется.

По умолчанию — 0 (ноль) секунд. Если для override установлено значение true и delay равна 0, существующая ревизия отменяется сразу после развертывания новой ревизии. Отрицательные значения рассматриваются как 0 (ноль) секунд.

Если 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 представлен в нотации объектов JavaScript (JSON). Ниже приведен ответ 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 : список именованных TargetServers (который можно создать с помощью API управления), используемый в расширенных конфигурациях для целей балансировки нагрузки.
  • TargetEndpoints : список именованных TargetEndpoints.

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

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

Скрипты против API

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

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

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

Затем создайте файл для хранения ваших учетных данных. Написанные вами сценарии развертывания будут импортировать эти параметры, помогая вам централизованно управлять учетными данными для вашей учетной записи. В примере платформы API этот файл называется 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

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

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

#!/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