ApsaraVideo VOD:Callback HTTP

Cara kerja

1. Deploy layanan HTTP untuk menerima pesan callback dan konfigurasikan URL callback di ApsaraVideo VOD.

2. Ketika suatu event terjadi, server ApsaraVideo VOD mengirim permintaan HTTP POST ke URL tersebut dengan konten notifikasi event dalam badan permintaan.

3. Layanan HTTP Anda mengotentikasi signature dari permintaan HTTP POST yang masuk. Jika otentikasi berhasil, layanan Anda harus memberikan respons dengan kode status 200 untuk menandakan callback berhasil. Kode status lain atau timeout respons akan mengakibatkan kegagalan callback. Untuk informasi lebih lanjut tentang cara kerja otentikasi, lihat Cara kerja otentikasi callback.

4. Setelah callback berhasil, URL callback yang Anda konfigurasi menerima notifikasi event yang sesuai. Jika callback gagal, ApsaraVideo VOD mencoba kembali permintaan tersebut dua kali lagi, sehingga total tiga kali percobaan. Jika ketiga percobaan tersebut gagal, ApsaraVideo VOD membuang notifikasi event tersebut. Untuk detail tentang logika penentuan dan retry callback, lihat Penentuan dan retry callback.

Cara menggunakan callback HTTP

Prasyarat

• Anda telah mendeploy layanan HTTP atau HTTPS untuk menerima pesan callback.

• Akun Alibaba Cloud telah dibuat dan verifikasi identitas telah selesai. Untuk membuat Akun Alibaba Cloud, kunjungi website resmi Alibaba Cloud. Untuk informasi lebih lanjut, lihat Buat Akun Alibaba Cloud.

• ApsaraVideo VOD telah diaktifkan. Untuk informasi lebih lanjut, lihat Aktifkan ApsaraVideo VOD.

Penggunaan

• ApsaraVideo VOD tersedia di beberapa Wilayah layanan. Pengaturan notifikasi event dikonfigurasi secara independen untuk setiap Wilayah. Anda dapat mengonfigurasi metode callback dan URL callback yang berbeda untuk setiap Wilayah layanan.

• Anda dapat mengonfigurasi beberapa URL callback untuk memenuhi kebutuhan pengembangan di berbagai lingkungan. Untuk informasi lebih lanjut, lihat Atur beberapa URL callback.

Prosedur

1. Konfigurasikan notifikasi event untuk callback HTTP di ApsaraVideo VOD.

   Catatan

   Pengaturan callback yang dikonfigurasi di Konsol ApsaraVideo VOD berlaku secara global. Anda juga dapat menggunakan API untuk mengonfigurasi callback global atau menerapkan override untuk satu permintaan.

   Konsol

   1. Masuk ke Konsol ApsaraVideo VOD.

   2. Pada panel navigasi kiri, pilih Configuration Management > Media Processing > Callback.

   3. Pada bilah navigasi atas, pilih Wilayah layanan dari daftar drop-down di samping Workbench.

   4. Konfigurasikan Callback Settings. Pada bagian Callback Authentication, Anda dapat mengaktifkan otentikasi dan menetapkan authentication key.

      1. Di samping Callback Settings, klik Modify.

      2. Konfigurasikan parameter callback.

         Parameter	Deskripsi
         Callback method	Pilih HTTP Request.
         Callback URL	Masukkan URL untuk menerima pesan callback. Ketika event callback terjadi, server ApsaraVideo VOD mengirim permintaan HTTP POST ke URL ini. Panjang URL maksimal 256 byte. Anda hanya dapat menentukan satu URL.
         Events	Pilih jenis event yang ingin Anda terima notifikasinya. Untuk informasi lebih lanjut tentang jenis event yang didukung dan maknanya, lihat Daftar event. Catatan Jika Anda memilih AI Processing Completed, notifikasi akan dikirim untuk semua event AI, termasuk AIMediaAuditComplete, AIMediaDNAComplete, dan AIVideoTagComplete, ketika salah satunya selesai.

      3. Klik OK untuk menyimpan pengaturan callback.

   5. Opsional: Konfigurasikan Callback Authentication.

      Ketika metode callback adalah HTTP Request, Anda dapat menambahkan parameter otentikasi ke header HTTP atau HTTPS. Hal ini memungkinkan receiver callback Anda memverifikasi signature permintaan dan mencegah permintaan yang tidak sah atau tidak valid.

      1. Nyalakan sakelar otentikasi callback, atau klik Modify di samping Callback Authentication.

      2. Tetapkan authentication key.

         Kunci ini sesuai dengan bidang AuthKey dalam algoritma signature. Untuk informasi lebih lanjut, lihat algoritma signature. Kunci ini ditentukan oleh pengguna, panjangnya maksimal 32 karakter, dan harus mengandung huruf kapital, huruf kecil, serta angka.

      3. Klik OK untuk menyimpan konfigurasi.

      4. Setelah mengaktifkan otentikasi callback, Anda harus menerapkan logika otentikasi yang sesuai pada layanan HTTP atau HTTPS Anda yang menerima callback. Untuk informasi lebih lanjut, lihat Cara kerja otentikasi callback.

   API

   Anda dapat memanggil operasi API yang berbeda untuk mengonfigurasi callback global atau menggunakan override untuk satu permintaan.

   • Konfigurasi global: Panggil operasi SetMessageCallback. Tetapkan parameter CallbackType ke HTTP dan konfigurasikan parameter lain seperti CallbackURL dan EventTypeList.

   • Override untuk satu permintaan: Saat Anda memanggil API untuk mengunggah aset media atau memulai pekerjaan pemrosesan media, Anda dapat menetapkan alamat callback untuk permintaan tertentu tersebut dengan menentukan bidang MessageCallback dalam parameter UserData. Ini berlaku untuk operasi API berikut:

     • CreateUploadVideo

     • CreateUploadImage

     • CreateUploadAttachedMedia

     • UploadMediaByURL

     • RegisterMedia

     • SubmitTranscodeJobs

     • SubmitSnapshotJob

     • SubmitAIMediaAuditJob

     • ProduceEditingProjectVideo

   Catatan

   Untuk menggunakan parameter MessageCallback dalam bidang UserData untuk override satu permintaan, Anda harus terlebih dahulu mengaktifkan notifikasi event global di ApsaraVideo VOD dan mengonfigurasi jenis event yang sesuai. Jika tidak, pengaturan override tidak akan berlaku.

2. Picu event callback.

   Setelah mengonfigurasi notifikasi event, lakukan aksi di ApsaraVideo VOD untuk memicu event. Misalnya, Anda dapat mengunggah file media (audio, video, atau gambar) atau memulai pekerjaan pemrosesan media seperti transkoding atau pembuatan snapshot.

3. Terima event callback.

   Setelah event callback terjadi, Anda dapat melihat notifikasi event di receiver callback Anda jika callback berhasil.

Cara kerja otentikasi callback

Ketika metode callback adalah HTTP Request, Anda dapat menambahkan parameter otentikasi ke header HTTP atau HTTPS. Hal ini memungkinkan receiver callback Anda memverifikasi signature permintaan dan mencegah permintaan yang tidak sah atau tidak valid.

Penggunaan

• Anda dapat memilih apakah akan mengaktifkan otentikasi callback HTTP (disarankan). Jika Anda menetapkan AuthKey (authentication key), semua permintaan callback akan menyertakan header otentikasi yang diperlukan agar receiver callback Anda dapat melakukan verifikasi. Menetapkan AuthKey tidak memengaruhi fungsionalitas yang sudah ada; Anda yang menentukan apakah akan menerapkan validasi di receiver Anda.

• Jika Anda tidak menetapkan AuthKey, fitur callback HTTP tetap berfungsi seperti biasa.

Parameter otentikasi

Algoritma signature

MD5Content = callback URL|X-VOD-TIMESTAMP|AuthKey
X-VOD-SIGNATURE = md5sum(MD5Content)

X-VOD-SIGNATURE = md5sum(https://www.example.com/your/callback|1519375990|Test123) = c72b60894140fa98920f1279219b****

Aturan validasi receiver

• Receiver callback Anda merekonstruksi string dengan menggabungkan URL callback yang Anda konfigurasi, nilai X-VOD-TIMESTAMP yang diterima, dan AuthKey yang Anda simpan. Kemudian, receiver menghitung hash MD5 dari string tersebut dan membandingkannya dengan nilai header X-VOD-SIGNATURE. Jika nilainya tidak cocok, permintaan tersebut tidak valid.

• Untuk mencegah serangan replay, receiver callback Anda dapat membandingkan waktu saat ini dengan waktu dalam header X-VOD-TIMESTAMP. Jika selisihnya melebihi ambang batas tertentu (misalnya, 5 menit), Anda dapat menganggap permintaan tersebut tidak valid.

  Catatan

  Karena kemungkinan adanya clock skew antar server, pemeriksaan berbasis waktu ini bisa tidak andal. Anda dapat memutuskan apakah akan menerapkan pemeriksaan ini.

Rotasi kunci

Ketika Anda melakukan rotasi AuthKey, receiver callback Anda harus sementara mendukung kedua kunci (lama dan baru) untuk memastikan transisi yang mulus dan mencegah kegagalan callback. Receiver Anda harus menangani logika validasi dua kunci ini.

Dokumen terkait

• Untuk perbandingan antara callback HTTP dan callback MNS, lihat Perbandingan antara callback HTTP dan MNS.

• Jika Anda mengalami masalah, lihat FAQ tentang notifikasi event.