Device Groups
Look up the fields of a device group, how a rule matches it with the device_group variable, and how a cache setting varies by it.
Device Groups is a Feature of Applications that groups the requests received by an Application according to the client device. A device group is a name and a regular expression that the Application compares with the User-Agent header of each request. A request belongs to the group when its header matches the expression. Device groups require Application Accelerator turned on in the Application. A rule or a cache setting can then treat those devices apart from the rest. Each Application holds its own device groups, and Create device groups shows how to add one in Azion Console.
Device group fields
A device group carries two fields that you set, and an ID and a creation date that the platform assigns. A rule refers to a device group by its name, and a cache setting refers to it by its ID. For the two fields you set, the Field column gives the label that Azion Console shows.
| Field | API field | Type | Bounds in the API | Description |
|---|---|---|---|---|
| Name | name |
string | 1 to 250 characters, letters and numbers only | The name of the group. A rule compares ${device_group} with this name |
| Regular Expression, in Match to User-Agent | user_agent |
string | 1 to 512 characters | The expression compared with the contents of the User-Agent header |
| ID | id |
integer | Read-only | The identifier of the group |
| Creation date | created_at |
date-time | Read-only | When the group was created |
The cache key of a copy that varies by device ends with the name of the group. The name takes only letters and numbers, with no spaces or symbols, and the API refuses another name with HTTP 400 and error 27003, Device Group Invalid Name. In Azion Console, the Name field states Use only letters and numbers, without spaces or symbols. The Console shows Name must be alphanumeric for a name with other characters.
The regular expression follows Perl Compatible Regular Expressions (PCRE). Azion Console shows these messages for an expression it refuses:
Enter a valid regular expression pattern.for an expression it cannot read.User Agent cannot contain emojis or null bytesfor an expression that carries either.User Agent cannot contain < > " or 'for an expression that carries one of those characters.
The cache_vary_by_devices.device_group field of a cache setting lists device groups by their ID.
User-Agent header
The User-Agent request header carries information on the client that sends the request: the browser, the operating system, the version, and the manufacturer. The header follows this syntax:
| Part | What it holds |
|---|---|
product |
The product identifier |
product-version |
The version number of the product |
comment |
System information, the platform name and its details, and extensions |
For example, a request from Mozilla Firefox on a Windows computer carries this header:
User-Agent matching
An Application compares the regular expression of each device group with the User-Agent header. A request belongs to a group when the expression matches. The expression does not have to match the whole header, because a match on part of it is enough. For example, a group named Mobile with this expression matches the headers of most mobile devices:
Match order
When a User-Agent header matches more than one device group, the request takes the first group that matches, from first to last in the list of device groups. The position of the matching words inside the header does not change the result. For example, an Application holds these three device groups, in this order:
| Order | Device group | Regular expression |
|---|---|---|
| 1 | Mobile |
(Mobile|Android) |
| 2 | Tablet |
(iPad|Android) |
| 3 | Desktop |
(Chrome|Mozilla) |
A header that contains Android Tablet Mobile (Mozilla Firefox) matches all three expressions, and the request takes Mobile, the first in the list. A header that contains iPad Apple Webkit Mobile matches Tablet through iPad. The request still takes Mobile, because Mobile matches too and comes first.
Rules Engine variable
In Rules Engine for Applications, the ${device_group} variable holds the name of the device group that a request belongs to. A criterion compares it with the name of a group, given as its argument. The behaviors of the rule then apply only to the requests from that group. The variable requires Application Accelerator turned on in the Application.
This criterion matches a request from the Mobile device group:
| Conditional | Variable | Operator | Argument |
|---|---|---|---|
if |
${device_group} |
is_equal |
Mobile |
A criterion can also match a device without a device group, by comparing ${http_user_agent} with a string or a regular expression. This criterion matches a request from an iPhone:
| Conditional | Variable | Operator | Argument |
|---|---|---|---|
if |
${http_user_agent} |
matches |
(?i)iPhone |
For every variable and operator a rule can use, refer to Rules Engine for Applications.
Cache variation
A cache setting can vary the cache key by device group. With the variation, Cache stores a separate copy of an object for each device group that the cache setting lists. Otherwise, Cache answers every device with the same copy. In the API, the variation is the modules.application_accelerator.cache_vary_by_devices field, whose device_group field lists device groups by ID. A cache setting that does not set the variation carries "behavior": "ignore" and an empty device_group list. Azion CLI has no flag for device group variation.
The modules.application_accelerator object of a cache setting requires Application Accelerator turned on in the Application. Without it, the API refuses with error 21013 a variation of that object whose behavior is not ignore. For the values each field takes and its label in Azion Console, refer to Application Accelerator settings.
Each copy that varies by device group has its own cache key. The key ends in @@ and the name of the device group, such as httpwww.example.com/@@Mobile. A URL purge does not reach these copies, so purge them by cache key or with a wildcard. For the key format, refer to Cache keys. For the purge types, refer to Real-Time Purge.
API
The API serves the device groups of an Application at https://api.azion.com/v4/workspace/applications/<application-id>/device_groups. Each call authenticates with a personal token in the Authorization: Token [TOKEN VALUE] header, and a call with a body also sends Content-Type: application/json.
| Operation | Method and path |
|---|---|
| Create a device group | POST /workspace/applications/<application-id>/device_groups |
| List the device groups of an Application | GET /workspace/applications/<application-id>/device_groups |
| Read one device group | GET /workspace/applications/<application-id>/device_groups/<device-group-id> |
| Replace a device group | PUT /workspace/applications/<application-id>/device_groups/<device-group-id> |
| Change part of a device group | PATCH /workspace/applications/<application-id>/device_groups/<device-group-id> |
| Delete a device group | DELETE /workspace/applications/<application-id>/device_groups/<device-group-id> |
A create request requires name and user_agent. The platform assigns id and created_at. While Application Accelerator is off in the Application, the API refuses the create request with HTTP 403 and error 27002, Application Acceleration Not Enabled.
CLI
Azion CLI manages device groups with five commands under the device-group noun. Every command takes --application-id, and a command that acts on one device group takes its ID in --group-id.
| Command | What it does | Flags |
|---|---|---|
azion create device-group |
Creates a device group | --application-id, --name, --user-agent, --file |
azion list device-group |
Lists the device groups of an Application | --application-id, --details, --filter, --order-by, --page, --page-size |
azion describe device-group |
Returns one device group | --application-id, --group-id |
azion update device-group |
Changes a device group | --application-id, --group-id, --name, --user-agent, --file |
azion delete device-group |
Deletes a device group | --application-id, --group-id |
--name sets the name field, and --user-agent sets the regular expression in user_agent. --file reads the device group from a JSON file instead.