You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@trafficcontrol.apache.org by GitBox <gi...@apache.org> on 2019/09/27 20:40:59 UTC
[GitHub] [trafficcontrol] mitchell852 commented on a change in pull request
#3744: Rewrote jobs endpoints to go
mitchell852 commented on a change in pull request #3744: Rewrote jobs endpoints to go
URL: https://github.com/apache/trafficcontrol/pull/3744#discussion_r329217292
##########
File path: docs/source/api/jobs.rst
##########
@@ -21,78 +21,470 @@
``GET``
=======
-Get all jobs (currently limited to invalidate content (PURGE) jobs) sorted by start time (descending).
+Retrieve content invalidation jobs.
:Auth. Required: Yes
-:Roles Required: "operations" or "admin"
+:Roles Required: None\ [#tenancy]_
:Response Type: Array
-.. warning:: This endpoint will respect tenancy rules *if and only if* the ``dsId`` query parameter is used.
-
Request Structure
-----------------
.. table:: Request Query Parameters
- +--------+----------+----------------------------------------------------------------------------------------------------------------------+
- | Name | Required | Description |
- +========+==========+======================================================================================================================+
- | dsId | no | Return only invalidation jobs pending on the :term:`Delivery Service` identified by this integral, unique identifier |
- +--------+----------+----------------------------------------------------------------------------------------------------------------------+
- | userId | no | Return only invalidation jobs created by the user identified by this integral, unique identifier |
- +--------+----------+----------------------------------------------------------------------------------------------------------------------+
+ +-----------------+----------+----------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +=================+==========+======================================================================================================================+
+ | assetUrl | no | Return only invalidation jobs that operate on URLs by matching this regular expression |
+ +-----------------+----------+----------------------------------------------------------------------------------------------------------------------+
+ | 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 :term:`Delivery Service` with this :ref:`ds-xmlid` |
+ +-----------------+----------+----------------------------------------------------------------------------------------------------------------------+
+ | dsId | no | Return only invalidation jobs pending on the :term:`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 |
+ +-----------------+----------+----------------------------------------------------------------------------------------------------------------------+
+ | userId | no | Return only invalidation jobs created by the user identified by this integral, unique identifier |
+ +-----------------+----------+----------------------------------------------------------------------------------------------------------------------+
-.. note:: If the ``dsId`` parameter is given, an error will be returned if the thereby identified :term:`Delivery Service` is not visible to the logged-in user's Tenant
.. code-block:: http
:caption: Request Example
- GET /api/1.4/jobs?dsId=1&userId=2 HTTP/1.1
+ GET /api/1.4/jobs?id=3&dsId=1&userId=2 HTTP/1.1
Host: trafficops.infra.ciab.test
- User-Agent: curl/7.47.0
+ 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' that uniquely identifies the :term:`Delivery Service` on which this job operates
+:deliveryService: The :ref:`ds-xmlid` of the :term:`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)
+ 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 ISO format
+:startTime: The date and time at which the job began, in a non-standard format
.. code-block:: http
:caption: Response Example
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
- Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept
+ 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: *
- Cache-Control: no-cache, no-store, max-age=0, must-revalidate
+ Content-Encoding: gzip
Content-Type: application/json
- Date: Wed, 05 Dec 2018 15:44:07 GMT
- Server: Mojolicious (Perl)
- Set-Cookie: mojolicious=...; expires=Wed, 05 Dec 2018 19:44:07 GMT; path=/; HttpOnly
- Vary: Accept-Encoding
- Whole-Content-Sha512: PfKJyahkUTjK2iNAuY3NZiljuHHVNJyNkdKRdtzHZN9fg4+HidejGIC19tcyRCDATQyZQ49/BLEIJDAAaqTwzA==
- Content-Length: 202
-
- { "response": [
- {
- "parameters": "TTL:48h",
- "keyword": "PURGE",
- "assetUrl": "http://origin.infra.ciab.test/.*\\.jpg",
+ Set-Cookie: mojolicious=...; Path=/; 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``
+========
+.. versionadded:: 1.4
+
+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 :term:`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 :term:`Snapshot` or a "Queue Updates". Furthermore, if the global :term:`Parameter` ``use_reval_pending`` *is* ``"0"``, this will cause all pending configuration changes to propagate to all :term:`cache servers` in the CDN. Take care when using this endpoint.
+
+:Auth. Required: Yes
+:Roles Required: "operations" or "admin"\ [#tenancy]_
+:Response Type: Object
+
+Request Structure
+-----------------
+:deliveryService: This should either be the integral, unique identifier of a :term:`Delivery Service`, or a string containing an :ref:`ds-xmlid`
+: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, but unlike :ref:`to-api-user-current-jobs` (or the PUT_ method of this endpoint), it is not required to be within two days from the time of creation.
+:regex: A regular expression that will be used to match the path part of URIs for content stored on :term:`cache servers` that service traffic for the :term:`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.
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.4/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 :ref:`ds-xmlid` of the :term:`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
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 201 Created
+ 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/1.4/jobs?id=3
+ Set-Cookie: mojolicious=...; Path=/; 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",
- "startTime": "2018-12-05 15:43:42+00",
- "id": 1,
- "deliveryService": "demo1"
+ "deliveryService": "demo1",
+ "id": 3,
+ "keyword": "PURGE",
+ "parameters": "TTL:2h",
+ "startTime": "2019-06-18 21:28:31+00"
+ }
+ }
+
+
+``PUT``
+=======
+.. versionadded:: 1.4
+ This was added at the same time as `PATCH`_, so it's recommended in most cases to instead use that method.
Review comment:
you have patch commented out in routes.go. want to remove any documentation associated with patch?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services