traffic-tag - API Gateway - Alibaba Cloud Documentation Center

Running attributes

Plug-in execution stage: default stage. Plug-in execution priority: 400.

Fields

The following table describes the fields of this plug-in.

Field	Type	Default value	Required	Description
`conditionGroups`	array of object	-	No	The content-based condition groups. For details, see the conditionGroups configurations.
`weightGroups`	array of object	-	No	The weight-based condition groups. For details, see the weightGroups configurations.
`defaultTagKey`	string	-	No	The default tag key. If no condition is matched, this key is used. Takes effect only when `defaultTagVal` is also configured.
`defaultTagVal`	string	-	No	The default tag value. If no condition is matched, this value is used. Takes effect only when `defaultTagKey` is also configured.

conditionGroups configurations

The following table describes the fields in conditionGroups.

Field	Type	Default value	Required	Description
`headerName`	string	-	Yes	The HTTP header name to add or modify.
`headerValue`	string	-	Yes	The value of the HTTP header.
`logic`	string	-	Yes	The logical relationship among conditions: `and` or `or`. Must be lowercase.
`conditions`	array of object	-	Yes	The tagging conditions.

The following table describes the fields in conditions.

Field	Type	Default value	Required	Description
`conditionType`	string	-	Yes	The condition type: `header`, `parameter`, or `cookie`.
`key`	string	-	Yes	The condition keyword.
`operator`	string	-	Yes	The operator: `equal`, `not_equal`, `prefix`, `in`, `not_in`, `regex`, or `percentage`.
`value`	array of string	-	Yes	The condition value. Multiple values are supported only when the operator is `in` or `not_in`.

Note

If the operator is regex, the regular expression engine RE2 is used. For more information, see RE2 official documentation.

weightGroups configurations

The following table describes the fields in weightGroups.

Field	Type	Default value	Required	Description
`headerName`	string	-	Yes	The HTTP header name to add or modify.
`headerValue`	string	-	Yes	The value of the HTTP header.
`weight`	integer	-	Yes	The traffic weight in percentage.

Operators

Operator	Description
`equal`	Matches if the value exactly equals the specified value.
`not_equal`	Matches if the value differs from the specified value.
`prefix`	Matches if the value starts with the specified value.
`in`	Matches if the value is in the specified list.
`not_in`	Matches if the value is not in the specified list.
`regex`	Matches if the value matches the specified regular expression.
`percentage`	Matches if `hash(get(key)) % 100 < value` is true.

Note

The percentage operator and weight field differ in the following aspects:

percentage: Evaluates a conditional expression based on a specified percentage and key-value pair. Results are idempotent: a matched key-value pair always produces the same result in subsequent evaluations.
weight: Defines the proportion of traffic routed to different paths. Unlike percentage, weight distributes traffic randomly: the same request may be routed to different paths across evaluations.

Use percentage for deterministic condition matching; use weight for random traffic distribution.

Configuration examples

Example 1: content-based matching

In this example, if the role header of a request is user, viewer, or editor and the request contains foo=bar, the header x-mse-tag: gray is added. If no condition is matched, the header x-mse-tag: base is added, as defined by defaultTagKey and defaultTagVal.

defaultTagKey: x-mse-tag
defaultTagVal: base
conditionGroups:
  - headerName: x-mse-tag
    headerValue: gray
    logic: and
    conditions:
      - conditionType: header
        key: role
        operator: in
        value:
          - user
          - viewer
          - editor
      - conditionType: parameter
        key: foo
        operator: equal
        value:
        - bar

Example 2: weight-based matching

In this example, a request has a 30% chance of being tagged with x-mse-tag: gray, a 30% chance of being tagged with x-mse-tag: blue, and a 40% chance of not being tagged.

# The total weight is 100. The weight value 40, which is not configured, indicates that no header is added.
weightGroups:
  - headerName: x-mse-tag
    headerValue: gray
    weight: 30
  - headerName: x-mse-tag
    headerValue: blue
    weight: 30