Todos os produtos
Search
Central de documentação

ApsaraVideo VOD:Upload SDK for JavaScript

Última atualização: Jun 27, 2026

Use o SDK de upload para JavaScript para enviar arquivos de mídia ao ApsaraVideo VOD.

Requisitos do navegador

Navegador

Suporte

Versão

IE

✔️

Internet Explorer 10 e posteriores

Microsoft Edge

✔️

Todas

Chrome

✔️

Versões principais dos navegadores

Firefox

✔️

Safari

✔️

Navegador padrão do Android

✔️

Navegador padrão do iOS

✔️

Navegador padrão do Windows Phone

✔️

Descrição dos recursos

O SDK de upload para JavaScript suporta apenas o envio de áudio, vídeo e imagens. Não há suporte para ativos de mídia auxiliares.

Baixe o SDK e a demonstração

Métodos de integração

O SDK de upload para JavaScript depende do OSS SDK. Defina window.OSS com um valor válido. Caso contrário, o erro ReferenceError: OSS is not defined ocorrerá.

(Recomendado) Importação via <script> no código HTML

<!--  es6-promise is required for Internet Explorer. Internet Explorer 10 and later are supported. -->
  <script src="../lib/es6-promise.min.js"></script>
  <script src="../lib/aliyun-oss-sdk-6.17.1.min.js"></script>
  <script src="../aliyun-upload-sdk-1.5.7.min.js"></script>

Importação via módulo

Atribua manualmente o módulo OSS a window.OSS:

Nota

Ignore esta etapa se já tiver incluído os arquivos por meio de tags <script>.

import OSS from '../lib/aliyun-upload-sdk/lib/aliyun-oss-sdk-6.17.1.min'
window.OSS = OSS;
import '../lib/aliyun-upload-sdk/aliyun-upload-sdk-1.5.7.min'

Configurações básicas

Inicializar a instância de upload

  • Especifique o parâmetro userId para identificar quem realiza o upload. Use um ID de conta Alibaba Cloud ou um ID de usuário personalizado da Central de Contas Alibaba Cloud. Se userId for nulo ou não especificado, um erro será gerado.

  • Defina o parâmetro region com um ID de região compatível com o ApsaraVideo VOD. Para mais informações, consulte IDs de região do ApsaraVideo VOD.

var uploader = new AliyunUpload.Vod({
  // Required. The identity of the uploader. The value can be an Alibaba Cloud account ID or a custom user ID. You can view the ID in Alibaba Cloud Account Center (https://account-console.alibabacloud.com/).
  userId: "122",
  // The regions where you want to upload the files. Default value: cn-shanghai. 
  // Examples: eu-central-1 and ap-southeast-1.
  region: "",
  // The size of each part in a multipart upload. Unit: bytes. The size cannot be smaller than 100 KB (100 × 1024). Default size: 1 MB (1 × 1024 × 1024).
  partSize: 1048576,
  // The maximum number of parts that can be uploaded in parallel. Default value: 5.
  parallel: 5,
  // The maximum number of times the system retries the upload when a network error occurs. Default value: 3.
  retryCount: 3,
  // The interval at which the system retries the upload when a network error occurs. Default value: 2. Unit: seconds.
  retryDuration: 2,
  // The upload is started.
  onUploadstarted: function (uploadInfo) {},
  // The upload is successful.
  onUploadSucceed: function (uploadInfo) {},
  // The upload fails.
  onUploadFailed: function (uploadInfo, code, message) {},
  // The upload progress. Unit: bytes.
  onUploadProgress: function (uploadInfo, totalSize, loadedPercent) {},
  // The upload credential or STS token expires.
  onUploadTokenExpired: function (uploadInfo) {},
  // All files are uploaded.
  onUploadEnd: function (uploadInfo) {},
});

Configure a credencial

Antes de prosseguir, entenda o processo de upload via cliente e implante um serviço de autorização. Para mais detalhes, consulte Upload a partir de clientes.

  1. Se usar o Método 1: URL e credencial de upload, obtenha as URLs e credenciais de upload no serviço de autorização.

  2. Se optar pelo Método 2: Token STS, obtenha um token STS no serviço de autorização. Consulte Obter um token STS para mais informações.

Configure as informações de autorização retornadas no callback onUploadstarted. Quando a credencial expira, o callback onUploadTokenExpired é acionado. Obtenha uma nova credencial chamando a operação de atualização.

Método 1: URL e credencial de upload

Chame setUploadAuthAndAddress para configurar a URL e a credencial de upload. Se a credencial expirar, o callback onUploadTokenExpired será disparado. Chame resumeUploadWithAuth informando a nova credencial para retomar o upload.

// The upload is started.
onUploadstarted: function (uploadInfo) {
  let refreshUrl = 'https://demo-vod.cn-shanghai.aliyuncs.com/voddemo/RefreshUploadVideo?BusinessType=vodai&TerminalType=pc&DeviceModel=iPhone9,2&UUID=59ECA-4193-4695-94DD-7E1247288&AppVersion=1.0.0&Title=haha1&FileName=xxx.mp4&VideoId=' + uploadInfo.videoId
  axios.get(refreshUrl).then(({data}) => {
    let uploadAuth = data.UploadAuth
    let uploadAddress = data.UploadAddress
    let videoId = data.VideoId
    uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress,videoId)
  })
},
// The upload credential expires.
onUploadTokenExpired: function (uploadInfo) {
  // If the upload of a large file times out when you use Method 1 (UploadAuth),
  // call the RefreshUploadVideo operation based on uploadInfo.videoId and re-obtain the value of UploadAuth.
  // Then, call the resumeUploadWithAuth method. In this example, the value of UploadAuth is directly obtained because resumeUploadWithAuth is a test method.
  let refreshUrl = 'https://demo-vod.cn-shanghai.aliyuncs.com/voddemo/RefreshUploadVideo?BusinessType=vodai&TerminalType=pc&DeviceModel=iPhone9,2&UUID=59ECA-4193-4695-94DD-7E1247288&AppVersion=1.0.0&Title=haha1&FileName=xxx.mp4&VideoId=' + uploadInfo.videoId
  axios.get(refreshUrl).then(({data}) => {
    let uploadAuth = data.UploadAuth
    uploader.resumeUploadWithAuth(uploadAuth)
    console.log('upload expired and resume upload with uploadauth ' + uploadAuth)
  })
  self.statusText = 'The upload times out...'
},

Descrição dos métodos

uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress, videoId)
uploader.resumeUploadWithAuth(uploadAuth)

Parâmetro

Descrição

uploadInfo

Primeiro parâmetro do callback onUploadstarted.

uploadAuth

Credencial de upload retornada pela operação CreateUploadVideo.

uploadAddress

URL de upload retornada pela operação CreateUploadVideo.

videoId

ID de áudio ou vídeo retornado pela operação CreateUploadVideo.

Método 2: Token STS

Use setSTSToken para definir o token STS. Caso o token expire, o sistema dispara o callback onUploadTokenExpired. Para continuar o envio, chame resumeUploadWithSTSToken passando o novo token.

 /*Callback method - The upload is started.*/
 onUploadstarted: function (uploadInfo) {
    let stsUrl = "***.***.stsUrl" /*Use the setSTSToken method to obtain the STS token.*/
    axios.get(stsUrl).then(({data}) => {
          var info = data.SecurityTokenInfo
          uploader.setSTSToken(uploadInfo, info.AccessKeyId, info.AccessKeySecret, info.SecretToken);
     })
 },
/*Callback method - The credential times out.*/
 onUploadTokenExpired: function (uploadInfo) { 
     let stsUrl = "***.***.stsUrl"  /*Use the resumeUploadWithSTSToken method to refresh the STS token.*/
     axios.get(stsUrl).then(({data}) => {
         var info = data.SecurityTokenInfo  
         uploader.resumeUploadWithSTSToken(info.AccessKeyId, info.AccessKeySecret, info.SecretToken);      
     })
 },

Descrição dos métodos

uploader.setSTSToken(uploadInfo, accessKeyId, accessKeySecret, secretToken)
uploader.resumeUploadWithSTSToken(accessKeyId, accessKeySecret, secretToken)

Parâmetro

Descrição

uploadInfo

Primeiro parâmetro do callback onUploadstarted.

accessKeyId

Campo AccessKeyId presente no token STS.

accessKeySecret

Campo AccessKeySecret presente no token STS.

secretToken

Campo SecretToken presente no token STS.

Adicionar arquivos

Monitore o evento change em <input type="file" /> para incluir arquivos na lista do uploader.

JavaScript Nativo

 <form action="">
   <input type="file" name="file" id="files" multiple/>
 </form>
 
 <script>
   userData = '';
   document.getElementById("files")
    .addEventListener('change', function (event) {
      for(var i=0; i<event.target.files.length; i++) {
        // The logic code.
        uploader.addFile(event.target.files[i],null,null,null,null)
      }
    });
 </script>

Vue

 <template>
  <input type="file" id="fileUpload" @change="fileChange($event)">
 </template>

<script>
  export default {
    data () {
      return {
        file: null,
      }
    },
    methods: {
      fileChange (e) {
        this.file = e.target.files[0]
        if (!this.file) {
          alert("Select the files that you want to upload.")
          return
        }
        var Title = this.file.name
        var userData = '{"Vod":{}}'
        if (this.uploader) {
          this.uploader.stopUpload()
        }
        // Initialize an uploader.
        this.uploader = this.createUploader() 
        this.uploader.addFile(this.file, null, null, null, userData)
      },
    }
  }
</script>

Descrição do método

uploader.addFile(file,endpoint,bucket,object,paramData)

Parâmetro

Obrigatório

Tipo

Descrição

file

Sim

File

Arquivo a ser enviado.

endpoint

Não

String

Endpoint do OSS. Se nulo, o AppServer seleciona o endpoint automaticamente.

bucket

Não

String

Bucket de destino. Se nulo, o AppServer escolhe o bucket.

object

Não

String

Objeto de destino. Se nulo, o AppServer define o objeto.

paramData

Não

String

Metadados do arquivo, como título, descrição, transcodificação e configurações de callback. Especifique paramData ao usar upload com token STS.

O valor do parâmetro paramData deve ser uma string JSON. Exemplo: '{"Vod":{}}'. É obrigatório especificar Vod na requisição. Você pode aninhar parâmetros compatíveis sob Vod, incluindo os parâmetros de requisição das operações CreateUploadVideo ou CreateUploadImage.

Iniciar o upload

uploader.startUpload();
  1. Após o início do envio do arquivo, o callback onUploadProgress é chamado para sincronizar o progresso do upload.

  2. Quando o upload for concluído com sucesso, o callback onUploadSucceed retorna o resultado da operação.

Visualize o progresso do upload

// The file upload progress. Unit: bytes. You can use this function to obtain the upload progress and display the upload progress on the page.
onUploadProgress: function (uploadInfo, totalSize, progress) {
  console.log("onUploadProgress:file:" + uploadInfo.file.name + ", fileSize:" + totalSize + ", percent:" + Math.ceil(progress * 100) + "%")
  let progressPercent = Math.ceil(progress * 100)
  self.authProgress = progressPercent
  self.statusText = 'The upload is ongoing...'
},

Obter o resultado do upload

// The upload is successful.
onUploadSucceed: function (uploadInfo) {
  console.log("onUploadSucceed: " + uploadInfo.file.name + ", endpoint:" + uploadInfo.endpoint + ", bucket:" + uploadInfo.bucket + ", object:" + uploadInfo.object)
  self.statusText = 'The upload is successful!'
},
// The upload fails.
onUploadFailed: function (uploadInfo, code, message) {
  console.log("onUploadFailed: file:" + uploadInfo.file.name + ",code:" + code + ", message:" + message)
  self.statusText = 'The upload fails!'
},
  • Após o upload do vídeo, use o videoId para obter a URL de reprodução. Para mais informações, consulte Obter uma credencial de reprodução.

  • O campo imageUrl não é retornado automaticamente em uploads de imagens. Configure um callback para obtê-lo. Consulte Configurar callbacks para detalhes.

Recursos avançados

Usar aceleração de upload

Ative a aceleração de upload para arquivos grandes (GB/TB) ou transferências entre regiões, como da China continental para a região de Singapura.

Para habilitar esse recurso, abra um ticket. Informe seu ID da Conta e o bucket que deseja acelerar.

Método 1: URL e credencial de upload

Chame a operação CreateUploadVideo e defina a aceleração no parâmetro UserData:

UserData={
  "AccelerateConfig": {
    "Type": "oss",
    "Domain": "https://oss-accelerate.aliyuncs.com"
  }
}

Método 2: Token STS

Use o método addFile incluindo a propriedade UserData no parâmetro parmData:

uploader.addFile(file,null,null,null,'{"Vod":{"UserData":{"AccelerateConfig":{"Type":"oss","Domain":"https://oss-accelerate.aliyuncs.com"}}}}');

Descrição do UserData

Nome

Tipo

Obrigatório

Descrição

userData

string

Não

Configurações personalizadas, como callbacks e aceleração de upload. Deve ser uma string JSON válida.

A tabela abaixo detalha os parâmetros.

Parâmetro

Tipo

Descrição

Type

string

Tipo de aceleração de upload. Defina como oss.

Domain

string

Nome de domínio acelerado. Usa HTTPS por padrão.

Nota

Um endpoint acelerado é atribuído após a ativação do recurso, por exemplo: vod-***.oss-accelerate.aliyuncs.com.

Para saber mais sobre a configuração de UserData, consulte Descrições dos parâmetros de requisição.

Parar um upload

Nota

O método stopUpload só tem efeito durante a transferência ativa de um arquivo.

uploader.stopUpload();

Gerencie a lista de arquivos

Use as operações abaixo para gerenciar arquivos enviados ou em andamento.

  • listFiles: Consulta a lista de uploads.

    Retorna os arquivos adicionados via addFile. A propriedade file indica o tipo de arquivo. Percorra a lista para obter os índices necessários às operações de gerenciamento.

    var list = uploader.listFiles();
    for (var i=0; i<list.length; i++) {
        console.log("file:" + list[i].file.name);
    }
  • deleteFile: Remove um arquivo pendente de upload.

    uploader.deleteFile(index);//The index of the file that you want to delete. The index is returned by the listFiles operation.
  • cancelFile: Cancela o envio de um arquivo específico.

    Nota
    • Ao chamar cancelFile, a mensagem oss is cancel as error aparece no console. Isso evita que partes já enviadas ocupem armazenamento e gerem custos desnecessários.

    • Para retomar um upload cancelado, restaure o arquivo primeiro chamando uploader.resumeFile(index);.

    uploader.cancelFile(index);
  • resumeFile: Retoma o upload de um arquivo interrompido.

    uploader.resumeFile(index);
  • cleanList: Limpa completamente a lista de uploads.

    uploader.cleanList();

Upload retomável

Se ocorrer uma falha devido a travamento da página ou erro no navegador, o SDK retoma o envio do ponto de interrupção e busca a credencial via callback onUploadstarted. No Método 1: URL e credencial de upload, chame as operações da API do ApsaraVideo VOD usando o videoId para recuperar as informações do ponto de interrupção:

// The upload is started.
onUploadstarted: function (uploadInfo) {
  // If you use UploadAuth to upload the file, call the uploader.setUploadAuthAndAddress method.
  // If you use UploadAuth to upload the file, call different ApsaraVideo VOD API operations to obtain uploadAuth and uploadAddress based on whether uploadInfo.videoId has a value.
  // If uploadInfo.videoId has a value, call the RefreshUploadVideo operation. Otherwise, call the CreateUploadVideo operation.
  // Take note of the following information: An operation is directly called to obtain UploadAuth because this is a test demo. In actual scenarios, you must call a specific operation to obtain UploadAuth based on whether uploadInfo.videoId has a value.
  // If uploadInfo.videoId has a value, call the RefreshUploadVideo operation.
  // If uploadInfo.videoId is empty, call the CreateUploadVideo operation.
  if (!uploadInfo.videoId) {
    let createUrl = 'https://demo-vod.cn-shanghai.aliyuncs.com/voddemo/CreateUploadVideo?Title=testvod1&FileName=aa.mp4&BusinessType=vodai&TerminalType=pc&DeviceModel=iPhone9,2&UUID=59ECA-4193-4695-94DD-7E1247288&AppVersion=1.0.0&VideoId=5bfcc7864fc14b96972842172207c9e6'
    axios.get(createUrl).then(({data}) => {
      let uploadAuth = data.UploadAuth
      let uploadAddress = data.UploadAddress
      let videoId = data.VideoId
      uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress,videoId)                
    })
    self.statusText = 'The file upload is started...'
    console.log("onUploadStarted:" + uploadInfo.file.name + ", endpoint:" + uploadInfo.endpoint + ", bucket:" + uploadInfo.bucket + ", object:" + uploadInfo.object)
  } else {
    // Display the breakpoint information.
    console.log(uploader.getCheckpoint(uploadInfo.file));
    // If the videoId parameter has a value, the video upload fails. The system resumes the upload from the breakpoint. You must refresh the upload credential based on the value of videoId.
    let refreshUrl = 'https://demo-vod.cn-shanghai.aliyuncs.com/voddemo/RefreshUploadVideo?BusinessType=vodai&TerminalType=pc&DeviceModel=iPhone9,2&UUID=59ECA-4193-4695-94DD-7E1247288&AppVersion=1.0.0&Title=haha1&FileName=xxx.mp4&VideoId=' + uploadInfo.videoId
    axios.get(refreshUrl).then(({data}) => {
      let uploadAuth = data.UploadAuth
      let uploadAddress = data.UploadAddress
      let videoId = data.VideoId
      uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress,videoId)
    })
  }
}

Obtenha as informações do ponto de interrupção:

 uploader.getCheckpoint(file);

Tratamento de exceções

Em caso de exceção, verifique a seção do SDK de upload para cliente no tópico Códigos de erro para identificar a causa raiz.