你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
适用于:所有 API 管理层级
本文介绍如何使用元数据描述导入 OData 服务。 本文以 SAP Gateway Foundation 为例。
在本文中,你将:
- 从 SAP 服务检索 OData 元数据
- 直接将 OData 元数据导入到 API 管理,或者在转换为 OpenAPI 规范后再导入
- 完成 API 配置
- 在 Azure 门户中测试 API
现有的 API 管理实例。 如果还没有实例,请创建一个。
公开为 OData v2 或 v4 的 SAP 系统和服务。
如果你的 SAP 后端使用自签名证书(用于测试目的),你可能需要禁用 SSL 的信任链验证。 为此,请在你的 API 管理实例中配置一个后端:
- 在 Azure 门户中的“API”下面,选择“后端”>“+ 添加”。
- 添加指向 SAP 后端服务的自定义 URL。
- 取消选中“验证证书链”和“验证证书名称”。
备注
对于生产方案,请使用适当的证书进行端到端 SSL 验证。
使用以下方法之一从 SAP 服务检索元数据 XML。 如果计划将元数据 XML 转换为 OpenAPI 规范,请在本地保存文件。
- 使用 SAP 网关客户端(事务
/IWFND/GW_CLIENT
),或
- 进行直接 HTTP 调用以检索 XML:
http://<OData server URL>:<port>/<path>/$metadata
在 Azure 门户中,搜索并选择“API 管理服务”。
在“API 管理”服务页上,选择你的 API 管理实例。
选择以下方法之一将 API 导入到 API 管理:将元数据 XML 作为 OData API 直接导入,或者将元数据 XML 转换为 OpenAPI 规范。
在左侧菜单中,选择“API”>“+ 添加 API”。
在“根据定义创建”下,选择“OData”。
输入 API 设置。 稍后可以转到 API 的“设置”选项卡来更新设置。
在 OData 规范中,输入 OData 元数据终结点的 URL,通常是服务根的 URL,并附加 /$metadata
。 或者,选择要导入的本地 OData XML 文件。
输入其余设置以配置 API。 在导入和发布第一个 API 教程中对这些设置进行了说明。
选择“创建”。
API 将添加到 API 列表中。 OData 元数据说明中公开的实体集和函数显示在 API 的“实体集和函数”选项卡上。
可以在门户中访问编辑器以查看 API 的 OData 架构。 如果 API 发生更改,还可以从文件或 OData 服务终结点更新 API 管理中的架构。
在门户中导航到 API 管理实例。
在左侧菜单中,选择 OData API 的“API”>。
在“实体集和函数”选项卡上,选择实体集或函数旁边的上下文菜单 (...),然后选择“编辑”。
查看架构。 如果要更新它,请选择“从文件更新”或“从终结点更新架构”。
在左侧菜单中,选择 OData API 的“API”>。
在“实体集和函数”选项卡上,选择实体集或函数旁边的上下文菜单 (...),然后选择“测试”。
在测试控制台中,输入测试的模板参数、查询参数和标头,然后选择“测试”。 详细了解如何在门户中测试 API。
通过应用现有的身份验证和授权策略以及 OData 验证策略来保护 OData API,防止通过 OData API 请求发动的攻击。
提示
在门户中,在“API 策略”选项卡上为 OData API 配置策略。
将 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” 。
在“创建新定义”下,选择“OpenAPI 规范”。
单击“选择文件”,然后选择在上一步中本地保存的 openapi-spec.json
文件。
输入 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。
选择“测试”选项卡以访问“测试”控制台。
选择一个操作,输入任何所需的值,然后选择“发送”。
例如,测试 GET /$metadata
调用以验证与 SAP 后端的连接
查看响应。 要进行故障排除,请跟踪调用。
测试完成后,退出测试控制台。