可以在不同的范围内为不同的目的使用访问限制策略。You can use access restriction policies in different scopes for different purposes.例如，可以通过在 API 级别上应用 validate-jwt 策略来使用 AAD 身份验证保护整个 API，也可以在 API 操作级别上应用它并使用 claims 进行更细粒度的控制。For example, you can secure the whole API with AAD authentication by applying the validate-jwt policy on the API level or you can apply it on the API operation level and use claims for more granular control.

检查 HTTP 标头Check HTTP header

使用 check-header 策略强制请求具有指定的 HTTP 标头。Use the check-header policy to enforce that a request has a specified HTTP header.可以选择性地查看标头是否具有特定值，或者检查是否存在一系列允许的值。You can optionally check to see if the header has a specific value or check for a range of allowed values.如果检查失败，此策略会终止请求处理，并返回其所指定的 HTTP 状态代码和错误消息。If the check fails, the policy terminates request processing and returns the HTTP status code and error message specified by the policy.

元素Elements

允许的 HTTP 标头值。Allowed HTTP header value.指定了多个值元素时，如果任何一个值匹配，则可认为检查成功。When multiple value elements are specified, the check is considered a success if any one of the values is a match.

否No

属性Attributes

NameName

说明Description

必须Required

默认Default

failed-check-error-messagefailed-check-error-message

在标头不存在或其值无效的情况下，需要在 HTTP 响应正文中返回的错误消息。Error message to return in the HTTP response body if the header doesn't exist or has an invalid value.此消息必须对任何特殊字符正确地进行转义。This message must have any special characters properly escaped.

是Yes

不适用N/A

failed-check-httpcodefailed-check-httpcode

在标头不存在或其值无效时需返回的 HTTP 状态代码。HTTP Status code to return if the header doesn't exist or has an invalid value.

是Yes

不适用N/A

header-nameheader-name

要检查的 HTTP 标头的名称。The name of the HTTP Header to check.

是Yes

不适用N/A

ignore-caseignore-case

可以设置为 True 或 False。Can be set to True or False.如果设置为 True，则在将标头值与一组可接受的值进行比较时，会忽略大小写。If set to True case is ignored when the header value is compared against the set of acceptable values.

是Yes

不适用N/A

使用情况Usage

此策略可在以下策略节和范围中使用。This policy can be used in the following policy sections and scopes.

策略节： 入站、出站Policy sections: inbound, outbound

策略范围： 所有范围Policy scopes: all scopes

按订阅限制调用速率Limit call rate by subscription

rate-limit 策略可以对调用速率进行限制，使每个指定时段的调用不超出指定的数目，避免单个订阅的 API 使用量暴增。The rate-limit policy prevents API usage spikes on a per subscription basis by limiting the call rate to a specified number per a specified time period.触发此策略时，调用方会收到 429 Too Many Requests 响应状态代码。When this policy is triggered the caller receives a 429 Too Many Requests response status code.

Important

每个策略文档只能使用此策略一次。This policy can be used only once per policy document.

由于限制体系结构的分布式性质，速率限制永远不可能完全准确。Due to the distributed nature of throttling architecture, rate limiting is never completely accurate.允许的请求的配置数字和实际数字之间的差异因请求量和速度、后端延迟以及其他因素而异。The difference between configured and the real number of allowed requests vary based on request volume and rate, backend latency, and other factors.

示例Example

元素Elements

NameName

说明Description

必须Required

rate-limitrate-limit

根元素。Root element.

是Yes

apiapi

添加一个或多个此类元素，对产品中的 API 施加调用速率限制。Add one or more of these elements to impose a call rate limit on APIs within the product.产品和 API 的调用速率限制是各自独立应用的。Product and API call rate limits are applied independently.可以通过 name 或 id 引用 API。API can be referenced either via name or id.如果同时提供了这两个属性，则将使用 id 并忽略 name。If both attributes are provided, id will be used and name will be ignored.

否No

operationoperation

添加一个或多个此类元素，对 API 中的操作施加调用速率限制。Add one or more of these elements to impose a call rate limit on operations within an API.产品、API 和操作的调用速率限制是各自独立应用的。Product, API, and operation call rate limits are applied independently.可以通过 name 或 id 引用 Operation。Operation can be referenced either via name or id.如果同时提供了这两个属性，则将使用 id 并忽略 name。If both attributes are provided, id will be used and name will be ignored.

否No

属性Attributes

NameName

说明Description

必须Required

默认Default

namename

要对其应用速率限制的 API 的名称。The name of the API for which to apply the rate limit.

是Yes

不适用N/A

callscalls

在 renewal-period 所指定的时间间隔内允许的最大总调用数。The maximum total number of calls allowed during the time interval specified in the renewal-period.

是Yes

不适用N/A

renewal-periodrenewal-period

在重置配额之前等待的时间长度，以秒为单位。The time period in seconds after which the quota resets.

是Yes

不适用N/A

使用情况Usage

此策略可在以下策略段和范围中使用。This policy can be used in the following policy sections and scopes.

策略节： 入站Policy sections: inbound

策略范围： 产品、API、操作Policy scopes: product, api, operation

按密钥限制调用速率Limit call rate by key

rate-limit-by-key 策略可以对调用速率进行限制，使每个指定时段的调用不超出指定的数目，避免单个密钥的 API 使用量暴增。The rate-limit-by-key policy prevents API usage spikes on a per key basis by limiting the call rate to a specified number per a specified time period.密钥的值可以是任意字符串，通常使用策略表达式来提供密钥。The key can have an arbitrary string value and is typically provided using a policy expression.可以添加可选增量条件，指定在判断请求数是否达到限制时应计入哪些请求。Optional increment condition can be added to specify which requests should be counted towards the limit.触发此策略时，调用方会收到429 Too Many Requests响应状态代码。When this policy is triggered the caller receives a 429 Too Many Requests response status code.

由于限制体系结构的分布式性质，速率限制永远不可能完全准确。Due to the distributed nature of throttling architecture, rate limiting is never completely accurate.允许的请求的配置数字和实际数字之间的差异因请求量和速度、后端延迟以及其他因素而异。The difference between configured and the real number of allowed requests vary based on request volume and rate, backend latency, and other factors.

示例Example

元素Elements

NameName

说明Description

必须Required

quotaquota

根元素。Root element.

是Yes

apiapi

添加一个或多个此类元素，对产品中的 API 设置调用配额。Add one or more of these elements to impose call quota on APIs within the product.产品和 API 的调用配额是分别应用的。Product and API call quotas are applied independently.可以通过 name 或 id 引用 API。API can be referenced either via name or id.如果同时提供了这两个属性，则将使用 id 并忽略 name。If both attributes are provided, id will be used and name will be ignored.

否No

operationoperation

添加一个或多个此类元素，对 API 中的操作设置调用配额。Add one or more of these elements to impose call quota on operations within an API.产品、API 和操作的调用配额是分别应用的。Product, API, and operation call quotas are applied independently.可以通过 name 或 id 引用 Operation。Operation can be referenced either via name or id.如果同时提供了这两个属性，则将使用 id 并忽略 name。If both attributes are provided, id will be used and name will be ignored.

否No

属性Attributes

NameName

说明Description

必须Required

默认Default

namename

要向其应用配额的 API 或操作的名称。The name of the API or operation for which the quota applies.

是Yes

不适用N/A

bandwidthbandwidth

在 renewal-period 所指定的时间间隔内允许的最大总字节数（千字节）。The maximum total number of kilobytes allowed during the time interval specified in the renewal-period.

必须指定 calls 和/或 bandwidth。Either calls, bandwidth, or both together must be specified.

不适用N/A

callscalls

在 renewal-period 所指定的时间间隔内允许的最大总调用数。The maximum total number of calls allowed during the time interval specified in the renewal-period.

必须指定 calls 和/或 bandwidth。Either calls, bandwidth, or both together must be specified.

不适用N/A

renewal-periodrenewal-period

在重置配额之前等待的时间长度，以秒为单位。The time period in seconds after which the quota resets.

是Yes

不适用N/A

使用情况Usage

此策略可在以下策略段和范围中使用。This policy can be used in the following policy sections and scopes.

策略段： 入站Policy sections: inbound

策略范围： 产品Policy scopes: product

按密钥设置使用量配额Set usage quota by key

quota-by-key 策略允许根据密钥强制实施可续订或有生存期的调用量和/或带宽配额。The quota-by-key policy enforces a renewable or lifetime call volume and/or bandwidth quota, on a per key basis.密钥的值可以是任意字符串，通常使用策略表达式来提供密钥。The key can have an arbitrary string value and is typically provided using a policy expression.可以添加可选增量条件，指定在判断请求数是否达到配额时应计入哪些请求。Optional increment condition can be added to specify which requests should be counted towards the quota.如果多个策略增加相同的键值，则每个请求的键值仅增加一次。If multiple policies would increment the same key value, it is incremented only once per request.达到调用限制时，调用方会收到 403 Forbidden 响应状态代码。When the call limit is reached, the caller receives a 403 Forbidden response status code.

元素Elements

元素Element

说明Description

必须Required

validate-jwtvalidate-jwt

根元素。Root element.

是Yes

audiencesaudiences

包含一系列可接受且可存在于令牌上的受众声明。Contains a list of acceptable audience claims that can be present on the token.如果存在多个受众值，则会对每个值进行尝试，直到所有值都试完（这种情况表明验证失败），或者直到有一个值成功。If multiple audience values are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds.必须指定至少一个受众。At least one audience must be specified.

否No

issuer-signing-keysissuer-signing-keys

一系列 Base64 编码的安全密钥，用于验证签名的令牌。A list of Base64-encoded security keys used to validate signed tokens.如果存在多个安全密钥，则会对每个密钥进行尝试，直到所有密钥都试完（这种情况表明验证失败），或者直到有一个密钥成功（对令牌滚动更新十分有用）。If multiple security keys are present, then each key is tried until either all are exhausted (in which case validation fails) or until one succeeds (useful for token rollover).密钥元素有一个可选的 id 属性，用于与 kid 声明进行比较。Key elements have an optional id attribute used to match against kid claim.

否No

decryption-keysdecryption-keys

用于解密令牌的 Base64 编码密钥列表。A list of Base64-encoded keys used to decrypt the tokens.如果存在多个安全密钥，则会对每个密钥进行尝试，直到所有密钥都试完（在这种情况下验证失败）或直到有一个密钥成功为止。If multiple security keys are present, then each key is tried until either all keys are exhausted (in which case validation fails) or until a key succeeds.密钥元素有一个可选的 id 属性，用于与 kid 声明进行比较。Key elements have an optional id attribute used to match against kid claim.

否No

issuersissuers

一系列可接受的、已颁发了令牌的主体。A list of acceptable principals that issued the token.如果存在多个颁发者值，则会对每个值进行尝试，直到有一个值成功（如果所有值都试完却没有一个成功，则表明验证失败）。If multiple issuer values are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds.

否No

openid-configopenid-config

一个元素，用于指定兼容的 Open ID 配置终结点，以便从该终结点获取签名密钥和颁发者。The element used for specifying a compliant Open ID configuration endpoint from which signing keys and issuer can be obtained.

否No

required-claimsrequired-claims

包含一系列应存在于令牌上的声明，否则令牌会被视为无效。Contains a list of claims expected to be present on the token for it to be considered valid.将 match 属性设置为 all 时，策略中的每个声明值都必须存在于令牌中才会使验证成功。When the match attribute is set to all every claim value in the policy must be present in the token for validation to succeed.将 match 属性设置为 any 时，至少一个声明必须存在于令牌中才会使验证成功。When the match attribute is set to any at least one claim must be present in the token for validation to succeed.

必须指定 header-name、query-parameter-name、token-value 中的一个。One of header-name, query-parameter-name or token-value must be specified.

不适用N/A

idid

使用 key 元素的 id 属性可以指定一个字符串，该字符串将与令牌中的 kid 声明（如果存在）进行比较，以便找出进行签名验证时需要使用的适当密钥。The id attribute on the key element allows you to specify the string that will be matched against kid claim in the token (if present) to find out the appropriate key to use for signature validation.

否No

不适用N/A

matchmatch

claim 元素的 match 属性用于指定：是否策略中的每个声明值都必须存在于令牌中验证才会成功。The match attribute on the claim element specifies whether every claim value in the policy must be present in the token for validation to succeed.可能的值包括：Possible values are:

- all - 策略中的每个声明值都必须存在于令牌中才会使验证成功。- all - every claim value in the policy must be present in the token for validation to succeed.

- any - 至少一个声明值必须存在于令牌中才会使验证成功。-any - at least one claim value must be present in the token for validation to succeed.

否No

allall

require-expiration-timerequire-expiration-time

布尔值。Boolean.指定令牌中是否需要到期声明。Specifies whether an expiration claim is required in the token.

否No

是true

require-schemerequire-scheme

令牌方案的名称，例如“Bearer”。The name of the token scheme, e.g. "Bearer".设置了此属性时，策略将确保 Authorization 标头值中存在指定的方案。When this attribute is set, the policy will ensure that specified scheme is present in the Authorization header value.

否No

不适用N/A

require-signed-tokensrequire-signed-tokens

布尔值。Boolean.指定令牌是否需要签名。Specifies whether a token is required to be signed.

否No

是true

分隔符separator

字符串。String.指定要用于从多值声明中提取一组值的分隔符（例如 ","）。Specifies a separator (e.g. ",") to be used for extracting a set of values from a multi-valued claim.