apply-policy-to-api-instance
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseApply 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:
-
Authentication ready
- Valid Bearer token for Anypoint Platform
- API Manager permissions: View APIs Configuration and Manage Policies scopes
-
Organization access
- The target API instance is already deployed in API Manager
在开始此工作流之前,请确保您具备:
-
已准备好身份验证
- Anypoint Platform 的有效 Bearer token
- API Manager 权限:View APIs Configuration 和 Manage Policies scopes
-
组织访问权限
- 目标 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 endpoint to get the current user's organization.
/meyaml
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 nameWhat happens next: You have the root organization ID derived from your credentials. If your account has sub-organizations (child Business Groups), use with this ID to list them and pick the right scope before continuing.
getOrganizations获取调用方的个人资料,以自动发现根组织。无需传入参数——Bearer token 用于标识用户并返回其组织详情,包括所有子 Business Groups(子组织)。
所需信息:
- 有效的 Bearer token(身份验证标头)
操作: 调用 端点以获取当前用户的组织。
/meyaml
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 调用 列出它们,并在继续之前选择正确的范围。
getOrganizationsStep 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 IDWhat 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 toWhat 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 to target.
environmentApiIdTips:
- Use the parameter to filter by name if the list is large
query - The parameter limits results to active instances only
filters=active
获取所选环境中的所有 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 (, , ) and gateway-compatible configuration for each template — these are required when applying a policy.
groupIdassetIdversionImportant: Use the endpoint () instead of the generic endpoint. The generic endpoint does not return Exchange coordinates or gateway-specific configuration property names, which are required for the apply step.
api-portal-xapigetExchangePolicyTemplateslistPolicyTemplatesWhat 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 and to filter for templates compatible with your API's gateway type (e.g., Omni Gateway, Mule Gateway).
apiInstanceIdenvironmentIdyaml
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 defaultsWhat 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 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.
policyConfigurationCommon issues:
- Empty list: Pass and
apiInstanceIdto get templates compatible with your gateway type. Without these filters, some templates may not appear.environmentId - Wrong config property names: Always use the configuration from this endpoint — the generic endpoint may return different (non-gateway-compatible) property names and defaults. For example, Omni Gateway uses
listPolicyTemplateswhile the generic template usescredentialsOriginHasHttpBasicAuthenticationHeader.credentialsOrigin
列出组织在 Exchange 中所有可用的策略模板。此端点会返回每个模板的完整 Exchange 坐标(、、)以及兼容 Gateway 的配置——应用策略时需要这些信息。
groupIdassetIdversion重要: 请使用 端点(),而不是通用的 端点。通用端点不会返回 Exchange 坐标或特定于 Gateway 的配置属性名称,而应用步骤需要这些内容。
api-portal-xapigetExchangePolicyTemplateslistPolicyTemplates所需信息:
- 第 1 步的 Organization ID
- 第 2 步的 Environment ID
- 第 3 步的 API 实例 ID(用于筛选兼容模板)
操作: 列出 Exchange 策略模板并选择要应用的模板。传入 和 ,以筛选与 API 的 Gateway 类型(例如 Omni Gateway、Mule Gateway)兼容的模板。
apiInstanceIdenvironmentIdyaml
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,以获取与 Gateway 类型兼容的模板。如果不使用这些筛选器,某些模板可能不会显示。environmentId - 配置属性名称错误:始终使用此端点返回的 ——通用
configuration端点可能返回不同的(不兼容 Gateway 的)属性名称和默认值。例如,Omni Gateway 使用listPolicyTemplates,而通用模板使用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 output
policyConfiguration
Action: Apply the policy to your API instance. Build the 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.
configurationDatayaml
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 instanceWhat 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 (Step 4) to get these values.
getExchangePolicyTemplates - 400 Bad Request — invalid configurationData: The configuration property names differ between gateway types. Use the property names from Step 4's output, not from the generic template endpoint. For example, Omni Gateway uses
policyConfigurationwhile the generic template usescredentialsOriginHasHttpBasicAuthenticationHeader.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 to the request URL to apply a second instance of the same policy type.
?allowDuplicated=true
使用适当的配置,将所选策略应用到您的 API 实例。使用第 4 步中的 Exchange 坐标和配置属性名称。
所需信息:
- 前面步骤中的 Organization ID、Environment ID 和 API instance ID
- 第 4 步中的 Policy Exchange 坐标(、
groupId、assetId)assetVersion - 基于第 4 步 输出中 schema 的策略配置
policyConfiguration
操作: 将策略应用到您的 API 实例。使用第 4 步配置 schema 中的属性名称构建 对象。对于每个配置属性,向用户展示属性名称、说明和默认值,然后询问用户是保留默认值还是提供自定义值。如果某个属性没有默认值,始终要求用户提供值。
configurationDatayaml
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。确保使用 (第 4 步)获取这些值。
getExchangePolicyTemplates - 400 Bad Request——configurationData 无效:不同 Gateway 类型的配置属性名称不同。请使用第 4 步 输出中的属性名称,而不是通用模板端点返回的属性名称。例如,Omni Gateway 使用
policyConfiguration,而通用模板使用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
后续步骤
-
Verify the policy — List applied policies withto confirm it's active and correctly configured.
listApiPolicies -
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).
-
Adjust configuration — Useto update configuration without removing the policy.
updateApiPolicy -
Apply additional policies — Repeat this workflow to layer multiple policies (e.g., add rate limiting on top of OAuth2). Useto control execution order.
reorderApiPolicies -
Consider automated policies — If you want this policy applied to all APIs in the organization automatically, explore.
createAutomatedPolicy
- 验证策略——使用 列出已应用的策略,确认其处于活动状态且配置正确。
listApiPolicies - 测试策略执行——向 API 发送请求并验证策略行为是否符合预期(例如拒绝未授权请求、执行速率限制)。
- 调整配置——使用 更新配置,无需移除策略。
updateApiPolicy - 应用其他策略——重复此工作流以叠加多个策略(例如在 OAuth2 之上添加速率限制)。使用 控制执行顺序。
reorderApiPolicies - 考虑自动化策略——如果希望将此策略自动应用到组织中的所有 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 — omit it to apply to all endpoints
pointcutData
症状: 请求未经策略评估即通过
可能原因:
- 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 endpoint which does not return Exchange coordinates
listPolicyTemplates
Solutions:
- Use from
getExchangePolicyTemplatesinstead — this returns the full Exchange coordinates needed by the apply endpointapi-portal-xapi
症状:
"要创建的策略缺少与策略模板相关的以下属性中的至少一项:'groupId'、'assetId'、'assetVersion'。"可能原因:
- 使用了通用 端点,该端点不会返回 Exchange 坐标
listPolicyTemplates
解决方案:
- 改用 中的
api-portal-xapi——它会返回应用端点所需的完整 Exchange 坐标getExchangePolicyTemplates
Configuration Property Name Mismatch
配置属性名称不匹配
Symptoms: 400 error with invalid
configurationDataPossible 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 output from
configuration(Step 4) — it returns gateway-specific property namesgetExchangePolicyTemplates - For example, Omni Gateway uses while the generic template uses
credentialsOriginHasHttpBasicAuthenticationHeadercredentialsOrigin - Match field types exactly (numbers, booleans, arrays)
- Only include fields defined in the schema
症状: 使用无效 时出现 400 错误
configurationData可能原因:
- 使用了通用模板端点中的属性名称,而不是兼容 Gateway 的属性名称
- 中缺少必填字段
configurationData - 数据类型错误(例如使用 string 而不是 integer)
解决方案:
- 始终使用 (第 4 步)的
getExchangePolicyTemplates输出——它会返回特定于 Gateway 的属性名称configuration - 例如,Omni Gateway 使用 ,而通用模板使用
credentialsOriginHasHttpBasicAuthenticationHeadercredentialsOrigin - 严格匹配字段类型(数字、布尔值、数组)
- 仅包含 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 or
apiInstanceIdfiltersenvironmentId - Custom policy template hasn't been published to this organization
Solutions:
- Pass both and
apiInstanceIdto filter for compatible templatesenvironmentId - 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——在应用策略后管理客户端应用的访问权限