apply-policy-to-api-instance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Apply Policy to an API Instance

将策略应用到 API 实例

Overview

概述

Applies a policy to an API Manager instance by walking through organization and environment selection, picking the target API, browsing the available policy template catalog, configuring the policy using its JSON schema, and finally enforcing it on the API. The workflow ensures you select only templates compatible with your API instance and that the configuration matches the template's schema before applying.
What you'll build: A fully configured policy enforced on your chosen API instance
通过选择组织和环境、确定目标 API、浏览可用策略模板目录、使用其 JSON schema 配置策略,并最终在 API 上实施策略,可以将策略应用到 API Manager 实例。该工作流确保您只选择与 API 实例兼容的模板,并确保配置与模板的 schema 相匹配,然后再应用策略。
构建成果: 一个已完全配置并在所选 API 实例上生效的策略

Prerequisites

前置条件

Before starting this workflow, ensure you have:
  1. Authentication ready
    • Valid Bearer token for Anypoint Platform
    • API Manager permissions: View APIs Configuration and Manage Policies scopes
  2. Organization access
    • The target API instance is already deployed in API Manager
在开始此工作流之前,请确保您具备:
  1. 已准备好身份验证
    • Anypoint Platform 的有效 Bearer token
    • API Manager 权限:View APIs Configuration 和 Manage Policies scopes
  2. 组织访问权限
    • 目标 API 实例已部署在 API Manager 中

Step 1: Get Current Organization

第 1 步:获取当前组织

Retrieve the caller's profile to discover the root organization automatically. No parameters needed — the Bearer token identifies the user and returns their organization details, including any child Business Groups (sub-organizations).
What you'll need:
  • A valid Bearer token (authentication header)
Action: Call the
/me
endpoint to get the current user's organization.
yaml
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
What happens next: You have the root organization ID derived from your credentials. If your account has sub-organizations (child Business Groups), use
getOrganizations
with this ID to list them and pick the right scope before continuing.
获取调用方的个人资料,以自动发现根组织。无需传入参数——Bearer token 用于标识用户并返回其组织详情,包括所有子 Business Groups(子组织)。
所需信息:
  • 有效的 Bearer token(身份验证标头)
操作: 调用
/me
端点以获取当前用户的组织。
yaml
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 Groups),请使用此 ID 调用
getOrganizations
列出它们,并在继续之前选择正确的范围。

Step 2: List Environments

第 2 步:列出环境

List all environments in the organization so you can select the one where your target API instance lives (e.g., Production, Sandbox).
What you'll need:
  • Organization ID from Step 1
Action: List available environments and select the target.
yaml
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
What happens next: Choose the environment that hosts the API instance you want to protect. The environment ID is required by API Manager in all remaining steps.
列出组织中的所有环境,以便选择目标 API 实例所在的环境(例如 Production、Sandbox)。
所需信息:
  • 第 1 步获得的 Organization ID
操作: 列出可用环境并选择目标环境。
yaml
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 的 Environment ID。

Step 3: List API Instances

第 3 步:列出 API 实例

Retrieve all API instances in the selected environment. Each entry represents a managed API registered in API Manager — this is the target you will apply the policy to.
What you'll need:
  • Organization ID from Step 1
  • Environment ID from Step 2
Action: List API instances and let the user pick one.
yaml
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
What happens next: Present the API instances to the user. Each asset may contain multiple instances (e.g., different versions or labels). The user selects the specific
environmentApiId
to target.
Tips:
  • Use the
    query
    parameter to filter by name if the list is large
  • The
    filters=active
    parameter limits results to active instances only
获取所选环境中的所有 API 实例。每个条目代表一个在 API Manager 中注册的受管理 API——这就是您要应用策略的目标。
所需信息:
  • 第 1 步的 Organization ID
  • 第 2 步的 Environment ID
操作: 列出 API 实例并让用户选择一个。
yaml
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 实例。每个 asset 可能包含多个实例(例如不同版本或标签)。用户选择要作为目标的特定
environmentApiId
。
提示:
  • 如果列表较长,可使用
    query
    参数按名称筛选
  • filters=active
    参数可将结果限制为活跃实例

Step 4: Browse Exchange Policy Catalog

第 4 步:浏览 Exchange 策略目录

List all available policy templates from Exchange for your organization. This endpoint returns the full Exchange coordinates (
groupId
,
assetId
,
version
) and gateway-compatible configuration for each template — these are required when applying a policy.
Important: Use the
api-portal-xapi
endpoint (
getExchangePolicyTemplates
) instead of the generic
listPolicyTemplates
endpoint. The generic endpoint does not return Exchange coordinates or gateway-specific configuration property names, which are required for the apply step.
What you'll need:
  • Organization ID from Step 1
  • Environment ID from Step 2
  • The API instance ID from Step 3 (to filter for compatible templates)
Action: List Exchange policy templates and select the one to apply. Pass
apiInstanceId
and
environmentId
to filter for templates compatible with your API's gateway type (e.g., Omni Gateway, Mule Gateway).
yaml
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
What happens next: You have the policy template's Exchange coordinates and its configuration schema with the correct property names for your gateway type. Review the
policyConfiguration
output to understand what settings the policy accepts before applying it. For each configuration property, present the user with the property name, its description, and the default value, then ask if they want to keep the default or provide a custom value. If a property has no default, always ask the user for a value.
Common issues:
  • Empty list: Pass
    apiInstanceId
    and
    environmentId
    to get templates compatible with your gateway type. Without these filters, some templates may not appear.
  • Wrong config property names: Always use the configuration from this endpoint — the generic
    listPolicyTemplates
    endpoint may return different (non-gateway-compatible) property names and defaults. For example, Omni Gateway uses
    credentialsOriginHasHttpBasicAuthenticationHeader
    while the generic template uses
    credentialsOrigin
    .
列出组织在 Exchange 中所有可用的策略模板。此端点会返回每个模板的完整 Exchange 坐标(
groupId
、
assetId
、
version
)以及兼容 Gateway 的配置——应用策略时需要这些信息。
重要: 请使用
api-portal-xapi
端点(
getExchangePolicyTemplates
),而不是通用的
listPolicyTemplates
端点。通用端点不会返回 Exchange 坐标或特定于 Gateway 的配置属性名称,而应用步骤需要这些内容。
所需信息:
  • 第 1 步的 Organization ID
  • 第 2 步的 Environment ID
  • 第 3 步的 API 实例 ID(用于筛选兼容模板)
操作: 列出 Exchange 策略模板并选择要应用的模板。传入
apiInstanceId
和
environmentId
,以筛选与 API 的 Gateway 类型(例如 Omni Gateway、Mule Gateway)兼容的模板。
yaml
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 坐标及其配置 schema,其中包含适用于您 Gateway 类型的正确属性名称。检查
policyConfiguration
输出,以了解该策略接受哪些设置。对于每个配置属性,向用户展示属性名称、说明和默认值,然后询问用户是保留默认值还是提供自定义值。如果某个属性没有默认值,始终要求用户提供值。
常见问题:
  • 结果为空:传入
    apiInstanceId
    和
    environmentId
    ,以获取与 Gateway 类型兼容的模板。如果不使用这些筛选器,某些模板可能不会显示。
  • 配置属性名称错误:始终使用此端点返回的
    configuration
    ——通用
    listPolicyTemplates
    端点可能返回不同的(不兼容 Gateway 的)属性名称和默认值。例如,Omni Gateway 使用
    credentialsOriginHasHttpBasicAuthenticationHeader
    ,而通用模板使用
    credentialsOrigin
    。

Step 5: Apply Policy to API Instance

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

Apply the selected policy to your API instance with the appropriate configuration. Use the Exchange coordinates and configuration property names from Step 4.
What you'll need:
  • Organization ID, Environment ID, and API instance ID from previous steps
  • Policy Exchange coordinates (groupId, assetId, assetVersion) from Step 4
  • Policy configuration based on the schema from Step 4's
    policyConfiguration
    output
Action: Apply the policy to your API instance. Build the
configurationData
object using the property names from Step 4's configuration schema. For each configuration property, present the user with the property name, its description, and the default value, then ask if they want to keep the default or provide a custom value. If a property has no default, always ask the user for a value.
yaml
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
What happens next: Your API is now protected with the selected policy. Incoming requests will be evaluated against the policy rules. You can verify by listing the API's applied policies or testing a request.
Common issues:
  • 400 Bad Request — missing groupId/assetId/assetVersion: The apply endpoint requires full Exchange coordinates, not just a template ID. Make sure you used
    getExchangePolicyTemplates
    (Step 4) to get these values.
  • 400 Bad Request — invalid configurationData: The configuration property names differ between gateway types. Use the property names from Step 4's
    policyConfiguration
    output, not from the generic template endpoint. For example, Omni Gateway uses
    credentialsOriginHasHttpBasicAuthenticationHeader
    while the generic template uses
    credentialsOrigin
    .
  • 403 Forbidden: Missing Manage Policies permission in this environment.
  • 409 Conflict: A policy of this type may already be applied to the API instance. List existing policies first to check, or add
    ?allowDuplicated=true
    to the request URL to apply a second instance of the same policy type.
使用适当的配置,将所选策略应用到您的 API 实例。使用第 4 步中的 Exchange 坐标和配置属性名称。
所需信息:
  • 前面步骤中的 Organization ID、Environment ID 和 API instance ID
  • 第 4 步中的 Policy Exchange 坐标(
    groupId
    、
    assetId
    、
    assetVersion
    )
  • 基于第 4 步
    policyConfiguration
    输出中 schema 的策略配置
操作: 将策略应用到您的 API 实例。使用第 4 步配置 schema 中的属性名称构建
configurationData
对象。对于每个配置属性,向用户展示属性名称、说明和默认值,然后询问用户是保留默认值还是提供自定义值。如果某个属性没有默认值,始终要求用户提供值。
yaml
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 无效:不同 Gateway 类型的配置属性名称不同。请使用第 4 步
    policyConfiguration
    输出中的属性名称,而不是通用模板端点返回的属性名称。例如,Omni Gateway 使用
    credentialsOriginHasHttpBasicAuthenticationHeader
    ,而通用模板使用
    credentialsOrigin
    。
  • 403 Forbidden:当前环境中缺少 Manage Policies 权限。
  • 409 Conflict:该 API 实例可能已经应用了此类型的策略。请先列出已有策略进行检查,或在请求 URL 中添加
    ?allowDuplicated=true
    ,以应用同类型策略的第二个实例。

Completion Checklist

完成检查清单

After completing all steps, verify the policy is properly applied:
  • Organization and environment selected
  • Target API instance identified
  • Policy template chosen from compatible catalog
  • Configuration built from the template's JSON schema
  • Policy applied successfully (201 response with policy ID)
  • Verify policy appears in the API's policy list
完成所有步骤后,验证策略是否已正确应用:
  • 已选择组织和环境
  • 已确定目标 API 实例
  • 已从兼容目录中选择策略模板
  • 已根据模板的 JSON schema 构建配置
  • 策略已成功应用(返回 201 响应及策略 ID)
  • 已验证策略出现在 API 的策略列表中

What You've Built

构建成果

✅ Policy Enforcement — The selected policy template is now active on your API instance, configured with the parameters you provided. Incoming traffic is evaluated against this policy.
✅ 策略执行——所选策略模板现已使用您提供的参数在 API 实例上激活。传入流量将根据此策略进行评估。

Next Steps

后续步骤

  1. Verify the policy — List applied policies with
    listApiPolicies
    to confirm it's active and correctly configured.
  2. Test the enforcement — Send requests to the API and verify the policy behaves as expected (e.g., unauthorized requests are rejected, rate limits are enforced).
  3. Adjust configuration — Use
    updateApiPolicy
    to update configuration without removing the policy.
  4. Apply additional policies — Repeat this workflow to layer multiple policies (e.g., add rate limiting on top of OAuth2). Use
    reorderApiPolicies
    to control execution order.
  5. Consider automated policies — If you want this policy applied to all APIs in the organization automatically, explore
    createAutomatedPolicy
    .
  1. 验证策略——使用
    listApiPolicies
    列出已应用的策略,确认其处于活动状态且配置正确。
  2. 测试策略执行——向 API 发送请求并验证策略行为是否符合预期(例如拒绝未授权请求、执行速率限制)。
  3. 调整配置——使用
    updateApiPolicy
    更新配置,无需移除策略。
  4. 应用其他策略——重复此工作流以叠加多个策略(例如在 OAuth2 之上添加速率限制)。使用
    reorderApiPolicies
    控制执行顺序。
  5. 考虑自动化策略——如果希望将此策略自动应用到组织中的所有 API,请探索
    createAutomatedPolicy
    。

Troubleshooting

故障排除

Policy Not Enforcing After Apply

应用策略后策略未生效

Symptoms: Requests pass through without policy evaluation
Possible causes:
  • API instance is not deployed or is in an error state
  • Gateway hasn't picked up the new configuration yet (wait 1-2 minutes)
  • Policy configuration has a permissive default that allows all traffic
  • Pointcut data excludes the endpoints you're testing
Solutions:
  • Check API instance status in API Manager
  • Wait for propagation and retry
  • Review policy configuration for overly permissive settings
  • Check
    pointcutData
    — omit it to apply to all endpoints
症状: 请求未经策略评估即通过
可能原因:
  • API 实例尚未部署或处于错误状态
  • Gateway 尚未获取新配置(等待 1 至 2 分钟)
  • 策略配置包含允许所有流量通过的宽松默认值
  • Pointcut 数据排除了正在测试的端点
解决方案:
  • 检查 API Manager 中的 API 实例状态
  • 等待配置传播并重试
  • 检查策略配置中是否有过于宽松的设置
  • 检查
    pointcutData
    ——省略该字段即可应用到所有端点

400 Error When Applying Policy

应用策略时出现 400 错误

Symptoms:
"The policy to be created is missing at least one of the following properties related to the policy template: 'groupId', 'assetId', 'assetVersion'."
Possible causes:
  • Used the generic
    listPolicyTemplates
    endpoint which does not return Exchange coordinates
Solutions:
  • Use
    getExchangePolicyTemplates
    from
    api-portal-xapi
    instead — this returns the full Exchange coordinates needed by the apply endpoint
症状:
"要创建的策略缺少与策略模板相关的以下属性中的至少一项:'groupId'、'assetId'、'assetVersion'。"
可能原因:
  • 使用了通用
    listPolicyTemplates
    端点,该端点不会返回 Exchange 坐标
解决方案:
  • 改用
    api-portal-xapi
    中的
    getExchangePolicyTemplates
    ——它会返回应用端点所需的完整 Exchange 坐标

Configuration Property Name Mismatch

配置属性名称不匹配

Symptoms: 400 error with invalid
configurationData
Possible causes:
  • Used property names from the generic template endpoint instead of the gateway-compatible ones
  • Required fields missing in
    configurationData
  • Wrong data types (e.g., string instead of integer)
Solutions:
  • Always use the
    configuration
    output from
    getExchangePolicyTemplates
    (Step 4) — it returns gateway-specific property names
  • For example, Omni Gateway uses
    credentialsOriginHasHttpBasicAuthenticationHeader
    while the generic template uses
    credentialsOrigin
  • Match field types exactly (numbers, booleans, arrays)
  • Only include fields defined in the schema
症状: 使用无效
configurationData
时出现 400 错误
可能原因:
  • 使用了通用模板端点中的属性名称,而不是兼容 Gateway 的属性名称
  • configurationData
    中缺少必填字段
  • 数据类型错误(例如使用 string 而不是 integer)
解决方案:
  • 始终使用
    getExchangePolicyTemplates
    (第 4 步)的
    configuration
    输出——它会返回特定于 Gateway 的属性名称
  • 例如,Omni Gateway 使用
    credentialsOriginHasHttpBasicAuthenticationHeader
    ,而通用模板使用
    credentialsOrigin
  • 严格匹配字段类型(数字、布尔值、数组)
  • 仅包含 schema 中定义的字段

Policy Template Not Found

找不到策略模板

Symptoms: Empty results in Step 4
Possible causes:
  • The API instance's gateway type doesn't support that template
  • Missing
    apiInstanceId
    or
    environmentId
    filters
  • Custom policy template hasn't been published to this organization
Solutions:
  • Pass both
    apiInstanceId
    and
    environmentId
    to filter for compatible templates
  • Remove filters to see all templates, then check compatibility manually
  • For custom policies, verify the template is published via
    listCustomPolicyTemplates
症状: 第 4 步的结果为空
可能原因:
  • API 实例的 Gateway 类型不支持该模板
  • 缺少
    apiInstanceId
    或
    environmentId
    筛选条件
  • 自定义策略模板尚未发布到此组织
解决方案:
  • 同时传入
    apiInstanceId
    和
    environmentId
    ,以筛选兼容模板
  • 移除筛选条件以查看所有模板,然后手动检查兼容性
  • 对于自定义策略,请通过
    listCustomPolicyTemplates
    验证模板是否已发布

Related Jobs

相关 Jobs

  • skill apply-universal-policy — Protect a portfolio slice with one Universal (canonical) policy across instances on any gateway. Use that when the user says all / many / my APIs / a named provider.
  • skill apply-native-policy-to-instance — List what's applied, edit an already-applied native policy, or apply one native plugin/template via the MuleSoft Platform MCP Server (Kong / Apigee / Azure / MuleSoft). Use that for "what protection do I have for my Apigee APIs" and "improve the IP filtering".
  • deploy-api-with-rate-limiting — Full workflow including API creation and tiered rate limiting with OAuth2
  • list-organization-api-instances — Discover existing API instances across environments
  • manage-consumer-contracts — Manage client application access after policies are applied
  • skill apply-universal-policy——使用一个 Universal(canonical)策略保护 API 组合中的目标部分,并将其应用于任意 Gateway 上的实例。当用户表示“全部/多个/我的 API/指定提供商”时,请使用该 skill。
  • skill apply-native-policy-to-instance——列出已应用的策略、编辑已应用的 native policy,或通过 MuleSoft Platform MCP Server(Kong / Apigee / Azure / MuleSoft)应用一个 native plugin/template。适用于“我的 Apigee API 当前有什么保护?”以及“改进 IP 过滤”之类的请求。
  • deploy-api-with-rate-limiting——包含 API 创建以及结合 OAuth2 的分层速率限制的完整工作流
  • list-organization-api-instances——发现各环境中的现有 API 实例
  • manage-consumer-contracts——在应用策略后管理客户端应用的访问权限