APIM Policy Authoring Skill 是一个面向 Azure API Management 的策略编写技能，目标是生成“生产就绪”的 APIM 策略 XML，帮助在 API 网关层统一处理认证、限流、跨域、错误处理与安全加固。
用途 当用户需要以下能力时启用该技能：
- 身份验证策略：OAuth 2.0、JWT 校验、订阅密钥与 OAuth 的混合认证
- 限流：按用户或按订阅进行节流
- CORS 配置：为浏览器客户端提供跨域访问
- 错误处理：带关联 ID 的标准化错误响应
- 请求/响应转换：请求头和正文操作
- 安全响应头：X-Content-Type-Options、X-Frame-Options 等
主要能力 技能提供完整的生产级 XML 模板（见 references/POLICY_TEMPLATES.md）：
- 混合认证：面向公开 API 的 OAuth + 订阅密钥回退
- 仅 OAuth：面向使用 Entra ID 的内部企业 API
- 仅订阅密钥：面向简单的公开只读 API
策略执行流程 INBOUND → BACKEND → OUTBOUND → ON-ERROR
- INBOUND：认证、限流、CORS、请求头
- BACKEND：转发、重试、熔断
- OUTBOUND：响应转换、安全响应头、清理
- ON-ERROR：结构化错误、日志、关联 ID
使用方式 重要：在编写策略之前，始终先使用 MCP 工具。
- 首先调用最佳实践：在生成任何策略前调用 Tool: mcp_azure_mcp_get_azure_bestpractices，Intent 为 “Azure API Management policy best practices for [authentication|rate-limiting|CORS|error-handling]”。
- 搜索文档：针对具体策略元素，使用 Tool: mcp_azure_mcp_documentation search，Query 例如 “APIM validate-jwt policy reference”。
技能内给出了若干可直接参考的代码片段，包括：使用 Entra ID 的 JWT 校验（validate-jwt 配合 openid-config 与 audiences）、按用户限流（set-variable 提取 JWT 的 Subject 作为 userId，再用 rate-limit-by-key 以该变量为 counter-key）、关联 ID 生成（set-variable 生成 GUID，并通过 set-header 覆盖 X-Correlation-ID）、标准化错误响应（on-error 中使用 set-body 返回包含 code、message、correlationId、timestamp 的 JSON），以及安全响应头设置（X-Content-Type-Options: nosniff、X-Frame-Options: DENY、Strict-Transport-Security: max-age=31536000; includeSubDomains）。
适用场景 技能提供认证决策矩阵，用于按 API 类型选择认证方式与限流额度：
- 公开只读：订阅密钥，500 请求/小时（如天气 API、公共假日）
- 内部企业：OAuth（Entra ID），10,000 请求/小时（如员工目录、HR 系统）
- 敏感公开：OAuth（Entra External ID），1,000 请求/小时（如支付、健康记录）
- 混合：OAuth + 订阅密钥回退，1,000/500 请求/小时（如带免费/高级档位的 API）
限制与校验要求 部署前需按检查清单确认：关联 ID 在 inbound 生成并出现在响应与错误中；认证采用 JWT 校验或订阅密钥检查；限流已按合适额度配置；on-error 块返回结构化 JSON；安全响应头齐全；在 outbound 中移除 X-Powered-By、Server 等后端信息；XML 良构且无未闭合标签；测试有效/无效令牌与超限场景。
相关技能与文档 相关技能包括 azure-apim-architecture（编写策略前先理解架构）与 api-security-review（策略创建后校验安全性）。微软文档参考内容包括 Policy Reference、validate-jwt、rate-limit-by-key、CORS、Policy Expressions。
技能版本 1.0，最后更新于 2026 年 1 月 29 日。主要知识来源：APIM_PLATFORM_BASELINE_POLICIES.md、references/POLICY_TEMPLATES.md。