使用 API 部署 API 代理

<ph type="x-smartling-placeholder"></ph> 您正在查看 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 代理的名称以及关联的 revision，其中包含一个关联编号。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 插件中所述 自述文件。

例如，您可以在 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 代理修订版本部署到生产环境后，您就可以将 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 文档。 信息

首先，取消部署现有修订版本。指定环境名称和修订版本号 要取消部署的 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，即表示一个修订版本 应基于当前部署的修订版本进行部署。其结果是， 部署序列反转：部署新的修订版本， 完成后，已部署的修订版本将被取消部署。

以下示例通过将 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 代理的 ID 号）：

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)。以下是对上述 POST 请求的默认 JSON 响应： 该命令创建了一个名为 weatherapi 的 API 代理。配置文件中每个元素的说明 如下：

{
  "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：可供用户使用的资源（JavaScript、Python、Java、XSLT）列表 在此 API 代理中执行
  • TargetServers：已命名 TargetServer 的列表（可使用 Management API），用于实现负载均衡目的的高级配置
  • TargetEndpoints：已命名的 TargetEndpoint 的列表

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

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

针对 API 编写脚本

使用示例 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 脚本，用于导入这些设置并使用它们来调用部署工具。 （有关示例，请参见 <ph type="x-smartling-placeholder"></ph> 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 代理

以下脚本会直接调用 Management 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