文档首页/ 对象存储服务 OBS/ SDK参考/ C/ 对象相关接口(C SDK)/ 对象基本操作(C SDK)/ 上传对象(C SDK)/ 多段相关接口(C SDK)/ 多段相关接口说明(C SDK)
更新时间：2026-09-08 GMT+08:00
多段相关接口说明(C SDK)
开发过程中，您有任何问题可以在GitHub上提交issue，或者在华为云对象存储服务论坛中发帖求助。
对于较大文件上传，可以切分成段上传。用户可以在如下的场景内（但不仅限于此）使用分段上传的模式：
- 上传超过100MB大小的文件。
- 网络条件较差，和OBS服务端之间的连接经常断开。
- 上传前无法确定将要上传文件的大小。
分段上传分为如下3个步骤：
分段上传的主要目的是解决大文件上传或网络条件较差的情况。下面的代码示例展示了如何使用分段上传并发上传大文件：
#include "eSDKOBS.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <pthread.h>
// 响应回调函数，可以在这个回调中把properties的内容记录到callback_data(用户自定义回调数据)中
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data);
// 上传段专用响应回调（callback_data为UploadPartTask*），记录段ETag
obs_status upload_part_properties_callback(const obs_response_properties *properties, void *callback_data);
// 结束回调函数（通用，callback_data为obs_status*），记录结果状态
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data);
// 上传段专用结束回调（callback_data为UploadPartTask*），记录段上传结果状态
void upload_part_complete_callback(obs_status status, const obs_error_details *error, void *callback_data);
// 合并段完成回调函数，返回合并结果
obs_status complete_multipart_upload_callback(const char *location, const char *bucket,
const char *key, const char *etag,
void *callback_data);
// 上传段的数据回调函数，SDK通过它读取分段数据
int upload_part_data_callback(int buffer_size, char *buffer, void *callback_data);
// 工作线程：从队列领取分段任务并上传
void *upload_part_worker(void *arg);
#define PART_SIZE (5 * 1024 * 1024) // 每段5MB
#define MAX_PARTS 10000 // 最大分段数
#define THREAD_NUM 5 // 并发上传段任务数
// 单个分段上传任务数据
typedef struct UploadPartTask
{
obs_options *options; // 复用主线程的options
char *key; // 对象名
char *upload_id; // 分段上传任务ID
unsigned int part_number; // 段编号
uint64_t part_size; // 本段大小
uint64_t start_byte; // 本段在文件中的起始偏移
FILE *infile; // 文件指针（每段独占一个）
char etag[256]; // 本段上传成功后的ETag
obs_status ret_status; // 本段上传结果状态
} UploadPartTask;
// 多线程共享的任务队列
static UploadPartTask *g_tasks = NULL;
static int g_task_count = 0;
static int g_task_index = 0;
static pthread_mutex_t g_task_mutex = PTHREAD_MUTEX_INITIALIZER;
int main(int argc, char **argv)
{
// 以下示例展示如何使用分段上传并发上传大文件：
// 分段上传分为3个步骤：1.初始化分段上传任务 2.上传段 3.合并段或取消分段上传任务。
// 在程序入口调用obs_initialize方法来初始化网络、内存等全局资源。
obs_status ret_status = obs_initialize(OBS_INIT_ALL);
if (OBS_STATUS_OK != ret_status)
{
printf("obs_initialize failed(%s).\n", obs_get_status_name(ret_status));
return -1;
}
obs_options options;
// 创建并初始化options，该参数包括访问域名(host_name)、访问密钥（access_key_id和access_key_secret）、桶名(bucket_name)、桶存储类别(storage_class)等配置信息
init_obs_options(&options);
// host_name填写桶所在的endpoint, 此处以华北-北京四为例，其他地区请按实际情况填写。
options.bucket_options.host_name = "obs.cn-north-4.myhuaweicloud.com";
// 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；
// 本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和SECRET_ACCESS_KEY。
options.bucket_options.access_key = getenv("ACCESS_KEY_ID");
options.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
if (!options.bucket_options.access_key || !options.bucket_options.secret_access_key) {
printf("ERROR: ACCESS_KEY_ID and SECRET_ACCESS_KEY environment variables must be set.\n");
obs_deinitialize();
return -1;
}
// 填写Bucket名称，例如example-bucket-name。
char * bucket_name = "example-bucket-name";
options.bucket_options.bucket_name = bucket_name;
// 待上传的本地大文件路径与对象名
char *key = (argc > 1) ? argv[1] : "example_multi_part_upload_object_key";
char *file_path = (argc > 2) ? argv[2] : "/local/path/to/largefile";
// 获取文件大小，计算分段数
FILE *fp = fopen(file_path, "rb");
if (fp == NULL) {
printf("ERROR: failed to open local file %s.\n", file_path);
obs_deinitialize();
return -1;
}
fseek(fp, 0, SEEK_END);
uint64_t filesize = (uint64_t)ftell(fp);
fclose(fp);
unsigned int part_count = (unsigned int)((filesize + PART_SIZE - 1) / PART_SIZE);
if (part_count > MAX_PARTS) {
printf("ERROR: file too large, part count %u exceeds max %d.\n", part_count, MAX_PARTS);
obs_deinitialize();
return -1;
}
printf("file size: %lu bytes, part count: %u, part size: %d bytes\n",
(unsigned long)filesize, part_count, PART_SIZE);
// 初始化上传属性
obs_put_properties put_properties;
init_put_properties(&put_properties);
// 设置响应回调函数
obs_response_handler handler =
{
&response_properties_callback,
&response_complete_callback
};
// ========== 步骤1：初始化分段上传任务，获取uploadId ==========
printf("\n[Step 1] initiate multi part upload...\n");
char upload_id[256] = {0};
int upload_id_size = (int)sizeof(upload_id);
ret_status = OBS_STATUS_BUTT;
initiate_multi_part_upload(&options, key, upload_id_size, upload_id,
&put_properties, 0, &handler, &ret_status);
if (OBS_STATUS_OK != ret_status) {
printf("initiate multi part upload failed(%s).\n", obs_get_status_name(ret_status));
obs_deinitialize();
return -1;
}
printf("initiate multi part upload successfully. uploadId=%s\n", upload_id);
// 构造分段上传任务队列
g_tasks = (UploadPartTask *)malloc(sizeof(UploadPartTask) * part_count);
if (g_tasks == NULL) {
printf("ERROR: failed to allocate task memory.\n");
abort_multi_part_upload(&options, key, upload_id, &handler, &ret_status);
obs_deinitialize();
return -1;
}
memset(g_tasks, 0, sizeof(UploadPartTask) * part_count);
for (unsigned int i = 0; i < part_count; i++) {
g_tasks[i].options = &options;
g_tasks[i].key = key;
g_tasks[i].upload_id = upload_id;
g_tasks[i].part_number = i + 1;
g_tasks[i].part_size = (i == part_count - 1) ? (filesize - (uint64_t)i * PART_SIZE) : PART_SIZE;
g_tasks[i].start_byte = (uint64_t)i * PART_SIZE;
g_tasks[i].infile = fopen(file_path, "rb");
if (g_tasks[i].infile) {
fseek(g_tasks[i].infile, (long)g_tasks[i].start_byte, SEEK_SET);
}
g_tasks[i].ret_status = OBS_STATUS_BUTT;
}
g_task_count = (int)part_count;
g_task_index = 0;
// ========== 步骤2：并发上传段 ==========
printf("\n[Step 2] upload parts concurrently (thread_num=%d)...\n", THREAD_NUM);
pthread_t threads[THREAD_NUM];
int thread_num = (THREAD_NUM < (int)part_count) ? THREAD_NUM : (int)part_count;
for (int i = 0; i < thread_num; i++) {
pthread_create(&threads[i], NULL, upload_part_worker, NULL);
}
for (int i = 0; i < thread_num; i++) {
pthread_join(threads[i], NULL);
}
// 检查各段上传结果
int failed_count = 0;
for (unsigned int i = 0; i < part_count; i++) {
if (g_tasks[i].ret_status != OBS_STATUS_OK || g_tasks[i].etag[0] == '\0') {
failed_count++;
}
if (g_tasks[i].infile) {
fclose(g_tasks[i].infile);
g_tasks[i].infile = NULL;
}
}
if (failed_count > 0) {
printf("upload parts failed, %d part(s) failed.\n", failed_count);
// 任一段上传失败，取消分段上传任务（步骤3的取消分支）
printf("\n[Step 3] abort multi part upload (due to part upload failure)...\n");
ret_status = OBS_STATUS_BUTT;
abort_multi_part_upload(&options, key, upload_id, &handler, &ret_status);
if (OBS_STATUS_OK == ret_status) {
printf("abort multi part upload successfully.\n");
} else {
printf("abort multi part upload failed(%s).\n", obs_get_status_name(ret_status));
}
free(g_tasks);
obs_deinitialize();
return -1;
}
// ========== 步骤3：合并段 ==========
printf("\n[Step 3] complete multi part upload...\n");
obs_complete_upload_Info *upload_info = (obs_complete_upload_Info *)malloc(
sizeof(obs_complete_upload_Info) * part_count);
if (upload_info == NULL) {
printf("ERROR: failed to allocate complete info memory.\n");
abort_multi_part_upload(&options, key, upload_id, &handler, &ret_status);
free(g_tasks);
obs_deinitialize();
return -1;
}
memset(upload_info, 0, sizeof(obs_complete_upload_Info) * part_count);
for (unsigned int i = 0; i < part_count; i++) {
upload_info[i].part_number = g_tasks[i].part_number;
upload_info[i].etag = g_tasks[i].etag;
}
obs_complete_multi_part_upload_handler complete_handler =
{
{&response_properties_callback, &response_complete_callback},
&complete_multipart_upload_callback
};
ret_status = OBS_STATUS_BUTT;
complete_multi_part_upload(&options, key, upload_id, part_count, upload_info,
&put_properties, &complete_handler, &ret_status);
if (OBS_STATUS_OK == ret_status) {
printf("complete multi part upload successfully.\n");
} else {
printf("complete multi part upload failed(%s).\n", obs_get_status_name(ret_status));
}
free(upload_info);
free(g_tasks);
// 释放分配的全局资源
obs_deinitialize();
return (ret_status == OBS_STATUS_OK) ? 0 : -1;
}
// 工作线程：从队列领取分段任务并上传
void *upload_part_worker(void *arg)
{
(void)arg;
while (1) {
pthread_mutex_lock(&g_task_mutex);
if (g_task_index >= g_task_count) {
pthread_mutex_unlock(&g_task_mutex);
break;
}
int idx = g_task_index++;
pthread_mutex_unlock(&g_task_mutex);
UploadPartTask *task = &g_tasks[idx];
obs_upload_part_info part_info;
memset(&part_info, 0, sizeof(obs_upload_part_info));
part_info.part_number = task->part_number;
part_info.upload_id = task->upload_id;
obs_upload_handler part_handler =
{
{&upload_part_properties_callback, &upload_part_complete_callback},
&upload_part_data_callback,
NULL
};
obs_put_properties put_properties;
init_put_properties(&put_properties);
// 上传段（数据通过 upload_part_data_callback 读取）
task->ret_status = OBS_STATUS_BUTT;
upload_part(task->options, task->key, &part_info, task->part_size,
&put_properties, 0, &part_handler, task);
if (OBS_STATUS_OK == task->ret_status) {
printf("[part %u] upload successfully (%lu bytes)\n",
task->part_number, (unsigned long)task->part_size);
} else {
printf("[part %u] upload failed(%s)\n", task->part_number,
obs_get_status_name(task->ret_status));
}
}
return NULL;
}
// 上传段的数据回调函数，SDK通过它读取分段数据
int upload_part_data_callback(int buffer_size, char *buffer, void *callback_data)
{
UploadPartTask *task = (UploadPartTask *)callback_data;
if (task == NULL || task->infile == NULL) {
return 0;
}
// 从文件当前位置读取数据填充到buffer
int toRead = (buffer_size < (int)task->part_size) ? buffer_size : (int)task->part_size;
size_t read = fread(buffer, 1, (size_t)toRead, task->infile);
task->part_size -= read;
return (int)read;
}
// 合并段完成回调函数，返回合并结果
obs_status complete_multipart_upload_callback(const char *location, const char *bucket,
const char *key, const char *etag,
void *callback_data)
{
(void)callback_data;
printf("complete result: location=%s, bucket=%s, key=%s, etag=%s\n",
location ? location : "(null)",
bucket ? bucket : "(null)",
key ? key : "(null)",
etag ? etag : "(null)");
return OBS_STATUS_OK;
}
// 响应回调函数，可以在这个回调中把properties的内容记录到callback_data(用户自定义回调数据)中
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data)
{
(void)callback_data;
if (properties == NULL)
{
printf("error! obs_response_properties is null!");
return OBS_STATUS_OK;
}
// 打印响应信息
#define print_nonnull(name, field) \
do { \
if (properties-> field) { \
printf("%s: %s\n", name, properties->field); \
} \
} while (0)
print_nonnull("request_id", request_id);
print_nonnull("request_id2", request_id2);
print_nonnull("content_type", content_type);
if (properties->content_length) {
printf("content_length: %lu\n", properties->content_length);
}
print_nonnull("server", server);
print_nonnull("ETag", etag);
print_nonnull("expiration", expiration);
print_nonnull("website_redirect_location", website_redirect_location);
print_nonnull("version_id", version_id);
print_nonnull("allow_origin", allow_origin);
print_nonnull("allow_headers", allow_headers);
print_nonnull("max_age", max_age);
print_nonnull("allow_methods", allow_methods);
print_nonnull("expose_headers", expose_headers);
print_nonnull("storage_class", storage_class);
print_nonnull("server_side_encryption", server_side_encryption);
print_nonnull("kms_key_id", kms_key_id);
print_nonnull("customer_algorithm", customer_algorithm);
print_nonnull("customer_key_md5", customer_key_md5);
print_nonnull("bucket_location", bucket_location);
print_nonnull("obs_version", obs_version);
print_nonnull("restore", restore);
print_nonnull("obs_object_type", obs_object_type);
print_nonnull("obs_next_append_position", obs_next_append_position);
print_nonnull("obs_head_epid", obs_head_epid);
print_nonnull("reserved_indicator", reserved_indicator);
int i;
for (i = 0; i < properties->meta_data_count; i++) {
printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
properties->meta_data[i].value);
}
return OBS_STATUS_OK;
}
// 上传段专用响应回调（callback_data为UploadPartTask*），记录段ETag
obs_status upload_part_properties_callback(const obs_response_properties *properties, void *callback_data)
{
if (properties == NULL || callback_data == NULL) {
return OBS_STATUS_OK;
}
UploadPartTask *task = (UploadPartTask *)callback_data;
if (properties->etag && task->etag[0] == '\0') {
strncpy(task->etag, properties->etag, sizeof(task->etag) - 1);
task->etag[sizeof(task->etag) - 1] = '\0';
}
return OBS_STATUS_OK;
}
// 结束回调函数（通用，callback_data为obs_status*），记录结果状态
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data)
{
if (callback_data) {
obs_status *ret_status = (obs_status *)callback_data;
*ret_status = status;
} else {
printf("Callback_data is NULL");
}
if (error && error->message) {
printf("Error Message: \n %s\n", error->message);
}
if (error && error->resource) {
printf("Error Resource: \n %s\n", error->resource);
}
if (error && error->further_details) {
printf("Error further_details: \n %s\n", error->further_details);
}
if (error && error->extra_details_count) {
int i;
for (i = 0; i < error->extra_details_count; i++) {
printf("Error Extra Detail(%d):\n %s:%s\n", i, error->extra_details[i].name,
error->extra_details[i].value);
}
}
if (error && error->error_headers_count) {
int i;
for (i = 0; i < error->error_headers_count; i++) {
const char *errorHeader = error->error_headers[i];
printf("Error Headers(%d):\n %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
}
}
}
// 上传段专用结束回调（callback_data为UploadPartTask*），记录段上传结果状态
void upload_part_complete_callback(obs_status status, const obs_error_details *error, void *callback_data)
{
UploadPartTask *task = (UploadPartTask *)callback_data;
if (task) {
task->ret_status = status;
}
if (error && error->message) {
printf("[part %u] Error: %s\n", task ? task->part_number : 0, error->message);
}
} 
大文件分段上传时，使用Offset参数和PartSize参数配合指定每段数据在文件中的起始结束位置。
并发数过大，可能会因为网络不稳定等原因，产生Timeout错误，需要限制并发数。
父主题： 多段相关接口(C SDK)
