你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

将 SAP OData 元数据作为 API 导入

项目
04/11/2024

适用于：所有 API 管理层级

本文介绍如何使用元数据描述导入 OData 服务。本文以 SAP Gateway Foundation 为例。

在本文中，你将：

从 SAP 服务检索 OData 元数据
直接将 OData 元数据导入到 API 管理，或者在转换为 OpenAPI 规范后再导入
完成 API 配置
在 Azure 门户中测试 API

注意

可从元数据说明中将 OData API 导入 API 管理，此功能现为预览版。了解详细信息。

先决条件

现有的 API 管理实例。如果还没有实例，请创建一个。
公开为 OData v2 或 v4 的 SAP 系统和服务。
如果你的 SAP 后端使用自签名证书（用于测试目的），你可能需要禁用 SSL 的信任链验证。为此，请在你的 API 管理实例中配置一个后端：
1. 在 Azure 门户中的“API”下面，选择“后端”>“+ 添加”。
2. 添加指向 SAP 后端服务的自定义 URL。
3. 取消选中“验证证书链”和“验证证书名称”。
注意

对于生产方案，请使用适当的证书进行端到端 SSL 验证。

从 SAP 服务检索 OData 元数据

使用以下方法之一从 SAP 服务检索元数据 XML。如果计划将元数据 XML 转换为 OpenAPI 规范，请在本地保存文件。

使用 SAP 网关客户端（事务 /IWFND/GW_CLIENT），或
进行直接 HTTP 调用以检索 XML：http://<OData server URL>:<port>/<path>/$metadata

转到你的 API 管理实例

在 Azure 门户中，搜索并选择“API 管理服务”。
在“API 管理”服务页上，选择你的 API 管理实例。

将 API 导入 API 管理

选择以下方法之一将 API 导入到 API 管理：将元数据 XML 作为 OData API 直接导入，或者将元数据 XML 转换为 OpenAPI 规范。

OData 元数据
OpenAPI 规范

导入 OData 元数据

在左侧菜单中，选择“API”>“+ 添加 API”。
在“根据定义创建”下，选择“OData”。
输入 API 设置。稍后可以转到 API 的“设置”选项卡来更新设置。
1. 在 OData 规范中，输入 OData 元数据终结点的 URL，通常是服务根的 URL，并附加 /$metadata。或者，选择要导入的本地 OData XML 文件。
2. 输入其余设置以配置 API。在导入和发布第一个 API 教程中对这些设置进行了说明。
选择“创建”。

API 将添加到 API 列表中。 OData 元数据说明中公开的实体集和函数显示在 API 的“实体集和函数”选项卡上。

更新 OData 架构

可以在门户中访问编辑器以查看 API 的 OData 架构。如果 API 发生更改，还可以从文件或 OData 服务终结点更新 API 管理中的架构。

在门户中导航到 API 管理实例。
在左侧菜单中，选择 OData API 的“API”>。
在“实体集和函数”选项卡上，选择实体集或函数旁边的上下文菜单 (...)，然后选择“编辑”。
查看架构。如果要更新它，请选择“从文件更新”或“从终结点更新架构”。

测试 OData API

在左侧菜单中，选择 OData API 的“API”>。
在“实体集和函数”选项卡上，选择实体集或函数旁边的上下文菜单 (...)，然后选择“测试”。
在测试控制台中，输入测试的模板参数、查询参数和标头，然后选择“测试”。详细了解如何在门户中测试 API。

保护 OData API

通过应用现有的身份验证和授权策略以及 OData 验证策略来保护 OData API，防止通过 OData API 请求发动的攻击。

提示

在门户中，在“API 策略”选项卡上为 OData API 配置策略。

将 OData 元数据转换为 OpenAPI JSON

将 OData XML 转换为 OpenAPI JSON 格式。根据你的元数据 XML，对 OData v2 或 OData v4 使用 OASIS 开源工具。

以下是针对测试服务 epm_ref_apps_prod_man_srv 转换 OData v2 XML 的示例命令：
```
odata-openapi -p --basePath '/sap/opu/odata/sap/epm_ref_apps_prod_man_srv' \
 --scheme https --host <your IP address>:<your SSL port> \
 ./epm_ref_apps_prod_man_srv.xml
```
注意
- 出于对单个 XML 文件的测试目的，你可以使用基于开源工具的基于 Web 的转换器。
- 使用该工具或基于 Web 的转换器，可以选择指定你的 SAP OData 服务器的 <IP 地址>:<端口>。或者，稍后在你生成的 OpenAPI 规范中或在导入 API 管理之后添加此信息。
将 openapi-spec.json 文件保存在本地以导入 API 管理。

导入和发布后端 API

在侧面导航菜单中的“API”部分下，选择“API” 。
在“创建新定义”下，选择“OpenAPI 规范”。
单击“选择文件”，然后选择在上一步中本地保存的 openapi-spec.json 文件。
输入 API 设置。可以在创建过程中设置这些值，也可以稍后转到“设置”选项卡来配置这些值。
- 在“API URL 后缀”中，我们建议使用与原始 SAP 服务中相同的 URL 路径。
- 有关 API 设置的更多信息，请参阅导入和发布你的第一个 API 教程。
选择“创建”。

注意

API 导入限制在另一篇文章中介绍。

完成 API 配置

将以下三个操作添加到你导入的 API 中。

GET /$metadata

操作	说明	进一步的操作配置
`GET /$metadata`	使 API 管理能够访问 `$metadata` 终结点，此终结点是客户端与 OData 服务器集成所必需的。你生成和导入的 OpenAPI 规范中未包含这一必需操作。	添加 `200 OK` 响应。

获取元数据操作

HEAD /

操作	说明	进一步的操作配置
`HEAD /`	使客户端能够在需要时与 SAP 服务器交换跨站点请求伪造 (CSRF) 令牌。 SAP 还允许使用 GET 动词交换 CSRF 令牌。本文不涉及 CSRF 令牌交换。请参阅代理令牌交换的示例 API 管理策略片段。	空值

用于提取令牌的操作

GET /

操作	说明	进一步的操作配置
`GET /`	在服务根目录启用策略配置。	配置以下入站 rewrite-uri 策略以将尾部斜杠附加到转发到服务根的请求： `<rewrite-uri template="/" copy-unmatched-params="true" />` 此策略消除了带有或不带有斜杠的请求的潜在歧义，某些后端对斜杠的处理方式有所不同。

获取服务根的操作

此外，请使用适合你环境的方法为你的后端配置身份验证。有关示例，请参阅 API 管理身份验证和身份验证策略。

测试 API

导航到 API 管理实例。
在侧面导航菜单中的“API”部分下，选择“API” 。
在“所有 API”下，选择导入的 API。
选择“测试”选项卡以访问“测试”控制台。
选择一个操作，输入任何所需的值，然后选择“发送”。

例如，测试 GET /$metadata 调用以验证与 SAP 后端的连接
查看响应。要进行故障排除，请跟踪调用。
测试完成后，退出测试控制台。

生产注意事项

请参阅端到端方案示例，以将 API 管理与 SAP 网关集成。
使用 API 管理策略控制对 SAP 后端的访问。例如，如果 API 作为 OData API 导入，请使用验证 OData 请求策略。另请参阅 SAP 主体传播和获取 X-CSRF 令牌的策略片段。
有关大规模部署、管理和迁移 API 的指南，请参阅：
- 通过 APIOps 自动部署 API
- 用于使用 Azure 资源管理器模板进行 API 管理的 CI/CD