本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 行动和资源范围的政策 本节中的策略是根据所**调用的内容（哪个操作、在**哪个网关上、使用哪些输入值）进行匹配，而不是根据谁在呼叫进行匹配。它们不控制哪些委托人可以采取行动；网关认证的任何呼叫者都在范围内。 有关基于来电者身份的规则，请参阅[Principal-scoped 政策](example-policies-principal.md)。最后的[组合策略](#example-policies-action-resource-combined)部分显示了这两种策略的协同作用。 每个示例都对[示例资源配置中描述的网关进行](example-policies-reference.md)授权。这些政策仅使用在 Dogwood 和 Cedar 中均有效的结构。 ## 行动要求和资源范围 本页上的每个策略都适用两个要求，而违反任何一个策略的策略在您创建时都会被拒绝。 **操作范围和资源范围必须一致。**你写的资源表单取决于你是否命名了特定的操作： | 如果操作范围是 | 资源范围必须是 | | --- | --- | | 一项或多项具体操作 — `action == …` 或 `action in […]` | 特定的网关 — `resource == AgentCore::Gateway::""` | | 不受约束——赤身裸体 `action` | 类型测试—— `resource is AgentCore::Gateway` | **资源永远不能不受限制。**无论你使用哪个操作范围`a wildcard resource was detected`，bar `resource` e 都会被拒绝。 因此，命名特定的操作意味着知道网关 ARN，只有在网关存在后才能知道网关 ARN。有关详细信息，请参阅[资源特异性要求。](policy-scope.md#policy-resource-specificity) ## 通配符在哪里起作用 `*`在政策的不同部分中意味着不同的内容，而且并非所有地方都接受它。 **不在动作名称中。**Cedar 没有用于操作名称的通配符，`AgentCore::Action::"InsuranceAPI___get*"`因此无效。列出与该目标相关的操作`action in [ …​ ]`，或者将策略范围限定为整个目标`action in AgentCore::Action::""`，这样还会选择稍后添加到该目标中的工具。有关更多信息，请参阅[多个操作](policy-scope.md#policy-action-wildcards)。 **不在资源中。**裸露`resource`被拒绝。使用特定的网关 ARN 或类型测试`resource is AgentCore::Gateway`，如上一节所述。 **在字符串比较中是。**在条件内部，`like`采用`*`与任何字符组匹配的模式 — 这是通配符应用的地方： ``` context.input.coverageType like "auto*" ``` 将模式固定在可以的地方：`auto*`匹配以开头的值`auto`，同时`*auto*`也会匹配`semi-auto-salvage`。 ## 选择动作 ### 允许同时执行多个操作 **意图：**允许阅读合同详情和索赔状态。 使用对相关的读取操作进行分组`action in [ …​ ]`可以避免每个工具使用一个策略。每个动作都是明确命名的，因为动作名称不带通配符——参见通[配符的工作原理](#example-policies-action-resource-wildcards)。 **当你想要整套工具集时，我们建议将范围限定在目标上。**写作`action in AgentCore::Action::""`涵盖了目标公开的所有工具，包括稍后添加的工具，因此无需在目标每次获得工具时都对策略进行编辑。权衡之处在于，目标范围的策略不能对工具输入设定条件，因为每个工具的输入都不同。有关更多信息，请参阅[多个操作](policy-scope.md#policy-action-wildcards)。 ``` permit( principal, action in [ AgentCore::Action::"InsuranceAPI___get_contract", AgentCore::Action::"InsuranceAPI___get_claim_status" ], resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ); ``` ### 允许调用运行时目标 **意图：**允许调用索赔助手。 AgentCore 运行时目标作为单个操作进行授权，该操作以目标及其调用方法和路径命名。这不是代理可能在内部使用的每种工具一个操作。对于运行时目标，该路径始终为`/invocations`。无论代理在该边界后面调用什么工具，都超出了该政策的覆盖范围，因此请管理他们自己的网关上的工具。 ``` permit( principal, action == AgentCore::Action::"ClaimsAgent___POST:/invocations", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ); ``` ### 允许在每条路径上发出推理请求 **意图：**允许网关公开的所有三个推理 API。 每个推理目标都是一个操作，网关每个 API 形状都有一个目标，因此策略必须命名您打算允许的每条路径。只命名一个会让其他人被拒绝，或者，对于 a 来说`forbid`，没有经过筛选。 ``` permit( principal, action in [ AgentCore::Action::"ClaimsChat___POST:/v1/chat/completions", AgentCore::Action::"ClaimsResponses___POST:/v1/responses", AgentCore::Action::"ClaimsMessages___POST:/v1/messages" ], resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ); ``` ### 限制可以调用哪个模型 **意图：**仅允许针对经批准的模特家族完成聊天。 `model`是每个推理信封中的标量字符串，因此普通条件可以直接读取它。这在 Dogwood 中的作用方式相同，因为 Dogwood 接受每个 Cedar 条件。 ``` permit( principal, action == AgentCore::Action::"ClaimsChat___POST:/v1/chat/completions", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ) when { context.input.model like "openai.gpt-oss-*" }; ``` 该`model`值以形式同时包含提供者和模型`.`。将其与固定一个模型完全匹配，如所示`"openai.gpt-oss-120b-1:0"`。在提供者前缀上锚定一个`like`模式，以仅允许该提供者的模型，如所示`like "openai.*"`。`ClaimsMessages`使用他们自己批准`ClaimsResponses`的值重复该政策。 **重要** **Cedar 状况无法读懂对话本身 —— 为此请使用护栏。** 推理目标上的条件只能到达请求正文的**标量**成员，例如`model`或。`max_tokens`他们无法收到消息文本。 `context.input.messages`是`Set`，没有 Dogwood 或 Cedar 操作员从一个字符串中读出一个字符串。诸如集合之类的集合运算符`isEmpty`适用于集合本身。但是，Cedar 和 Dogwood 都没有用于其中的字符串的数组投影语法。 要根据实际所说的内容采取行动，请在消息数组中写一个数据路径为 jsonPath 的护栏。有关可以为每个推理 API 复制的策略，请参阅使用 [JSONPath 访问数组内的文本](example-policies-guardrails.md#example-policies-guardrails-jsonpath)。 ## 刀具输入条件 `context.input`保存正在授权的呼叫的参数。对于 MCP 工具，它保存工具参数；对于运行时或推理目标，它保存请求正文。参数上可用的运算符取决于其类型，请参阅[条件中的参数类型](example-policies-reference.md#example-policies-types)。 ### 字符串相等 **意图：**仅允许对企业支持的索赔类型提出索赔。 ``` permit( principal, action == AgentCore::Action::"InsuranceAPI___file_claim", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ) when { (context.input.claimType == "health" || context.input.claimType == "property" || context.input.claimType == "auto") }; ``` ### 设置成员资格 **意图：**对可接受的值列表表达相同的规则。 一个集合文字，随着列表的增长，其`.contains()`读数要好于`||`比较链，并且这两种形式是等效的。注意方向：集合是接收者，值是参数。 ``` permit( principal, action == AgentCore::Action::"InsuranceAPI___file_claim", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ) when { ["health", "property", "auto"].contains(context.input.claimType) }; ``` ### 模式匹配 **意图：**允许计算任何汽车保险类型的保费。 在`like`模式中`*`匹配任何一组字符，so、`auto``auto-liability`、and `auto-collision` 都匹配。这是策略中唯一适用通配符的地方，而不是操作名称或资源。有关更多信息，请参阅[通配符的工作](#example-policies-action-resource-wildcards)原理。 ``` permit( principal, action == AgentCore::Action::"InsuranceAPI___calculate_premium", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ) when { context.input.coverageType like "auto*" }; ``` ### 整数比较 **意图：**仅允许针对至少十二个月的保单期限提出索赔。 `policyTermMonths`是工具架构`integer`中的一个，因此它是 Cedar `Long` 和有序运算符`<``⇐`、`>`、和直接`>=`应用。 ``` permit( principal, action == AgentCore::Action::"InsuranceAPI___file_claim", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ) when { context.input.policyTermMonths >= 12 }; ``` ### 十进制比较 **意图：**仅允许对低于 1,000 的金额提出索赔。 ``` permit( principal, action == AgentCore::Action::"InsuranceAPI___file_claim", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ) when { context.input.amount.lessThan(decimal("1000.00")) }; ``` **重要** 在对数字参数进行比较之前，请确认其类型支持哪些运算符。 `amount`是工具架构`number`中的一个，所以它是 Cedar`decimal`：将其与`lessThan`、`lessThanOrEqual``greaterThan`、或`greaterThanOrEqual`与带引号的`decimal("…​")`文字进行比较。`integer`参数是 Cedar`Long`，它使用普通`<`的 and `>` 运算符来代替。 有关每种数值类型接受的运算符的更多信息，请参阅[数字参数](example-policies-reference.md#example-policies-numeric)，其中还涵盖了`temporal { }`块内的额外限制以及如何报告类型错误。 ### Boolean condition **意图：**允许仅在批准获得批准时才记录批准。 `boolean`参数直接用作条件。要提出相反的要求，请写作`!context.input.approved`。顺序运算符不适用 — 创建`context.input.approved > true`失败`expected datetime, or duration, or Long`。 ``` permit( principal, action == AgentCore::Action::"InsuranceAPI___approve_claim", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ) when { context.input.approved }; ``` ### 嵌套对象成员 **意图：**仅允许在受支持地区之前没有索赔的保单计算保费。 `object`参数变成 Cedar 记录，这是一组带点的命名成员。`has`在阅读每个级别之前，请先对其进行测试：因为`riskFactors`这是可选的，因此省略任一防护都无法创建策略。`unable to guarantee safety of access to optional attribute`记录的最大嵌套深度为 64 级；更深的记录在运行时会`context.input`被拒绝`Cannot determine input entity type`。 ``` permit( principal, action == AgentCore::Action::"InsuranceAPI___calculate_premium", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ) when { context.input has riskFactors && context.input.riskFactors has priorClaims && context.input.riskFactors.priorClaims == 0 && context.input.riskFactors has region && ["us-west", "us-east"].contains(context.input.riskFactors.region) }; ``` ### 需要一个可选参数 **意图：**尽管工具架构将其设为可选，但要求对每份已提交的索赔进行描述。 可选参数是指工具架构未按要求列出的参数，因此调用者可以省略该参数。在参考网关的 MCP 工具`description`上，on `file_claim` 和 `riskFactors` on `calculate_premium` 是唯一的可选参数；运行时目标也需要一个可选`sessionAttributes`参数。 有两种方法可以写这篇文章，它们的行为方式不同。**我们建议使用第二`forbid`张显示的表格**，因为无论适用哪种其他政策，该表格都适用。`permit`表单之所以排在第一位，是因为它是读者想要的，而且它没有该属性。当该字段存在时，A 会`permit`授予访问权限： ``` permit( principal, action == AgentCore::Action::"InsuranceAPI___file_claim", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ) when { context.input has description }; ``` 无论适用哪种其他政策，A `forbid` 都将该字段设置为必填字段： ``` forbid( principal, action == AgentCore::Action::"InsuranceAPI___file_claim", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ) unless { context.input has description }; ``` 对于要无条件保留的业务规则，最好使用`forbid`表单，因为其他业务规则`permit`无法覆盖该表单。 **重要** `has`对于可选参数来说是**必需的**，而不仅仅是防御性的。在不保护可选属性的情况下读取该属性会导致策略创建失败： ``` unable to guarantee safety of access to optional attribute `input.riskFactors` ``` 警卫是必需的，而不是建议性的，省略它会导致策略创建失败。**必填参数不需要**保护，因此`has`只有在工具架构将该字段标记为可选时才需要该参数。 ## 操作模式 这些策略是运行网关的工具，而不是业务规则的表达方式。因为它们很宽泛，所以要故意添加它们，并在需要它们的情况过去后将其删除。 ### 停止所有工具调用 **意图：**在事件发生期间，停止网关上的所有操作。 这会拒绝对连接到策略引擎的每个网关发出的每个请求，从而覆盖所有`permit`策略。添加它将在不更改任何其他策略的情况下生效，删除它会恢复正常操作。 ``` forbid( principal, action, resource is AgentCore::Gateway ); ``` **警告** 在依赖此策略之前，请先验证引擎的强制模式。如果网关`policyEngineConfiguration.mode`是`LOG_ONLY`，则会记录决策，但不会强制执行，并且每个工具调用仍然会成功。有关更多信息，请参阅[策略实施模式](policy-enforcement-modes.md)。 ### 禁用一个工具 **意图：**在不影响网关其余部分的情况下拒绝访问单个工具。 此政策生效后，每个来电者的该工具都会消失，因此代理停止尝试该工具，而不是拨打该工具并被拒绝。`tools/list` ``` forbid( principal, action == AgentCore::Action::"InsuranceAPI___disburse_payment", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ); ``` ## 组合政策 前两节按策略的匹配内容来区分策略。一条规则通常会限制两者。这些示例在一个策略中将主条件与操作和输入条件结合在一起。 ### 将职称及其输入限制在一起 **意图：**仅允许对支持的保险类型进行覆盖范围更新，并且仅当提供新的限制并且保持在来电者的职称所拥有的权限之内时。 一项策略可以将委托人和投入限制在一起，而在单一的策略中这样做`permit`才是条件**结合**在一起的原因。如果参数是可选的，则在它保护的读取之前先对其`has`进行测试。 ``` permit( principal is AgentCore::OAuthUser, action == AgentCore::Action::"InsuranceAPI___update_coverage", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ) when { principal.hasTag("role") && principal.getTag("role") == "senior-adjuster" && ["liability", "collision"].contains(context.input.coverageType) && context.input.newLimit.lessThanOrEqual(decimal("50000.00")) }; ``` ### 为两个角色设置一个工具的不同限制 **意图：**让理算师支付少量款项，让经理支付大笔款项。 分级权限`permit`每级一个，每个级别将职称与自己的上限配对。由于这两种政策是替代方案，因此经理不受理算师政策的限制。 `amountCents`是`integer`，因此它使用普通的有序运算符而不是`decimal`方法。 ``` // Adjusters: up to 1,000.00 permit( principal is AgentCore::OAuthUser, action == AgentCore::Action::"InsuranceAPI___disburse_payment", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ) when { principal.hasTag("role") && principal.getTag("role") == "adjuster" && context.input.amountCents <= 100000 }; // Managers: up to 25,000.00 permit( principal is AgentCore::OAuthUser, action == AgentCore::Action::"InsuranceAPI___disburse_payment", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance-gw-a1b2c3d4e5" ) when { principal.hasTag("role") && principal.getTag("role") == "manager" && context.input.amountCents <= 2500000 }; ``` ## 这些政策是如何结合在一起的 一个引擎上的策略是一起评估的，结果不是每个策略允许的总和。三个规则决定每个请求： **默认情况下拒绝** 只有当某些请求与之`permit`匹配时，才允许该请求。没有策略的引擎会拒绝所有内容。 **禁止获胜** 如果有任何`forbid`匹配项，则请求将被拒绝，即使 a 也`permit`与之匹配。这就是让 [Stop all 工具调用](#example-policies-action-resource-shutdown)变得可靠的原因，也是无法通过添加来覆盖`forbid …​ unless`限制的原因。`permit` **许可证不相交** 同一操作的两种`permit`策略是替代方案，而不是要求。如果一个`permit`允许`update_coverage`经理，另一个允许变更责任，则允许经理更改任何内容，也允许任何人更改负债。要要求这两个条件，请将它们合而`permit`为一，就像[限制职称及其输入合在一起](#example-policies-action-resource-combined-authority)一样，或者将限制表示为`forbid …​ unless`。 请注意，a `permit` 不能缩小另一个的范围`permit`。以下三项策略适用于该`update_coverage`操作： + [允许特定用户](example-policies-principal.md#example-policies-principal-username)许可`clare`。 + [禁止所有人，除非一组职位](example-policies-principal.md#example-policies-principal-role-forbid)拒绝任何不是高级理算师或经理的人。 + [限制职称及其输入允许高级理算师在其](#example-policies-action-resource-combined-authority)限制范围内更改责任或碰撞。 既不是高级理算师也不是经理的申请**被拒绝**：第一份保单允许，但第二份保单禁止这样做。`clare`第三份保单**允许**高级理算师提出将责任限额提高到40,000的请求，而第二份保单不禁止这样做。高级理算师更改`comprehensive`保险类型被**拒绝**，因为没有该`permit`保险类型的保险。 要在强制执行之前根据已部署的引擎检查您的推理，请通过[在 LOG\_ONLY 模式下测试策略来运行请求，或者将引擎附加到`LOG_ONLY`模式下并从策略日志](policy-test-a-policy.md)中读取决策。