QuerySnapshotJobList-阿里云帮助中心

Queries snapshot jobs.

Operation description

You can specify multiple snapshot job IDs (SnapshotJobIds) to query. Alternatively, you can perform a paging query without specifying snapshot job IDs by filtering by conditions such as snapshot status, creation time, and MPS queue.
You can query up to 10 snapshot jobs in a single call.
By default, the returned results are sorted in descending order of CreationTime.

QPS limits

The QPS limit per user for this operation is 100 calls per second. If the limit is exceeded, API calls are throttled, which may affect your services. Call the operation properly. For more information, see QPS limits.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

mts:QuerySnapshotJobList

list

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
SnapshotJobIds	string	No	The list of snapshot job IDs. You can query up to 10 IDs at a time. Separate multiple IDs with commas (,). You can obtain the IDs from the MPS console by choosing Job Management > Snapshots, or from the response parameters of Submit a snapshot job.	72dfa5e679ab4be9a3ed9974c736****
NextPageToken	string	No	The token for the next page, which is a 32-character UUID. If the query results exceed one page, the NextPageToken parameter is returned and updated with each query. Use the returned token in the next query.	cc6cbef8e8d5481ca536f5d2a466****
MaximumPageSize	integer	No	The maximum number of entries to return on each page in a paging query. Valid values: [1,300]. Default value: 30.	30
State	string	No	The snapshot status to query. Valid values: Submitted: The job is submitted. Snapshoting: The snapshot is being taken. Success: The snapshot is taken successfully. Fail: The snapshot fails.	Snapshoting
StartOfJobCreatedTimeRange	string	No	The earliest time when the job was created. Specify the time in the ISO 8601 standard. The time must be in UTC. Format: YYYY-MM-DDThh:mm:ssZ.	2014-01-10T12:00:00Z
EndOfJobCreatedTimeRange	string	No	The latest time when the job was created. Specify the time in the ISO 8601 standard. The time must be in UTC. Format: YYYY-MM-DDThh:mm:ssZ.	2014-01-12T12:00:00Z
PipelineId	string	No	The ID of the MPS queue. For more information, see Terms. Valid values: You can query and create MPS queues in the MPS console by choosing Global Settings > MPS Queues. If you require asynchronous notifications, bind an MNS message to the MPS queue. For more information, see Receive message notifications.	b11c171cced04565b1f38f1ecc39****

Response elements

Element	Type	Description	Example
	object	The response parameters.
SnapshotJobList	object
SnapshotJob	array<object>	The list of snapshot jobs.
	array<object>	The response parameters.
CreationTime	string	The time when the job was created. The time is displayed in UTC and formatted in accordance with the ISO 8601 standard in the YYYY-MM-DDTHH:mm:ssZ format.	2021-06-30T12:34:29Z
SnapshotConfig	object	The snapshot configurations.
Time	string	The start time of the snapshot. Unit: milliseconds.	4
TileOut	object	The image sprite configurations.
Padding	string	The spacing between images. Default value: 0. Unit: pixels.	0
Color	string	The background color. Default value: black. Valid values: color keyword and random. Note Color keywords support three formats. For example, black can be represented as Black, black, or #000000.	black
CellSelStep	string	The step size for selecting a single image.	3
CellHeight	string	The height of a single image. Default value: the height of the snapshot output resolution.	8
CellWidth	string	The width of a single image. Default value: the width of the snapshot output resolution.	8
Margin	string	The width of the outer frame. Default value: 0. Unit: pixels.	0
Columns	string	The number of columns in the image sprite. Default value: 10.	10
IsKeepCellPic	string	Specifies whether to retain single images. Default value: true.	false
Lines	string	The number of rows in the image sprite. Default value: 10.	10
Interval	string	The time interval between snapshots. If this parameter is specified, sequence snapshots are taken, and the value must be greater than 0. Unit: seconds. Default value: 10.	10
FrameType	string	The snapshot type. Valid values: normal: normal frame. intra: I-frame. Default value: intra.	intra
Width	string	The width of the output snapshot image.	8
Height	string	The height of the output snapshot image.	8
OutputFile	object	The OSS configurations for the snapshot output.
RoleArn	string	The ARN of the specified role. Format: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	The snapshot output file (OSS object).	example.png
Location	string	The data center where the OSS bucket for the snapshot output resides (OSS location).	example-location
Bucket	string	The OSS bucket where the snapshot output file is stored.	example
Num	string	The number of snapshots. If this parameter is specified, sequence snapshots are taken.	10
TileOutputFile	object	The OSS configurations for the output image sprite.
RoleArn	string	The ARN of the specified role. Format: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	The output file (OSS object).	example.png
Location	string	The data center where the output OSS bucket resides (OSS location).	example-location
Bucket	string	The OSS bucket where the output file is stored.	example
TimeArray	object
TimePointList	array	The array of specified time points.
	integer	The array of specified time points. Unit: milliseconds. The values are floating-point numbers with two decimal places. The values can be duplicate and submitted out of order, and are sorted by MPS. You can specify up to 100 time points. If this parameter is specified, do not specify Num, Time, or Interval. Otherwise, the InvalidParameter.Ambiguity error is reported.	[10050, 50000, 110000, 1000500, 1100500]
State	string	The snapshot status. Valid values: Submitted: The job is submitted. Snapshoting: The snapshot is being taken. Success: The snapshot is taken successfully. Fail: The snapshot fails.	Snapshoting
Message	string	The error message returned when the snapshot fails. This parameter is not returned if the job is successful.	The resource operated InputFile is bad
MNSMessageResult	object	The result of the MNS notification sent to the user upon job completion.
MessageId	string	The message ID returned when the notification is successful. This parameter is not returned if the notification fails.	799454621135656C7F815F198A76****
ErrorMessage	string	The error message returned when the notification fails. This parameter is not returned if the notification is successful.	The resource operated InputFile is bad
ErrorCode	string	The error code returned when the notification fails. This parameter is not returned if the notification is successful.	InvalidParameter
Input	object	The job input.
RoleArn	string	The ARN of the specified role. Format: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	The input file (OSS object).	example.flv
Location	string	The data center where the input OSS bucket resides (OSS location).	example-location
Bucket	string	The OSS bucket where the input file is stored.	example
Count	string	The number of captured images.	1
TileCount	string	The number of images in the image sprite.	7
UserData	string	The custom user data.	testid-001
Code	string	The error code returned when the snapshot fails. This parameter is not returned if the job is successful.	InvalidParameter
PipelineId	string	The ID of the MPS queue.	b11c171cced04565b1f38f1ecc39****
Id	string	The ID of the snapshot job.	cc6cbef8e8d5481ca536f5d2a466****
RequestId	string	The request ID.	34BCAB31-2833-43A7-9FBD-B34302AB23EQ
NonExistSnapshotJobIds	object
String	array	The list of non-existent snapshot job IDs.
	string	The details of the non-existent snapshot job IDs. This parameter is not returned if no data is available.	c6d973c33d1c4b21bc39907d3b29****
NextPageToken	string	The token for the next page, which is a 32-character UUID. This parameter is returned and updated with each query when the query results exceed one page.	b11c171cced04565b1f38f1ecc39****

Examples

Success response

JSON format

{
  "SnapshotJobList": {
    "SnapshotJob": [
      {
        "CreationTime": "2021-06-30T12:34:29Z",
        "SnapshotConfig": {
          "Time": "4",
          "TileOut": {
            "Padding": "0",
            "Color": "black",
            "CellSelStep": "3",
            "CellHeight": "8",
            "CellWidth": "8",
            "Margin": "0",
            "Columns": "10",
            "IsKeepCellPic": "false",
            "Lines": "10"
          },
          "Interval": "10",
          "FrameType": "intra",
          "Width": "8",
          "Height": "8",
          "OutputFile": {
            "RoleArn": "acs:ram::1:role/testrole",
            "Object": "example.png",
            "Location": "example-location",
            "Bucket": "example"
          },
          "Num": "10",
          "TileOutputFile": {
            "RoleArn": "acs:ram::1:role/testrole",
            "Object": "example.png",
            "Location": "example-location",
            "Bucket": "example"
          },
          "TimeArray": {
            "TimePointList": [
              0
            ]
          }
        },
        "State": "Snapshoting",
        "Message": "The resource operated InputFile is bad",
        "MNSMessageResult": {
          "MessageId": "799454621135656C7F815F198A76****",
          "ErrorMessage": "The resource operated InputFile is bad",
          "ErrorCode": "InvalidParameter"
        },
        "Input": {
          "RoleArn": "acs:ram::1:role/testrole",
          "Object": "example.flv",
          "Location": "example-location",
          "Bucket": "example"
        },
        "Count": "1",
        "TileCount": "7",
        "UserData": "testid-001",
        "Code": "InvalidParameter",
        "PipelineId": "b11c171cced04565b1f38f1ecc39****",
        "Id": "cc6cbef8e8d5481ca536f5d2a466****"
      }
    ]
  },
  "RequestId": "34BCAB31-2833-43A7-9FBD-B34302AB23EQ",
  "NonExistSnapshotJobIds": {
    "String": [
      "c6d973c33d1c4b21bc39907d3b29****"
    ]
  },
  "NextPageToken": "b11c171cced04565b1f38f1ecc39****"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.