All Products
Search
Document Center

ApsaraVideo VOD:Mengunggah file menggunakan JavaScript SDK

Last Updated:Oct 28, 2026

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

Integrasi cepat

Instalasi

npm install aliyun-vod-upload-sdk

SDK 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

{ UploadAuth, UploadAddress, VideoId }

Refresh kredensial unggahan video

RefreshUploadVideo

{ UploadAuth, UploadAddress, VideoId }

Buat kredensial unggahan gambar

CreateUploadImage

{ UploadAuth, UploadAddress, ImageId }

Buat kredensial unggahan aset media pendukung

CreateUploadAttachedMedia

{ UploadAuth, UploadAddress, MediaId }

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 = MediaId

businessType / mediaExt dan bidang terkait dijelaskan di bawah ini:

Bidang

Deskripsi

businessType

Wajib. Nilai diteruskan ke VOD apa adanya (nilai yang didokumentasikan: watermark / subtitle / material). SDK tidak memvalidasi enumerasi, sehingga Anda tidak perlu melakukan upgrade SDK saat VOD menambahkan jenis bisnis baru

mediaExt

Opsional. Jika dihilangkan, mode STS menurunkannya dari ekstensi nama file (sub.srt → srt). Anda hanya perlu meneruskannya secara eksplisit jika nama file tidak memiliki ekstensi, atau saat Anda mengunggah Blob.

title / fileName / description / tags / cateIds / storageLocation / appId / userData

Opsional. Bidang-bidang ini setara dengan bidang meta video. Perhatikan bahwa cateIds adalah string yang dipisahkan koma (hingga 5 nilai), yang berbeda dari cateId: number pada video.

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 MediaId baru). 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 meneruskan businessType, 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:

  1. Menyimpan progress bagian yang selesai di localStorage.

  2. Setelah halaman di-refresh, panggil upload(file) lagi, maka unggahan akan berlanjut secara otomatis dari titik terakhir.

  3. 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),
  ]),
});
Catatan

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

getAuth

GetAuth

Sediakan ini atau getSTS.

—

Callback pengambilan kredensial. Untuk informasi selengkapnya, lihat Callback kredensial getAuth.

getSTS

GetSTS

Sediakan ini atau getAuth.

—

Callback kredensial temporary STS (mode unggahan langsung browser). Untuk informasi selengkapnya, lihat Mode unggahan langsung getSTS.

region

string

Mode getSTS: wajib

—

Wilayah layanan VOD (misalnya, cn-shanghai), yang menentukan endpoint vod.<region>.aliyuncs.com.

retry

RetryPolicy

Tidak

{count: 3}

Kebijakan retry otomatis untuk unggahan bagian OSS yang gagal.

checkpoint

false | { store?: CheckpointStore }

Tidak

localStorage

Konfigurasi unggahan yang dapat dilanjutkan. false menonaktifkannya; { store } menyuntikkan penyimpanan kustom.

parallel

number

Tidak

4

Jumlah bagian OSS konkuren.

partSize

number

Tidak

1048576 (1MB)

Ukuran bagian OSS dalam byte.

timeout

number

Tidak

60000

Timeout permintaan jaringan dalam milidetik. Ini berlaku untuk unggahan OSS maupun panggilan VOD OpenAPI dalam mode STS.

cname

string

Tidak

—

Nama domain OSS kustom.

enableMD5

boolean

Tidak

false

Saat diaktifkan, setiap bagian menghitung dan membawa Content-MD5, dan OSS memverifikasi integritas data (setara dengan multipartUpload ali-oss dengan disabledMD5: false). Ini menambah overhead CPU.

refreshSTSTokenInterval

number

Tidak

300000 (5mnt)

Interval minimum, dalam milidetik, antara dua refresh kredensial unggahan. Ini hanya berlaku untuk unggahan video (di-refresh melalui refresh-video) dan diteruskan ke refreshSTSTokenInterval ali-oss. Refresh digerakkan oleh permintaan: SDK hanya memeriksa sebelum mengeluarkan permintaan OSS, sehingga tidak ada permintaan berarti tidak ada refresh, dan permintaan unggahan yang lambat memperpanjang interval refresh aktual. Perhatikan bahwa ini mengatur kredensial unggahan OSS, bukan kredensial STS pengguna. 0, angka negatif, atau NaN dinormalisasi kembali ke nilai default.

RetryPolicy

Bidang

Tipe

Default

Deskripsi

count

number

3

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

meta

VodVideoMeta | VodImageMeta | VodAttachedMediaMeta

Metadata aset media (judul, kategori, tag, dll.). Jika businessType ada, unggahan akan melalui pipeline aset media pendukung.

signal

AbortSignal

Sinyal pembatalan web standar.

onProgress

(percent, loaded, total) => void

Callback progress. percent berkisar dari 0 hingga 1.

partSize

number

Menimpa partSize global.

parallel

number

Menimpa parallel global.

VodVideoMeta (metadata video)

Bidang

Tipe

Deskripsi

title

string

Judul video.

description

string

Deskripsi video.

cateId

number

ID kategori.

tags

string

Tag (dipisahkan koma).

templateGroupId

string

ID kelompok templat transkoding.

storageLocation

string

Alamat penyimpanan.

coverUrl

string

URL gambar mini.

workflowId

string

ID alur kerja.

appId

string

ID aplikasi.

userData

Record<string, unknown>

Data yang ditentukan pengguna.

fileName

string

Saat Anda mengunggah Blob (yang tidak memiliki name) dalam mode STS, ini menyediakan nilai FileName.

transCodeMode

string

Khusus mode STS: mode transkoding (VOD TransCodeMode). Jika dihilangkan, parameter tidak dikirim.

VodImageMeta (metadata gambar)

Bidang

Tipe

Deskripsi

title

string

Judul gambar

description

string

Deskripsi gambar

imageType

'default' | 'cover' | 'watermark'

Jenis gambar

imageExt

string

Ekstensi file gambar

tags

string

Tag

cateId

number

ID kategori

storageLocation

string

Alamat penyimpanan

VodAttachedMediaMeta (metadata aset media pendukung)

Bidang

Tipe

Deskripsi

businessType

string

Wajib. watermark/subtitle/material, dan sebagainya. Nilai diteruskan tanpa validasi. Keberadaan bidang ini merutekan unggahan ke pipeline aset media pendukung.

mediaExt

string

Ekstensi file. Jika dihilangkan, mode STS menurunkannya dari nama file. Jika keduanya tidak tersedia, parameter tidak dikirim.

title

string

Judul (opsional untuk aset media pendukung; SDK tidak menurunkannya).

fileName

string

Saat Anda mengunggah Blob (yang tidak memiliki name) dalam mode STS, ini menyediakan nilai FileName.

description

string

Deskripsi.

tags

string

Tag (dipisahkan koma).

cateIds

string

ID kategori, dipisahkan koma dengan maksimal 5 nilai (ini berbeda dari cateId: number pada video).

storageLocation

string

Alamat penyimpanan.

appId

string

ID aplikasi.

userData

Record<string, unknown>

Data yang ditentukan pengguna.

UploadResult (hasil unggahan)

Bidang

Jenis

Deskripsi

videoId

string?

ID video (dikembalikan untuk unggahan video).

imageId

string?

ID gambar (dikembalikan untuk unggahan gambar).

mediaId

string?

ID aset media terpadu di ketiga pipeline: video = VideoId, gambar = ImageId, aset media pendukung = MediaId.

etag

string

ETag OSS.

requestId

string

ID permintaan OSS.

durationMs

number

Durasi unggahan dalam milidetik.

uploadTaskId

string

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;
};
Penting

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

'create-video'

Unggahan video pertama

file, meta?.

'refresh-video'

Refresh kredensial selama unggahan yang dapat dilanjutkan

file, videoId.

'create-image'

Unggahan gambar

file, meta?.

'create-attached-media'

Aset media pendukung (watermark / subtitle / materi)

file, meta? (termasuk businessType).

AuthResult

JSON OpenAPI mentah yang dikembalikan oleh Backend Anda. SDK mendekodenya secara internal:

Bidang

Tipe

Wajib

Deskripsi

UploadAuth

string

Ya

Kredensial STS yang dienkode Base64.

UploadAddress

string

Ya

URL unggahan OSS yang dienkode Base64.

VideoId

string

Wajib untuk create-video

ID video.

ImageId

string

Wajib untuk create-image

ID gambar.

MediaId

string

Wajib untuk create-attached-media

ID aset media pendukung.

ImageURL

string

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.subtle dan tidak tersedia di halaman HTTP biasa. Mode getAuth tidak 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 mengembalikan InvalidSecurityToken.Expired, SDK secara otomatis memanggil getSTS() sekali lagi dan mencoba ulang sekali.

  • Tanpa caching dan tanpa deduplikasi permintaan konkuren: beberapa panggilan upload() konkuren masing-masing memanggil getSTS(). Implementasikan caching sendiri jika Anda memerlukannya.

  • Title / FileName diturunkan oleh SDK dari file: FileName=file.name (unggahan Blob menggunakan meta.fileName), Title=meta.title ?? FileName; nilai turunan dipotong hingga 128 karakter, sedangkan meta.title yang disediakan secara eksplisit tidak dipotong.

  • FileSize diisi oleh SDK: setiap panggilan CreateUploadVideo tanpa syarat menyertakan FileSize=file.size (di v1 Anda harus meneruskannya sendiri di userData; jika dilewatkan, VOD tidak memiliki informasi ukuran file).

  • Ketika panggilan VOD gagal, kode kesalahan adalah UPLOAD.VOD.CREATE_FAILED/UPLOAD.VOD.REFRESH_FAILED. Bidang suggestion berisi tautan troubleshooting VOD. Message VOD asli tidak pernah mencapai UploadError (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

UPLOAD.AUTH.GET_AUTH_FAILED

Callback getAuth melempar kesalahan atau mengembalikan struktur yang salah format

Periksa apakah callback getAuth mengembalikan JSON dengan benar yang berisi UploadAuth dan UploadAddress. Pastikan layanan backend tersedia dan format respons benar.

UPLOAD.AUTH.GET_STS_FAILED

Callback getSTS melempar kesalahan (mode STS)

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.

UPLOAD.VOD.CREATE_FAILED

Dalam mode STS, panggilan CreateUploadVideo/CreateUploadImage/CreateUploadAttachedMedia gagal

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.

UPLOAD.VOD.REFRESH_FAILED

Dalam mode STS, panggilan RefreshUploadVideo gagal

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.

UPLOAD.CONFIG.INVALID

Konfigurasi tidak valid: (1) createUploader tidak menyediakan tepat satu dari getAuth/getSTS, atau mode STS kehilangan region (dilempar secara sinkron saat build); (2) kunci meta.businessType ada tetapi nilainya bukan string yang tidak kosong (pada waktu unggahan ini mengembalikan UploadTask yang ditolak)

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).

UPLOAD.OSS.ACCESS_DENIED

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.

UPLOAD.OSS.NO_SUCH_BUCKET

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.

UPLOAD.OSS.NO_SUCH_UPLOAD

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.

UPLOAD.OSS.UNKNOWN

Kesalahan OSS tidak dikenal

Terjadi kesalahan yang tidak dikenal selama unggahan OSS. Periksa konsol browser untuk pesan kesalahan terperinci.

UPLOAD.NETWORK.TIMEOUT

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.

UPLOAD.NETWORK.ERROR

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.

UPLOAD.NETWORK.OFFLINE

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.

UPLOAD.FILE.EMPTY

Ukuran file adalah 0

Ukuran file adalah 0, sehingga file kosong tidak dapat diunggah. Pastikan file dipilih dengan benar.

UPLOAD.INTERNAL.DISPOSED

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 });