# 进度回调(HarmonyOS SDK)
#### 功能说明
进度回调是 SDK 本地能力：应用在上传或下载接口的入参中设置 ProgressCallback 回调函数，SDK 在数据传输过程中按已传字节数调用该函数，应用据此刷新界面进度。回调函数仅上报已传字节数等进度信息，不干预主传输流程。回调失败不影响主数据传输，SDK 捕获并忽略回调异常。
#### 方法定义
ProgressCallback 是一个函数类型的参数,不是独立接口，而是putObject/getObject/uploadFile/downloadFile 等上传下载接口共用的入参。
```
type ProgressCallback = (
  transferredAmount: number,
  totalAmount: number,
  totalSeconds: number,
) => void;
```
#### 参数说明
表1ProgressCallback 参数 
| **参数名称**          | **参数类型** | **是否必选** | **描述**                                                                                    |
|:---|:---|:---|:---|
| transferredAmount | number   | 必选       | **参数解释：** 本次请求已传输的字节数。上传为已上传字节数,下载为已接收字节数，从0累计至totalAmount。 |
| totalAmount       | number   | 必选       | **参数解释：** 本次请求待传输的总字节数。上传为请求体大小,下载为响应体大小。                   |
| totalSeconds      | number   | 必选       | **参数解释：** 本次请求从开始传输到本次回调时刻的耗时，单位秒，用于计算传输速率。                  |
   
表2覆盖接口 
| 接口           | 覆盖方向 | 说明                                          |
|:---|:---|:---|
| putObject    | 上传进度 | 上传对象时按已上传字节数回调，覆盖单次上传全程进度。                  |
| getObject    | 下载进度 | 文件下载（SaveFilePath 落盘）时按已接收字节数回调，覆盖单次下载全程进度。 |
| uploadFile   | 上传进度 | 断点续传上传时按各段已上传字节数累加回调，覆盖分段上传全程进度。            |
| downloadFile | 下载进度 | 断点续传下载时按各段已下载字节数累加回调，覆盖分段下载全程进度。            |
   
#### 代码示例-上传进度
本示例在上传对象时设置 ProgressCallback,按已传输字节数刷新进度。
```
// 引入依赖包
import ObsClient, { PutObjectInput } from '@obs/esdk-obs-harmony';
import { process } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
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() {
  try {
    const params: PutObjectInput = {
      // 指定存储桶名称
      Bucket: "examplebucket",
      // 指定对象,此处以 example/objectname 为例
      Key: "example/objectname",
      // 指定上传内容
      Body: 'Hello OBS',
      ProgressCallback: (transferred, total, seconds) => {
        const percent = total > 0 ? Math.round(transferred / total * 100) : 0;
        hilog.info(0x0001, 'OBS-Harmony', "progress: %d%% (%d bytes, %ds)", percent, transferred, seconds);
      },
    };
    // 上传对象
    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();
```
#### 相关链接
- 关于进度回调的说明,请参见[获取对象内容](https://support.huaweicloud.com/api-obs/obs_04_0083.html)。
- 下载对象过程中返回的错误码含义、问题原因及处理措施可参考[OBS错误码](https://support.huaweicloud.com/api-obs/obs_04_0115.html#section1)。
- 下载对象常见问题请参见[下载对象失败](https://support.huaweicloud.com/obs_faq/obs_faq_0135.html)。