Azure API 管理：网关、策略、认证与生产实践总结

服务器技术 2026-06-11 14:48:40 4

最近折腾了 Azure API Management（APIM），踩了几个坑，这篇把生产实践中学到的东西说清楚。

APIM 是一个全托管的网关服务，放在所有后端 API 的前面。外部请求不会直接打到你的原始 API，而是先经过 APIM。它把安全防护、流量限制、数据转换、监控和文档这些事情全部收拢到一个地方。

在 Blue Yonder 的时候，我们用 APIM 作为 SIAM 平台所有集成的入口。Salesforce、ServiceNow、第三方厂商——所有外部系统都通过 APIM 调用我们的 API。这样做的好处很明显：一个地方管所有入口，安全策略、监控告警、调用控制全部统一。

核心组件

API 网关负责接收所有传入的 API 调用，在转发到后端之前执行策略，然后返回响应。这是实际处理每个请求的运行时组件。

开发者门户是一个自动生成的文档网站，开发者可以在这里发现和测试你的 API，申请 API 密钥，不需要找团队就能上手。完全支持用你的品牌定制外观。

管理平面是 Azure 门户的操作界面，你在这里定义 API、产品、策略和用户。可以直接从 OpenAPI 规范、WSDL 文件、Logic Apps 或 Function Apps 导入 API。

分析功能自动记录每个请求，包括响应时间、错误率、按调用方统计的使用量。内置仪表盘清楚展示所有 API 的运行状况。

API、产品和订阅

理解这个三层结构是正确使用 APIM 的关键。

API 是一组相关操作的集合。比如一个订单 API 会包含 GET /orders、GET /orders/{id}、POST /orders 和 DELETE /orders/{id} 这些操作。

产品是一个或多个 API 的捆绑包，有自己独立的订阅密钥和策略。比如一个合作伙伴产品可以包含订单 API 和库存 API，限制每天 5000 次调用，需要审批才能订阅。

订阅是一对密钥，授予访问某个产品的权限。每个调用方都有自己独立的订阅密钥。你可以单独吊销某个密钥而不影响其他调用方——这对安全事件处理至关重要。

我们在 Blue Yonder 定义了三个产品：

内部产品——无速率限制，无需审批
合作伙伴产品——每天 5000 次调用，需要审批
公开产品——每天 100 次调用，开放注册

策略——APIM 的核心

策略是运行在每个请求或响应上的规则，用 XML 编写，可以在四个层级应用——全局层、产品层、API 层或操作层，提供极其精细的控制能力。

每个请求都会按顺序经过四个策略段：

Inbound（入站）——在请求到达后端之前执行
Backend（后端）——控制如何调用后端
Outbound（出站）——在响应到达调用方之前执行
On-Error（错误处理）——当任何策略抛出异常时执行

生产环境中我最常用的几个策略：

Rate limiting（速率限制）——限制调用方在某个时间窗口内的调用次数。超过限制时返回 429 Too Many Requests。

Quota（配额）——更长时间段内的硬性累计限制。和速率限制不同，配额计算的是整天累计调用量，而不是每分钟调用数。

IP filtering（IP 过滤）——只允许来自指定 IP 地址范围的请求。对那些永远不应该从公网访问的内部 API 来说，这是必备配置。

Validate JWT（JWT 验证）——验证每个请求携带的 Azure AD JWT 令牌。对外暴露的 API 来说，这是最重要的安全策略。它检查令牌是否有效、是否过期、是否包含必需的声明（claims）。

Set header（设置请求头）——在后端请求上添加或修改请求头。我们用它来向后端服务传递内部 API 密钥，而不暴露给调用方。调用方发送的是订阅密钥，APIM 验证后，在转发前换成真实的内部密钥。

Rewrite URL（URL 重写）——把外部 URL 映射到不同的内部 URL。调用方访问 /orders/{id}，后端收到的是 /v2/orders/{id}。这样你可以在不破坏现有调用方的情况下升级后端版本。

Cache response（缓存响应）——缓存 GET 响应的结果，可配置缓存时长。我们把库存查询缓存了 5 分钟，在高峰期后端负载降低了 60%。

Transform JSON to XML（JSON 转 XML）——在转发给遗留后端之前，把 JSON 请求体转换为 XML。现代调用方发送 JSON，APIM 透明处理转换。

认证方式

APIM 支持四种认证方式。根据调用方身份和安全需求来选择。

Subscription Key（订阅密钥）是最简单的方案。调用方在 Ocp-Apim-Subscription-Key 请求头中传递密钥。适用于合作伙伴和内部系统集成，因为两端都在你的控制之下。

OAuth 2.0 配合 Azure AD 是对外 API 最安全的方案。调用方先从 Azure AD 获取 JWT 令牌，然后作为 Bearer Token 发送。APIM 用 validate-jwt 策略验证令牌。令牌包含调用方身份、角色和权限。所有面向用户的应用和 B2B 企业集成都应该用这个。

Client Certificate（客户端证书，即 mTLS）要求调用方提供证书而非密码。APIM 验证证书指纹。我们在 Blue Yonder 用这个做银行集成，那里需要最高级别的安全保障。

Basic Authentication（基本认证）传递 Base64 编码的用户名和密码。只在遗留系统不支持其他方案时使用，而且必须走 HTTPS。任何新集成都强烈建议避免。

命名值——安全存储密钥

命名值（Named Values）是 APIM 的变量，用来存储敏感信息如 API 密钥和连接字符串。在策略中用双花括号引用，永远不需要在 XML 中硬编码实际值。

创建命名值时标记为 secret，值在存储时加密，保存后在门户中不再可见。最佳实践是直接链接到 Azure Key Vault，这样密钥可以自动轮换，不需要修改任何策略。

版本和修订

版本（Version）处理破坏性变更。你同时运行 v1 和 v2，分别对应不同的 URL。调用方自行选择使用哪个版本，等所有调用方都迁移完成后才退役 v1。不会有强制升级。

修订（Revision）处理非破坏性变更。你创建修订版 2 作为正在开发中的版本，此时还不生效。安全地做修改和测试，准备好后发布。如果出问题，立刻回滚到修订版 1。

这就是我们在 Blue Yonder 部署所有 APIM 变更的方式——零停机、零调用方影响、即时回滚能力。

监控和追踪

每个 APIM 请求都会自动记录时间戳、调用方 IP、使用的订阅密钥、调用的操作、响应时间和 HTTP 状态码。

最有用的调试工具是请求追踪（request tracing）。在任何请求中添加 Ocp-Apim-Trace: true 请求头，响应中就会包含完整的策略执行追踪——每个策略入参是什么、出了什么、耗时多久。在 Blue Yonder，这给我节省了大量调试时间。你可以精确看到哪个策略对请求做了什么修改，哪里变慢了或失败了。

把 APIM 连接到 Application Insights，每个请求会自动出现在那里。在错误率阈值或响应时间下降时设置告警，在调用方发现问题之前你就能收到通知。

完整的企业集成架构

这是我在 Blue Yonder 构建的完整架构，结合了 APIM、Logic Apps、Service Bus 和 Azure SQL：

每一层各司其职。APIM 负责入口，Logic Apps 负责编排，Service Bus 负责可靠性，API 负责业务逻辑，SQL 负责持久化。

生产实践的关键教训

永远用命名值存储密钥——永远不要在策略 XML 中硬编码 API 密钥或密码
在产品层应用速率限制而不是全局层——不同调用方有不同需求，合作伙伴的配额应该高于公开用户
每次变更都用修订——即时回滚在生产事故中救过我们不止一次
从第一天就启用 Application Insights——一旦生产环境出问题，你就会需要那些日志
开发时用 Trace 请求头——它显示每个策略对每个请求做了什么，调试复杂策略链时无可替代
尽早搭建开发者门户——合作伙伴和调用方喜欢自助式文档，这能大幅减少支持工单
所有对外 API 都用 validate-jwt——只有订阅密钥是不够的，令牌给你身份、角色和过期时间
每个后端都加熔断器——当下游系统故障时保护你的服务不被级联失败拖垮

APIM 定价层级

Consumption（消耗）层级按调用次数计费，没有月度承诺——适合学习和低流量 API。Developer（开发者）层级大约每月 50 美元，功能完整但没有 SLA——适合开发和测试。Basic（基础）层级大约每月 150 美元，是生产工作负载的入门级。Standard（标准）层级大约每月 700 美元，增加了 VNet 支持，适合企业使用。Premium（高级）层级大约每月 2800 美元，支持多区域部署和区域冗余，适合全球企业应用。

总结

Azure API Management 是在企业级 Azure 架构中暴露 API 的专业方案。一个网关处理安全防护、流量限制、数据转换、版本管理和监控，服务所有 API。

配合 Azure AD 做认证、Key Vault 存储密钥、Logic Apps 编排流程、Service Bus 处理消息——APIM 完成了 Azure 上的企业集成技术栈。如果你在 Azure 上构建严肃的集成系统，APIM 不是可选项，而是整个架构的基础。