你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
将 Microsoft Azure Data Manager for Energy API 发布到安全 API 网关
Azure API 管理充当客户端应用程序和后端 API 之间的重要中介。 它通过隐藏技术详情，并为组织提供对 API 安全性的控制，使客户能够更轻松地访问服务。
通过 Azure API 管理发布 Azure Data Manager for Energy API，可以使用 Azure Data Manager for Energy 专用链接功能来处理私有流量，并完全删除对实例的直接公共访问。
本文介绍如何设置 Azure API 管理以保护 Azure Data Manager for Energy API。
先决条件
需要以下可用组件、工具和信息来完成本演练：
具有两个可用子网的虚拟网络，一个用于 Azure Data Manager for Energy 专用终结点，另一个用于 Azure API 管理虚拟网络注入。
Azure Data Manager for Energy 配置了部署到子网中的专用链接。
一个代码编辑器（例如 Visual Studio Code），用于修改每个正在发布的 API 的 Azure Data Manager for Energy OpenAPI 规范。
从 adme-samples GitHub 存储库下载 Azure Data Manager for Energy OpenAPI 规范。 导航到 rest-apis 目录并为应用程序选择适当的版本。
从预配时使用的 Azure Data Manager for Energy 应用程序的应用程序注册中，记下租户 ID 和客户端 ID：
准备 API 管理实例
使用以下步骤对 Azure API 管理实例进行配置更改：
从“所有资源”窗格中，选择用于本演练的 Azure API 管理实例。
通过从 API 设置分组中选择“产品设置”页，导航到该页面：
在“产品”页上，选择“添加”按钮以创建新产品。 Azure API 管理产品可用于创建可以一起治理和管理的松散耦合的 API 分组。 我们为 Azure Data Manager for Energy API 创建了一个产品。
在“添加产品”页上，输入下表中描述的值以创建产品。
设置 “值” 显示名称 “Azure Data Manager for Energy 产品” ID “adme-product” 说明 输入说明，向开发人员表明我们正在对哪些 API 进行分组 已发行 选中此框可发布我们创建的产品 需要订阅 选中此框可为我们的 API 提供基本授权 需要批准 （可选）如果希望管理员审查并接受或拒绝此产品的订阅尝试，请选中该项。 如果未选中此项，则会自动批准订阅尝试。 订阅计数限制 （可选）限制多个同步订阅的计数。 法律条款 （可选）定义产品的使用条款，订阅者必须接受这些条款才能使用该产品。 API 我们可以忽略此功能。 我们将在本文后面关联 API 选择“创建”以创建新产品。
产品创建完成后，门户将返回到“产品”页。 选择新创建的产品 Azure Data Manager for Energy Product 以转到“产品资源”页。 从设置菜单中选择“策略”设置菜单项。
在入站处理窗格中，选择 </> 图标，以便修改产品的策略。 添加三组策略来增强解决方案的安全性：
- 验证 Entra ID 令牌，用于确保 API 网关捕获未经身份验证的请求
- 配额和速率限制，用于控制请求速率和传输的请求总数/数据
- 设置标头，用于删除后端 API 返回的标头，这可能会向潜在的不良行为者泄露敏感详细信息
将以下 validate-azure-ad-token 策略添加到入站标记内和基本标记下方的配置中。 请务必使用先决条件中注明的 Microsoft Entra ID 应用程序详细信息更新模板。
<validate-azure-ad-token tenant-id="INSERT_TENANT_ID"> <client-application-ids> <application-id>INSERT_APP_ID</application-id> </client-application-ids> </validate-azure-ad-token>在 validate-azure-ad-token 策略下，添加以下配额和速率限制策略。 根据使用者的情况更新策略配置值。
<rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/> <quota calls="10000" bandwidth="40000" renewal-period="3600" />在策略编辑器的出站部分的基本标记下，添加以下 set-header 策略。
<set-header name="x-envoy-upstream-service-time" exists-action="delete" /> <set-header name="x-internal-uri-pattern" exists-action="delete" />选择“保存”，以提交更改。
导航回 Azure 门户中的 API 管理资源。 选择“后端”菜单项，然后选择“+ 添加”按钮。
在后端模式中，输入下表中描述的值以创建后端。
设置 值 名称 “adme-backend” 说明 输入说明，向开发人员表明此后端与用于能源 API 的 Azure 数据管理器相关 类型 自定义 URL 运行时 URL 输入 Azure Data Manager for Energy URI _ex。 https://INSERT_ADME_NAME.energy.azure.com/验证证书链 已选中 验证证书名称 已选中 
选择“创建”以创建后端。 我们在下一节中发布 API 时，将使用此新创建的后端。
导入 Azure Data Manager for Energy API
使用以下步骤将 Azure Data Manager for Energy API 导入、配置和发布到 Azure API 管理网关：
导航回上一节中使用的 Azure API 管理实例。
从菜单中选择“API”菜单项，然后选择“+ 添加 API”按钮。
在“从定义创建”标题下选择“OpenAPI”。
在“基于 OpenAPI 规范创建”模式窗口中，选择“完全”切换开关。
找到作为先决条件下载的 OpenAPI 规范，并使用所选代码编辑器打开架构规范。 搜索单词“server”并记下文件 ex. /api/schema-service/v1/ 中的服务器 URL。
选择“选择文件”并选择架构 API 规范。 上传完成后，模式窗口会加载规范中的一些值。
对于其他字段，输入下表中描述的值：
设置 “值” 在操作模板中包含所需的查询参数 已选中 显示名称 输入对应用开发人员有意义的显示名称 ex.Azure Data Manager for Energy 架构服务 名称 API 管理建议使用带短横线的名称。 （可选）可以更改名称，但该名称对于实例必须是唯一的 说明 OpenAPI 规范可能会定义说明，如果是这样，则会自动填充说明。 （可选）根据用例更新说明。 URL 方案 选择“两者” API URL 后缀 输入所有 Azure Data Manager for Energy API 的后缀（ex. adme）。 然后输入步骤 5 中的服务器 URL。 最终值应类似于 /adme/api/schema-service/v1/。 后缀使我们能够与通常直接连接到 Azure Data Manager for Energy API 的现有客户端和软件开发套件兼容 标记 （可选）输入标记 产品 选择在上一节中创建的“Azure Data Manager for Energy”产品 重要
验证 API URL 后缀，这是发布用于 Azure Data Manager for Energy API 时出现错误的常见原因
选择“创建”以创建 API 外观。
从 API 列表中选择新创建的架构 API 外观，然后在操作列表中选择“所有操作”。 在“入站处理”窗格中，选择 </> 图标以编辑策略文档。
若要配置 API，请添加两组策略：
- 设置后端服务，用于将请求路由到 Azure Data Manager for Energy 实例
- 重写 URI，用于删除 adme 前缀并构建对后端 API 的请求。 此策略语句使用策略表达式将当前操作的 URL 模板的值动态添加到我们的服务器 URL。
记下步骤 5 中的服务器 URL。 在基本标记下方的入站部分中，插入以下两个策略语句。
<set-backend-service backend-id="adme-backend" /><!-- replace the '/api/schema-service/v1' with the server URL for this API specification you noted in step 5 --> <rewrite-uri template="@{return "/api/schema-service/v1"+context.Operation.UrlTemplate;}" />选择“保存”，以提交更改。
通过从操作列表中选择“获取版本信息”操作来测试 API。 然后选择“测试”选项卡，以导航到 Azure API 管理控制台。
输入下表中描述的值。 为 Azure Data Manager for Energy 生成身份验证令牌。 选择发送以测试 API。
设置 “值” data-partition-id Azure Data Manager for Energy 实例的数据分区 ID 产品 选择之前创建的 Azure Data Manager for Energy 产品 授权 “Bearer”和生成的身份验证令牌 
如果 API 配置正确，你应该会看到类似于屏幕截图的 HTTP 200 - OK（HTTP 200 - 确定）响应。 如果没有，请查看“故障排除”部分。
对每个 Azure Data Manager for Energy API 和相关规范重复上述步骤。
故障排除
在通过 Azure API 管理测试 API 期间，如果遇到错误，它们通常指向配置问题。 根据错误，查看可能的解决方法步骤。
| 代码 | 错误消息 | 详细信息 |
|---|---|---|
HTTP 401 Unauthorized |
Invalid Azure AD JWT |
检查以确保 Azure Data Manager for Energy 实例的 Microsoft Entra ID 租户和客户端应用程序具有有效的身份验证标头。 |
HTTP 401 Unauthorized |
Azure AD JWT not present |
检查以确保身份验证标头已添加到测试请求中。 |
HTTP 404 Not Found |
此错误通常意味着对后端 API 的请求正在向错误的 URL 发出。 在 API 管理中跟踪 API 请求，以了解为后端请求生成的 URL 并确保其有效。 如果无效，请仔细检查 url-rewrite 策略或 后端。 | |
HTTP 500 Internal Server Error |
Internal server error |
此错误通常反映向后端 API 发出请求时出现问题。 通常，在这种情况下，问题与域名服务 (DNS) 相关。 检查以确保虚拟网络中配置了专用 DNS 区域，或者自定义 DNS 解析具有适当的转发器。 在 API 管理中跟踪 API 请求，以了解发出了哪些后端请求以及 API 管理在尝试发出请求时报告了哪些错误。 |
其他注意事项
API 管理内部虚拟网络模式
内部模式会完全隔离 Azure API 管理，而不会通过公共 IP 地址公开终结点。 在此配置中，组织可以确保所有 Azure Data Manager for Energy 都是内部的。 由于 Azure Data Manager for Energy 是与合作伙伴和客户合作的协作解决方案，因此在这种情况下，直接使用它可能不太有用。
具有 Web 应用程序防火墙的应用程序网关
许多组织不单独使用内部虚拟网络模式，而是选择应用安全的反向代理机制，将内部模式 Azure API 管理实例公开给外部合作伙伴和客户。 内部模式实例与必须通过代理的、严格控制的流入量始终完全隔离。
Azure 应用程序网关是用作反向代理的常用服务。 Azure 应用程序网关还具有 Web 应用程序防火墙 (WAF) 功能，可主动检测针对应用程序和 API 中的漏洞的潜在攻击。
使用自定义域配置 Azure API 管理
此体系结构的另一个常见功能是将自定义域应用于 API。 尽管 Azure Data Manager for Energy 不支持此功能，但你可以在 Azure API 管理上配置自定义域。
域证书是先决条件。 但是，Azure API 管理支持为自定义域创建免费的托管证书。