jobs

GET

Retrieve Content Invalidation Jobs.

Auth. Required

Yes

Roles Required

None1

Permissions Required

JOB:READ, DELIVERY-SERVICE:READ1

Response Type

Array

Request Structure

Table 354 Request Query Parameters

Name

Required

Description

assetUrl

no

Return only Content Invalidation Jobs with this Asset URL

cdn

no

Return only Content Invalidation Jobs for Delivery Services within the CDN with this name

createdBy

no

Return only Content Invalidation Jobs that were created by the user with this username

deliveryService

no

Return only Content Invalidation Jobs that operate on the Delivery Service with this xml_id

dsId

no

Return only Content Invalidation Jobs pending on the Delivery Service identified by this integral, unique identifier

id

no

Return only the single Content Invalidation Job with this ID

maxRevalDurationDays

no

Return only Content Invalidation Jobs with a Start Time that is within the window defined by the maxRevalDurationDays Parameter in The GLOBAL Profile

userId

no

Return only Content Invalidation Jobs created by the user identified by this integral, unique identifier

#838 Request Example
GET /api/4.0/jobs?id=1&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

#839 Response Example
HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Type: application/json
Permissions-Policy: interest-cohort=()
Set-Cookie: mojolicious=...
Vary: Accept-Encoding
X-Server-Name: traffic_ops_golang/
Date: Fri, 12 Nov 2021 19:30:36 GMT
Content-Length: 206

{ "response": [{
    "id": 1,
    "assetUrl": "http://origin.infra.ciab.test/.+",
    "createdBy": "admin",
    "deliveryService": "demo1",
    "ttlHours": 72,
    "invalidationType": "REFETCH",
    "startTime": "2021-11-09T01:02:03Z"
}]}

POST

Creates a new Content Invalidation Jobs.

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

Permissions Required

JOB:CREATE, JOB:READ, DELIVERY-SERVICE:READ, DELIVERY-SERVICE:UPDATE1

Response Type

Object

Request Structure

deliveryService

The Delivery Service

invalidationType

The Invalidation Type

regex

The Regular Expression

startTime

The Start Time

ttl

The TTL

#840 Request Example
POST /api/4.0/jobs HTTP/1.1
User-Agent: python-requests/2.25.1
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...
Transfer-Encoding: chunked
Content-Type: application/json

{
    "deliveryService": "demo1",
    "invalidationType": "REFRESH",
    "regex": "/.+",
    "startTime": "2021-11-09T01:02:03Z",
    "ttlHours": 72
}

Response Structure

assetUrl

The Asset URL

createdBy

The Created By

deliveryService

The Delivery Service

id

The ID.

invalidationType

The Invalidation Type

ttlHours

The TTL

startTime

The Start Time

#841 Response Example
HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Type: application/json
Location: https://localhost:6443/api/4.0/jobs?id=1
Permissions-Policy: interest-cohort=()
Set-Cookie: mojolicious=...
Vary: Accept-Encoding
X-Server-Name: traffic_ops_golang/
Date: Mon, 08 Nov 2021 15:44:46 GMT
Content-Length: 265

{
    "alerts": [
        {
            "text": "Invalidation (REFRESH) request created for http://origin.infra.ciab.test/.+, start:2021-11-09 01:02:03 +0000 UTC end 2021-11-12 01:02:03 +0000 UTC",
            "level": "success"
        }
    ],
    "response": {
        "id": 1,
        "assetUrl": "http://origin.infra.ciab.test/.+",
        "createdBy": "admin",
        "deliveryService": "demo1",
        "ttlHours": 72,
        "invalidationType": "REFRESH",
        "startTime": "2021-11-09T01:02:03Z"
    }
}

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

Permissions Required

JOB:UPDATE, DELIVERY-SERVICE:UPDATE, JOB:READ, DELIVERY-SERVICE:READ1

Response Type

Object

Request Structure

Table 355 Query Parameters

Name

Required

Description

id

yes

The integral, unique identifier of the Content Invalidation Job being modified

assetUrl

The Asset URL - the scheme and authority parts of the regular expression cannot be changed

createdBy

The Created By2

deliveryService

The Delivery Service2

id

The ID2

invalidationType

The Invalidation Type

ttlHours

The TTL

startTime

The Start Time

#842 Request Example
PUT /api/4.0/jobs?id=1 HTTP/1.1
User-Agent: python-requests/2.25.1
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...
Content-Length: 191

{
    "assetUrl": "http://origin.infra.ciab.test/.+",
    "createdBy": "admin",
    "deliveryService": "demo1",
    "id": 1,
    "invalidationType": "REFETCH",
    "startTime": "2021-11-09T01:02:03Z",
    "ttlHours": 72
}

Response Structure

assetUrl

The Asset URL

createdBy

The Created By

deliveryService

The Delivery Service

id

The ID

invalidationType

The Invalidation Type

ttlHours

The TTL

startTime

The Start Time

#843 Response Example
HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Type: application/json
Permissions-Policy: interest-cohort=()
Set-Cookie: mojolicious=...
Vary: Accept-Encoding
X-Server-Name: traffic_ops_golang/
Date: Mon, 08 Nov 2021 16:43:35 GMT
Content-Length: 266

{ "alerts": [
    {
        "text": "Invalidation request created for http://origin.infra.ciab.test/.+, start: 2021-11-09 01:02:03 +0000 UTC end: 2021-11-12 01:02:03 +0000 UTC invalidation type: REFETCH",
        "level": "success"
    }
],
"response": {
    "assetUrl": "http://origin.infra.ciab.test/.+",
    "createdBy": "admin",
    "deliveryService": "demo1",
    "id": 1,
    "invalidationType": "REFETCH",
    "startTime": "2021-11-09T01:02:03Z",
    "ttlHours": 72
}}

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

Permissions Required

JOB:DELETE, JOB:READ, DELIVERY-SERVICE:UPDATE, DELIVERY-SERVICE:READ1

Response Type

Object

Request Structure

Table 356 Query Parameters

Name

Required

Description

id

yes

The integral, unique identifier of the Content Invalidation Job being modified

#844 Request Example
DELETE /api/4.0/jobs?id=1 HTTP/1.1
User-Agent: python-requests/2.25.1
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...
Content-Length: 0

Response Structure

assetUrl

The Asset URL of the deleted Content Invalidation Job

createdBy

The Created By of the deleted Content Invalidation Job

deliveryService

The Delivery Service of the deleted Content Invalidation Job

id

The ID. of the deleted Content Invalidation Job

invalidationType

The Invalidation Type of the deleted Content Invalidation Job

ttlHours

The TTL of the deleted Content Invalidation Job

startTime

The Start Time of the deleted Content Invalidation Job

#845 Response Example
HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Type: application/json
Permissions-Policy: interest-cohort=()
Set-Cookie: mojolicious=...
Vary: Accept-Encoding
X-Server-Name: traffic_ops_golang/
Date: Mon, 08 Nov 2021 16:54:32 GMT
Content-Length: 230

{ "alerts": [
    {
        "text": "Content invalidation job was deleted",
        "level": "success"
    }
],
"response": {
    "assetUrl": "http://origin.infra.ciab.test/.+",
    "createdBy": "admin",
    "deliveryService": "demo1",
    "id": 1,
    "invalidationType": "REFETCH",
    "startTime": "2021-11-09T01:02:03Z",
    "ttlHours": 72
}}
1(1,2,3,4,5,6,7,8)

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 Jobs requires that the target Delivery Service is modifiable by the requesting user’s Tenant. However, when modifying or deleting an existing Content Invalidation Jobs, 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). That is, this cannot be changed.