将 SOAP 服务公开为 API 代理

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

本主题介绍如何为基于 SOAP 的网络服务创建 API 代理。您可以在 Edge 中创建两种 SOAP 代理。其中一个生成后端 SOAP 服务的 RESTful 接口，另一个将 SOAP 消息执行到后端执行。本主题介绍了这两种方法。

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

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

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

概览

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

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

基本步骤

Edge

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

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

    选择 WSDL 的来源。

    • From web address (网址) - 输入或粘贴 WSDL 的网址。
    • 从我的计算机 - 从本地目录上传 WSDL 文件。如果存在依赖项，您可以上传多个文件。
  6. 点击验证以验证 WSDL。
  7. 输入以下代理详细信息：
    字段 说明
    名称 为您的 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/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 中，端口类型元素定义您可以对网络服务调用的操作。
  12. （可选）更改操作的 REST API 路径。该路径将用作 API 代理网址中的资源名称。
  13. （可选）更改与操作关联的 Verb（HTTP 方法）。
  14. 点击下一步。
  15. 在向导的虚拟主机页面上，选择 API 代理在部署时将绑定到的虚拟主机。如需了解详情，请参阅关于虚拟主机。
  16. 点击下一步。
  17. 选择部署环境，然后点击创建和部署
    您的新 API 代理已创建并部署到所选环境。
  18. 点击修改代理，以显示 API 代理的详细信息页面。

传统 Edge (Private Cloud)

如需使用传统版 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 文件。如果存在其他依赖文件，您可以选择所有这些文件。
    • 示例网址 - 从公开提供的网络服务的 WSDL 列表中选择。这对于试用 Edge 的 SOAP/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/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. 从 Port Type 列中选择您希望使用的一组操作。在 WSDL 中，端口类型元素定义您可以对网络服务调用的操作。
  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 的服务的直通代理

本部分介绍如何使用“Create New Proxy”对话框中的 Pass-Through Proxy 选项创建直通式代理。

概览

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

对于此类代理，Edge 会托管 WSDL，并在代理中创建流，以便您访问该代理。这个边缘托管的 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 的来源。

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

    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/members 和 https://[host]/team/green/members，而无需创建新的 API 代理来支持新团队。请注意，不支持 /**/。

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

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

传统 Edge (Private Cloud)

如需使用传统版 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 文件。如果存在其他依赖文件，您可以选择所有这些文件。
    • 示例网址 - 从公开提供的网络服务的 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 代理类型设置为 Pass-Through SOAP，并按端口类型整理 GetQuote 等操作列表。
  10. 从 Port Type 列中选择您希望使用的一组操作。在 WSDL 中，端口类型元素定义您可以对网络服务调用的操作。
  11. 点击向导的其余部分以添加安全性、选择虚拟主机和部署环境。
  12. 在“构建”页面中，点击构建和部署。Edge 会根据 WSDL 生成和部署新的 API 代理。

关于最终代理

当 Edge 生成直通式代理时，生成的代理实际上是一个复杂的流程，其中包括用于转换数据、提取和设置变量、处理消息等的政策。生成直通式代理后，请在 API 管理界面的“开发”视图中查看生成的流程。在此处，您可以确切了解已添加哪些政策。

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

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

边缘托管的 WSDL：如需查看为此类代理生成的边缘托管的 WSDL，请转到 http(s)://[proxy_domain]/[proxy_base_path]?wsdl。

高级 SOAP 到 REST 代理开发

前面的部分介绍了如何在 Edge 中使用 API 代理向导创建 SOAP-to-REST API 代理。但是，如果您想要对 SOAP 到 REST 的转换进行更精细的控制，则可以绕过向导提供的自动化功能，并通过手动添加和配置政策来构建代理，以获得您想要的行为。如需了解详情，请参阅 教程：在 Apigee Edge 中手动构建 SOAP-to-REST API 代理。