Topik ini menjelaskan cara menggunakan JavaScript SDK untuk mengunggah file media dari mesin lokal ke penyimpanan ApsaraVideo VOD.
Persyaratan browser
Browser | Versi |
Chrome | 66+ |
Microsoft Edge | 79+ (Berbasis Chromium) |
Firefox | 57+ |
Safari | 12.1+ |
Browser default Android | 66+ |
Browser default iOS | 12.2+ |
Unduh demo
URL unduhan: Kode sumber demo
Integrasi cepat
Instalasi
npm install aliyun-vod-upload-sdkSDK ini menyediakan tiga artefak build (ESM, CJS, dan UMD) serta mendukung semua bundler modern seperti Vite, webpack, Rollup, dan esbuild.
Impor CDN
<script src="https://g.alicdn.com/apsara-media-box/imp-web-vod-upload/2.1.0/vod-upload.umd.js"></script>
<script>
const { createUploader, UploadError } = window.AliyunVodUpload;
</script>Unggah dalam lima baris kode
import { createUploader } from 'aliyun-vod-upload-sdk';
const uploader = createUploader({
getAuth: () => fetch('/api/vod/auth').then(r => r.json()),
});
const { videoId } = await uploader.upload(file);Persyaratan API Backend
Dalam mode getAuth, SDK tidak memanggil Alibaba Cloud OpenAPI secara langsung. Sebaliknya, SDK mendelegasikan pengambilan kredensial unggahan ke Backend Anda melalui callback getAuth. Backend Anda harus mengimplementasikan API berikut (yang dipetakan ke operasi VOD OpenAPI):
API Backend | Operasi OpenAPI yang sesuai | Bidang respons |
Buat kredensial unggahan video | CreateUploadVideo |
|
Refresh kredensial unggahan video | RefreshUploadVideo |
|
Buat kredensial unggahan gambar | CreateUploadImage |
|
Buat kredensial unggahan aset media pendukung | CreateUploadAttachedMedia |
|
Teruskan JSON yang dikembalikan oleh Backend Anda ke SDK apa adanya. SDK akan melakukan decoding Base64 dan pemetaan bidang secara internal.
Jika server Anda hanya dapat menyediakan kredensial sementara STS, gunakan mode unggahan langsung getSTS: SDK akan menandatangani dan memanggil operasi VOD OpenAPI tersebut secara langsung di browser, sehingga Anda tidak perlu mengimplementasikan API ini.
Fitur dasar
Mengunggah video
import { createUploader } from 'aliyun-vod-upload-sdk';
const uploader = createUploader({
getAuth: async (ctx) => {
switch (ctx.kind) {
case 'create-video':
return fetch('/api/vod/create-auth', {
method: 'POST',
body: JSON.stringify({ fileName: ctx.file.name, ...ctx.meta }),
}).then(r => r.json());
case 'refresh-video':
return fetch(`/api/vod/refresh-auth?videoId=${ctx.videoId}`)
.then(r => r.json());
}
},
});
const result = await uploader.upload(file, {
meta: { title: 'My video', cateId: 1000, tags: 'tutorial,example' },
});
console.log('Upload succeeded, videoId:', result.videoId);Callback getAuth menerima satu parameter ctx, dan SDK secara otomatis menentukan ctx.kind berdasarkan skenario:
create-video— unggahan pertama. Backend Anda harus memanggil CreateUploadVideo.refresh-video— penyegaran kredensial selama unggahan yang dapat dilanjutkan atau setelah kedaluwarsanya kredensial. Backend Anda harus memanggil RefreshUploadVideo.create-image— unggahan gambar. Backend Anda harus memanggil CreateUploadImage.create-attached-media— unggahan aset media pendukung. Backend Anda harus memanggil CreateUploadAttachedMedia.
Mengunggah gambar
Unggahan gambar menggunakan metode upload() yang sama. SDK mendeteksi jenis file secara otomatis dari file.type (jenis image/* akan diproses melalui pipeline gambar):
const uploader = createUploader({
getAuth: async (ctx) => {
if (ctx.kind === 'create-image') {
return fetch('/api/vod/image-auth', {
method: 'POST',
body: JSON.stringify({ imageType: 'default' }),
}).then(r => r.json());
}
},
});
const result = await uploader.upload(imageFile);
console.log('Image upload succeeded, imageId:', result.imageId);Mengunggah aset media pendukung (watermark / subtitle / materi)
Gambar Watermark, file subtitle (srt / ass / vtt), dan materi (zip / gambar / klip video) memerlukan CreateUploadAttachedMedia - Mendapatkan URL unggahan dan kredensial aset media pendukung. Dalam meta, sertakan businessType untuk merutekan unggahan ke pipeline ini. Fitur lainnya berfungsi sama persis seperti pada video dan gambar (progress, pembatalan, retry timeout, dan pelacakan event).
// Subtitle: tanpa businessType, file .srt akan diambil alih oleh pipeline video dan membuat record video dengan jenis yang salah
const r1 = await uploader.upload(srtFile, { meta: { businessType: 'subtitle' } });
// Materi
const r2 = await uploader.upload(materialFile, { meta: { businessType: 'material' } });
// Gambar watermark: melalui pipeline aset media pendukung (outputnya adalah jenis resource yang berbeda dari "pipeline gambar + imageType: 'watermark'")
const r3 = await uploader.upload(logoFile, {
meta: { businessType: 'watermark', mediaExt: 'png' },
});
console.log('mediaId:', r1.mediaId); // Bidang terpadu di ketiga pipeline: video = VideoId, gambar = ImageId, aset media pendukung = MediaIdbusinessType / mediaExt dan bidang terkait dijelaskan di bawah ini:
Bidang | Deskripsi |
| Wajib. Nilai diteruskan ke VOD apa adanya (nilai yang didokumentasikan: |
| Opsional. Jika dihilangkan, mode STS menurunkannya dari ekstensi nama file ( |
| Opsional. Bidang-bidang ini setara dengan bidang |
Terdapat dua perbedaan perilaku:
Tanpa unggahan yang dapat dilanjutkan: ApsaraVideo VOD tidak memiliki versi Refresh untuk API ini (kredensial berlaku selama sekitar 3.000 detik, dan setelah kedaluwarsa Anda hanya dapat memanggil Create lagi untuk mendapatkan
MediaIdbaru). Oleh karena itu, SDK tidak membaca atau menulis checkpoint untuk aset media pendukung. Mengunggah ulang setelah gangguan akan memulai unggahan baru sepenuhnya.Watermark PNG memiliki dua jalur resmi: pipeline gambar (
VodImageMeta.imageType = 'watermark') dan pipeline aset media pendukung (businessType: 'watermark') menghasilkan dua jenis resource yang berbeda. SDK tidak memutuskannya untuk Anda: hanya ketika Anda meneruskanbusinessType, unggahan akan masuk ke pipeline aset media pendukung. Tanpanya, unggahan mengikuti pipeline gambar berdasarkan jenis file.
Dalam mode uploadAuth, getAuth menerima ctx.kind === 'create-attached-media'. Teruskan ctx.meta.businessType ke Backend Anda. Dalam mode STS (getSTS), SDK menandatangani dan memanggil API secara otomatis, sehingga getSTS tidak memerlukan perubahan.
Progress unggahan
const result = await uploader.upload(file, {
onProgress: (percent, loaded, total) => {
// percent: 0..1 (misalnya, 0.5 berarti 50%)
// loaded: byte yang telah diunggah sejauh ini
// total: ukuran file total dalam byte
progressBar.value = percent;
console.log(`${(percent * 100).toFixed(1)}% - ${loaded} / ${total}`);
},
});SDK menjamin bahwa ketika unggahan selesai, nilai percent akhirnya akan menjadi 1.
Membatalkan unggahan
Opsi 1: task.abort() — pendekatan paling sederhana
const task = uploader.upload(file); cancelBtn.onclick = () => task.abort(); try { const result = await task; } catch (e) { if (e.name === 'AbortError') { console.log('The user canceled the upload'); } }Opsi 2: AbortSignal — paling cocok untuk siklus hidup komponen React dan Vue
const ctrl = new AbortController(); cancelBtn.onclick = () => ctrl.abort(); try { const result = await uploader.upload(file, { signal: ctrl.signal }); } catch (e) { if (e.name === 'AbortError') { console.log('Canceled'); } }
Setelah pembatalan, checkpoint tetap dipertahankan, sehingga panggilan upload(file) berikutnya secara otomatis melanjutkan dari checkpoint (hanya untuk video; gambar dan aset media pendukung tidak menggunakan unggahan yang dapat dilanjutkan, sehingga mengunggahnya lagi akan memulai unggahan baru sepenuhnya).
Unggahan yang dapat dilanjutkan
Unggahan yang dapat dilanjutkan diaktifkan secara default dan tidak memerlukan konfigurasi tambahan (hanya untuk unggahan video; unggahan gambar dan aset media pendukung tidak mendukung fitur ini). SDK secara otomatis:
Menyimpan progress bagian yang selesai di
localStorage.Setelah halaman di-refresh, panggil
upload(file)lagi, maka unggahan akan berlanjut secara otomatis dari titik terakhir.Aturan pencocokan: file.name + file.size + file.lastModified yang sama akan mencocokkan checkpoint.
// Unggahan pertama (pengguna menutup halaman saat 40% terunggah)
await uploader.upload(file);
// Pengguna membuka kembali halaman dan mengunggah file yang sama lagi
// SDK secara otomatis melanjutkan dari 40% dan tidak mengunggah data lagi
const result = await uploader.upload(file);Menonaktifkan unggahan yang dapat dilanjutkan:
const uploader = createUploader({
getAuth: myGetAuth,
checkpoint: false, // dinonaktifkan
});Fitur lanjutan
Unggahan batch
SDK menyediakan API upload() untuk file tunggal. Gunakan primitif asinkron JavaScript standar untuk menyusun unggahan batch:
// Unggahan berurutan (pendekatan paling sederhana)
for (const file of files) {
const result = await uploader.upload(file, {
onProgress: p => updateProgress(file.name, p),
});
console.log(`${file.name} completed, videoId: ${result.videoId}`);
}// Unggahan konkuren (bandwidth tinggi + file kecil)
const results = await Promise.all(
files.map(f => uploader.upload(f)),
);// Konkurensi terbatas (disarankan untuk file besar)
import pLimit from 'p-limit';
const limit = pLimit(2); // unggah maksimal 2 file secara bersamaan
const results = await Promise.all(
files.map(f => limit(() => uploader.upload(f, {
onProgress: p => updateItemProgress(f, p),
}))),
);Jeda dan lanjutkan
SDK tidak memiliki API jeda yang eksplisit. Anda dapat menjeda unggahan melalui mekanisme batal + lanjutkan:
// Jeda: batalkan unggahan saat ini
task.abort();
// Lanjutkan: unggah file yang sama lagi; secara otomatis melanjutkan dari checkpoint
const result = await uploader.upload(file);Pembatalan timeout dan pembatalan multi-sumber
// Timeout 60 detik dengan pembatalan otomatis
await uploader.upload(file, {
signal: AbortSignal.timeout(60_000),
});
// Pembatalan multi-sumber: pengguna membatalkan secara manual, atau terjadi timeout 60 detik
const userCtrl = new AbortController();
await uploader.upload(file, {
signal: AbortSignal.any([
userCtrl.signal,
AbortSignal.timeout(60_000),
]),
});AbortSignal.timeout memerlukan Chrome 103+, dan AbortSignal.any memerlukan Chrome 116+. SDK itu sendiri kompatibel hingga Chrome 60. Untuk mendukung browser lama, gunakan kombinasi AbortController+setTimeout.
Integrasi React dan Vue
Contoh React Hook
import { useEffect, useRef, useState } from 'react';
import { createUploader } from 'aliyun-vod-upload-sdk';
function useUploader(getAuth) {
const uploaderRef = useRef(null);
// Buat di dalam effect untuk menghindari pemanggilan createUploader pada setiap render;
// StrictMode menyebabkan effect berjalan, melakukan pembersihan, dan berjalan lagi; instans yang dilepaskan saat pembersihan akan dibuat ulang
useEffect(() => {
const uploader = createUploader({ getAuth });
uploaderRef.current = uploader;
return () => {
uploader.dispose(); // Lepaskan sumber daya saat unmount dan batalkan unggahan yang sedang berlangsung
uploaderRef.current = null;
};
}, []);
return uploaderRef;
}
function UploadButton({ file }) {
const uploaderRef = useUploader(myGetAuth);
const ctrlRef = useRef(null);
const [progress, setProgress] = useState(0);
const handleUpload = () => {
const uploader = uploaderRef.current;
if (!uploader) return;
const ctrl = new AbortController();
ctrlRef.current = ctrl;
uploader.upload(file, {
signal: ctrl.signal,
onProgress: p => setProgress(p),
}).then(result => {
console.log('Succeeded', result.videoId);
}).catch(e => {
if (e.name !== 'AbortError') {
console.error('Failed', e);
}
});
};
return (
<>
<button onClick={handleUpload}>Upload ({(progress * 100).toFixed(0)}%)</button>
<button onClick={() => ctrlRef.current?.abort()}>Cancel</button>
</>
);
}Contoh Vue 3 Composable
import { onUnmounted, ref } from 'vue';
import { createUploader } from 'aliyun-vod-upload-sdk';
export function useUploader(getAuth) {
const uploader = createUploader({ getAuth });
const progress = ref(0);
onUnmounted(() => uploader.dispose());
async function upload(file) {
return uploader.upload(file, {
onProgress: p => { progress.value = p; },
});
}
return { upload, progress };
}Referensi API
createUploader(config)
Membuat instans Uploader.
import { createUploader } from 'aliyun-vod-upload-sdk';
const uploader = createUploader(config);UploaderConfig
Parameter | Tipe | Wajib | Default | Deskripsi |
|
| Sediakan ini atau | — | Callback pengambilan kredensial. Untuk informasi selengkapnya, lihat Callback kredensial getAuth. |
|
| Sediakan ini atau | — | Callback kredensial temporary STS (mode unggahan langsung browser). Untuk informasi selengkapnya, lihat Mode unggahan langsung getSTS. |
|
| Mode | — | Wilayah layanan VOD (misalnya, |
|
| Tidak |
| Kebijakan retry otomatis untuk unggahan bagian OSS yang gagal. |
|
| Tidak | localStorage | Konfigurasi unggahan yang dapat dilanjutkan. |
|
| Tidak |
| Jumlah bagian OSS konkuren. |
|
| Tidak |
| Ukuran bagian OSS dalam byte. |
|
| Tidak |
| Timeout permintaan jaringan dalam milidetik. Ini berlaku untuk unggahan OSS maupun panggilan VOD OpenAPI dalam mode STS. |
|
| Tidak | — | Nama domain OSS kustom. |
|
| Tidak |
| Saat diaktifkan, setiap bagian menghitung dan membawa |
|
| Tidak |
| Interval minimum, dalam milidetik, antara dua refresh kredensial unggahan. Ini hanya berlaku untuk unggahan video (di-refresh melalui |
RetryPolicy
Bidang | Tipe | Default | Deskripsi |
|
|
| Jumlah retry maksimum |
uploader.upload(file, options?)
Mengunggah satu file. Mengembalikan UploadTask, yang merupakan Promise<UploadResult> sekaligus memiliki metode .abort().
const task = uploader.upload(file, options);UploadOptions
Parameter | Tipe | Deskripsi |
|
| Metadata aset media (judul, kategori, tag, dll.). Jika |
|
| Sinyal pembatalan web standar. |
|
| Callback progress. |
|
| Menimpa partSize global. |
|
| Menimpa parallel global. |
VodVideoMeta (metadata video)
Bidang | Tipe | Deskripsi |
|
| Judul video. |
|
| Deskripsi video. |
|
| ID kategori. |
|
| Tag (dipisahkan koma). |
|
| ID kelompok templat transkoding. |
|
| Alamat penyimpanan. |
|
| URL gambar mini. |
|
| ID alur kerja. |
|
| ID aplikasi. |
|
| Data yang ditentukan pengguna. |
|
| Saat Anda mengunggah |
|
| Khusus mode STS: mode transkoding (VOD |
VodImageMeta (metadata gambar)
Bidang | Tipe | Deskripsi |
|
| Judul gambar |
|
| Deskripsi gambar |
|
| Jenis gambar |
|
| Ekstensi file gambar |
|
| Tag |
|
| ID kategori |
|
| Alamat penyimpanan |
VodAttachedMediaMeta (metadata aset media pendukung)
Bidang | Tipe | Deskripsi |
|
| Wajib. |
|
| Ekstensi file. Jika dihilangkan, mode STS menurunkannya dari nama file. Jika keduanya tidak tersedia, parameter tidak dikirim. |
|
| Judul (opsional untuk aset media pendukung; SDK tidak menurunkannya). |
|
| Saat Anda mengunggah |
|
| Deskripsi. |
|
| Tag (dipisahkan koma). |
|
| ID kategori, dipisahkan koma dengan maksimal 5 nilai (ini berbeda dari |
|
| Alamat penyimpanan. |
|
| ID aplikasi. |
|
| Data yang ditentukan pengguna. |
UploadResult (hasil unggahan)
Bidang | Jenis | Deskripsi |
|
| ID video (dikembalikan untuk unggahan video). |
|
| ID gambar (dikembalikan untuk unggahan gambar). |
|
| ID aset media terpadu di ketiga pipeline: video = |
|
| ETag OSS. |
|
| ID permintaan OSS. |
|
| Durasi unggahan dalam milidetik. |
|
| ID task unggahan unik (berguna untuk troubleshooting purna jual). |
UploadTask
upload() mengembalikan objek yang merupakan Promise<UploadResult> sekaligus objek dengan metode .abort().
type UploadTask = Promise<UploadResult> & {
abort(): void;
};Setelah dirantai (chaining), metode .abort() akan hilang. task.then(fn) mengembalikan Promise biasa. Agar pembatalan tetap tersedia setelah perantaian, gunakan options.signal.
uploader.dispose()
Melepaskan resource: membatalkan semua unggahan yang sedang berlangsung dan membersihkan status internal.
uploader.dispose();Setelah panggilan ini, instans uploader tidak dapat lagi digunakan. Selalu panggil metode ini saat komponen React atau Vue di-unmount untuk menghindari kebocoran memori.
Callback kredensial getAuth
type GetAuth = (ctx: AuthContext) => Promise<AuthResult>;AuthContext
Tergantung pada skenario unggahan, SDK meneruskan ctx yang berbeda:
ctx.kind | Skenario pemicu | Bidang ctx tambahan |
| Unggahan video pertama |
|
| Refresh kredensial selama unggahan yang dapat dilanjutkan |
|
| Unggahan gambar |
|
| Aset media pendukung (watermark / subtitle / materi) |
|
AuthResult
JSON OpenAPI mentah yang dikembalikan oleh Backend Anda. SDK mendekodenya secara internal:
Bidang | Tipe | Wajib | Deskripsi |
|
| Ya | Kredensial STS yang dienkode Base64. |
|
| Ya | URL unggahan OSS yang dienkode Base64. |
|
| Wajib untuk create-video | ID video. |
|
| Wajib untuk create-image | ID gambar. |
|
| Wajib untuk create-attached-media | ID aset media pendukung. |
|
| Tidak | URL gambar (diteruskan). |
Implementasi minimal getAuth:
// Satu rute backend. Perhatikan bahwa ctx.file adalah File / Blob dan JSON.stringify mengubahnya menjadi {},
// jadi ekstrak informasi file yang diperlukan backend (seperti fileName) secara terpisah
createUploader({
getAuth: ({ file, ...rest }) => fetch('/api/vod/auth', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ ...rest, fileName: file.name, fileSize: file.size }),
}).then(r => r.json()),
});Fallback otomatis saat refresh-video gagal: ketika penyegaran kredensial unggahan yang dapat dilanjutkan gagal, SDK secara otomatis kembali ke create-video dan mengunggah ulang. Proses ini sepenuhnya transparan bagi pemanggil.
Mode unggah langsung getSTS
Mode getAuth mengharuskan server Anda memanggil VOD OpenAPI untuk mendapatkan UploadAuth/UploadAddress. Jika server Anda hanya menyediakan kredensial sementara STS, Anda dapat menggunakan mode getSTS: SDK menggunakan kredensial tersebut untuk menandatangani panggilan VOD OpenAPI di browser, mendapatkan kredensial unggahan, lalu mengunggah file.
type GetSTS = () => Promise<STSCredential>;
interface STSCredential {
accessKeyId: string;
accessKeySecret: string;
securityToken: string;
}createUploader({
region: 'cn-shanghai', // mode getSTS: wajib; menentukan endpoint vod.<region>.aliyuncs.com
getSTS: async () => {
const { AccessKeyId, AccessKeySecret, SecurityToken } = await fetch('/api/sts').then(r => r.json());
return { accessKeyId: AccessKeyId, accessKeySecret: AccessKeySecret, securityToken: SecurityToken };
},
});Poin penting:
Harus berjalan di HTTPS atau localhost: signature V3 dalam mode STS bergantung pada Web Crypto API
crypto.subtledan tidak tersedia di halaman HTTP biasa. ModegetAuthtidak tunduk pada pembatasan ini.Saling eksklusif dengan
getAuth: Anda hanya dapat meneruskan salah satunya.Tidak mengambil argumen dan tidak membawa
expiration: SDK tidak secara proaktif memeriksa apakah kredensial STS telah kedaluwarsa. Ketika VOD mengembalikanInvalidSecurityToken.Expired, SDK secara otomatis memanggilgetSTS()sekali lagi dan mencoba ulang sekali.Tanpa caching dan tanpa deduplikasi permintaan konkuren: beberapa panggilan
upload()konkuren masing-masing memanggilgetSTS(). Implementasikan caching sendiri jika Anda memerlukannya.Title/FileNamediturunkan oleh SDK dari file:FileName=file.name(unggahanBlobmenggunakanmeta.fileName),Title=meta.title ?? FileName; nilai turunan dipotong hingga 128 karakter, sedangkanmeta.titleyang disediakan secara eksplisit tidak dipotong.FileSizediisi oleh SDK: setiap panggilanCreateUploadVideotanpa syarat menyertakanFileSize=file.size(di v1 Anda harus meneruskannya sendiri diuserData; jika dilewatkan, VOD tidak memiliki informasi ukuran file).Ketika panggilan VOD gagal, kode kesalahan adalah
UPLOAD.VOD.CREATE_FAILED/UPLOAD.VOD.REFRESH_FAILED. Bidangsuggestionberisi tautan troubleshooting VOD.MessageVOD asli tidak pernah mencapaiUploadError(karena mungkin berisi kredensial teks biasa); pesan ini dilaporkan ke pelacakan event hanya setelah disunting.Timeout dan retry menggunakan kembali pengaturan
timeout/retry.count. Baik 4xx maupun 5xx tidak dicoba ulang (satu-satunya pengecualian adalah kode kedaluwarsa yang disebutkan di atas).
Penanganan kesalahan
Struktur UploadError
Semua kesalahan unggahan adalah instans UploadError (mewarisi dari Error):
import { UploadError } from 'aliyun-vod-upload-sdk';
class UploadError extends Error {
readonly code: string; // Kode kesalahan terstruktur, seperti 'UPLOAD.OSS.ACCESS_DENIED'
readonly message: string; // Deskripsi kesalahan
readonly suggestion: string; // Saran perbaikan (dalam bahasa Mandarin)
readonly cause?: unknown; // Kesalahan asli yang mendasari
readonly uploadTaskId?: string; // ID task unggahan (berguna untuk troubleshooting purna jual)
}Pembatalan yang dilakukan pengguna bukanlah UploadError, melainkan DOMException standar (name === 'AbortError').
Kode kesalahan
Format kode kesalahan: UPLOAD.{level}.{type}
Kode kesalahan | Arti | Saran perbaikan |
| Callback | Periksa apakah callback getAuth mengembalikan JSON dengan benar yang berisi UploadAuth dan UploadAddress. Pastikan layanan backend tersedia dan format respons benar. |
| Callback | Dalam mode STS, callback getSTS gagal mendapatkan kredensial temporary. Periksa apakah implementasi getSTS Anda dapat memanggil layanan STS Anda dengan sukses (konektivitas jaringan, autentikasi, dan konfigurasi CORS), serta apakah accessKeyId, accessKeySecret, dan securityToken yang dikembalikan lengkap. |
| Dalam mode STS, panggilan | Dalam mode STS, SDK gagal memanggil API VOD untuk membuat kredensial unggahan. Periksa apakah wilayah yang diteruskan ke createUploader cocok dengan wilayah akun Anda, apakah kredensial temporary yang dikembalikan oleh getSTS memiliki izin VOD (CreateUploadVideo, CreateUploadImage, dan CreateUploadAttachedMedia), dan apakah parameter aset media di meta valid. |
| Dalam mode STS, panggilan | Dalam mode STS, SDK gagal memanggil API VOD untuk memperbarui kredensial unggahan. Periksa apakah kredensial temporary yang dikembalikan oleh getSTS valid dan memiliki izin RefreshUploadVideo, serta apakah aset media untuk videoId masih ada. |
| Konfigurasi tidak valid: (1) | Konfigurasi tidak valid. Pastikan Anda hanya meneruskan salah satu dari getAuth dan getSTS ke createUploader. Dalam mode STS (saat Anda meneruskan getSTS), Anda harus menyediakan region yang tidak kosong dan cocok dengan wilayah akun Anda (misalnya, cn-shanghai). Saat mengunggah aset media pendukung, meta.businessType harus berupa string yang tidak kosong (seperti watermark, subtitle, atau material). |
| Kesalahan izin OSS (403) | Akses OSS ditolak. Periksa apakah kredensial unggahan (STS Token) valid dan belum kedaluwarsa, serta apakah kebijakan RAM memberikan izin tulis OSS. |
| Bucket tidak ada | Bucket OSS tidak ada. Periksa apakah nama bucket di URL unggahan benar, dan konfirmasi bahwa bucket telah dibuat di wilayah yang sesuai. |
| Sesi unggahan multi-bagian telah kedaluwarsa | Sesi unggahan multi-bagian telah kedaluwarsa (mungkin lebih dari 24 jam). SDK secara otomatis mengunggah ulang, sehingga tidak diperlukan tindakan manual. |
| Kesalahan OSS tidak dikenal | Terjadi kesalahan yang tidak dikenal selama unggahan OSS. Periksa konsol browser untuk pesan kesalahan terperinci. |
| Permintaan habis waktu | Permintaan jaringan habis waktu. Buka panel Network di alat developer browser Anda untuk memeriksa permintaan yang gagal, pastikan koneksi jaringan stabil, atau coba tingkatkan nilai timeout. |
| Kesalahan koneksi jaringan | Terjadi kesalahan koneksi jaringan. Buka panel Network di alat developer browser Anda untuk memeriksa kode status dan respons dari permintaan yang gagal, konfirmasi bahwa browser dapat mencapai alamat layanan OSS, dan periksa apakah proxy atau firewall memblokir permintaan. |
| Browser offline | Browser mendeteksi bahwa saat ini sedang offline. Buka panel Network di alat developer browser Anda untuk mengonfirmasi status jaringan, lalu sambungkan kembali ke jaringan dan coba unggah ulang. |
| Ukuran file adalah 0 | Ukuran file adalah 0, sehingga file kosong tidak dapat diunggah. Pastikan file dipilih dengan benar. |
| Instans Uploader telah dihancurkan | Instans Uploader telah dihancurkan dan tidak dapat lagi digunakan. Panggil createUploader lagi untuk membuat instans baru. |
Menggunakan konstanta kode kesalahan
Gunakan konstanta ErrorCode alih-alih literal string:
import { ErrorCode, UploadError } from 'aliyun-vod-upload-sdk';
try {
await uploader.upload(file);
} catch (e) {
if (e instanceof UploadError) {
switch (e.code) {
case ErrorCode.AUTH_GET_AUTH_FAILED:
showToast('Failed to obtain the credential. Refresh the page and try again');
break;
case ErrorCode.NETWORK_TIMEOUT:
case ErrorCode.NETWORK_ERROR:
showToast('Network error. Check your connection and try again');
break;
case ErrorCode.OSS_ACCESS_DENIED:
showToast('Insufficient upload permissions. Contact your administrator');
break;
default:
showToast(`Upload failed: ${e.suggestion || e.message}`);
}
}
}Troubleshooting
Setiap UploadError membawa uploadTaskId, yang merupakan ID korelasi global dari seluruh unggahan. Berikan ID ini kepada dukungan purna jual Alibaba Cloud untuk menemukan masalah dengan cepat:
catch (e) {
if (e instanceof UploadError) {
// Kirim ini ke tim dukungan teknis Anda
const diagnostic = {
code: e.code,
message: e.message,
uploadTaskId: e.uploadTaskId,
suggestion: e.suggestion,
};
reportToSupport(diagnostic);
}
}UploadResult.uploadTaskId juga dapat digunakan untuk mengkorelasikan log setelah unggahan berhasil:
const result = await uploader.upload(file);
myLogger.info('Upload succeeded', { videoId: result.videoId, uploadTaskId: result.uploadTaskId });