将 SOAP 服务公开为 API 代理

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

本主题介绍了如何为基于 SOAP 的 Web 服务创建 API 代理。您可以在 Edge 中创建两种 SOAP 代理。一个用于生成指向后端 SOAP 服务的 RESTful 接口，另一个用于将 SOAP 消息“直通”到后端。本主题介绍了这两种方法。

此视频提供了一个端到端演示，展示了如何使用 API 代理向导将 SOAP 服务转换为 Apigee Edge 中的 REST 服务。不过，如果您想更好地控制 SOAP 到 REST 的转换，可以使用政策构建代理。如需了解详情，请参阅 教程：在 Apigee Edge 中手动构建 SOAP 到 REST API 代理。

为基于 SOAP 的服务创建 RESTful API 代理

本部分介绍了如何使用“构建代理”向导中的 REST to SOAP to REST 选项创建 RESTful SOAP API 代理。

概览

REST to SOAP to REST 选项会处理 WSDL 以生成 RESTful API 代理。Edge 会根据 WSDL 确定服务支持的操作、输入参数等。Edge 会“猜测”应针对每项操作使用哪种 HTTP 方法。通常，边缘会将操作转换为 GET 请求，这类请求具有可缓存的优势。Edge 还会设置后端目标端点，该端点可能会因 SOAP 操作而异。

对于此类代理，Edge 会自动生成 OpenAPI 规范，您可以使用该规范创建 API 文档。

基本步骤

Edge

如需使用 Edge 界面创建指向基于 SOAP 的服务的 RESTful API 代理，请执行以下操作：

  1. 登录 apigee.com/edge。
  2. 在左侧导航栏中，选择开发 > API 代理。
  3. 点击 +代理。
  4. 点击 SOAP 服务。
  5. 在“代理详情”页面上，提供 WSDL 文件。
    字段 说明
    提供 WSDL 文件

    选择 WSDL 的来源。

    • 通过网址 (网址) - 输入或粘贴 WSDL 的网址。
    • 从我的计算机上传 - 从本地目录上传 WSDL 文件。如果存在依赖项，您可以上传多个文件。
  6. 点击验证以验证 WSDL。
  7. 输入以下代理详细信息：
    字段 说明
    名称 为您的 API 显示的名称。指定字母数字字符、短划线 (-) 或下划线 (_)。
    基本路径

    显示在 API 代理的 http(s)://[host] 地址之后的 URI 片段。Edge 使用基本路径 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/members 和 https://[host]/team/green/members，而无需创建新的 API 代理来支持新团队。请注意，不支持 /**/。
    说明 （可选）API 的说明。
  8. 点击下一步。
  9. 在向导的通用政策页面上，配置以下各项：
    • 安全性：授权下的安全授权要求。请参阅添加安全性。
    • 支持安全性：浏览器下的跨域资源共享 (CORS)。请参阅添加对 CORS 的支持。
    • 配额可用于在配额下保护后端服务免遭高流量访问。参见配额。（如果选择了直通式授权，则不会显示。）
  10. 在 WSDL 操作页面上，选择 API 代理类型 REST to SOAP to REST。

    系统会显示一个表格，其中列出了 Edge 在 WSDL 文件中“发现”的操作。您可以选择并配置要纳入 API 代理中的操作。该表格如下图所示。

  11. 从下拉菜单中选择端口类型，以指定要使用哪组操作。在 WSDL 中，端口类型元素定义了您可以对 Web 服务调用的操作。
  12. 您可以选择更改操作的 REST API Path。该路径将用作 API 代理网址中的资源名称。
  13. （可选）更改与操作关联的动词（HTTP 方法）。
  14. 点击下一步。
  15. 在向导的虚拟主机页面上，选择 API 代理在部署时将绑定到的虚拟主机。如需了解详情，请参阅关于虚拟主机。
  16. 点击下一步。
  17. 选择部署环境，然后点击创建和部署
    系统会创建新的 API 代理并将其部署到所选环境。
  18. 点击修改代理，以显示 API 代理的详细信息页面。

传统边缘（私有云）

如需使用经典版 Edge 界面创建指向基于 SOAP 的服务的 RESTful API 代理，请执行以下操作：

  1. 登录 http://ms-ip:9000，其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。
  2. 在顶部导航栏中依次选择 API > API 代理。
  3. 点击 + API 代理。
  4. 在“构建代理”向导中，选择 SOAP 服务。
  5. 点击下一步。
  6. 在“详细信息”页面中，进行以下选择。选择 WSDL 后，您必须点击验证。
    在此字段中 执行该操作
    WSDL

    选择 WSDL 的来源。

    • 网址 - 输入您要使用的 WSDL 的网址。
    • 文件 - 选择文件系统中的 WSDL 文件。如果有其他依赖文件，您可以选择所有这些文件。
    • 示例网址 - 从公开可用 Web 服务的 WSDL 列表中进行选择。这些工具非常适合试用 Edge 的 SOAP/API 代理功能。
    代理名称

    这是您要创建的代理的名称。
    代理基本路径

    显示在 API 代理的 http(s)://[host] 地址之后的 URI 片段。Edge 使用基本路径 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/members 和 https://[host]/team/green/members，而无需创建新的 API 代理来支持新团队。请注意，不支持 /**/。
    说明 代理的简要说明。
  7. 点击下一步。
  8. 在 WSDL 页面中，选择 API 代理类型 REST to SOAP to REST。

    系统会显示一个表格，其中列出了 Edge 在 WSDL 文件中“发现”的操作。您可以选择并配置要纳入 API 代理中的操作。该表格如下图所示。

    在 WSDL 操作页面上，API 代理类型设置为“REST to SOAP to REST”，并且表格中显示了一条包含添加操作的结果。

  9. 从“端口类型”列中选择要使用的操作组合。在 WSDL 中，端口类型元素定义了您可以对 Web 服务调用的操作。
  10. （可选）更改与操作关联的 HTTP 方法。

    注意：Edge 会做出“最佳猜测”，以确定要对每项操作使用哪种 HTTP 方法。通常首选 GET，因为 GET 请求可以缓存。
  11. 您可以选择更改操作的 REST API 路径。该路径将用作 API 代理网址中的资源名称。
  12. 点击完成向导的其余部分，以添加安全设置、选择虚拟主机和部署环境。
  13. 在“构建”页面中，点击构建和部署。Edge 会根据 WSDL 生成并部署新的 API 代理。
  14. 前往新 API 代理的摘要页面。请注意，系统已根据在 WSDL 文件中发现的操作构建了一组资源。

    在代理的“概览”页面上，资源列表详细介绍了新 API、其操作和参数。您可以将此表示法视为 API 的参考文档。Edge 会自动为您生成此 API 模型视图。只需展开相应资源，即可查看其说明和路径信息。

最终代理简介

当 Edge 基于 WSDL 生成 API 代理时，生成的代理实际上是一个复杂的流程，其中包含用于转换数据、提取和设置变量、操控消息等的政策。基于 WSDL 生成代理后，请在 API 管理界面的“开发”视图中查看生成的流程。您可以在其中查看具体添加了哪些政策。

例如，在请求端，AssignMessage 政策用于设置目标网址。在响应端，政策会执行以将响应从 XML 转换为 JSON，将响应的 SOAP 正文部分提取到变量中，并设置响应消息。创建代理时，系统会自动添加这些政策（以及其他政策）。

OpenAPI 规范：如需查看为此代理自动生成的 OpenAPI 规范，请访问 http(s)://[proxy_domain]/[proxy_base_path]/openapi.json。不过，转换并不总是准确的，因为 XML 架构的部分规则无法在 OpenAPI 规范中表示。

创建指向基于 SOAP 的服务的直通代理

本部分介绍了如何使用“创建新代理”对话框中的透传代理选项创建透传代理。

概览

借助“直通代理”选项，您可以创建一个代理，将请求中的 SOAP 消息“原封不动”地传递给后端服务，从而非常轻松地为基于 SOAP 的 Web 服务创建代理。Edge 会在后台自动为您处理所有转换和其他流程活动。例如，如果请求恰好采用 JSON 格式，Edge 会采取措施将其转换为具有正确命名空间的有效 XML SOAP 消息，然后再将其 POST 到服务。同样，当服务返回基于 XML 的 SOAP 响应时，Edge 会先将其转换回 JSON，然后再将其返回给客户端。此外，Edge 会设置后端目标端点，该端点可能会因 SOAP 操作而异。

对于此类代理，Edge 会托管 WSDL 并在代理中创建一个流，以便您访问它。此 Edge 托管 WSDL 的地址 http(s)://[proxy_domain]/[proxy_base_path]?wsdl 将成为通过代理调用 SOAP 服务的客户端的新服务端点网址。

基本步骤

Edge

如需使用 Edge 界面创建指向基于 SOAP 的服务的直通代理，请执行以下操作：

  1. 登录 apigee.com/edge。
  2. 在左侧导航栏中，选择开发 > API 代理。
  3. 点击 +代理。
  4. 点击 SOAP 服务。
  5. 在“代理详情”页面上，提供 WSDL 详细信息。
    字段 说明
    WSDL

    选择 WSDL 的来源。

    • 通过网址 (网址) - 输入或粘贴 WSDL 的网址。
    • 从我的计算机上传 - 从本地目录上传 WSDL 文件。如果存在依赖项，您可以上传多个文件。
    名称

    API 代理的名称。
    基本路径

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

    注意：如需 Apigee 关于 API 版本控制的建议，请参阅《网络 API 设计：缺失的环节》(Web API Design: The Missing Link) 电子书中的 版本控制。

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

    https://[host]/base_path/conditional_flow_path

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

    在基本路径中使用通配符

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

    注意：除非您在“基本路径”字段中明确修改内容，否则 API 代理基本路径默认为“名称”字段指定的值，且全部为小写。
    说明 （可选）API 的说明。
  6. 点击下一步。
  7. 在向导的通用政策页面上，配置以下各项：
  8. 在 WSDL 页面上，选择 API 代理类型 Pass-Through SOAP。

  9. 从下拉菜单中选择端口类型，以指定要使用哪组操作。在 WSDL 中，端口类型元素定义了您可以对 Web 服务调用的操作。
  10. 点击下一步。
  11. 在向导的虚拟主机页面上，选择 API 代理在部署时将绑定到的虚拟主机。如需了解详情，请参阅虚拟主机简介。
  12. 选择部署环境，然后点击创建和部署
    新的 API 代理会在所选环境中创建和部署。
  13. 点击修改代理，以显示 API 代理的详细信息页面。

传统边缘（私有云）

如需使用经典版 Edge 界面为基于 SOAP 的服务创建直通代理，请执行以下操作：

  1. 登录 http://ms-ip:9000，其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。
  2. 在顶部导航栏中依次选择 API > API 代理。
  3. 点击 + API 代理。
  4. 在“构建代理”向导中，选择 SOAP 服务。
  5. 点击下一步。
  6. 在“详细信息”页面中，进行以下选择。选择 WSDL 后，您必须点击验证。
    在此字段中 执行该操作
    WSDL

    选择 WSDL 的来源。

    • 网址 - 输入您要使用的 WSDL 的网址。
    • 文件 - 选择文件系统中的 WSDL 文件。如果有其他依赖文件，您可以选择所有这些文件。
    • 示例网址 - 从公开可用 Web 服务的 WSDL 列表中进行选择。这些工具非常适合试用 Edge 的 SOAP/API 代理功能。
    代理名称

    这是您要创建的代理的名称。
    代理基本路径 代理基本路径是一个 URI 片段，用于唯一标识此 API 代理公开的 API。API 服务使用基本路径 URI 来将传入的请求消息匹配并路由到适当的 API 代理。（基本路径会附加到 API 的域名，该域名会根据您的组织名称和 API 代理部署的环境自动生成。）最佳实践是在项目名称中添加版本号，例如 /v1/delayedstockquote。这将决定使用方应用调用您的 API 的方式。

    注意：除非您在“代理基本路径”字段中明确修改内容，否则“代理基本路径”默认为“代理名称”字段指定的值，且全部为小写。
    说明 代理的简要说明。

  8. 点击下一步。
  9. 在 WSDL 页面中，选择 API 代理类型 Pass-Through SOAP。

    注意：系统会显示一个表格，其中列出了每个 WSDL 操作及其对应的 SOAP 载荷。这是“传递”到后端 SOAP 服务的载荷。

    在 WSDL 页面中，API 代理类型设置为“透传 SOAP”，并且 GetQuote 等操作的列表按端口类型进行整理。
  10. 从“端口类型”列中选择要使用的操作组合。在 WSDL 中，端口类型元素定义了您可以对 Web 服务调用的操作。
  11. 点击完成向导的其余部分，以添加安全设置、选择虚拟主机和部署环境。
  12. 在“构建”页面中，点击构建和部署。Edge 会根据 WSDL 生成并部署新的 API 代理。

最终代理简介

当 Edge 生成传输代理时，生成的代理实际上是一个复杂流程，其中包含用于转换数据、提取和设置变量、操控消息等的政策。生成传输代理后，请在 API 管理界面的“开发”视图中查看生成的流程。您可以在其中查看具体添加了哪些政策。

例如，下图显示了透传代理的“目标端点预流程”部分。在请求端，AssignMessage 政策用于设置目标网址。在响应端，政策会执行以将响应从 XML 转换为 JSON，将响应的 SOAP 正文部分提取到变量中，并设置响应消息。创建代理时，系统会自动添加这些政策（以及其他政策）。

在“开发”视图的“流程”面板中，箭头表示从请求到响应的流程，图标表示政策。

由 Edge 托管的 WSDL：如需查看为此类代理生成的由 Edge 托管的 WSDL，请前往 http(s)://[proxy_domain]/[proxy_base_path]?wsdl。

高级 SOAP 到 REST 代理开发

前面部分介绍了如何使用 Edge 中的 API 代理向导创建 SOAP 到 REST API 代理。不过，如果您希望更精细地控制 SOAP 到 REST 的转换，可以绕过向导提供的自动化功能，通过手动添加和配置政策来构建代理，以实现所需的行为。如需了解详情，请参阅 教程：在 Apigee Edge 中手动构建 SOAP 到 REST API 代理。