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

Kirimkan pekerjaan snapshot. Setelah Anda memanggil API ini, ApsaraVideo Media Processing (MPS) akan melakukan pengambilan snapshot dan penyusunan gambar pada file input.

Deskripsi operasi

Ukuran maksimum file input tunggal adalah 100 GB. File yang melebihi batas ini dapat menyebabkan pekerjaan gagal.
Pastikan file telah berhasil diunggah ke Object Storage Service (OSS) sebelum mengirimkan pekerjaan snapshot. Jika tidak, pekerjaan akan gagal. Anda dapat mengonfigurasi pesan callback OSS untuk memverifikasi status unggahan file.
Pekerjaan snapshot mendukung mode sinkron dan mode asinkron:
- Mode sinkron hanya mendukung pengambilan satu snapshot. Gambar dihasilkan saat API mengembalikan respons.
- Mode asinkron tidak menjamin ketepatan waktu. Setelah Anda mengirimkan pekerjaan snapshot, tugas tersebut ditambahkan ke antrian MPS untuk penjadwalan dan eksekusi. Oleh karena itu, snapshot mungkin belum tersedia saat API mengembalikan respons. Setelah pekerjaan selesai, Anda harus melakukan polling hasil dengan memanggil API Query Snapshot Job Result atau menerima hasil melalui pesan MNS dengan menyambungkan topik MNS ke antrian MPS. Untuk informasi selengkapnya, lihat Receive Message Notifications.
- Jika salah satu parameter Interval atau Num ditentukan, maka mode asinkron akan digunakan.
Saat ini, hanya gambar dalam format JPG yang didukung.
Untuk pertanyaan umum lainnya tentang snapshot, lihat Snapshot FAQ.

Batas Permintaan per Detik (QPS)

Batas QPS untuk API ini adalah 50 permintaan per detik (QPS) per pengguna. Jika batas ini dilampaui, panggilan API akan dikenai pembatasan laju (Rate Limiting), yang dapat berdampak pada bisnis Anda. Gunakan API ini secara bijak. Untuk informasi selengkapnya, lihat 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	Informasi tentang input pekerjaan. Nilainya harus berupa objek JSON. Anda harus menambahkan bucket Object Storage Service (OSS) yang menyimpan objek OSS yang akan digunakan sebagai input pekerjaan sebagai bucket media di konsol MPS. Untuk menambahkan bucket OSS sebagai bucket media, Anda dapat login ke konsol MPS, pilih Workflows > Media Buckets di panel navigasi sebelah kiri, lalu klik Add Bucket. Setelah bucket OSS ditambahkan sebagai bucket media, Anda harus melakukan URL encoding untuk objek OSS tersebut. Contoh: `{"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}`. Contoh ini merepresentasikan objek `"example-bucket.example-location.aliyuncs.com/example/test.flv"`. Catatan Bucket OSS harus berada di wilayah yang sama dengan layanan MPS Anda.	{"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}
SnapshotConfig	string	Yes	Konfigurasi snapshot. Untuk informasi selengkapnya, lihat bagian "AliyunSnapshotConfig" pada topik Data types. Catatan Jika Anda mengatur parameter Interval yang bersarang di bawah SnapshotConfig, snapshot akan diambil pada interval yang ditentukan. Nilai default parameter Interval adalah 10, dalam satuan detik. Jika video input pendek tetapi Anda menentukan nilai besar untuk kedua parameter Num dan Interval, jumlah snapshot yang benar-benar diambil mungkin lebih sedikit dari jumlah yang ditentukan. Misalnya, jika Anda mengatur parameter Num ke 5 dan parameter Interval ke 3 untuk video berdurasi 10 detik, jumlah snapshot yang diambil tidak dapat mencapai 5.	{"OutputFile":{"Bucket":"example-001","Location":"example-location","Object":"{Count}.jpg"},"Time":"5","Num":"10","Interval":"20"}
UserData	string	No	Data kustom. Data kustom dapat berisi huruf, angka, dan tanda hubung (-), serta memiliki ukuran maksimal 1.024 byte. Data kustom tidak boleh dimulai dengan karakter khusus.	testid-001
PipelineId	string	No	ID antrian MPS tempat Anda ingin mengirimkan pekerjaan snapshot. Untuk mendapatkan ID tersebut, Anda dapat login ke MPS console dan memilih Global Settings > Pipelines di panel navigasi sebelah kiri. Catatan Pastikan topik Message Service (MNS) yang tersedia telah diikat ke antrian MPS yang ditentukan. Jika tidak, pesan terkait mungkin gagal dikirim sesuai harapan.	dd3dae411e704030b921e52698e5****

Elemen respons

Element	Type	Description	Example
	object	Parameter respons.
RequestId	string	ID permintaan.	19B6D8C5-A5DD-467A-B435-29D393C71E2D
SnapshotJob	object	Informasi tentang pekerjaan snapshot.
CreationTime	string	Waktu saat pekerjaan dibuat.	2021-05-19T03:11:48Z
SnapshotConfig	object	Konfigurasi snapshot.
Time	string	Waktu mulai pengambilan snapshot. Satuan: milidetik.	5
TileOut	object	Konfigurasi tiling.
Padding	string	Jarak antara dua gambar tunggal berturut-turut dalam gambar tiling. Nilai default: 0. Satuan: piksel.	0
Color	string	Warna latar belakang. Nilai default: black. Anda dapat mengatur parameter Color ke color keyword atau random dalam permintaan. Catatan Jika Anda ingin mengatur warna latar belakang menjadi hitam, Anda dapat menentukan kata kunci warna dalam salah satu dari tiga format berikut: Black, black, dan #000000.	black
CellSelStep	string	Langkah pemilihan gambar tunggal.	3
CellHeight	string	Tinggi gambar tunggal. Nilai default adalah tinggi snapshot output.	100
CellWidth	string	Lebar gambar tunggal. Nilai default adalah lebar snapshot output.	100
Margin	string	Lebar margin gambar tiling. Nilai default: 0. Satuan: piksel.	5
Columns	string	Jumlah kolom dalam gambar tiling. Nilai default: 10.	10
IsKeepCellPic	string	Menunjukkan apakah gambar tunggal dipertahankan. Nilai yang valid: true: Gambar tunggal dipertahankan. false: Gambar tunggal tidak dipertahankan. Nilai default: true.	false
Lines	string	Jumlah baris dalam gambar tiling. Nilai default: 10.	10
Interval	string	Interval pengambilan snapshot. Jika parameter ini ditentukan dalam permintaan, snapshot diambil pada interval tertentu. Nilainya harus lebih besar dari 0 dalam permintaan. Satuan: detik. Nilai default: 10.	20
FrameType	string	Jenis snapshot. Nilai default: Normal. Nilai yang valid: normal: frame normal. intra: Frame-I (keyframe). Catatan Jika parameter FrameType diatur ke intra dalam permintaan, hanya keyframe yang diambil. Jika tidak ditemukan keyframe pada titik waktu yang ditentukan, keyframe terdekat dengan titik waktu tersebut yang diambil. Keyframe diambil lebih cepat daripada frame normal jika aturan snapshot yang sama diterapkan.	intra
Width	string	Lebar snapshot output.	8
Height	string	Tinggi snapshot output.	8
OutputFile	object	Informasi tentang file output pekerjaan snapshot.
RoleArn	string	Nama Sumber Daya Alibaba Cloud (ARN) dari peran RAM yang ditentukan. Format: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	Objek OSS yang dihasilkan sebagai file output pekerjaan snapshot.	test.png
Location	string	Wilayah OSS tempat bucket OSS untuk menyimpan snapshot output berada.	example-location
Bucket	string	Bucket OSS yang menyimpan snapshot output.	example
Num	string	Jumlah snapshot. Jika parameter Num diatur dalam permintaan, snapshot diambil pada interval tertentu.	10
TileOutputFile	object	Informasi tentang file output pekerjaan tiling.
RoleArn	string	ARN dari peran RAM yang ditentukan. Format: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	Objek OSS yang dihasilkan sebagai file output pekerjaan tiling.	example.png
Location	string	ID wilayah tempat bucket OSS yang menyimpan objek berada.	example-location
Bucket	string	Bucket OSS yang menyimpan objek.	example
TimeArray	object
TimePointList	array	Array titik waktu yang ditentukan.
	integer	Array titik waktu yang ditentukan. Satuan adalah milidetik, direpresentasikan sebagai bilangan titik mengambang dengan dua tempat desimal. Nilai dapat diduplikasi dan dikirimkan dalam urutan apa pun; MPS akan melakukan pengurutan. Maksimal 100 titik waktu diperbolehkan. Saat parameter ini ditentukan, parameter Num, Time, atau Interval tidak boleh ditentukan. Jika salah satunya ditentukan, sistem akan mengembalikan kesalahan: InvalidParameter.Ambiguity.	[10050, 50000, 110000, 1000500, 1100500]
State	string	Status pekerjaan snapshot. Nilai yang valid: Submitted: Pekerjaan telah dikirim. Snapshoting: Pekerjaan sedang diproses. Success: Pekerjaan berhasil. Fail: Pekerjaan gagal.	Snapshoting
Message	string	Pesan kesalahan yang dikembalikan jika pekerjaan gagal. Parameter ini tidak dikembalikan jika pekerjaan berhasil.	The resource operated InputFile is bad
MNSMessageResult	object	Pesan yang dikirim oleh MNS untuk memberi tahu pengguna tentang hasil pekerjaan.
MessageId	string	ID pesan. Parameter ini tidak dikembalikan jika pekerjaan gagal.	799454621135656C7F815F198A76****
ErrorMessage	string	Pesan kesalahan yang dikembalikan jika pekerjaan gagal. Parameter ini tidak dikembalikan jika pekerjaan berhasil.	The resource operated InputFile is bad
ErrorCode	string	Kode kesalahan yang dikembalikan jika pekerjaan gagal. Parameter ini tidak dikembalikan jika pekerjaan berhasil.	InvalidParameter
Input	object	Informasi tentang input pekerjaan.
RoleArn	string	ARN dari peran RAM yang ditentukan. Format: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	Objek OSS yang digunakan sebagai file input.	example.flv
Location	string	Wilayah tempat bucket OSS berada.	example-location'
Bucket	string	Bucket OSS yang menyimpan objek.	example
Count	string	Jumlah snapshot yang diambil.	1
TileCount	string	Jumlah gambar tunggal yang terdapat dalam gambar tiling.	5
UserData	string	Data kustom.	testid-001
Code	string	Kode kesalahan yang dikembalikan jika pekerjaan gagal. Parameter ini tidak dikembalikan jika pekerjaan berhasil.	ResourceContentBad
PipelineId	string	ID antrian MPS tempat pekerjaan snapshot dikirimkan.	dd3dae411e704030b921e52698e5****
Id	string	ID pekerjaan snapshot.	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.