Help & Documentation>Cloud Object Storage>API Documentation>Batch Operation APIs>ListJobs

ListJobs

Last updated: 2023-09-19 18:57:34

On this page:

Feature Overview

This API is used to list your batch operation jobs. For more information on batch operation, please see Batch Operation Overview.

Requests

Sample request
GET /jobs?jobStatuses=<JobStatuses>&maxResults=<MaxResults>&nextToken=<NextToken> HTTP/1.1
Host: <UIN>.cos-control.<Region>.myqcloud.com
Date: GMT Date
Content-Type: application/xml
Content-Length: Content Length
Authorization: Auth String
x-cos-appid: <APPID>
Note
Authorization: Auth String (For more information, see Request Signature.)
Request parameters
Calling the ListJobs API requires the following parameters:
Category
Description
Required
jobStatuses
Status of the job to be queried. If no status is specified, COS will return all jobs, including those in progress; otherwise, only jobs in the specified status will be returned. Valid values: Active, Cancelled, Cancelling, Complete, Completing, Failed, Failing, New, Paused, Pausing, Preparing, Ready, Suspended.
Not required
maxResults
Maximum number of jobs to be returned by COS. If this parameter is configured, the number of jobs returned each time will not exceed its value. If it is used together with the nextToken parameter, COS can return the results in multiple pages. Value range: 1–1000. Default value: 1000.
Not required
nextToken
Page break with a length of 1–64 bytes. Each ListJobs call will return the last JobId in the job list as nextToken. You can pass in the nextToken in the next ListJobs call for COS to list jobs starting from the end of the previous list. In this way, the results can be returned in multiple pages.
Not required
x-cos-appid
User APPID with a length of 1–64 bytes.
Required
Request headers
This API only uses Common Request Headers.
Request body This request has no request body.

Response

Response header
This API only returns Common Response Headers.
Response body
<ListJobsResult>
    <Jobs>
        <member>
            <CreationTime>timestamp</CreationTime>
            <Description>string</Description>
            <JobId>string</JobId>
            <Operation>string</Operation>
            <Priority>integer</Priority>
            <ProgressSummary>
                <NumberOfTasksFailed>integer</NumberOfTasksFailed>
                <NumberOfTasksSucceeded>integer</NumberOfTasksSucceeded>
                <TotalNumberOfTasks>integer</TotalNumberOfTasks>
            </ProgressSummary>
            <Status>string</Status>
            <TerminationDate>timestamp</TerminationDate>
        </member>
    </Jobs>
    <NextToken></NextToken>
</ListJobsResult>
The content is described in details below:
ListJobsResult Contains the batch processing task list information returned by COS.
Node name
Parent Node
Description
Local Disk Types
Jobs
ListJobsResult
Information on the batch operation jobs returned by COS.
Jobs Object
NextToken
ListJobsResult
Page break with a length of 1–64 bytes. Each ListJobs call will return the last JobId in the job list as nextToken. You can pass in the nextToken in the next ListJobs call for COS to list jobs starting from the end of the previous list. In this way, the results can be returned in multiple pages.
String
Jobs
Node name
Parent Node
Description
Local Disk Types
member
Jobs
Information on one of the batch operation jobs returned by COS.
member Object
member
Node name
Parent Node
Description
Local Disk Types
CreationTime
member
Job creation time.
Timestamp
Description
member
Job description; length: 0–256 bytes.
String
JobId
member
Job ID; length: 1–64 bytes.
String
Operation
member
Operation performed on objects in a batch operation job, e.g. COSPutObjectCopy
String
Priority
member
Job priority; tasks with higher values will be executed first.
Priority range: 0–2147483647.
Integer
ProgressSummary
member
Overview of job execution, which describes how many operations were performed in the job, how many succeeded, and how many failed.
ProgressSummary Object
Status
member
Job status. Valid values: Active, Cancelled, Cancelling, Complete, Completing, Failed, Failing, New, Paused, Pausing, Preparing, Ready, Suspended.
String
TerminationDate
member
Job end time.
Timestamp
For other elements, see CommonElements.

Error Codes

The following describes some common errors that may occur when making requests using this API.
Error Codes
Description
Status code
API
InvalidArgument
Parameter jobStatuses is invalid
400
ListJobs
InvalidArgument
The maxResults parameter must be an integer
400
ListJobs
InvalidArgument
The nextToken parameter is invalid
400
ListJobs
For other errors, see ErrorResponse.

Examples

Requests

GET /jobs?maxResults=2 HTTP/1.1
Host: 100000000001.cos-control.ap-chengdu.myqcloud.com
Date: Fri, 20 Dec 2019 03:31:41 GMT
x-cos-appid: 1250000000
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO<1>**&q-sign-time=1576812701;1576819901&q-key-time=1576812701;1576819901&q-header-list=date;host;x-cos-appid&q-url-param-list=maxresults&q-signature=432bc3f2116d579e257742596c31528c0d72</1>**
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1166
Connection: close
Date: Fri, 20 Dec 2019 03:31:41 GMT
Server: tencent-cos
x-cos-request-id: NWRmYzQwOWRfNWFiMjU4NjRfNmU1M18xMTFh****

<ListJobsResult>
    <Jobs>
        <member>
            <CreationTime>2019-12-19T11:05:40Z</CreationTime>
            <Description>example-job</Description>
            <JobId>021140d8-67ca-4e89-8089-0de9a1e40943</JobId>
            <Operation>COSPutObjectCopy</Operation>
            <Priority>10</Priority>
            <ProgressSummary>
                <NumberOfTasksFailed>0</NumberOfTasksFailed>
                <NumberOfTasksSucceeded>10</NumberOfTasksSucceeded>
                <TotalNumberOfTasks>10</TotalNumberOfTasks>
            </ProgressSummary>
            <Status>Complete</Status>
            <TerminationDate>2019-12-19T11:05:56Z</TerminationDate>
        </member>
        <member>
            <CreationTime>2019-12-19T11:07:05Z</CreationTime>
            <Description>example-job</Description>
            <JobId>066d919e-49b9-429e-b844-e17ea7b16421</JobId>
            <Operation>COSPutObjectCopy</Operation>
            <Priority>10</Priority>
            <ProgressSummary>
                <NumberOfTasksFailed>0</NumberOfTasksFailed>
                <NumberOfTasksSucceeded>10</NumberOfTasksSucceeded>
                <TotalNumberOfTasks>10</TotalNumberOfTasks>
            </ProgressSummary>
            <Status>Complete</Status>
            <TerminationDate>2019-12-19T11:07:21Z</TerminationDate>
        </member>
    </Jobs>
    <NextToken>066d919e-49b9-429e-b844-e17ea7b16421</NextToken>
</ListJobsResult>

中国站 - English