Как развернуть прокси API с помощью API

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

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

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

Edge API не делает никаких предположений о вашем SDLC (или чьем-либо ещё). Он предоставляет атомарные функции, которые ваша команда разработчиков может координировать для автоматизации и оптимизации жизненного цикла разработки 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.company.com/v1) должна меняться очень редко. Когда вы увеличиваете версию API, разработчики понимают, что в сигнатуре внешнего интерфейса, предоставляемого API, произошли значительные изменения.

Ревизия прокси-сервера API – это число, которое увеличивается при изменении конфигурации прокси-сервера API. Сервисы API сохраняют версии конфигураций, чтобы вы могли восстановить предыдущую конфигурацию, если что-то пойдет не так. По умолчанию номер ревизии прокси-сервера API автоматически увеличивается каждый раз, когда вы импортируете прокси-сервер API с помощью API Импорт прокси API. Если вы не хотите увеличивать номер ревизии прокси-сервера API, используйте API Update API proxy revision (Обновить ревизию прокси API). Если вы используете Maven для развертывания, воспользуйтесь вариантами clean или update, как описано в файле README плагина Maven.

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

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 в рабочей среде, вы сможете опубликовать prod URL для внешних разработчиков.

Как получить список сред

В каждой организации 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. Информация

Сначала отмените развертывание существующей версии. Укажите название среды и номер версии прокси-сервера 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 новый трафик будет направляться в нее. Новый трафик не направляется на версию 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: список именованных конечных точек прокси-сервера.
• Resources – список ресурсов (JavaScript, Python, Java, XSLT), которые можно выполнить в этом прокси-сервере API.
• TargetServers – список именованных целевых серверов (которые можно создать с помощью API управления), используемых в расширенных конфигурациях для балансировки нагрузки.
• 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

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

Теперь создайте сценарий командной строки, который импортирует эти настройки и использует их для вызова инструмента развертывания. (Пример можно найти в разделе Примеры платформы 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.

Приведенный ниже скрипт напрямую вызывает Management 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