Resource URL: /platform/<<version=3>>/cloud/jobs

    Overview: This resource applies the standard collection pattern to cloud
              jobs.

     Methods: GET, POST

********************************************************************************

Method GET: List all cloudpools jobs.

       URL: GET /platform/<<version=3>>/cloud/jobs

Query arguments:
  sort=<string> The field that will be used for sorting.
limit=<integer> Return no more than this many results at once (see resume).
     dir=<enum> Where <enum> is one of ASC, DESC.  The direction of the sort.

GET response body schema:
{
  "type": "object", 
  "properties": {
    "total": {
      "type": "integer", 
      "description": "Total number of items available."
    }, 
    "jobs": {
      "items": {
        "type": "object", 
        "description": "A cloud job for archiving or recalling files", 
        "properties": {
          "files": {
            "type": "object", 
            "description": "The files and filters addressed by this job", 
            "properties": {
              "total_failed": {
                "type": "integer", 
                "description": "The number of files which failed"
              }, 
              "total_succeeded": {
                "type": "integer", 
                "description": "The total number of files successfully completed"
              }, 
              "total_processing": {
                "type": "integer", 
                "description": "The number of files currently being processed"
              }, 
              "total_pending": {
                "type": "integer", 
                "description": "The number of files pending action"
              }, 
              "total_canceled": {
                "type": "integer", 
                "description": "The number of canceled files"
              }, 
              "file_matching_pattern": {
                "type": "object", 
                "description": "The file filtering logic to find files for this job"
              }, 
              "names": {
                "items": {
                  "type": "object", 
                  "properties": {
                    "state": {
                      "type": "string", 
                      "description": "The current state of this file"
                    }, 
                    "name": {
                      "type": "string", 
                      "description": "The full path name of a file to be acted on by this job"
                    }
                  }
                }, 
                "type": "array", 
                "description": "A list of files to be addressed by this job.  (Note* these are only reported when audit_level is 'high'"
              }, 
              "total": {
                "type": "integer", 
                "description": "The total number of files addressed by this job"
              }
            }
          }, 
          "job_engine_job": {
            "type": "object", 
            "description": "Information about the related job engine job if there is one", 
            "properties": {
              "state": {
                "enum": [
                  "null", 
                  "running", 
                  "user-paused", 
                  "system-paused", 
                  "policy-paused", 
                  "waiting", 
                  "user-canceled", 
                  "system-canceled", 
                  "failed", 
                  "succeeded"
                ], 
                "type": "string", 
                "description": "The state of the related job engine job"
              }, 
              "id": {
                "type": "integer", 
                "description": "ID of the related job engine job"
              }
            }
          }, 
          "operation_state": {
            "enum": [
              "running", 
              "paused"
            ], 
            "type": "string", 
            "description": "The current state of the operation associated with the job"
          }, 
          "description": {
            "type": "string", 
            "description": "A brief description of the job contents"
          }, 
          "effective_state": {
            "enum": [
              "running", 
              "paused", 
              "canceled", 
              "completed", 
              "failed"
            ], 
            "type": "string", 
            "description": "The effective state of the job (e.g,. the combination of operation_state and job_state)"
          }, 
          "job_state": {
            "enum": [
              "running", 
              "paused", 
              "canceled", 
              "completed", 
              "failed"
            ], 
            "type": "string", 
            "description": "The current state of the job"
          }, 
          "state_change_time": {
            "type": "integer", 
            "description": "The last time at which the job state changed"
          }, 
          "completion_time": {
            "type": "integer", 
            "description": "The time at which the job was completed (if applicable)"
          }, 
          "create_time": {
            "type": "integer", 
            "description": "The time at which the job was created"
          }, 
          "type": {
            "enum": [
              "archive", 
              "recall", 
              "local-garbage-collection", 
              "cloud-garbage-collection", 
              "cache-writeback", 
              "cache-on-access", 
              "cache-invalidation", 
              "restore-coi"
            ], 
            "type": "string", 
            "description": "The type of cloud action to be performed by this job."
          }, 
          "id": {
            "type": "integer", 
            "description": "The job's ID"
          }
        }
      }, 
      "type": "array"
    }, 
    "resume": {
      "type": [
        "string", 
        "null"
      ], 
      "description": "Continue returning results from previous call using this token (token should come from the previous call, resume cannot be used with other options)."
    }
  }
}

********************************************************************************

Method POST: Create a new job.

        URL: POST /platform/<<version=3>>/cloud/jobs

There are no query arguments for this method.

Required POST request body fields:
type

POST request body schema:
{
  "type": "object", 
  "description": "A cloud job for archiving or recalling files or restoring COI", 
  "properties": {
    "files": {
      "items": {
        "type": "string"
      }, 
      "type": "array", 
      "description": "Filenames addressed by this job"
    }, 
    "expiration_date": {
      "type": "integer", 
      "description": "The new expiration date in seconds"
    }, 
    "directories": {
      "items": {
        "type": "string"
      }, 
      "type": "array", 
      "description": "Directories addressed by this job"
    }, 
    "file_matching_pattern": {
      "type": "object", 
      "description": "The file filtering logic to find files for this job. (Only applicable for 'recall' jobs)"
    }, 
    "accounts": {
      "items": {
        "type": "string"
      }, 
      "type": "array", 
      "description": "The names of accounts for COI restore"
    }, 
    "policy": {
      "type": "string", 
      "description": "The name of an existing cloudpool policy to apply to this job. (Only applicable for 'archive' jobs)"
    }, 
    "type": {
      "enum": [
        "archive", 
        "recall", 
        "local-garbage-collection", 
        "cloud-garbage-collection", 
        "cache-writeback", 
        "cache-on-access", 
        "cache-invalidation", 
        "restore-coi"
      ], 
      "type": "string", 
      "description": "The type of cloud action to be performed by this job.", 
      "required": true
    }
  }
}

POST response body schema:
{
  "type": "object", 
  "properties": {
    "id": {
      "type": "integer", 
      "description": "The id of the new job"
    }
  }
}
