构建简单的 API 代理

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

Apigee Edge 可让您将后端服务快速公开为 API。您可以创建一个 API 代理,为您要公开的后端服务提供表层。您只需要提供后端服务的网络地址,以及 Edge 用于创建向开发者公开的 API 代理的部分信息。

API 代理会将后端服务实现与开发者所用的 API 分隔开来。这样可以防止开发者日后对您的后端服务进行更改。在您更新后端服务时,开发者不受这些变更的影响,才能继续调用 API。

观看此视频,简要了解 API 代理的创建流程。

使用界面创建 API 代理

创建 API 代理的最简单方法是使用“创建代理”向导。

Edge

如需使用 Edge 界面访问“创建代理”向导,请执行以下操作:

  1. 登录 apigee.com/edge
  2. 在左侧导航栏中,选择开发 > API 代理
  3. 点击 +代理

系统会显示“创建代理”向导,引导您完成生成相应功能并向 API 代理添加基础功能的步骤。

“创建代理”向导的第一页提示您选择反向代理、SOAP 服务、无目标或代理软件包来自定义向导流程。

传统 Edge (Private Cloud)

如需使用传统版 Edge 界面访问“创建代理”向导,请执行以下操作:

  1. 登录 http://ms-ip:9000,其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。
  2. 在顶部导航栏中,依次选择 API > API 代理
  3. 点击 + API 代理

系统会显示“创建代理”向导,引导您完成生成相应功能并向 API 代理添加基础功能的步骤。

“创建代理”向导的第一页提示您选择反向代理、SOAP 服务、无目标或代理软件包来自定义向导流程。

向导的第一页允许您从以下来源创建 API 代理:

类型 说明
反向代理(最常见)

用于将传入请求路由到现有 HTTP 后端服务的 API 代理。可以是 JSON 或 XML API。请参阅本部分后面的为 HTTP 服务创建反向代理

点击使用 OpenAPI 规范,通过有效的 OpenAPI 规范生成代理。如需详细了解此选项,请参阅本部分后面的使用 OpenAPI 规范生成代理

SOAP 服务 从 WSDL 文件生成的 API 代理。请参阅公开基于 SOAP 的网络服务作为 API 代理
无目标

没有 API 后端的 API 代理(“无目标”)。与上述为 HTTP 服务创建反向代理类似,但您在定义 API 代理详细信息时不会指定现有 API。

点击使用 OpenAPI 规范,通过有效的 OpenAPI 规范生成代理。如需详细了解此选项,请参阅本部分后面的使用 OpenAPI 规范生成代理

托管的目标

一个 API 代理,用于路由到已部署到 Hosted Target 环境的 Node.js 应用。 请参阅托管目标概览

上传代理软件包 现有 API 代理软件包(例如 GitHub 上提供的一个示例 API 代理)。请参阅从 API 代理软件包导入 API 代理

以下部分介绍如何使用每个来源创建 API 代理。

为 HTTP 服务创建反向代理

Edge 根据两部分信息生成反向代理:

  • 后端服务的网址
  • 唯一标识 API 代理将向使用方应用公开的 API 的 URI 路径

后端服务网址通常表示您的组织拥有的启用服务的应用。它还可指向公开提供的 API。API 或服务可由您控管(例如,内部 HR 应用或 Cloud 中的 Rails 应用),也可以是第三方 API 或服务(例如 Twitter 或 Instagram)。

Edge

  1. 按照前面部分中的使用界面创建 API 代理所述,访问“创建代理”向导。
  2. 在“创建代理”向导中,点击反向代理(最常见)。要根据现有的有效 OpenAPI 规范生成代理,请点击使用 OpenAPI 规范。如需详细了解此选项,请参阅使用 OpenAPI 规范生成代理
  3. 在向导的详细信息页面上,输入以下信息。
    字段 说明
    名称 为您的 API 显示的名称。指定字母数字字符、短划线 (-) 或下划线 (_)。
    基本路径

    显示在 API 代理的 http(s)://[host] 地址之后的 URI 片段。边缘使用基本路径 URI 来匹配传入请求消息,并将其路由到正确的 API 代理。

    注意:API 代理基本路径默认为 Name 字段指定的值,且全部为小写。

    基本路径后是任何其他资源网址。以下是客户端用于调用您的 API 代理的完整网址结构:

    https://[host]/base_path/conditional_flow_path

    注意:基本路径必须是唯一的,您无法部署具有相同基本路径的两个 API 代理。如果您修改已部署的 API 代理并将基本路径设置为与另一个 API 代理的基本路径相同的值,则 Edge 会在您保存该 API 代理时自动取消部署该代理。在重新部署 API 代理之前,必须修改基本路径以使其唯一。

    在基本路径中使用通配符

    在 API 代理基本路径中使用一个或多个 /*/ 通配符,以使您的 API 代理可适应未来的需求。例如,/team/*/members 的基本路径允许客户端调用 https://[host]/team/blue/membershttps://[host]/team/green/members,而无需创建新的 API 代理来支持新团队。请注意,不支持 /**/

    说明 (可选)API 的说明。
    目标(现有 API) 此 API 代理调用的后端服务网址。
  4. 在向导的通用政策页面上,配置以下各项:
    • 安全性:授权下的安全授权要求。请参阅本部分后面的添加安全性
    • 支持安全性:浏览器下的跨域资源共享 (CORS)。请参阅本部分后面的添加对 CORS 的支持
    • 配额可用于在配额下保护后端服务免遭高流量访问。参见配额。(如果选择了直通式授权,则不会显示。)
    • 获利下,对启用了获利功能的组织强制执行获利限制。请参阅对 API 代理实施获利限制
  5. 在向导的虚拟主机页面上,选择 API 代理在部署时将绑定到的虚拟主机。如需了解详情,请参阅关于虚拟主机
  6. 摘要页面上,根据需要选择部署环境,然后点击创建和部署

    新的 API 代理会在所选环境中创建和部署。

  7. 点击修改代理,以显示 API 代理的详细信息页面。

传统 Edge (Private Cloud)

  1. 按照前面部分中的使用界面创建 API 代理所述,访问“创建代理”向导。
  2. 在“构建代理”向导中,选择反向代理(最常见)。如需根据现有的有效 OpenAPI 规范生成代理,请点击使用 OpenAPI。 如需详细了解此选项,请参阅下文的使用 OpenAPI 规范生成代理
  3. 点击下一步
  4. 在向导的 Details 页面上,输入以下信息。
    字段 说明
    代理名称 为您的 API 显示的名称。
    代理基本路径

    代理基本路径是 API 代理的 http(s)://[host] 地址后面的 URI 片段。边缘使用基本路径 URI 来匹配传入请求消息,并将其路由到正确的 API 代理。

    注意:如需查看 Apigee 的 API 版本控制建议,请参阅 Web API 设计:缺失的链接电子书中的版本控制

    基本路径后面是任何其他资源网址。以下是客户端用于调用 API 代理的完整网址结构:

    https://[host]/base_path/conditional_flow_path

    注意:基本路径必须是唯一的。如果您稍后修改此代理并将其基本路径设置为与另一个 API 代理相同,则当您保存此 API 代理时,系统会自动取消部署该代理。您必须先修改基本路径,然后才能重新部署它。

    在基本路径中使用通配符

    您可以在 API 代理基路径中使用一个或多个 /*/ 通配符,以便让代理能够适应未来变化。例如,借助 /team/*/members 的基本路径,客户端可以调用 https://[host]/team/blue/membershttps://[host]/team/green/members,而无需创建新的 API 代理来支持新团队。请注意,不支持 /**/。

    注意:除非您明确修改“代理基本路径”字段中的内容,否则代理基本路径会默认采用为代理名称转换为全小写形式指定的值。

    现有 API API 平台代表通过 API 代理网址调用您的 API 的应用调用的网址。
    说明 API 的说明。
  5. 在向导的 Security 页面上,配置以下内容:
  6. 在向导的 Virtual Hosts(虚拟主机)页面上,选择 API 代理在部署后将绑定到的虚拟主机。如需了解详情,请参阅关于虚拟主机
  7. 选择部署环境,然后点击构建和部署
    系统会发送确认通知,确认您已在所选环境中成功创建并部署了新的 API 代理。
  8. 点击 在编辑器中查看 <proxy name> 代理以显示 API 代理的详情页面。

从 API 代理软件包导入 API 代理

通常,您将 API 代理定义为 XML 文件的集合以及其他任何其他支持文件。通过将 API 代理定义为 Edge 以外的一组文件,您可以将它们保留在源控制系统中,然后导入 Edge 以进行测试和部署。

观看此视频,了解如何通过 API 代理软件包创建和导入 API 代理。

Edge

如需从 API 代理软件包导入 API 代理,请执行以下操作:

  1. 按照前面部分中的使用界面创建 API 代理所述,访问“创建代理”向导。
  2. 点击上传代理软件包
  3. 在代理向导的上传代理软件包页面上,输入以下信息。

    字段 说明
    ZIP 软件包 包含 API 代理配置的 ZIP 文件。拖放或点击进入该文件。
    名称 为您的 API 显示的名称。默认为不带扩展名的 ZIP 文件的名称。
  4. 点击下一步
  5. 摘要页面上,根据需要选择部署环境,然后点击创建和部署
    系统将显示确认消息,确认新 API 代理已成功创建。
  6. 点击修改代理,以显示 API 代理的详细信息页面。

传统 Edge (Private Cloud)

  1. 按照前面部分中的使用界面创建 API 代理所述,访问“创建代理”向导。
  2. 在“Build a Proxy”向导中,选择 Proxy bundle
  3. 点击下一步
  4. 在代理向导的详细信息页面上,输入以下信息。

    字段 说明
    ZIP 软件包 点击选择文件,然后找到包含 API 代理配置的 ZIP 文件。
    代理名称 为您的 API 显示的名称。
  5. 查看构建信息,然后点击 Build
    如果成功,系统会显示一条消息,Edge 自动将导入的 API 代理部署到组织中的所选环境。API 代理公开的 API 可供调用。
  6. 点击编辑器中的查看 <proxy name> 代理,以显示 API 代理的详情页面。
  7. 如需部署代理,请点击部署下拉菜单,选择要部署到的环境,然后响应提示。

公开基于 SOAP 的网络服务作为 API 代理

在“创建代理”向导中,点击 SOAP 服务,然后按照向导为 SOAP 服务创建直通或基于 REST 的代理。如需了解详情,请参阅将 SOAP 服务公开为 API 代理

添加安全措施

在“创建代理”向导的通用政策 (Edge) 或安全(经典版 Edge)页面上,选择要添加的安全授权类型。下表汇总了可用的选项:

安全授权 说明
API 密钥 对您定义的 API 代理添加简单的 API 密钥验证。为进行响应,API 平台会将 VerifyAPIKey 政策和 AssignMessage 政策添加到您的 API 代理。VerifyAPIKey 政策会验证应用所请求的 API 密钥。AssignMessage 政策从 API 调用(作为查询参数)发送到 API 调用的请求中移除该 API 密钥。
OAuth 2.0 向您的 API 代理添加基于 OAuth 2.0 的身份验证。Apigee Edge 会自动向您的 API 代理添加两项政策:一条政策用于验证访问令牌,另一条政策用于将访问令牌从消息中删除,然后再将消息转发到后端服务。如需了解如何获取访问令牌,请参阅 OAuth
经过(无授权) 无需授权。请求将传递给后端,而无需对 Apigee Edge 进行任何安全检查。

添加对 CORS 的支持

CORS(跨域资源共享)是一种标准机制,可让网络浏览器直接请求发送到其他网域。CORS 标准定义了一组网络浏览器标头用于实现跨域通信的 HTTP 标头。

您可以通过在通用政策 (Edge) 或安全(经典版 Edge)中选择添加 CORS 标头,向 API 添加 CORS 支持页面。

如需详细了解 CORS 支持(包括向代理添加 CORS 预检支持),请参阅向 API 代理添加 CORS 支持

使用 OpenAPI 规范生成代理

本部分介绍了“使用 OpenAPI”选项,该选项可用于根据 OpenAPI 规范生成以下类型的 API 代理:reverse、Node.js 或无目标。

什么是 OpenAPI 规范?

Open API 计划徽标“Open API 计划 (OAI) 专注于根据 Swagger 规范创建、改进和推广供应商中立的 API 描述格式。”如需详细了解 Open API 计划,请访问 https://openapis.org

OpenAPI 规范使用标准格式来描述 RESTful API。OpenAPI 规范采用 JSON 或 YAML 机器可读格式编写,但便于人类阅读和理解。该规范将 API 的此类元素描述为基本路径、路径和动词、标头、查询参数、操作、内容类型、响应描述等。此外,OpenAPI 规范通常用于生成 API 文档。

以下是摘自 Apigee 的模拟目标服务 (http://mocktarget.apigee.net) 的 OpenAPI 规范中的 Fragment。如需了解详情,请参阅 https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

通过“创建代理”向导,您可以导入 OpenAPI 规范并使用它来生成 API 代理。生成代理后,可以使用 Edge 界面通过添加政策、实现自定义代码等来进一步开发代理,就像任何 Edge 代理一样。

根据 OpenAPI 规范创建 API 代理

根据 OpenAPI 规范创建 API 代理。您只需点击几下,便可使用包含路径、参数、条件流和目标端点自动生成的 API 代理。然后,您可以添加 OAuth 安全机制、速率限制和缓存等功能。

在“创建代理”向导中,点击使用 OpenAPI 规范,然后按照向导从 OpenAPI 规范创建反向或无目标代理。如需了解详情,请参阅通过 OpenAPI 规范创建 API 代理

观看此视频,了解如何通过 OpenAPI 规范创建 API 代理。

使用 OpenAPI 规范更新 API 代理中的流程

在根据 OpenAPI 规范创建 API 代理后,如果您修改规范以添加其他资源路径,则可以使用该规范将关联的条件流添加到 API 代理。

如需使用 OpenAPI 规范更新 API 代理中的流程,请执行以下操作:

  1. 将新的资源路径添加到 OpenAPI 规范。请参阅修改现有 OpenAPI 规范
  2. 在用户界面中打开 API 代理,然后点击开发标签页。
  3. 在导航器中,点击您要更新的代理端点旁边的 +
    此时会打开“新条件流”对话框。
  4. 若未选择,点击来自 OpenAPI
    如果 OpenAPI 规范中的资源在 API 代理中没有对应的条件流,则会在对话框中列出这些资源,如下图所示。不属于当前 API 代理中的流的资源。此示例包括 /loveapis、/ip、/json 和 /xml。
  5. 选择要添加条件流的每个资源。
  6. 点击添加

条件流会添加到您的 API 代理。

创建 API 代理的新修订版本

创建 API 代理的新修订版本,如下所述。

Edge

如需使用 Edge 界面创建新的 API 代理修订版本,请执行以下操作:

  1. 登录 apigee.com/edge
  2. 在左侧导航栏中,选择开发 > API 代理
  3. 点击要复制的列表中的 API 代理。
  4. 依次选择项目 > 保存为新版本

传统 Edge (Private Cloud)

如需使用传统版 Edge 界面创建新的 API 代理修订版本,请执行以下操作:

  1. 登录 http://ms-ip:9000,其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。
  2. 在顶部导航栏中依次选择 API > API 代理
  3. 在列表中点击要复制的 API 代理。
  4. 依次选择项目 > 保存为新版本

复制 API 代理

将现有 API 代理复制到新的 API 代理,如下所述。

Edge

如需使用 Edge 界面复制 API 代理,请执行以下操作:

  1. 登录 apigee.com/edge
  2. 在左侧导航栏中,选择开发 > API 代理
  3. 点击要复制的列表中的 API 代理。
  4. 依次选择项目 > 另存为新 API 代理
  5. 在“另存为新代理”对话框中,输入新 API 代理的名称。
  6. 点击添加

传统 Edge (Private Cloud)

如需使用传统版 Edge 界面复制 API 代理,请执行以下操作:

  1. 登录 http://ms-ip:9000,其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。
  2. 在顶部导航栏中依次选择 API > API 代理
  3. 在列表中点击要复制的 API 代理。
  4. 依次选择项目 > 另存为新 API 代理
  5. 在“另存为新代理”对话框中,输入新 API 代理的名称。
  6. 点击添加

备份 API 代理

您可以将现有 API 代理作为 API 代理软件包中的一组 XML 文件进行备份。将 API 代理导出到软件包后,您可以按照本部分前面从 API 代理软件包导入 API 代理所述,将 API 代理导入新代理。如需了解详情,请参阅下载 API 代理

使用 API 创建 API 代理

如需使用 API 创建 API 代理,请参阅 API 代理 API