Gunakan SubmitSnapshotJob API untuk otomatisasi snapshot async-ApsaraVideo MPS-Alibaba Cloud - ApsaraVideo Media Processing

Mengirimkan Pekerjaan Snapshot. Layanan Media Processing Service (MPS) kemudian mengambil tangkapan layar dan menghasilkan gambar Sprite dari file input.

Deskripsi operasi

The maximum size for a single input file is 100 GB. Exceeding this limit may cause the job to fail.
Before you submit a snapshot job, ensure the file has been successfully uploaded to OSS. Otherwise, the job may fail. You can configure OSS callbacks to confirm the file upload status.
Snapshot jobs support both synchronous and asynchronous modes.
- Synchronous mode supports only a single snapshot and generates the image when the API call returns.
- Asynchronous mode does not guarantee immediate processing. After you submit a snapshot job, it enters a pipeline, where it is queued and scheduled for execution. Therefore, the snapshot is not guaranteed to be generated when the API call returns. After the job is complete, you can poll for the results by calling the Query snapshot job results API or receive message notifications by binding MNS to the pipeline. For more information, see Receive message notifications.
- Specifying either the Interval or Num parameter triggers asynchronous mode.
Currently, only images in JPG format are supported.
For more information about common snapshot issues, see Snapshot FAQ.

QPS limit

The QPS limit for this API is 50 requests per second per user. API calls that exceed this limit are subject to throttling, which may impact your business. Please call this API at a reasonable rate. For more information, see QPS limit.

Coba sekarang

Coba API ini di OpenAPI Explorer tanpa perlu penandatanganan manual. Panggilan yang berhasil akan secara otomatis menghasilkan contoh kode SDK sesuai dengan parameter Anda. Unduh kode tersebut dengan kredensial bawaan yang aman untuk penggunaan lokal.

Test

RAM authorization

Tabel berikut menjelaskan otorisasi yang diperlukan untuk memanggil API ini. Anda dapat menentukannya dalam kebijakan Resource Access Management (RAM). Kolom pada tabel dijelaskan sebagai berikut:

Action: Aksi yang dapat digunakan dalam elemen Action pada pernyataan kebijakan izin RAM untuk memberikan izin guna melakukan operasi tersebut.
API: API yang dapat Anda panggil untuk melakukan aksi tersebut.
Access level: Tingkat akses yang telah ditentukan untuk setiap API. Nilai yang valid: create, list, get, update, dan delete.
Resource type: Jenis resource yang mendukung otorisasi untuk melakukan aksi tersebut. Ini menunjukkan apakah aksi tersebut mendukung izin tingkat resource. Resource yang ditentukan harus kompatibel dengan aksi tersebut. Jika tidak, kebijakan tersebut tidak akan berlaku.
- Untuk API dengan izin tingkat resource, jenis resource yang diperlukan ditandai dengan tanda bintang (*). Tentukan Nama Sumber Daya Alibaba Cloud (ARN) yang sesuai dalam elemen Resource pada kebijakan.
- Untuk API tanpa izin tingkat resource, ditampilkan sebagai All Resources. Gunakan tanda bintang (*) dalam elemen Resource pada kebijakan.
Condition key: Kunci kondisi yang didefinisikan oleh layanan. Kunci ini memungkinkan kontrol granular, berlaku baik hanya untuk aksi maupun untuk aksi yang terkait dengan resource tertentu. Selain kunci kondisi spesifik layanan, Alibaba Cloud menyediakan serangkaian common condition keys yang berlaku di semua layanan yang didukung RAM.
Dependent action: Aksi dependen yang diperlukan untuk menjalankan aksi tersebut. Untuk menyelesaikan aksi tersebut, pengguna RAM atau role RAM harus memiliki izin untuk melakukan semua aksi dependen.

Action

Access level

Resource type

Condition key

Dependent action

mts:SubmitSnapshotJob

create

*全部资源

*

None

Parameter permintaan

Parameter	Type	Required	Description	Example
Input	string	Yes	Input Pekerjaan. Untuk informasi selengkapnya, lihat Input. Catatan Di API ApsaraVideo for Media Processing (MPS), Anda harus URL-encode nilai `Object` dalam UTF-8. Wilayah OSS harus sama dengan wilayah MPS.	{"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}
SnapshotConfig	string	Yes	Konfigurasi Snapshot. Untuk informasi selengkapnya, lihat SnapshotConfig.	{"OutputFile":{"Bucket":"example-001","Location":"example-location","Object":"{Count}.jpg"},"Time":"5","Num":"10","Interval":"20"}
UserData	string	No	Data kustom. Nilai dapat berisi huruf, angka, dan tanda hubung (-), tetapi tidak dapat diawali dengan karakter khusus. Panjang nilai dapat mencapai 1.024 byte.	testid-001
PipelineId	string	No	ID Antrian MPS. Untuk informasi selengkapnya, lihat Konsep dasar. Anda dapat melihat atau membuat Antrian MPS di Konsol MPS dengan memilih Pengaturan Global > Antrian. Untuk menerima Notifikasi asinkron, ikatkan Antrian Message Service (MNS) ke Antrian MPS. Untuk informasi selengkapnya, lihat Menerima Notifikasi Paket.	dd3dae411e704030b921e52698e5****

Elemen respons

Element	Type	Description	Example
	object	The response parameters.
RequestId	string	The request ID.	19B6D8C5-A5DD-467A-B435-29D393C71E2D
SnapshotJob	object	The snapshot job.
CreationTime	string	The time the job was created.	2021-05-19T03:11:48Z
SnapshotConfig	object	The snapshot configuration.
Time	string	The start time for capturing snapshots. Unit: milliseconds.	5
TileOut	object	The tiling configurations.
Padding	string	The distance between two consecutive single images in the tiled image. Default value: 0. Unit: pixel.	0
Color	string	The background color. Default value: black. You can set the Color parameter to a color keyword or random in the request. Catatan If you want to set the background color to black, you can specify the color keyword in one of the following three formats: Black, black, and #000000.	black
CellSelStep	string	The step for selecting a single image.	3
CellHeight	string	The height of a single image. The default value is the height of the output snapshot.	100
CellWidth	string	The width of a single image. The default value is the width of the output snapshot.	100
Margin	string	The margin width of the tiled image. Default value: 0. Unit: pixel.	5
Columns	string	The number of columns that the tiled image contains. Default value: 10.	10
IsKeepCellPic	string	Indicates whether the single images are retained. Valid values: true: The single images are retained. false: The single images are not retained. Default value: true.	false
Lines	string	The number of rows that the tiled image contains. Default value: 10.	10
Interval	string	The interval for capturing snapshots. If this parameter is specified in the request, snapshots are captured at intervals. The value must be greater than 0 in the request. Unit: seconds. Default value: 10.	20
FrameType	string	The type of the snapshot. Default value: Normal. Valid values: normal: normal frames. intra: I-frames (keyframes). Catatan If the FrameType parameter is set to intra in the request, only keyframes are captured. If no keyframe is found at the specified point in time, the keyframe closest to the specified point in time is captured. Keyframes are captured faster than normal frames if the same snapshot rules are applied.	intra
Width	string	The width of the output snapshot.	8
Height	string	The height of the output snapshot.	8
OutputFile	object	The information about the output file of the snapshot job.
RoleArn	string	The Alibaba Cloud Resource Name (ARN) of the specified RAM role. Format: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	The OSS object that is generated as the output file of the snapshot job.	test.png
Location	string	The OSS region in which the OSS bucket for storing the output snapshot resides.	example-location
Bucket	string	The OSS bucket that stores the output snapshot.	example
Num	string	The number of snapshots. If the Num parameter is set in the request, snapshots are captured at intervals.	10
TileOutputFile	object	The information about the output file of the tiling job.
RoleArn	string	The ARN of the specified RAM role. Format: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	The OSS object that is generated as the output file of the tiling job.	example.png
Location	string	The ID of the region in which the OSS bucket that stores the object is located.	example-location
Bucket	string	The OSS bucket that stores the object.	example
TimeArray	object
TimePointList	array	An array of specified time points.
	integer	An array of specified time points. The unit is milliseconds, represented as a floating-point number with two decimal places. Values can be duplicated and submitted in any order; MPS will perform sorting. A maximum of 100 time points is allowed. When this parameter is specified, none of the parameters Num, Time, or Interval should be specified. If any of them are specified, the system returns an error: InvalidParameter.Ambiguity.	[10050, 50000, 110000, 1000500, 1100500]
State	string	The state of the snapshot job. Valid values: Submitted: The job has been submitted. Snapshotting: The snapshot job is in progress. Success: The job was successful. Fail: The job failed.	Snapshoting
Message	string	The error message. This parameter is returned only if the job fails.	The resource operated InputFile is bad
MNSMessageResult	object	The result of the MNS notification sent to the user upon job completion.
MessageId	string	The ID of the message. This parameter is not returned if the job fails.	799454621135656C7F815F198A76****
ErrorMessage	string	The error message returned if the job fails. This parameter is not returned if the job is successful.	The resource operated InputFile is bad
ErrorCode	string	The error code returned if the job fails. This parameter is not returned if the job is successful.	InvalidParameter
Input	object	The job input.
RoleArn	string	The ARN of the specified RAM role. Format: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	The OSS object that is used as the input file.	example.flv
Location	string	The region in which the OSS bucket resides.	example-location'
Bucket	string	The OSS bucket that stores the object.	example
Count	string	The total number of captured snapshots.	1
TileCount	string	The number of tiled images.	5
UserData	string	The user-defined data.	testid-001
Code	string	The error code. This parameter is returned only when the job status is Fail.	ResourceContentBad
PipelineId	string	The pipeline ID.	dd3dae411e704030b921e52698e5****
Id	string	The ID of the snapshot job.	f4e3b9ba9f3840c39d6e288056f0****

Contoh

Respons sukses

JSONformat

{
  "RequestId": "19B6D8C5-A5DD-467A-B435-29D393C71E2D",
  "SnapshotJob": {
    "CreationTime": "2021-05-19T03:11:48Z",
    "SnapshotConfig": {
      "Time": "5",
      "TileOut": {
        "Padding": "0",
        "Color": "black",
        "CellSelStep": "3",
        "CellHeight": "100",
        "CellWidth": "100",
        "Margin": "5",
        "Columns": "10",
        "IsKeepCellPic": "false",
        "Lines": "10"
      },
      "Interval": "20",
      "FrameType": "intra",
      "Width": "8",
      "Height": "8",
      "OutputFile": {
        "RoleArn": "acs:ram::1:role/testrole",
        "Object": "test.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": "5",
    "UserData": "testid-001",
    "Code": "ResourceContentBad",
    "PipelineId": "dd3dae411e704030b921e52698e5****",
    "Id": "f4e3b9ba9f3840c39d6e288056f0****"
  }
}

Kode kesalahan

Lihat Error Codes untuk daftar lengkap.

Catatan rilis

Lihat Release Notes untuk daftar lengkap.