使用 API 部署 API 代理

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

每个组织都有唯一的软件开发生命周期 (SDLC)。通常有必要将 API 代理部署与后端服务使用的进程同步和对齐。

本主题中演示的 Edge API 方法可用于将 API 代理管理集成到组织的 SDLC 中。此 API 的一个常见用途是编写脚本或代码，以部署 API 代理或将 API 代理从一个环境迁移到另一个环境，这也是大型自动化流程的一部分，该流程还部署或迁移其他应用。

Edge API 对您的 SDLC（或者其他任何人的 SDLC）不做任何假设。相反，它公开了可由开发团队协调的原子函数，以自动化和优化 API 开发生命周期。

如需了解完整信息，请参阅 Edge API。

如需使用 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

您可以对组织中的任何 API 代理调用 GET 方法。此调用会返回 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 服务会维护配置的修订版本，以便您在出现问题时恢复配置。默认情况下，每次使用 Import an API proxy API 导入 API 代理时，该 API 代理的修订版本都会自动递增。如果您不想递增 API 代理的修订版本，请使用更新 API 代理修订版本 API。如果您使用 Maven 进行部署，请使用 clean 或 update 选项，如 Maven 插件 README 中所述。

例如，您可以对 API 代理修订版本 1 调用 GET 方法，以获取详细视图。

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 代理配置为可正确接收和转发请求后，您可以将其部署到一个或多个环境。通常，您会在 test 中迭代 API 代理，然后在准备就绪后，将 API 代理修订版本提升到 prod。通常，您会发现测试环境中的 API 代理修订版本比生产环境中的多得多，这主要是因为您在生产环境中进行的迭代要少得多。

API 代理在部署到环境之前无法调用。将 API 代理修订版本部署到生产环境后，您便可以将 prod 网址发布给外部开发者。

如何列出环境

Apigee Edge 中的每个组织至少有两个环境：test 和 prod。这种区分是任意的。这样做的目的是为您提供一个区域，让您可以在向外部开发者开放 API 代理之前验证其是否正常运行。

每个环境实际上只是一个网络地址，因此您可以在正在构建的 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 完全部署后，新流量会发送到修订版本 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 API，因此您只需使用 POST 方法以及 JSON 或 XML 载荷，针对同一资源创建 API 代理。

系统会生成 API 代理的配置文件。API 代理的默认表示法是 JavaScript 对象表示法 (JSON)。以下是针对上述 POST 请求（创建名为 weatherapi 的 API 代理）的默认 JSON 响应。下面介绍了配置中的每个元素：

{
  "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：创建 API 代理的 Apigee Edge 用户的电子邮件地址
  • DisplayName：API 代理的易记名称
  • LastModifiedAt：生成 API 代理的时间，以 UNIX 时间格式表示
  • LastModifiedBy：创建 API 代理的 Apigee Edge 用户的电子邮件地址
  • Policies：已添加到此 API 代理的政策的列表
  • ProxyEndpoints：已命名的 ProxyEndpoint 的列表
  • Resources：可在相应 API 代理中执行的资源（JavaScript、Python、Java、XSLT）的列表
  • TargetServers：已命名的 TargetServer 列表（可以使用管理 API 创建），用于高级配置以实现负载均衡
  • TargetEndpoints：命名 TargetEndpoint 的列表

请注意，使用上述简单的 POST 方法创建的 API 代理配置的许多元素都是空的。在以下主题中，您将了解如何添加和配置 API 代理的关键组件。

您还可以在 API 代理配置参考中了解这些配置元素。

针对 API 编写脚本

GitHub 上提供的使用示例 API 代理包含封装了 Apigee 部署工具的 shell 脚本。如果出于某种原因，您无法使用 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

上述文件可让封装部署工具的 shell 脚本使用您的所有设置。

现在，创建一个 shell 脚本，用于导入这些设置并使用它们来调用部署工具。 （如需查看示例，请参阅 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

编写简单的 shell 脚本来自动执行上传和部署 API 代理的过程会很有用。

以下脚本直接调用管理 API。它会取消部署您要更新的 API 代理的现有修订版本，从包含代理配置文件的 /apiproxy 目录创建 ZIP 文件，然后上传、导入和部署该配置。

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