文档首页/ 对象存储服务 OBS/ SDK参考/ BrowserJS/ 上传对象/ 上传回调
更新时间：2025-09-22 GMT+08:00
查看PDF
分享

上传回调

开发过程中，您有任何问题可以在github上提交issue。接口参考文档详细介绍了每个接口的参数和使用方法。

用户可以在上传对象请求中设置回调参数，OBS在对象上传成功之后，将上传结果回调特定服务器，并将回调结果返回给用户。

表1 回调参数

参数名称

参数类型

是否必选

描述

CallbackUrl

string

必选

参数解释：

对象上传成功之后，OBS向此url发送回调请求，请求方法为POST。

约束限制：

  • CallbackUrl需要做url编码。例如：“http://www.example.com/中文?key=中文名”需要编码成“http://www.example.com/%E4%B8%AD%E6%96%87?key=%E4%B8%AD%E6%96%87%E5%90%8D”。
  • 最多支持设置10个url，以英文分号（;）分隔。

默认取值：

无

CallbackHost

string

可选

参数解释：

发起回调请求的Host头域的值。

默认取值：

如果不设置CallbackHost的值，会使用CallbackUrl解析出来的Host。

CallbackBody

string

必选

参数解释：

发起回调请求的body体。

约束限制：

  • body体格式必须符合CallbackBodyType中设置的媒体类型。
  • 回调body体支持系统变量，系统变量如表2所示。例如：key=$(key)&hash=$(etag)，其中变量key、etag是系统变量。如果用户上传的对象是图片，可以在参数中设置imageInfo.width和imageInfo.height表示该图片的宽高。例如：key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)。

默认取值：

无

CallbackBodyType

string

可选

参数解释：

发起回调请求的Content-Type头域的值。

取值范围：

  • application/x-www-form-urlencoded
  • application/json

默认取值：

application/json
表2 回调body体支持的系统变量

变量名称

参数类型

描述

fname

string

参数解释：

上传的原始文件名。

fsize

string

参数解释：

文件的大小，单位为字节。

名称兼容size。

etag

string

参数解释：

对象的ETag。

bucket

string

参数解释：

上传的对象所属桶名。

key

string

参数解释：

上传对象的名字。对象名是对象在存储桶中的唯一标识。对象名是对象在桶中的完整路径，路径中不包含桶名。

例如，您对象的访问地址为examplebucket.obs.cn-north-4.ap-southeast-1.myhuaweicloud.com/folder/test.txt 中，对象名为folder/test.txt。

取值范围：

长度大于0且不超过1024的字符串。

默认取值：

无

ext

string

参数解释：

上传文件的后缀名，通过自动检测的mimeType或者$(fname)的后缀来获取。

名称兼容mimeType。

override

string

参数解释：

上传对象是否产生覆盖。

取值范围：

取值为true或false。上传对象的对象名在桶中已存在，即会产生覆盖，override为true，否则为false。当桶开启多版本时，不会产生覆盖写，override始终为false。

imageInfo

string

参数解释：

获取所上传图片的基本信息。只支持上传图片的场景。

该变量包含$(imageInfo.width)和$(imageInfo.height)两个子字段，分别表示图片的宽度和高度。

说明：

如果上传的图片大小超过25M，则无法通过imageInfo相关魔法变量获取图片基本信息，会导致回调失败。
本示例用于文件上传，并指定上传回调服务器为http://example.com:80。代码示例如下所示： 
// 创建ObsClient实例
var obsClient = new ObsClient({
    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量AccessKeyID和SecretAccessKey。
    // 前端本身没有process对象，可以使用webpack类打包工具定义环境变量，就可以在代码中运行了。
    // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/intl/zh-cn/usermanual-ca/ca_01_0003.html
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // 这里以中国-香港为例，其他地区请按实际情况填写
    server: 'https://obs.ap-southeast-1.myhuaweicloud.com'
});

obsClient.putObject({
       Bucket: 'bucketname',
       // 对象名，是对象在桶中的完整路径，路径中不包含桶名。
       Key: 'objectname',
       // 待上传对象的文件。
       SourceFile: document.getElementById('input-file').files[0],
       Callback: {
          CallbackUrl: "http://example.com:80",
          CallbackBody: "filename=${object}&size=${size}&mimeType=${mimeType}",
          // CallbackHost: "example.com",
          // CallbackBodyType: "application/x-www-form-urlencoded", 
       }
}, function (err, result) {
       if(err){
              console.error('Error-->' + err);
       }else{
              console.log('Status-->' + result.CommonMsg.Status);
              console.log('CallbackResponse-->' + result.InterfaceResult.CallbackResponse);
       }
});
本示例展示如何使用断点续传上传接口上传文件，并指定上传回调服务器为http://example.com:80：。代码示例如下所示： 
// 创建ObsClient实例
var obsClient = new ObsClient({
    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量AccessKeyID和SecretAccessKey。
    // 前端本身没有process对象，可以使用webpack类打包工具定义环境变量，就可以在代码中运行了。
    // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/intl/zh-cn/usermanual-ca/ca_01_0003.html
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // 这里以中国-香港为例，其他地区请按实际情况填写
    server: 'https://obs.ap-southeast-1.myhuaweicloud.com'
});

var cp;
var hook;
obsClient.uploadFile({
       Bucket : 'bucketname',
       Key : 'objectname',
       SourceFile : document.getElementById('input-file').files[0],
       PartSize : 9 * 1024 * 1024,
       ProgressCallback : function(transferredAmount, totalAmount, totalSeconds){
           console.log(transferredAmount * 1.0 / totalSeconds / 1024);
           console.log(transferredAmount * 100.0 / totalAmount);
           if(hook && (transferredAmount / totalAmount) > 0.5){
               // 暂停断点续传任务
               // hook.cancel();
           }
       },
       EventCallback : function(eventType, eventParam, eventResult){
           // 处理事件响应
       },
       ResumeCallback : function(resumeHook, uploadCheckpoint){
           // 获取取消断点续传上传任务控制参数
           hook = resumeHook;
           // 记录断点
           cp = uploadCheckpoint;
       },
       Callback: {
          CallbackUrl: "http://example.com:80",
          CallbackBody: "filename=${object}&size=${size}&mimeType=${mimeType}",
          // CallbackHost: "example.com",
          // CallbackBodyType: "application/x-www-form-urlencoded", 
       }
}, function(err, result){
    console.error('Error-->' + err);
    // 出现错误，再次调用断点续传接口，继续上传任务
    if(err){
       obsClient.uploadFile({
          UploadCheckpoint : cp,
          ProgressCallback : function(transferredAmount, totalAmount, totalSeconds){
              console.log(transferredAmount * 1.0 / totalSeconds / 1024);
              console.log(transferredAmount * 100.0 / totalAmount);
          },
          EventCallback : function(eventType, eventParam, eventResult){
             // 处理事件响应
          },
        }, function(err, result){
          if(err){
              console.error('Error-->' + err);
          }else{
              if(result.CommonMsg.Status < 300){
                 console.log('RequestId-->' + result.InterfaceResult.RequestId);
                 console.log('CallbackResponse-->' + result.InterfaceResult.CallbackResponse);
              }else{
                 console.log('Code-->' + result.CommonMsg.Code);
                 console.log('Message-->' + result.CommonMsg.Message);
              }
        }
      });
    }else {
         console.log('Status-->' + result.CommonMsg.Status);
         if (result.CommonMsg.Status < 300 && result.InterfaceResult) {
                console.log('RequestId-->' + result.InterfaceResult.RequestId);
         }
    }
});
父主题： 上传对象