You need to enable JavaScript to run this app.
导航
集成 Web 上传 SDK
最近更新时间:2024.07.15 14:58:00首次发布时间:2022.11.01 15:39:42

本文介绍 Web 上传 SDK 的集成方法。Web 上传 SDK 支持将本地视频上传至企业直播媒资库,以及上传本地图片做为媒资库中视频的封面。

前提条件

  • 您已开通定制版套餐。详见计费说明
  • 在火山引擎控制台获取账号 ID、Access Key ID (AK) 和 Secret Access Key (SK):
    1. 登录火山引擎控制台
    2. 单击账号头像,在下拉菜单中复制并保存账号ID
      图片
    3. 单击账号头像下拉菜单中的API访问密钥,进入密钥管理页面
    4. 单击新建密钥,即可创建一对 AK 和 SK。
  • 由于 Web 上传 SDK 的 API 不支持跨域调用,请联系企业直播技术支持将您的域名加入白名单。

服务端搭建用户 token 生成服务

企业直播服务通过 token 对用户进行鉴权。因此,在使用上传 SDK 之前,您需要在您自己的服务端搭建一个用户 token 生成服务,即通过您获取到的 AK 和 SK 生成用户 token。可参考以下步骤:

  1. 在您项目的package.json 文件中添加以下代码,通过 npm 安装 1.5.1 或以上版本的 OpenAPI Node SDK

    "dependencies": {
        "@volcengine/openapi": "^1.5.1",
    }
    
  2. 在您项目的 config.js 文件中添加以下代码,配置 AK 和 SK、区域和域名。

    module.exports = {
        AKSK: {
            // 此处填写您的 AK 和 SK
            ACCESS_KEY_ID: "Fill in your AK",
            SECRET_ACCESS_KEY: "Fill in your SK",
        },
        region: 'cn-north-1',
        domain: 'livesaas.volcengineapi.com'
    }
    
  3. 参考以下示例代码生成用户 token:

    const Koa = require('koa');
    const { livesaasOpenapi } = require('@volcengine/openapi');
    const { AKSK } = require('./config');
    const koaApp = new Koa();
    koaApp.use(async (ctx, next) => {
      // 创建 VolcUserClient 实例
      const VolcUserClient = new livesaasOpenapi.LivesaasService({
        accessKeyId: AKSK.ACCESS_KEY_ID,
        secretKey: AKSK.SECRET_ACCESS_KEY,
      })
      // 生成用户 token
      const VolcUserToken = VolcUserClient.GetLivesaasUploadUserToken()
      console.log(VolcUserToken)
      ctx.body = {
        userToken: VolcUserToken
      };
    });
    

客户端集成上传 SDK

参考以下步骤,将上传 SDK 集成到您的 Web 应用中。

步骤一:引入 SDK

在您项目的 .html 文件中添加以下代码引入 SDK。

<script src="https://unpkg.byted-static.com/byted/byte-live-console-tools/0.1.2-alpha.0/dist/index.min.js"></script>

步骤二:初始化 SDK

创建 uploader 实例,初始化 SDK。示例代码如下:

let uploader

document.getElementById('test').addEventListener('change', async function () {
    const fileList = this.files;
    // 从服务端获取用户 token
    const data = await (await fetch(`http://127.0.0.1:3000`, {
        mode: 'cors'
    })).json()

    // 创建 uploader 实例
    uploader = new ByteConsoleTools.Uploader({
        userId: "210020****",
        region: "cn-north-1",
        service: "iframeTest"
        videoConfig: {
            spaceName: "livesaas-new",
            processAction: [
                {
                    name: "GetMeta",
                },
            ]
        },
        userToken: data.userToken,
    });
  
    uploader.initCheck({
        file: fileList,
        type: 'video',
    }).then(fileKey => {
        console.log(fileKey);
    }).catch(e => {
        console.log(e)
    })
});

创建 uploader 实例时,您需要设置以下参数:

名称

类型

是否必选

默认值

描述

userId

Integer

不适用

账户 ID。

region

String

不适用

上传地区。您需将此参数设为 cn-north-1

service

String

不适用

服务名称,仅用于标记。
企业直播技术支持会在配置白名单后,向您同步该参数值。

videoConfig

JSON

不适用

视频上传配置。当前仅支持以下参数:

  • spaceName: 用于储存上传文件的空间名。您需要将此参数设为 "livesaas-new"
  • processAction:视频上传后的处理 action 对象数组,详见 processAction

userToken

String

不适用

用户 token。

processAction

视频上传后的处理 action 对象数组,包含以下参数:

名称

描述

name

Action 名称。当前仅可设为 GetMeta,即获取上传视频的 Meta 信息。SDK 会返回 VideoMeta

步骤三:上传前检查

在上传文件前,调用 initCheck 检查以下内容:

  • 用户是否拥有可以访问企业直播媒资库的权限。
  • 待上传的视频或图片是否符合以下要求:
    • 视频必须为 MP4 格式,且大小不超过 20 GB。
    • 图片必须为 PNG 或 JPG 格式,且大小不超过 2 GB。
  • 企业直播媒资库的剩余空间是否足够。

上传视频前进行检查的示例代码如下:

uploader.initCheck({
      file: fileList,
      type: 'video',
  }).then(fileKey => {
      console.log(fileKey);
  }).catch(e => {
      console.log(e)
  })

上传图片前进行检查的示例代码如下:

uploader.initCheck({
     file: fileList,
     type: 'image',
     vid: document.getElementById('vid-input').value
 }).then(fileKey => {
     console.log(fileKey);
 }).catch(e => {
     console.log(e)
 })

调用 initCheck 时,您需要设置以下参数:

名称

类型

是否必选

默认值

描述

file

Array

不适用

待上传文件。每次仅可上传一个文件。

type

'video'

'image'

  • 'video'
  • 'image'

vid

String

如果您将 type 设为 'image',即上传本地图片,需要设置 vid 指定此图片作为哪个视频的封面。

检查通过后,SDK 会返回上传任务 ID fileKey,例如 'file_1495442273603_999031'

步骤四:控制上传任务

您可调用以下方法控制上传任务:

  • 调用 start 启动上传任务。示例代码如下:

    uploader.start();
    
  • 调用 pause 暂停上传任务。SDK 会暂存当前文件的上传信息。

    uploader.pause();
    
  • 调用 restart 重启上传任务。SDK 会从暂停位置重新开始上传。

    uploader.restart();
    
  • 调用 cancel 取消上传任务,并删除当前文件的上传信息。

    uploader.cancel();
    

步骤五:监听事件

参考以下示例代码监听上传任务的事件:

uploader.on('event_name', function(data) {
    console.log('event_name', data);
});

下表列出上传任务生命周期中 SDK 可能触发的事件。

事件名称

描述

crc32

SDK 进行视频切片后触发。上传视频时,SDK 会将视频切分成多个片段。该事件返回 CRC-32 信息数组和每个片段的长度。

progress

返回上传任务的进度 (%)。

fileMerge

所有视频分片上传成功并合并后触发。

complete

上传任务完成时触发。SDK 触发 complete 事件即表示上传任务进度为100%。该事件的 data 参数中包含 uploadResult 参数。在 uploadResult 参数中您可以获取到 vid,即企业直播媒资库中视频文件的唯一标识符。

error

提示错误信息。

tokenExpired

在用户 token 过期时触发。用户 token 的有效期为 24 小时。用户 token 过期后,您可以调用 uploader.refreshUserToken(newUserToken) 更新用户 token。如果您没有及时更新用户 token,SDK 会不断重试当前操作。每次重试的超时时间为 5 秒。5 次重试失败后,SDK 会抛出异常并结束上传。