文档首页/ 对象存储服务 OBS/ SDK参考/ C/ 对象相关接口(C SDK)/ 对象基本操作(C SDK)/ 上传对象(C SDK)/ 文本上传(C SDK)
更新时间：2026-07-13 GMT+08:00
查看PDF
分享

文本上传(C SDK)

开发过程中，您有任何问题可以在GitHub上提交issue，或者在华为云对象存储服务论坛中发帖求助。

功能说明

调用文本上传接口，您可以将文本内容直接上传至OBS指定桶中的对象。文本上传是对流式上传（put_object）的简化封装，无需实现put_object_data_callback回调函数，直接传入文本内容即可完成上传，适用于小文件或内存中的文本数据上传场景。

接口约束

  • 您必须是桶拥有者或拥有上传对象的权限，才能上传对象。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。
  • OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。
  • 单次上传对象大小范围是[0, 5GB]。
  • 如果需要上传超过5GB的大文件，需要通过多段操作来分段上传。

方法定义

void put_object_content(const obs_options *options, const char *key,
    const char *content, uint64_t content_length,
    obs_put_properties *put_properties,
    server_side_encryption_params *encryption_params,
    obs_put_object_handler *handler, void *callback_data);

请求参数说明

表1 请求参数列表

参数名称

参数类型

是否必选

描述

options

const obs_options*

必选

参数解释：

请求桶的上下文，配置option(C SDK)，通过obs_options设置AK、SK、endpoint、bucket、超时时间、临时鉴权。

约束限制：

无

key

const char *

必选

参数解释：

对象名。对象名在桶中唯一标识一个对象，即桶内不能存在两个相同的对象名。

约束限制：

无

取值范围：

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

默认取值：

无

content

const char *

必选

参数解释：

待上传的文本内容。

约束限制：

无

取值范围：

无

默认取值：

无

content_length

uint64_t

必选

参数解释：

文本内容的长度，单位为字节。

约束限制：

无

取值范围：

0~5GB。

默认取值：

无

put_properties

表3 obs_put_properties *

可选

参数解释：

上传属性，包含content_type、md5、ACL、元数据、上传限速等配置。可通过init_put_properties初始化。

约束限制：

无

encryption_params

表4 server_side_encryption_params*

可选

参数解释：

服务端加密参数。

约束限制：

无

handler

表2 obs_put_object_handler*

必选

参数解释：

回调结构体，包含响应回调、上传数据回调和进度回调。

约束限制：

使用put_object_content时无需实现put_object_data_callback，SDK内部会自动处理。

callback_data

void *

可选

参数解释：

用户自定义回调数据。

约束限制：

无

取值范围：

无

默认取值：

无
表2 obs_put_object_handler

参数名称

参数类型

是否必选

描述

response_handler

obs_response_handler

必选

参数解释：

响应回调函数结构体，包含properties_callback和complete_callback。

约束限制：

无

put_object_data_callback

表3 obs_put_object_data_callback*

可选

参数解释：

上传数据回调函数指针。使用put_object_content时SDK内部会自动设置此回调，无需用户实现。

约束限制：

无

progress_callback

表4 obs_progress_callback_internal*

可选

参数解释：

进度回调函数指针，用于获取上传进度。

约束限制：

无
表3 obs_put_object_data_callback

参数名称

参数类型

是否必选

描述

buffer_size

int

必选

参数解释：

buffer的长度。

约束限制：

无

取值范围：

无

默认取值：

无

buffer

char *

必选

参数解释：

待上传的数据缓冲区，把要上传的数据复制到这个缓冲区。

约束限制：

无

取值范围：

无

默认取值：

无

callback_data

void *

必选

参数解释：

用户自定义回调数据指针。

约束限制：

无

取值范围：

无

默认取值：

无
表4 obs_progress_callback_internal

参数名称

参数类型

是否必选

描述

now

uint64_t

必选

参数解释：

已上传的字节数。

约束限制：

无

取值范围：

无

默认取值：

无

total

uint64_t

必选

参数解释：

总共需要上传的字节数。

约束限制：

无

取值范围：

无

默认取值：

无

callback_data

void *

必选

参数解释：

用户自定义回调数据指针。

约束限制：

无

取值范围：

无

默认取值：

无
表5 obs_put_properties

参数名称

参数类型

是否必选

描述

content_type

char *

可选

参数解释：

指定对象被下载时的文件类型。

约束限制：

无

取值范围：

参见HTTP标准头域Content-Type的取值。

默认取值：

无

md5

char *

可选

参数解释：

对象数据的MD5值（经过Base64编码），提供给OBS服务端校验数据完整性。

约束限制：

对象数据的MD5值必须经过Base64编码。如果不设置，OBS服务端会忽略对对象数据的MD5值校验。

取值范围：

按照RFC 1864标准计算出消息体的MD5摘要字符串，即消息体128-bit MD5值经过Base64编码后得到的字符串。

默认取值：

无

cache_control

char *

可选

参数解释：

指定对象被下载时的网页的缓存行为。

约束限制：

无

取值范围：

参见HTTP标准头域Cache-Control的取值。

默认取值：

无

content_disposition_filename

char *

可选

参数解释：

指定对象被下载时的名称。

约束限制：

无

取值范围：

参见HTTP标准头域Content-Disposition的取值。

默认取值：

无

content_encoding

char *

可选

参数解释：

指定对象被下载时的内容编码格式。

约束限制：

无

取值范围：

参见HTTP标准头域Content-Encoding的取值。

默认取值：

无

website_redirect_location

char *

可选

参数解释：

当桶设置了Website配置，可以将获取这个对象的请求重定向到桶内另一个对象或一个外部的URL。

约束限制：

必须以"/"、"http://"或"https://"开头，长度不超过2KB。

取值范围：

无

默认取值：

无

upload_limit

uint64_t

可选

参数解释：

对单链接请求的带宽限制。

约束限制：

无

取值范围：

819200~838860800，单位为bit/s。

默认取值：

0，表示不限速。

expires

int64_t

可选

参数解释：

OBS请求中Expires头的值。指定对象被下载时的网页的缓存过期时间。

约束限制：

无

取值范围：

无

默认取值：

无

obs_expires

int64_t

可选

参数解释：

指定对象过期时间，单位是天。过期之后对象会被自动删除。

约束限制：

设置的天数计算出的过期时间不能早于当前时间。

取值范围：

大于0的整数值。

默认取值：

无

canned_acl

表6 obs_canned_acl

可选

参数解释：

权限控制策略。

约束限制：

无

取值范围：

无

默认取值：

无

meta_data_count

int

可选

参数解释：

meta_data数组中元素的个数。

约束限制：

无

取值范围：

无

默认取值：

无

meta_data

表7 obs_name_value*

可选

参数解释：

对象的自定义元数据。

约束限制：

所有自定义元数据大小的总和不超过8KB。自定义元数据的key值不区分大小写，OBS统一转为小写进行存储。value值区分大小写。

取值范围：

无

默认取值：

无

metadata_action

表8 metadata_action_indicator

可选

参数解释：

元数据操作指示符。

约束限制：

无

取值范围：

OBS_REPLACE：使用当前请求中携带的头域完整替换，未指定的元数据会被删除；OBS_REPLACE_NEW：对已存在值的元数据进行替换，不存在值的元数据进行赋值，未指定的元数据保持不变。

默认取值：

无

server_callback

表9 obs_upload_file_server_callback

可选

参数解释：

服务端回调相关参数。

约束限制：

无

取值范围：

无

默认取值：

无
表6 server_side_encryption_params

参数名称

参数类型

是否必选

描述

encryption_type

obs_encryption_type

可选

参数解释：

加密类型。

约束限制：

无

取值范围：

请详见obs_encryption_type。

kms_server_side_encryption

char *

可选

参数解释：

使用该头域表示对象使用的服务端加密方式是SSE-KMS。

约束限制：

无

取值范围：

  • kms
  • AES256

默认取值：

无

kms_key_id

char *

可选

参数解释：

密钥ID。当加密方式为SSE-KMS且使用指定密钥加密时，需输入密钥ID。

约束限制：

当您设置了kms_server_side_encryption且赋值为“kms”，即选择kms加密方式时，才能使用该头域指定加密密钥。

取值范围：

密钥ID获取方法请参见查看密钥。

默认取值：

当您选择使用kms加密方式，但未设置此头域时，默认的主密钥将会被使用。如果默认主密钥不存在，系统将默认创建并使用。

ssec_customer_algorithm

char *

可选

参数解释：

该头域表示加密对象使用的算法。

约束限制：

仅SSE-C方式下使用该头域。

取值范围：

AES256（指AES256加密算法）

默认取值：

无

ssec_customer_key

char *

可选

参数解释：

该头域表示加密对象使用的密钥。

约束限制：

仅SSE-C方式下使用该头域。

取值范围：

256位密钥的base64编码。

默认取值：

无

des_ssec_customer_algorithm

char *

可选

参数解释：

该头域表示解密源对象使用的算法。

约束限制：

仅SSE-C方式下使用该头域。

取值范围：

无

默认取值：

无

des_ssec_customer_key

char *

可选

参数解释：

该头域表示解密源对象使用的密钥。

约束限制：

仅SSE-C方式下使用该头域。

取值范围：

无

默认取值：

无
表7 obs_encryption_type

常量名

原始值

说明

OBS_ENCRYPTION_KMS

kms

使用KMS加密方式。

OBS_ENCRYPTION_SSEC

AES256

使用SSE-C加密方式。
表8 obs_canned_acl

常量名

原始值

说明

OBS_CANNED_ACL_PRIVATE

private

私有读写，桶或对象的所有者拥有完全控制的权限，其他任何人都没有访问权限。

OBS_CANNED_ACL_PUBLIC_READ

public-read

公共读私有写，设在桶上，所有人可以获取该桶内对象列表、桶内多段任务、桶的元数据、桶的多版本。设在对象上，所有人可以获取该对象内容和元数据。

OBS_CANNED_ACL_PUBLIC_READ_WRITE

public-read-write

公共读写，设在桶上，所有人可以获取该桶内对象列表、桶内多段任务、桶的元数据、上传对象删除对象、初始化段任务、上传段、合并段、复制段、取消多段上传任务。设在对象上，所有人可以获取该对象内容和元数据。

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

bucket-owner-full-control

设在对象上，桶和对象的所有者拥有对象的完全控制权限，其他任何人都没有访问权限。默认情况下，上传对象至其他用户的桶中，桶拥有者没有对象的控制权限。对象拥有者为桶拥有者添加此权限控制策略后，桶所有者可以完全控制对象。例如，用户A上传对象x至用户B的桶中，系统默认用户B没有对象x的控制权。当用户A为对象x设置bucket-owner-full-control策略后，用户B就拥有了对象x的控制权。仅S3 API支持。

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

public-read-delivered

桶公共读，桶内对象公共读，设在桶上，所有人可以获取该桶内对象列表、桶内多段任务、桶的元数据，可以获取该桶内对象的内容和元数据。不能应用于对象。

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

public-read-write-delivered

桶公共读写，桶内对象公共读写，设在桶上，所有人可以获取该桶内对象列表、桶内多段任务、桶的元数据、上传对象、删除对象、初始化段任务、上传段、合并段、复制段、取消多段上传任务，可以获取该桶内对象的内容和元数据。不能应用于对象。
表9 obs_name_value

参数名称

参数类型

是否必选

描述

name

char *

可选

参数解释：

属性的键。

约束限制：

无

取值范围：

无

默认取值：

无

value

char *

可选

参数解释：

属性的值。

约束限制：

无

取值范围：

无

默认取值：

无
表10 metadata_action_indicator

常量名

原始值

说明

OBS_NO_METADATA_ACTION

-

默认的无效值。

OBS_REPLACE

REPLACE

表示使用当前请求中携带的头域完整替换，未指定的元数据会被删除。

OBS_REPLACE_NEW

REPLACE_NEW

表示对于已经存在值的元数据进行替换，不存在值的元数据进行赋值，未指定的元数据保持不变（自定义元数据作替换处理）。
表11 obs_upload_file_server_callback

参数名称

参数类型

是否必选

描述

callback_url

char *

必选

参数解释：

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

支持设置多个url，以英文分号（;）分隔，最多支持10个。

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”。

约束限制：

无

取值范围：

无

默认取值：

无

callback_host

char *

可选

参数解释：

发起回调请求的Host头域的值，如果不设置，会使用callbackUrl解析出来的Host。

约束限制：

无

取值范围：

无

默认取值：

无

callback_body

char *

必选

参数解释：

发起回调请求的body体。body体格式必须符合callbackBodyType中设置的媒体类型。

回调body体支持系统变量和自定义变量，系统变量如回调body体支持的系统变量表所示，自定义变量就是以x:开头的变量。例如：key=$(key)&hash=$(etag)&fileid=$(x:fileid)，其中变量key、etag是系统变量，x:fileid是自定义变量。如果用户上传的对象是图片，可以在参数中设置imageInfo.width和imageInfo.height表示该图片的宽高。例如：key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)。

约束限制：

无

取值范围：

无

默认取值：

无

callback_body_type

char *

可选

参数解释：

发起回调请求的Content-Type头域的值。支持application/x-www-form-urlencoded、application/json。如果不设置，默认为

application/json。

约束限制：

无

取值范围：

无

默认取值：

无

代码示例

以下示例展示如何使用文本上传接口上传文本内容：

#include "eSDKOBS.h"
#include <stdio.h>
#include <string.h>
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data);
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data);
int main()
{
    obs_initialize(OBS_INIT_ALL);
    obs_options options;
    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");
    options.bucket_options.bucket_name = "example-bucket-name";
    // 设置上传属性
    obs_put_properties put_properties;
    init_put_properties(&put_properties);
    put_properties.content_type = "text/plain";
    // 待上传的文本内容
    const char *content = "Hello, OBS!";
    uint64_t content_length = strlen(content);
    obs_response_handler response_handler = {&response_properties_callback, &response_complete_callback};
    obs_put_object_handler handler = {response_handler, NULL, NULL};
    obs_status ret_status = OBS_STATUS_BUTT;
    put_object_content(&options, "objectname", content, content_length,
                       &put_properties, NULL, &handler, &ret_status);
    if (OBS_STATUS_OK == ret_status) {
        printf("put object content successfully.\n");
    } else {
        printf("put object content failed(%s).\n", obs_get_status_name(ret_status));
    }
    obs_deinitialize();
}
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data)
{
    (void)properties; (void)callback_data;
    return OBS_STATUS_OK;
}
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data)
{
    if (callback_data) { *(obs_status*)callback_data = status; }
    if (error && error->message) { printf("Error: %s\n", error->message); }
}

相关链接

  • 关于文本上传的API说明，请参见PUT上传。
  • 文本上传过程中返回的错误码含义、问题原因及处理措施可参考OBS错误码。
父主题： 上传对象(C SDK)

相关文档