1. Overview
A throttling plug-in is used to control traffic from the perspectives of
APIs
,apps
,users who own the apps
, andcustom parameters
. You can control the traffic of apps based on their AppKeys.The
throttling plug-in
supports two configuration templates:Configuration template for parameter-based throttling: This template is used to configure
custom parameter
-based throttling.Configuration template for basic throttling: This template is compatible with the
throttling
feature in the API Gateway console.
Throttling
is integrated into the plug-in system. The originalthrottling
interface and console are still in use.Throttling policies
andthrottling plug-ins
belong to the same plug-in type. If you bind athrottling plug-in
to an API, thethrottling policies
that are bound to this API become invalid.When you create or modify throttling policies in the original throttling interface or console, modifications are synchronized to the plug-in system. However, the modifications you made in the plug-in system cannot be synchronized to the throttling interface or console.
2. Basic throttling configuration
2.1. Throttling thresholds
Basic throttling supports the following throttling thresholds:
API-level throttling threshold: the maximum number of times that an API bound with a throttling policy can be called within a specific unit of time. This unit of time can be second, minute, hour, or day. For example, you can set this threshold to 5,000 times per minute.
App-level throttling threshold: the maximum number of times that each app can call an API bound with a throttling policy within a specific unit of time. For example, you can set this threshold to 50,000 times per hour.
User-level throttling threshold: the maximum number of times that each Alibaba Cloud account can call an API bound with a throttling policy within a specific unit of time. An Alibaba Cloud account may have multiple apps. This throttling threshold limits the total number of API calls that all the apps under this account can initiate. For example, you can set this threshold to 500,000 times per day.
You can specify all the preceding thresholds in one throttling policy. The user-level throttling threshold cannot be greater than the API-level throttling threshold. The app-level throttling threshold cannot be greater than the user-level throttling threshold.
You can also add special apps or users to a throttling policy. Only the API-level throttling threshold in the throttling policy applies to these special apps or users. However, you still need to set a special throttling threshold for each of them. This special throttling threshold cannot be greater than the API-level throttling threshold.
2.2. Plug-in configuration
You can configure a throttling plug-in in JSON or YAML format. The two formats use the same schema. You can use the YAML to JSON
converter to convert the configuration format of a throttling plug-in. The following code describes a plug-in configuration template in YAML format:
---
unit: SECOND # The unit of time. Valid values: SECOND, MINUTE, HOUR, and DAY.
apiDefault: 1000 # The default API-level throttling threshold.
userDefault: 30 # Optional. The default user-level throttling threshold. If you set this threshold to 0, user-level throttling is not performed. The user-level throttling threshold cannot be greater than the API-level throttling threshold.
appDefault: 30 # Optional. The default app-level throttling threshold. If you set this threshold to 0, app-level throttling is not performed. The app-level throttling threshold cannot be greater than the user-level throttling threshold.
specials: # Optional. The special throttling settings. You can set throttling thresholds for special apps or users in a throttling policy.
- type: "APP" # The special throttling type. The value APP indicates that throttling is performed for special apps based on their AppKeys.
policies:
- key: 10123123 # The app ID. You can obtain the ID of an app from the app details page. To go to this page, click Consume APIs and then APPs in the left-side navigation pane of the API Gateway console and click the name of the app.
value: 10 # The special throttling threshold for the app. This threshold cannot be greater than the user-level throttling threshold in the throttling policy.
- key: 10123123 # The app ID.
value: 10 # The special throttling threshold for the app. This threshold cannot be greater than the user-level throttling threshold in the throttling policy.
- type: "USER" # The special throttling type. The value USER indicates that throttling is performed for special Alibaba Cloud accounts.
policies:
- key: 123455 # The ID of an Alibaba Cloud account. You can move the pointer over the profile picture in the upper-right corner of the Alibaba Cloud Management Console to obtain the ID.
value: 100 # The special throttling threshold for the Alibaba Cloud account. This threshold cannot be greater than the API-level throttling threshold in the throttling policy.
3. Parameter-based throttling configuration
Parameter-based throttling allows you to control traffic based on the request parameters of users and conditional executions. The following parameter-based throttling configurations are supported:
Throttling at the second, minute, hour, or day level is supported.
You can use request and system parameters to set conditions and implement different throttling thresholds.
You can configure throttling by using a single parameter or a combination of multiple parameters.
You can set the throttling scope to API or PLUGIN.
3.1. Quick start
Use a scenario where the following throttling rules apply as an example: If the AppKey of the app with the ID of 10001
is used as the signature information of a user, the throttling threshold for each client IP address is 100 requests per second
. Otherwise, the throttling threshold is 10 requests per second
.
For this scenario, a throttling plug-in in YAML
format is configured.
---
scope: "PLUGIN"
#
# Throttling depends on two system parameters.
# 1. The app ID signed by the user is obtained from the CaAppId system parameter.
# 2. The client IP address of the user is obtained from the CaClientIp system parameter.
parameters:
AppId: "System: CaAppId"
ClientIP: "System: CaClientIp"
rules:
# The first throttling policy. This policy applies to the app whose ID is 10001. The throttling threshold for each client IP address is 100 requests per second.
- name: "Vip"
condition: "$AppId = 10001"
byParameters: "ClientIP"
value: 100
period: SECOND
# The second throttling policy named PerClientIP. The throttling threshold for each client IP address is 10 requests per second.
- name: "PerClientIP"
byParameters: "ClientIP"
value: 10
period: SECOND
3.2. Plug-in configuration
The YAML
or equivalent JSON
format is used to configure the metadata of the throttling plug-in.
---
scope: "PLUGIN" # The scope of the throttling plug-in. Valid values: PLUGIN and API.
defaultLimit: 100 # The default throttling threshold.
defaultPeriod: SECOND # The default unit of time for throttling.
defaultErrorMessage: "Throttled by 100/SECOND"
parameters: # The parameters that can be used for throttling.
clientIp: "System:CaClientIp"
userId: "Token:userId"
rules:
- name: "ByClientIp"
byParameters: "clientIp"
condition: "$clientIp ! in_cidr '61.7.8.8/24'"
limit: 10
period: MINUTE
errorMessage: "Throttled by 10/MINUTE from ${clientIp}"
- name: "A maximum of 10 requests per minute are allowed for each user, except the administrator."
byParameters: "clientIp"
condition: "$userId ! like 'admin%'"
limit: 10
period: MINUTE
- name: "A maximum of 10 requests per minute are allowed for each client IP address."
byParameters: "clientIp"
condition: "$clientIp in_cidr '67.0.0.0/8'"
limit: 10
period: MINUTE
- name: "A maximum of 15 requests per minute are allowed for each user."
condition: "$userId ! like 'admin%'"
limit: 15
period: MINUTE
byParameters: "clientIp"
Fields:
scope
: required. The scope of the throttling plug-in. Valid values:API
andPLUGIN
. If one throttling plug-in is bound to multiple APIs, the setting of thescope
field affects the scope of throttling policies bound to the APIs. For example, a throttling policy is10 times per second
.If the value of this field is
API
, the throttling threshold for each API is10 times per second
.If the value of this field is
PLUGIN
, the total throttling threshold for all the APIs is10 times per second
.
parameters
: required. The parameters that are used for throttling. For more information, see Use parameters and conditional expressionsrules
: optional. The throttling policies. IfdefaultLimit
anddefaultPeriod
are not specified, the rules field must be specified. Each throttling policy contains the following fields:name
: required. The name of the throttling policy. The value of this field must comply with the[A-Za-z0-9_-]+
regular expression. The name of each throttling policy must be unique in a throttling plug-in.byParameters
: required. The parameter that is used for throttling. If multiple parameters are specified, separate them with commas (,
). If the value of this field isclientIp
, throttling is performed based on the value of theclientIp
parameter. If the value of this field isuserId,action
, throttling is performed based on the combined values of the two parameters.condition
: optional. If you specify this field, the related throttling policy is used only when the condition indicated by this field is met.limit
: required. The throttling threshold. The value must be a positive integer. If you set this field to-1
, throttling is not performed if the specified condition is met.period
: required. The unit of time for throttling. Valid values:SECOND
,MINUTE
,HOUR
, andDAY
.errorMessage
: required. The error message. You can use a template to customize error messages. For parameters specified in theparameters
field, you can define error messages for them by using the${Name}
format.
defaultLimit
: optional. The default throttling threshold. The value must be a positive integer.defaultPeriod
: optional. The unit of time for throttling. Valid values:SECOND
,MINUTE
,HOUR
, andDAY
.defaultErrorMessage
: optional. The custom error message. If this field is specified, the returnedX-Ca-Error-Message
header contains the custom error message.
3.3. Parameters supported by a throttling plug-in
The following table describes the parameters that are supported by a throttling plug-in.
Parameter | Scope | Description |
---|---|---|
Method | Requests | The HTTP request method, in uppercase, such as |
Path | Requests | The complete HTTP request path, such as |
Header | Requests | Use |
Query | Requests | Use |
Form | Requests | Use |
Host | Requests | Use |
Parameter | Requests | Use |
System | Requests | Use |
Token | Requests | If |
3.4. Throttling rules
API Gateway performs parameter-based throttling by using the following rules:
Plug-ins use the
parameters
field to obtain parameters from the context of a request.If all specified
conditions
are met or noconditions
are specified in a throttling policy, the policy is executed.If multiple matched policies have the same
byParameters
setting, only the policy that comes first in the throttling plug-in takes effect.
4. Configuration examples
4.1. Basic throttling configuration
You can perform basic throttling for APIs, apps, or users. Throttling for apps is based on their AppKeys.
---
unit: SECOND # The default unit of time for throttling. Valid values: SECOND, MINUTE, HOUR, and DAY.
apiDefault: 50 # The default API-level throttling threshold.
appDefault: 20 # Optional. The default app-level throttling threshold. This threshold cannot be greater than the user-level throttling threshold.
userDefault: 30 # Optional. The default user-level throttling threshold. This threshold cannot be greater than the API-level throttling threshold.
specials: # Optional. The special throttling settings. You can set throttling thresholds for special apps and users in a throttling policy.
- type: "APP" # The special throttling type. The value APP indicates that throttling is performed for special apps based on their AppKeys.
policies:
- key: 10001 # The app ID. You can obtain the ID of an app from the app details page. To go to this page, click Consume APIs and then APPs in the left-side navigation pane of the API Gateway console and click the name of the app.
value: 3 # The special throttling threshold for the app. This threshold cannot be greater than the user-level throttling threshold.
- key: 10003
value: 40
- type: "USER" # The special throttling type. The value USER indicates that throttling is performed for special Alibaba Cloud accounts.
policies:
- key: 102 # The ID of an Alibaba Cloud account. You can move the pointer over the profile picture in the upper-right corner of the Alibaba Cloud Management Console to obtain the ID.
value: 10 # The special throttling threshold for the Alibaba Cloud account. This threshold cannot be greater than the API-level throttling threshold.
- key: 233
value: 35
4.2. Throttling based on the ClientIP parameter
In this example, the following throttling policies are used:
A maximum of
100
API calls per minute are allowed for each client IP address.If a client IP address falls in the
58.66.66.0/24
CIDR block, throttling is not performed for this client IP address.If a client IP address falls in the
63.0.0.22/24
or73.0.2.0/24
CIDR block, a maximum offive
API calls per day are allowed for this client IP address.
---
scope: API # The throttling scope. Valid values: API and PLUGIN.
parameters: # The parameters that are used for throttling. Throttling is performed only based on the ClientIP parameter. You can obtain the values of this parameter from the CaClientIp system parameter.
ClientIp: "System:CaClientIp"
rules:
- name: whitelist # The whitelist policy. Throttling is not performed for client IP addresses that meet the condition specified in this policy.
condition: "$ClientIp in_cidr '58.66.66.0/24'"
limit: -1 # The value -1 indicates that throttling is not performed.
- name: banList # The special throttling policy. If a client IP address meets the condition specified in this policy, a maximum of five API calls per day are allowed for the client IP address.
condition: "$ClientIp in_cidr '63.0.0.22' or $ClientIp in_cidr '73.0.2.0/24'"
byParameters: "ClientIp"
limit: 5
period: DAY
- name: 100perIp # The default throttling policy. A maximum of 100 API calls per minute are allowed for each client IP address.
byParameters: "ClientIp"
limit: 100
period: MINUTE # The unit of time. Valid values: SECOND, MINUTE, HOUR, and DAY.
5. Error codes
T429ID | 429 | Throttled by INNER DOMAIN Flow Control, ${Domain} is a test domain, only 1000 requests per day | The error message returned because the number of requests initiated has exceeded the upper limit allowed for a default second-level domain name. To increase the quota, use your own domain name. |
T429IN | 429 | Throttled by INSTANCE Flow Control | The error message returned because throttling is performed for the current instance. |
T429GR | 429 | Throttled by GROUP Flow Control | The error message returned because throttling is performed for the current group. |
T429PA | 429 | Throttled by API Flow Control | The error message returned because the default API-level throttling policy defined in the throttling plug-in is used. |
T429PR | 429 | Throttled by PLUGIN Flow Control | The error message returned because the special throttling policy defined in the throttling plug-in is used. |
T429UP | 429 | Throttled by Usage Plan Flow Control | The error message returned because throttling is performed for the usage plan. |
6. Limits
A maximum of 16 parameters can be specified in a throttling plug-in.
A single expression can contain a maximum of 512 characters.
The metadata of a throttling plug-in can contain a maximum of 16,380 characters.
A maximum of 16
throttling policies
can be defined in a throttling plug-in.A maximum of three parameters can be specified in the
byParameters
field of eachthrottling policy
.If day-level throttling is specified for client IP addresses and the system stores excessive throttling records, some records are released. For a shared instance, a throttling plug-in can control traffic based on a maximum of 1,000 parameters. For a dedicated instance, a throttling plug-in can control traffic based on a maximum of 100,000 parameters.