jobs

GET

Retrieve content invalidation jobs.

Auth. Required

Yes

Roles Required

None1

Response Type

Array

Request Structure

Table 175 Request Query Parameters

Name

Required

Description

assetUrl

no

Return only invalidation jobs that operate on URLs by matching this regular expression

cdn

no

Return only invalidation jobs for delivery services with this CDN name

createdBy

no

Return only invalidation jobs that were created by the user with this username

deliveryService

no

Return only invalidation jobs that operate on the Delivery Service with this xml_id

dsId

no

Return only invalidation jobs pending on the Delivery Service identified by this integral, unique identifier

id

no

Return only the single invalidation job identified by this integral, unique identifer

keyword

no

Return only invalidation jobs that have this “keyword” - only “PURGE” should exist

maxRevalDurationDays

no

Return only invalidation jobs with a startTime that is within the window defined by the maxRevalDurationDays Parameter in The GLOBAL Profile

userId

no

Return only invalidation jobs created by the user identified by this integral, unique identifier

#367 Request Example
GET /api/2.0/jobs?id=3&dsId=1&userId=2 HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: python-requests/2.20.1
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...

Response Structure

assetUrl

A regular expression - matching URLs will be operated upon according to keyword

createdBy

The username of the user who initiated the job

deliveryService

The xml_id of the Delivery Service on which this job operates

id

An integral, unique identifier for this job

keyword

A keyword that represents the operation being performed by the job:

PURGE

This job will prevent caching of URLs matching the assetUrl until it is removed (or its Time to Live expires)

parameters

A string containing key/value pairs representing parameters associated with the job - currently only uses Time to Live e.g. "TTL:48h"

startTime

The date and time at which the job began, in a non-standard format

#368 Response Example
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Encoding: gzip
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: gH41oEi2zrd3y8yo+wfohn4/oHU098RpyPnqBzU7HlLUDkMOPKjAZnamcYqfdy7yDCFDUcgqkvbFAvnljxyb8w==
X-Server-Name: traffic_ops_golang/
Date: Tue, 18 Jun 2019 19:47:30 GMT
Content-Length: 186

{ "response": [{
    "assetUrl": "http://origin.infra.ciab.test/.*",
    "createdBy": "admin",
    "deliveryService": "demo1",
    "id": 3,
    "keyword": "PURGE",
    "parameters": "TTL:2h",
    "startTime": "2019-06-18 21:28:31+00"
}]}

POST

Creates a new content invalidation job.

Caution

Creating a content invalidation job immediately triggers a CDN-wide revalidation update. In the case that the global Parameter use_reval_pending has a value of exactly "0", this will instead trigger a CDN-wide “Queue Updates”. This means that content invalidation jobs become active immediately at their startTime - unlike most other configuration changes they do not wait for a Snapshot or a “Queue Updates”. Furthermore, if the global Parameter use_reval_pending is "0", this will cause all pending configuration changes to propagate to all cache servers in the CDN. Take care when using this endpoint.

Auth. Required

Yes

Roles Required

“operations” or “admin”1

Response Type

Object

Request Structure

deliveryService

This should either be the integral, unique identifier of a Delivery Service, or a string containing an xml_id

startTime

This can be a string in the legacy YYYY-MM-DD HH:MM:SS format, or a string in RFC 3339 format, or a string representing a date in the same non-standard format as the last_updated fields common in other API responses, or finally it can be a number indicating the number of milliseconds since the Unix Epoch (January 1, 1970 UTC). This date must be in the future.

regex

A regular expression that will be used to match the path part of URIs for content stored on cache servers that service traffic for the Delivery Service identified by deliveryService.

ttl

Either the number of hours for which the content invalidation job should remain active, or a “duration” string, which is a sequence of numbers followed by units. The accepted units are:

  • h gives a duration in hours

  • m gives a duration in minutes

  • s gives a duration in seconds

  • ms gives a duration in milliseconds

  • us (or µs) gives a duration in microseconds

  • ns gives a duration in nanoseconds

These durations can be combined e.g. 2h45m specifies a TTL of two hours and forty-five minutes - however note that durations are always rounded up to the nearest hour so that e.g. 121m becomes three hours. TTLs cannot ever be negative, obviously.

#369 Request Example
POST /api/2.0/jobs HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: python-requests/2.20.1
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...
Content-Length: 80
Content-Type: application/json

{
    "deliveryService": "demo1",
    "startTime": 1560893311219,
    "regex": "/.*",
    "ttl": "121m"
}

Response Structure

assetUrl

A regular expression - matching URLs will be operated upon according to keyword

createdBy

The username of the user who initiated the job

deliveryService

The xml_id of the Delivery Service on which this job operates

id

An integral, unique identifier for this job

keyword

A keyword that represents the operation being performed by the job:

PURGE

This job will prevent caching of URLs matching the assetUrl until it is removed (or its Time to Live expires)

parameters

A string containing key/value pairs representing parameters associated with the job - currently only uses Time to Live e.g. "TTL:48h"

startTime

The date and time at which the job began, in a non-standard format

#370 Response Example
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Encoding: gzip
Content-Type: application/json
Location: https://trafficops.infra.ciab.test/api/2.0/jobs?id=3
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: nB2xg2IqO56rLT8dI4+KZgxOsTe5ShctG1U8epRsY9NyyMIpx8TZYt5MrO2QikuYh+NnyoR6V0VICCnGCKZpKw==
X-Server-Name: traffic_ops_golang/
Date: Tue, 18 Jun 2019 19:37:06 GMT
Content-Length: 238

{
    "alerts": [
        {
            "text": "Invalidation Job creation was successful",
            "level": "success"
        }
    ],
    "response": {
        "assetUrl": "http://origin.infra.ciab.test/.*",
        "createdBy": "admin",
        "deliveryService": "demo1",
        "id": 3,
        "keyword": "PURGE",
        "parameters": "TTL:2h",
        "startTime": "2019-06-18 21:28:31+00"
    }
}

PUT

Replaces an existing content invalidation job with a new one provided in the request. This method of editing a content invalidation job does not prevent the requesting user from changing fields that normally only have one value. Use with care.

Caution

Modifying a content invalidation job immediately triggers a CDN-wide revalidation update. In the case that the global Parameter use_reval_pending has a value of exactly "0", this will instead trigger a CDN-wide “Queue Updates”. This means that content invalidation jobs become active immediately at their startTime - unlike most other configuration changes they do not wait for a Snapshot or a “Queue Updates”. Furthermore, if the global Parameter use_reval_pending is "0", this will cause all pending configuration changes to propagate to all cache servers in the CDN. Take care when using this endpoint.

Auth. Required

Yes

Roles Required

“operations” or “admin”1

Response Type

Object

Request Structure

Table 176 Query Parameters

Name

Required

Description

id

yes

The integral, unique identifier of the content invalidation job being modified

assetUrl

A regular expression - matching URLs will be operated upon according to keyword

Note

Unlike in the payloads of POST requests to this endpoint, this must be a full URL regular expression, as it is not combined with the Origin Server Base URL of the Delivery Service identified by deliveryService.

createdBy

The username of the user who initiated the job2

deliveryService

The xml_id of the Delivery Service on which this job operates2 - unlike POST request payloads, this cannot be an integral, unique identifier

id

An integral, unique identifier for this job2

keyword

A keyword that represents the operation being performed by the job. It can have any (string) value, but the only value with any meaning to Traffic Control is:

PURGE

This job will prevent caching of URLs matching the assetUrl until it is removed (or its Time to Live expires)

parameters

A string containing space-separated key/value pairs - delimited by colons (:s) representing parameters associated with the job. In practice, any string can be passed as a job’s parameters, but the only value with meaning is a single key/value pair indicated a TTL in hours in the format TTL:hoursh, and any other type of value may cause components of Traffic Control to work improperly or not at all.

startTime

This can be a string in the legacy YYYY-MM-DD HH:MM:SS format, or a string in RFC 3339 format, or a string representing a date in the same non-standard format as the last_updated fields common in other API responses, or finally it can be a number indicating the number of milliseconds since the Unix Epoch (January 1, 1970 UTC). This must be in the future, but only by no more than two days.

#371 Request Example
PUT /api/2.0/jobs?id=3 HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: python-requests/2.20.1
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...
Content-Length: 188
Content-Type: application/json

{
    "assetUrl": "http://origin.infra.ciab.test/.*",
    "createdBy": "admin",
    "deliveryService": "demo1",
    "id": 3,
    "keyword": "PURGE",
    "parameters": "TTL:360h",
    "startTime": "2019-06-20 18:33:40+00"
}

Response Structure

assetUrl

A regular expression - matching URLs will be operated upon according to keyword

createdBy

The username of the user who initiated the job

deliveryService

The xml_id of the Delivery Service on which this job operates

id

An integral, unique identifier for this job

keyword

A keyword that represents the operation being performed by the job:

PURGE

This job will prevent caching of URLs matching the assetUrl until it is removed (or its Time to Live expires)

parameters

A string containing key/value pairs representing parameters associated with the job - currently only uses Time to Live e.g. "TTL:48h"

startTime

The date and time at which the job began, in a non-standard format

#372 Response Example
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Encoding: gzip
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: +P1PTav4ZBoiQcCqQnUqf+J0dCfQgVj8mzzKtUCA69mWYulya9Bjf6BUd8Aro2apmpgPBkCEA5sITJV1tMYA0Q==
X-Server-Name: traffic_ops_golang/
Date: Wed, 19 Jun 2019 13:38:59 GMT
Content-Length: 234

{ "alerts": [{
    "text": "Content invalidation job updated",
    "level": "success"
}],
"response": {
    "assetUrl": "http://origin.infra.ciab.test/.*",
    "createdBy": "admin",
    "deliveryService": "demo1",
    "id": 3,
    "keyword": "PURGE",
    "parameters": "TTL:360h",
    "startTime": "2019-06-20 18:33:40+00"
}}

DELETE

Deletes a content invalidation job.

Tip

Content invalidation jobs that have passed their TTL are not automatically deleted - for record-keeping purposes - so use this to clean up old jobs that are no longer useful.

Caution

Deleting a content invalidation job immediately triggers a CDN-wide revalidation update. In the case that the global Parameter use_reval_pending has a value of exactly "0", this will instead trigger a CDN-wide “Queue Updates”. This means that content invalidation jobs become active immediately at their startTime - unlike most other configuration changes they do not wait for a Snapshot or a “Queue Updates”. Furthermore, if the global Parameter use_reval_pending is "0", this will cause all pending configuration changes to propagate to all cache servers in the CDN. Take care when using this endpoint.

Auth. Required

Yes

Roles Required

“operations” or “admin”1

Response Type

Object

Request Structure

Table 177 Query Parameters

Name

Required

Description

id

yes

The integral, unique identifier of the content invalidation job being modified

#373 Request Example
DELETE /api/2.0/jobs?id=3 HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: python-requests/2.20.1
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...
Content-Length: 0

Response Structure

assetUrl

A regular expression - matching URLs will be operated upon according to keyword

createdBy

The username of the user who initiated the job

deliveryService

The xml_id of the Delivery Service on which this job operates

id

An integral, unique identifier for this job

keyword

A keyword that represents the operation being performed by the job:

PURGE

This job will prevent caching of URLs matching the assetUrl until it is removed (or its Time to Live expires)

parameters

A string containing key/value pairs representing parameters associated with the job - currently only uses Time to Live e.g. "TTL:48h"

startTime

The date and time at which the job began, in a non-standard format

#374 Response Example
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Encoding: gzip
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: FqfziXJYYwHb84Fac9+p4NEY3EsklYxe94wg/VOmlXk4R6l4SaPSh015CChPt/yT72MsWSETnIuRD9KtoK4I+w==
X-Server-Name: traffic_ops_golang/
Date: Tue, 18 Jun 2019 22:55:15 GMT
Content-Length: 234

{ "alerts": [
    {
        "text": "Content invalidation job was deleted",
        "level": "success"
    }
],
"response": {
    "assetUrl": "http://origin.infra.ciab.test/.*",
    "createdBy": "admin",
    "deliveryService": "demo1",
    "id": 3,
    "keyword": "PURGE",
    "parameters": "TTL:36h",
    "startTime": "2019-06-20 18:33:40+00"
}}
1(1,2,3,4)

When viewing content invalidation jobs, only those jobs that operate on a Delivery Service visible to the requesting user’s Tenant will be returned. Likewise, creating a new content invalidation job requires that the target Delivery Service is modifiable by the requesting user’s Tenant. However, when modifying or deleting an existing content invalidation job, the operation can be completed if and only if the requesting user’s Tenant is the same as the job’s Delivery Service’s Tenant or a descendant thereof, and if the requesting user’s Tenant is the same as the Tenant of the user who initially created the job or a descendant thereof.

2(1,2,3)

This field must exist, but it must not be different than the same field of the existing job (i.e. as seen in a GET response)