apply-policy-to-api-instance

将策略应用到 API 实例

概述

通过依次选择组织和环境、选取目标 API、浏览可用的策略模板目录、根据其 JSON 架构配置策略，最后在 API 上强制执行策略，将策略应用到 API Manager 实例。该工作流可确保你只选择与 API 实例兼容的模板，并确保配置符合模板的架构后再应用。

你将构建： 在所选 API 实例上强制执行的完整配置策略

先决条件

开始此工作流之前，请确保你已具备：

1. 准备好身份验证

   • 有效的 Anypoint Platform Bearer 令牌
   • API Manager 权限：View APIs Configuration 和 Manage Policies 作用域

2. 组织访问权限

   • 目标 API 实例已部署在 API Manager 中

第 1 步：获取当前组织

检索调用者的个人资料，自动查找根组织。无需参数——Bearer 令牌可识别用户并返回其组织详情，包括任何子 Business Group（子组织）。

你需要：

• 有效的 Bearer 令牌（身份验证标头）

操作： 调用 /me 端点以获取当前用户的组织。

api: urn:api:access-management
operationId: listMe
inputs: {}
outputs:
  - name: organizationId
    path: $.user.organization.id
    description: Root organization Business Group GUID
  - name: organizationName
    path: $.user.organization.name
    description: Organization display name

接下来： 你已根据凭据获取根组织 ID。如果你的账户有子组织（子 Business Group），请使用此 ID 调用 getOrganizations，列出这些组织，并在继续之前选择正确的范围。

第 2 步：列出环境

列出组织中的所有环境，以便选择目标 API 实例所在的环境（例如 Production、Sandbox）。

你需要：

• 第 1 步获取的组织 ID

操作： 列出可用环境并选择目标环境。

api: urn:api:access-management
operationId: listEnvironments
inputs:
  organizationId:
    from:
      variable: organizationId
    description: Organization ID from Step 1
outputs:
  - name: environmentId
    path: $.data[*].id
    labels: $.data[*].name
    description: Selected environment ID

接下来： 选择托管你要保护的 API 实例的环境。在所有后续步骤中，API Manager 都需要环境 ID。

第 3 步：列出 API 实例

检索所选环境中的所有 API 实例。每个条目都代表在 API Manager 中注册的受管理 API，也就是你要应用策略的目标。

你需要：

• 第 1 步获取的组织 ID
• 第 2 步获取的环境 ID

操作： 列出 API 实例，并让用户选择一个。

api: urn:api:api-manager
operationId: listApiInstances
inputs:
  organizationId:
    from:
      variable: organizationId
    description: Organization ID from Step 1
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 2
outputs:
  - name: environmentApiId
    path: $.assets[*].apis[*].id
    labels: $.assets[*].apis[*].instanceLabel
    description: The API instance ID to apply the policy to

接下来： 向用户展示 API 实例。每个资产可能包含多个实例（例如，不同版本或标签）。用户选择要作为目标的特定 environmentApiId。

提示：

• 如果列表很长，可使用 query 参数按名称筛选
• filters=active 参数可将结果限制为仅包含活动实例

第 4 步：浏览 Exchange 策略目录

列出 Exchange 中适用于你组织的所有可用策略模板。此端点会返回每个模板的完整 Exchange 坐标（groupId、assetId、version）以及兼容网关的配置，这些信息是应用策略所必需的。

**重要提示：**请使用 api-portal-xapi 端点（getExchangePolicyTemplates），而不是通用的 listPolicyTemplates 端点。通用端点不会返回 Exchange 坐标或网关专用的配置属性名称，而这些信息是应用策略时必需的。

你需要准备：

• 第 1 步中的组织 ID
• 第 2 步中的环境 ID
• 第 3 步中的 API 实例 ID（用于筛选兼容的模板）

**操作：**列出 Exchange 策略模板，并选择要应用的模板。传入 apiInstanceId 和 environmentId，筛选出兼容你的 API 网关类型（例如 Omni Gateway、Mule Gateway）的模板。

api: urn:api:api-portal-xapi
operationId: getExchangePolicyTemplates
inputs:
  organizationId:
    from:
      variable: organizationId
    description: Organization ID from Step 1
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 2
  apiInstanceId:
    from:
      variable: environmentApiId
    description: API instance ID from Step 3 (filters for compatible templates)
  includeConfiguration:
    value: "true"
    description: Include the configuration schema for each template
  latest:
    value: "true"
    description: Return only the latest version of each template
outputs:
  - name: policyGroupId
    path: $[*].groupId
    labels: $[*].assetId
    description: Exchange group ID of the selected policy template
  - name: policyAssetId
    path: $[*].assetId
    description: Exchange asset ID of the selected policy template
  - name: policyAssetVersion
    path: $[*].version
    description: Exchange version of the selected policy template (gateway-compatible)
  - name: policyConfiguration
    path: $[*].configuration
    description: Configuration schema with gateway-compatible property names and defaults

**接下来会发生什么：**你将获得策略模板的 Exchange 坐标，以及包含适用于你的网关类型的正确属性名称的配置架构。查看 policyConfiguration 输出，了解该策略接受哪些设置，然后再应用策略。对于每个配置属性，向用户展示属性名称、描述和默认值，然后询问他们是保留默认值还是提供自定义值。如果某个属性没有默认值，务必向用户询问所需值。

常见问题：

• 列表为空：传入 apiInstanceId 和 environmentId，以获取兼容你的网关类型的模板。如果没有这些筛选条件，部分模板可能不会显示。
• 配置属性名称错误：始终使用此端点返回的配置；通用的 listPolicyTemplates 端点可能会返回不同的（不兼容网关的）属性名称和默认值。例如，Omni Gateway 使用 credentialsOriginHasHttpBasicAuthenticationHeader，而通用模板使用 credentialsOrigin。

第 5 步：将策略应用到 API 实例

使用适当的配置，将所选策略应用到你的 API 实例。使用第 4 步中提供的 Exchange 坐标和配置属性名称。

你需要准备：

• 前面步骤中的组织 ID、环境 ID 和 API 实例 ID
• 第 4 步中的策略 Exchange 坐标（groupId、assetId、assetVersion）
• 根据第 4 步 policyConfiguration 输出中的架构配置的策略

**操作：**将策略应用到你的 API 实例。使用第 4 步配置架构中的属性名称构建 configurationData 对象。对于每个配置属性，向用户展示属性名称、描述和默认值，然后询问他们是保留默认值还是提供自定义值。如果某个属性没有默认值，务必向用户询问所需值。

api: urn:api:api-manager
operationId: applyApiInstancePolicy
inputs:
  organizationId:
    from:
      variable: organizationId
    description: Organization ID from Step 1
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 2
  environmentApiId:
    from:
      variable: environmentApiId
    description: API instance ID from Step 3
  groupId:
    from:
      variable: policyGroupId
    description: Policy Exchange group ID from Step 4
  assetId:
    from:
      variable: policyAssetId
    description: Policy Exchange asset ID from Step 4
  assetVersion:
    from:
      variable: policyAssetVersion
    description: Policy Exchange version from Step 4
outputs:
  - name: policyId
    path: $.id
    description: The ID of the applied policy instance

**接下来会发生什么：**你的 API 现在已受到所选策略的保护。传入请求将根据策略规则进行评估。你可以通过列出 API 已应用的策略或测试请求来进行验证。

常见问题：

• 400 Bad Request — 缺少 groupId/assetId/assetVersion：应用端点需要完整的 Exchange 坐标，不能只提供模板 ID。请确保你使用了 getExchangePolicyTemplates（第 4 步）来获取这些值。
• 400 Bad Request — configurationData 无效：配置属性名称因网关类型而异。请使用第 4 步 policyConfiguration 输出中的属性名称，而不是通用模板端点中的名称。例如，Omni Gateway 使用 credentialsOriginHasHttpBasicAuthenticationHeader，而通用模板使用 credentialsOrigin。
• 403 Forbidden：在此环境中缺少 Manage Policies 权限。
• 409 Conflict：此类型的策略可能已应用到该 API 实例。请先列出现有策略进行检查，或者在请求 URL 中添加 ?allowDuplicated=true，以应用同一策略类型的第二个实例。

完成清单

完成所有步骤后，请确认已正确应用策略：

• 已选择组织和环境
• 已识别目标 API 实例
• 已从兼容目录中选择策略模板
• 已根据模板的 JSON 架构构建配置
• 已成功应用策略（返回 201 响应，并包含策略 ID）
• 已确认策略显示在 API 的策略列表中

已完成的工作

✅ 策略执行 — 所选策略模板现已在 API 实例上启用，并已使用你提供的参数进行配置。传入流量会根据此策略进行评估。

后续步骤

1. 验证策略 — 使用 listApiPolicies 列出已应用的策略，确认策略已启用且配置正确。

2. 测试策略执行 — 向 API 发送请求，并确认策略行为符合预期（例如，拒绝未经授权的请求、执行速率限制）。

3. 调整配置 — 使用 updateApiPolicy 更新配置，无需移除策略。

4. 应用其他策略 — 重复此工作流以叠加多个策略（例如，在 OAuth2 之上添加速率限制）。使用 reorderApiPolicies 控制执行顺序。

5. 考虑自动化策略 — 如果你希望此策略自动应用于组织中的所有 API，请探索 createAutomatedPolicy。

故障排除

应用后策略未生效

症状： 请求通过时未经过策略评估

可能原因：

• API 实例尚未部署或处于错误状态
• 网关尚未加载新配置（等待 1-2 分钟）
• 策略配置的默认设置过于宽松，允许所有流量通过
• 点切数据排除了你正在测试的端点

解决方案：

• 在 API Manager 中检查 API 实例状态
• 等待配置传播后重试
• 检查策略配置，确认设置没有过于宽松
• 检查 pointcutData — 省略该参数即可应用于所有端点

应用策略时出现 400 错误

症状： "The policy to be created is missing at least one of the following properties related to the policy template: 'groupId', 'assetId', 'assetVersion'."

可能原因：

• 使用了通用的 listPolicyTemplates 端点，该端点不会返回 Exchange 坐标

解决方案：

• 改用 api-portal-xapi 中的 getExchangePolicyTemplates — 此端点会返回应用端点所需的完整 Exchange 坐标

配置属性名称不匹配

症状： configurationData 无效，出现 400 错误

可能原因：

• 使用了通用模板端点中的属性名称，而非与网关兼容的名称
• configurationData 中缺少必填字段
• 数据类型错误（例如，使用字符串而非整数）

解决方案：

• 始终使用 getExchangePolicyTemplates（步骤 4）返回的 configuration 输出 — 其中包含特定于网关的属性名称
• 例如，Omni Gateway 使用 credentialsOriginHasHttpBasicAuthenticationHeader，而通用模板使用 credentialsOrigin
• 确保字段类型完全匹配（数字、布尔值、数组）
• 仅包含架构中定义的字段

未找到策略模板

症状： 步骤 4 返回空结果

可能原因：

• API 实例的网关类型不支持此模板
• 缺少 apiInstanceId 或 environmentId 筛选条件
• 自定义策略模板尚未发布到此组织

解决方案：

• 同时传入 apiInstanceId 和 environmentId，筛选兼容的模板
• 移除筛选条件以查看所有模板，然后手动检查兼容性
• 对于自定义策略，请使用 listCustomPolicyTemplates 确认模板已发布

相关任务

• skill apply-universal-policy — 在任意网关的多个实例上，通过一条通用（规范）策略保护一部分 API。用户提到所有 / 多个 / 我的 API / 指定提供方时使用此技能。
• skill apply-native-policy-to-instance — 查看已应用的策略、编辑已应用的原生策略，或通过 MuleSoft Platform MCP Server 应用一条原生插件 / 模板（Kong / Apigee / Azure / MuleSoft）。用户询问“我的 Apigee API 有哪些防护措施”和“改进 IP 过滤”时使用此技能。
• deploy-api-with-rate-limiting — 完整工作流，包括创建 API、配置分级速率限制和 OAuth2
• list-organization-api-instances — 跨环境发现现有 API 实例
• manage-consumer-contracts — 应用策略后管理客户端应用访问权限