更新时间:2026-08-28 GMT+08:00
分享

上传回调(HarmonyOS SDK)

功能说明

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

  • 回调成功,返回回调结果给客户端,同时将上传对象的Etag以头域返回,当回调结果也包含Etag时,将对Etag拼接后返回。
  • 回调失败,返回203,表示对象上传成功但是回调失败。

接口约束

  • 您必须是桶拥有者或拥有上传对象的权限,才能上传对象。建议使用IAM或桶策略进行授权,如果使用IAM则需授予obs:object:PutObject权限,如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见OBS权限控制概述,配置方式详见使用IAM自定义策略配置对象策略
  • OBS支持的Region与Endpoint的对应关系,详细信息请参见地区与终端节点
  • 如果上传的图片大小超过25M,则无法通过imageInfo相关魔法变量获取图片基本信息,会导致回调失败。
  • CallbackUrl 与 CallbackBody 必填(无论嵌套还是扁平写法),否则入参校验终止请求。
  • 回调服务器不可达或回调失败属服务端或网络特性,不影响对象写入。

方法定义

上传回调是入参参数,支持putObject和uploadFile方法。

请求参数

表1 Callback 入参

参数名称

参数类型

是否必选

描述

CallbackUrl

string

必选

参数解释:

回调地址,服务端在对象写入完成后向该地址发起回调请求。

CallbackBody

string

必选

参数解释:

回调请求体内容,可引用服务端变量 $(key)/$(etag)/$(bucket) 等。

CallbackHost

string

可选

参数解释:

回调请求的 Host 头值。

CallbackBodyType

string

可选

参数解释:

回调请求体类型,默认 application/json。

代码示例

二进制文件上传回调,上传后的对象命名为example/objectname,对象存储在名为examplebucket的桶中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
// 引入依赖包
import ObsClient, { PutObjectInput } from '@obs/esdk-obs-harmony';
import { process } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { fileIo as fs } from '@kit.CoreFileKit';
const processManager = new process.ProcessManager();

// 创建ObsClient实例
const obsClient = new ObsClient({
  // 推荐通过环境变量获取AKSK,这里也可以使用其他外部引入方式传入,如果使用硬编码可能会存在泄露风险
  // 您可以登录访问管理控制台获取访问密钥AK/SK,获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
  AccessKeyId: processManager.getEnvironmentVar("ACCESS_KEY_ID"),
  SecretAccessKey: processManager.getEnvironmentVar("SECRET_ACCESS_KEY"),
  // 【可选】如果使用临时AK/SK和SecurityToken访问OBS,同样建议您尽量避免使用硬编码,以降低信息泄露风险。您可以通过环境变量获取访问密钥AK/SK,也可以使用其他外部引入方式传入
  // SecurityToken: processManager.getEnvironmentVar("SECURITY_TOKEN"),
  // Server填写Bucket对应的Endpoint, 这里以华北-北京四为例,其他地区请按实际情况填写
  Server: "https://obs.cn-north-4.myhuaweicloud.com",
});

async function putObject() {

  // 指定文件路径,这里以cacheDir目录下的hello.txt为例,需要保证fs模块可以正常读取。
  let sourceFile = getContext().cacheDir + "/hello.txt";
  // 打开文件句柄,如果代码运行在生产环境上,推荐加上异常捕获(try...catch)逻辑。
  let file = fs.openSync(sourceFile, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
  // 模拟文件内容
  fs.writeSync(file.fd, "hello Obs");
  // 获取文件属性
  let fileStat = fs.statSync(file.fd);
  // 根据文件大小 构建文件缓冲区
  let buf = new ArrayBuffer(fileStat.size);
  fs.readSync(file.fd, buf, { offset: 0 });
  // 用完记得关闭文件
  fs.closeSync(file.fd);

  try {
    const params: PutObjectInput = {
      // 指定存储桶名称
      Bucket: "examplebucket",
      // 指定对象,此处以 example/objectname 为例
      Key: "example/objectname",
      // 指定上传内容,注意这里接收的类型是ArrayBuffer
      Body: buf,
      CallbackUrl: "http://example.com/callback",
      CallbackBody: '{"key":"$(key)"}',
    };
    // 上传对象
    const result = await obsClient.putObject(params);
    if (result.CommonMsg.Status < 300) {
      hilog.info(0x0001, 'OBS-Harmony', "Put object(%s) under the bucket(%s) successful!!", params.Key, params.Bucket);
      hilog.info(0x0001, 'OBS-Harmony', "RequestId: %s", result.CommonMsg.RequestId);
      hilog.info(0x0001, 'OBS-Harmony', "StorageClass:%s, ETag:%s", result.InterfaceResult.StorageClass, result.InterfaceResult.ETag);
      return;
    }
    hilog.error(0x0001, 'OBS-Harmony', "An ObsError was found, which means your request sent to OBS was rejected with an error response.");
    hilog.error(0x0001, 'OBS-Harmony', "Status: %d", result.CommonMsg.Status);
    hilog.error(0x0001, 'OBS-Harmony', "Code: %s", result.CommonMsg.Code);
    hilog.error(0x0001, 'OBS-Harmony', "Message: %s", result.CommonMsg.Message);
    hilog.error(0x0001, 'OBS-Harmony', "RequestId: %s", result.CommonMsg.RequestId);
  } catch (error) {
    const err = error as BusinessError;
    hilog.error(0x0001, 'OBS-Harmony', 'An Exception occurred: code=%d, message: %s', err.code, err.message);
  }
}


putObject();

相关链接

  • 上传对象过程中返回的错误码含义、问题原因及处理措施可参考OBS错误码
  • 上传对象常见问题请参见上传对象失败
  • 回调功能更多介绍参考OBS回调

相关文档