通过 Web 上传 SDK，您可以上传本地视频或图片、管理视频封面，并创建和更新点播间，快速完成企业直播媒资接入。本文档介绍如何集成 Web 上传 SDK 并使用 Web 上传 SDK 完成上述功能。

前提条件 #

• 您已开通尊享版套餐。详见计费说明。
• 由于 Web 上传 SDK 的 API 不支持跨域调用，在集成 Web 上传 SDK 前，您需参考Web SDK 配置将您使用的域名 URL 加入白名单。

获取临时上传 token #

Web 上传 SDK 需要使用临时 token 进行初始化，您可以借助火山引擎的 STS (Security Token Service) 服务来获取。
具体流程如下：您的服务端使用一个具有固定权限的子账号（拥有永久 AK/SK）调用 AssumeRole 接口，获取一个有权限和时间限制的临时安全凭证（临时 AK/SK + SessionToken），然后将该凭证下发给前端的上传 SDK 使用。

步骤一：新建角色，获取角色的 TRN 值 #

创建子账号前，您需先创建一个具有企业直播管理员（LiveSaaSFullAccess）权限的角色。

1. 在火山引擎角色管理页面，点击 新建角色。
   
2. 在新建角色弹窗中，选择账号作为信任身份，然后单击下一步。
   
3. 将角色名设置为 livesaas_videoroom，然后单击下一步。
   
4. 在选择策略搜索框中，搜索 LiveSaaSFullAccess 策略并勾选。然后单击提交。
   
   您将在角色列表中看到新创建的角色。
5. 点击 livesaas_videoroom 角色名，进入角色详情。
   
6. 在角色详情中，找到角色TRN，鼠标悬浮在 TRN 编码上，然后复制并保存该 TRN。后续子账号调用接口时，需要使用该值。
   

步骤二：新建子账号，并获取其 AK/SK 和 ID #

创建一个具有企业直播管理员权限（LiveSaaSFullAccess）和 STS 角色扮演（STSAssumeRoleAccess）权限的子账号，用于调用 AssumeRole 接口。

1. 在访问控制用户页面，单击右上方的新建用户。
   
2. 在创建用户页面，单击通过用户名创建。
3. 设置用户名为 Videoroom，勾选编程访问，然后单击下一步。
   
4. 分别搜索并勾选 LiveSaaSFullAccess 和 STSAssumeRoleAccess 策略，然后单击下一步。
   
5. 审阅完毕后，单击下一步，完成创建。
   
6. 在用户列表，单击新创建的用户的名称，进入用户详情页面。
7. 在用户详情页面，单击密钥，然后单击创建 Access Key，为该用户创建并保存访问密钥（AK/SK）。您的后端服务器将使用它来调用 AssumeRole 接口。
   
8. 在用户详情页面，复制并保存当前子用户的 ID。在初始化 SDK 时，您需要传入该值。
   

步骤三：调用 AssumeRole 接口获取临时凭证 #

使用步骤二中创建的子账号 AK/SK，调用 AssumeRole 接口，获取临时凭证的 AccessKeyId、SecretAccessKey 和 SessionToken。接口文档请参考 AssumeRole API 文档。
为遵循“最小权限原则”，建议您在调用 AssumeRole 接口时，通过 Policy 参数精细化地限制临时凭证的权限。以下代码示例展示通过 assumeRoleRequest.setPolicy 设置的集成 Web 上传 SDK 所需的最小权限配置。

/**
* Example Code generated by Beijing Volcanoengine Technology.
*/
package com.volcengine.sample;

import com.volcengine.ApiClient;
import com.volcengine.ApiException;
import com.volcengine.sign.Credentials;

import com.volcengine.sts.StsApi;
import com.volcengine.sts.model.*;


public class TestAssumeRole {
    public static void main(String[] args) throws Exception {
        String ak = "Your AK"; // 填入步骤二获取的子账号的 AK
        String sk = "Your SK";  // 填入步骤二获取的子账号的 SK
        String region = "cn-beijing";

        ApiClient apiClient = new ApiClient()
                .setCredentials(Credentials.getCredentials(ak, sk))
                .setRegion(region);

        StsApi api = new StsApi(apiClient);
        
        AssumeRoleRequest assumeRoleRequest = new AssumeRoleRequest();
        assumeRoleRequest.setDurationSeconds(3600); // 临时密钥有效时长，单位为秒。默认为 3600 秒
        assumeRoleRequest.setPolicy("{\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"livesaas:GetUploadTokenSDK\",\"livesaas:UploadActivityMediaSDK\",\"livesaas:CheckSpaceActivityMediaSDK\",\"livesaas:UpdateMediaCoverImageSDK\",\"livesaas:CreateVideoRoomConsole\",\"livesaas:ListActivityMedia\",\"livesaas:UploadMedia\",\"livesaas:ListActivityMedias\",\"livesaas:UpdateActivityMediaOnlineStatus\"],\"Resource\":[\"*\"],\"Condition\":{\"StringEquals\":{\"volc:RequestedRegion\":[\"cn-beijing\"]}}}]}");  // 最小权限配置
        assumeRoleRequest.setRoleSessionName("a");  // 角色会话名称，用于区分会话
        assumeRoleRequest.setRoleTrn("trn:iam::2100xxxxxx:role/livesaas_videoroom"); // 传入步骤一获取的角色 TRN 值
        
        try {
            // 复制代码运行示例，请自行打印API返回值。
            api.assumeRole(assumeRoleRequest);
        } catch (ApiException e) {
            // 复制代码运行示例，请自行打印API错误信息。
            // System.out.println(e.getResponseBody());
        }
    }
}

步骤四：​适配临时凭证返回格式 #

AssumeRole 接口成功调用后，您的后端服务会获取到一个包含临时凭证的结果，包括 AccessKeyId、SecretAccessKey 和 SessionToken。请确保前端最终传入 SDK 的临时凭证符合如下 JSON 结构。

{
  userToken: {
    AccessKeyId: Result.Credentials.AccessKeyId,
    SecretAccessKey: Result.Credentials.SecretAccessKey,
    SessionToken: Result.Credentials.SessionToken,
  }
}

您可以根据现有业务架构，选择以下任一方式完成适配：

• 方式一：服务端从 AssumeRole 返回结果中提取临时凭证信息，并按照上述结构重新封装返回，前端无需改造。
• 方式二：服务端直接返回 AssumeRole 的原始结果，由前端提取相应字段并组装为上述结构后传入 SDK。

客户端集成上传 SDK #

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

步骤一：引入 SDK #

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

<script src="https://unpkg.byted-static.com/byted/byte-live-console-uploader/1.0.1/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",
                },
            ]
        },
    // 包含 AccessKeyId、SecretAccessKey 和 SessionToken 的对象
        userToken: data.userToken,
    });
  // 上传前检查，详情参考下文
    uploader.initCheck({
        file: fileList,
        type: 'video',
    }).then(fileKey => {
        console.log(fileKey);
    }).catch(e => {
        console.log(e)
    })
});

创建 uploader 实例时，您需要设置以下参数：

{
  userToken: {
    AccessKeyId: Result.Credentials.AccessKeyId,
    SecretAccessKey: Result.Credentials.SecretAccessKey,
    SessionToken: Result.Credentials.SessionToken,
    }
}

processAction

用于视频上传后处理的 Action 对象数组，包含以下参数：

步骤三：上传前检查 #

在上传文件前，调用 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)
 })

上传视频或图片前检查的相关参数如下表所示：

检查通过后，SDK 会返回上传任务 ID fileKey，例如 'file_149544227xxxx_xxxxxx'。

步骤四：控制上传任务 #

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

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

  uploader.start();
  

• 调用 pause 暂停上传任务。SDK 会暂存当前文件的上传信息。

  uploader.pause();
  

• 调用 restart 重启上传任务。SDK 会从暂停位置重新开始上传。

  uploader.restart();
  

• 调用 cancel 取消上传任务，并删除当前文件的上传信息。

  uploader.cancel();
  

步骤五：创建点播间 #

如果您希望在本地视频上传完成后自动创建点播间，您需要在 initCheck 中传入与点播间相关的参数。相关参数如下表所示。

示例代码如下所示。SDK 会先进行上传前检查，之后上传视频：

• 检查通过后，SDK 会返回上传任务 ID fileKey，例如 'file_149544227xxxx_xxxxxx'。
• 本地视频上传成功后，SDK 会创建点播间。

uploader.initCheck({
  newVideoRoomName: '<点播间名称>',
  file: fileList,   // 每次仅可上传一个文件。
  type: 'video',
});

uploader.start();

步骤六：更新点播间 #

调用 updateVideoRoom，通过传入视频 ID、或上传本地视频的方式，更新点播间。

以下示例代码展示了同时处理本地视频上传和 vids 指定视频上传的场景：SDK 会先上传本地视频文件，再上传 vids 中指定的视频。

uploader.updateVideoRoom({
  videoRoomId: '<点播间id>',  // 可通过监听 video_room_created_result 事件获取点播间 ID。详见文档末尾。
  file: fileList, // 每次仅可上传一个文件。
  type: 'video', // 固定取值为 `video`。
  vids: ['<vid1>', '<vid2>'],  // 传入视频的 ID。
  isAppend: true  // 保留点播间内已有视频，追加新视频。
});

步骤七：监听事件 #

监听上传任务事件

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

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

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

监听点播间创建结果事件

video_room_created_result 用于监听点播间创建结果。示例代码如下：

uploader.on('video_room_created_result', result => {
  console.log(result);  // result.VideoRoomId
});

无论创建成功还是失败，SDK 都会触发该事件：

• 若点播间创建成功，将返回 VideoRoomId，即点播间 ID；
• 若创建失败，将返回具体错误信息。