Cara kerja operasi API asinkron - Intelligent Media Management

IMM mendukung berbagai operasi output data. Beberapa operasi tersebut memerlukan waktu lama dan tidak dapat mengembalikan hasil dalam satu permintaan sinkron. Untuk menangani kasus-kasus ini, IMM menyediakan operasi API asinkron—biasanya dinamai dalam format CreateXXXTask—serta mekanisme notifikasi untuk mengambil hasilnya.

Catatan

Operasi API asinkron di IMM dirancang untuk pekerjaan berdurasi panjang yang tidak dapat mengembalikan hasil dalam satu permintaan sinkron. Pendekatan asinkron ini mencegah pemblokiran pada klien, meningkatkan kinerja sistem, serta menjalankan pekerjaan intensif sumber daya atau terjadwal di latar belakang tanpa memengaruhi pengalaman pengguna.

Cara kerja

Unggah data sumber Anda ke Alibaba Cloud Object Storage Service (OSS).
Panggil operasi API IMM, seperti CreateXXXTask, untuk memulai tugas asinkron.
IMM mengambil dan memproses data sumber dari URI OSS yang ditentukan.
IMM menulis hasil pemrosesan ke URI OSS yang ditentukan.
Setelah tugas selesai, IMM mengirim status tugas ke topik MNS atau ApsaraMQ for RocketMQ yang Anda tentukan.
MNS atau ApsaraMQ for RocketMQ kemudian mendorong pesan notifikasi ke aplikasi atau layanan Anda.

Data masukan dan keluaran tugas

Parameter data masukan biasanya diawali dengan Source. Parameter berikut tersedia:
- SourceURI: Lokasi data masukan. Hanya URI OSS yang didukung.
- Sources: Array berisi beberapa URI masukan.
- Source: Objek yang berisi beberapa URI masukan.
Parameter data keluaran biasanya diawali dengan Target. Parameter berikut tersedia:
- TargetURI: Tujuan output. Parameter ini mendukung sintaksis templat.
- TargetURIPrefix: Awalan untuk URI tujuan output.
- Target: Objek yang berisi beberapa URI output.

Penting

Data masukan dan keluaran harus berada di wilayah yang sama dengan layanan IMM.

URI OSS

URI OSS secara unik mengidentifikasi sebuah resource di OSS dan menggunakan format oss://<bucket>/<object>, contohnya oss://test-bucket/test-object/test.docx.

Catatan

<bucket> adalah nama bucket OSS di wilayah yang sama dengan proyek Anda. <object> adalah path lengkap ke file, termasuk ekstensinya.

Format yang umum tidak valid meliputi:

http://bucket.oss-cn-hangzhou.aliyuncs.com/test-object/test.docx
oss://bucket.oss-cn-hangzhou.aliyuncs.com/test-object/test.docx

Templat TargetURI

Templat TargetURI memungkinkan Anda menggunakan placeholder dalam URI. Placeholder tersebut diganti dengan nilai aktual saat waktu proses untuk menghasilkan URI output akhir secara dinamis. Contohnya: oss://{bucket}/{tags.custom}/{dirname}/{barename}.{autoext}.

Untuk informasi lebih lanjut, lihat Templat TargetURI.

Otorisasi

Untuk tugas asinkron, Anda harus memberikan izin kepada IMM untuk membaca data masukan dan menulis data keluaran ke lokasi yang Anda sediakan. Izin ini ditentukan oleh parameter Project Name dalam permintaan Anda, yang mengidentifikasi proyek dan peran service-link terkaitnya. Anda menentukan peran ini untuk proyek menggunakan parameter Service Role dalam operasi API Create Project. Secara default, AliyunIMMDefaultRole digunakan, yang dibuat secara otomatis saat Anda mengaktifkan layanan. Selama pemrosesan tugas, IMM mengasumsikan peran ini untuk mengakses data Anda.

Mendapatkan status tugas

Menggunakan MNS atau ApsaraMQ for RocketMQ

Seperti dijelaskan dalam bagian Cara kerja, Anda dapat mengonfigurasi MNS atau ApsaraMQ for RocketMQ untuk menerima notifikasi status tugas IMM. Ini merupakan metode yang direkomendasikan. Untuk detail format notifikasi, lihat Format pesan notifikasi asinkron.

Penting

MNS atau ApsaraMQ for RocketMQ harus berada di wilayah yang sama dengan IMM.

(Direkomendasikan) Gunakan parameter Notification untuk menentukan konfigurasi MNS atau ApsaraMQ for RocketMQ guna menerima notifikasi asinkron.
- MNS: Gunakan bidang MNS dalam parameter Notification untuk menentukan endpoint dan topik MNS.
```
{
  "Notification": {
    "MNS": {
      "Endpoint": "The MNS endpoint",
      "TopicName": "The MNS topic"
    }
  }
}
```
- ApsaraMQ for RocketMQ: Gunakan bidang RocketMQ dalam parameter Notification untuk menentukan endpoint, topik, dan ID instans ApsaraMQ for RocketMQ.
```
{
  "Notification": {
    "RocketMQ": {
      "Endpoint": "The ApsaraMQ for RocketMQ endpoint",
      "TopicName": "The ApsaraMQ for RocketMQ topic",
      "InstanceId": "The ApsaraMQ for RocketMQ instance ID"
    }
  }
}
```
Gunakan parameter NotifyEndpoint dan NotifyTopicName untuk menentukan endpoint dan topik MNS guna menerima notifikasi pesan asinkron.
- NotifyEndpoint: Endpoint MNS untuk menerima notifikasi. Secara default, ini adalah endpoint MNS pemanggil.
- NotifyTopicName: Nama topik MNS. Jika parameter ini dikosongkan, tidak ada notifikasi yang dikirim.

Menggunakan API GetTask

IMM juga menyediakan operasi API GetTask untuk mengkueri status suatu tugas.

Meskipun Anda dapat memanggil berulang kali operasi API GetTask untuk melakukan polling status tugas hingga selesai, metode ini tidak efisien dan tidak direkomendasikan untuk lingkungan produksi. Untuk tugas berdurasi panjang, polling dapat menghasilkan banyak panggilan GetTask. Jika banyak tugas dalam antrian, hal ini dapat memicu pembatasan kecepatan global dan memengaruhi panggilan API lainnya. Selain itu, polling menimbulkan latensi. Tugas dapat selesai kapan saja di antara interval polling, tetapi Anda tidak akan mengetahui penyelesaiannya hingga polling berikutnya, sehingga menimbulkan penundaan rata-rata setengah dari interval polling.

Catatan

Informasi tugas hanya disimpan selama 7 hari setelah tugas dimulai, setelah itu tidak dapat lagi diambil.

Menggunakan tag

Parameter Tags dalam permintaan Anda memungkinkan Anda memberi tag pada suatu tugas. Anda dapat menggunakan tag dengan cara berikut:

Mencari tugas berdasarkan tag.
Menggunakan tag sebagai variabel dalam templat TargetURI.