# 文本上传(C SDK) ![](https://support.huaweicloud.com/sdk-c-devg-obs/public_sys-resources/notice_3.0-zh-cn.png) 开发过程中，您有任何问题可以在GitHub上[提交issue](https://github.com/huaweicloud/huaweicloud-sdk-c-obs/issues)，或者在[华为云对象存储服务论坛](https://bbs.huaweicloud.com/forum/forum-620-1.html)中发帖求助。 #### 功能说明 调用文本上传接口，您可以将文本内容直接上传至OBS指定桶中的对象。文本上传是对流式上传（put_object）的简化封装，无需实现put_object_data_callback回调函数，直接传入文本内容即可完成上传，适用于小文件或内存中的文本数据上传场景。 #### 接口约束 - 您必须是桶拥有者或拥有上传对象的权限，才能上传对象。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见[OBS权限控制概述](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0001.html)，配置方式详见[使用IAM自定义策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0121.html)、[配置对象策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0075.html)。 - OBS支持的Region与Endpoint的对应关系，详细信息请参见[地区与终端节点](https://console.huaweicloud.com/apiexplorer/#/endpoint/OBS)。 - 单次上传对象大小范围是\[0, 5GB\]。 - 如果需要上传超过5GB的大文件，需要通过[多段操作](https://support.huaweicloud.com/sdk-c-devg-obs/obs_20_1812.html)来分段上传。 #### 方法定义 ``` 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](https://support.huaweicloud.com/sdk-c-devg-obs/obs_20_0085.html#obs_20_0085__table9681927859)\* | 必选 | **参数解释：** 请求桶的上下文，配置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 \* | 可选 | **参数解释：** 用户自定义回调数据。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无 | 表2obs_put_object_handler | 参数名称 | 参数类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | response_handler | [obs_response_handler](https://support.huaweicloud.com/sdk-c-devg-obs/obs_20_0087.html#obs_20_0087__table53755070) | 必选 | **参数解释：** 响应回调函数结构体，包含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]\* | 可选 | **参数解释：** 进度回调函数指针，用于获取上传进度。 **约束限制：** 无 | 表3obs_put_object_data_callback | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | buffer_size | int | 必选 | **参数解释：** buffer的长度。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无 | | buffer | char \* | 必选 | **参数解释：** 待上传的数据缓冲区，把要上传的数据复制到这个缓冲区。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无 | | callback_data | void \* | 必选 | **参数解释：** 用户自定义回调数据指针。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无 | 表4obs_progress_callback_internal | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | now | uint64_t | 必选 | **参数解释：** 已上传的字节数。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无 | | total | uint64_t | 必选 | **参数解释：** 总共需要上传的字节数。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无 | | callback_data | void \* | 必选 | **参数解释：** 用户自定义回调数据指针。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无 | 表5obs_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] | 可选 | **参数解释：** 服务端回调相关参数。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无 | 表6server_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获取方法请参见[查看密钥](https://support.huaweicloud.com/usermanual-dew/dew_01_0179.html)。 **默认取值：** 当您选择使用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方式下使用该头域。 **取值范围：** 无 **默认取值：** 无 | 表7obs_encryption_type | **常量名** | **原始值** | **说明** | |:---|:---|:---| | OBS_ENCRYPTION_KMS | kms | 使用KMS加密方式。 | | OBS_ENCRYPTION_SSEC | AES256 | 使用SSE-C加密方式。 | 表8obs_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 | 桶公共读写，桶内对象公共读写，设在桶上，所有人可以获取该桶内对象列表、桶内多段任务、桶的元数据、上传对象、删除对象、初始化段任务、上传段、合并段、复制段、取消多段上传任务，可以获取该桶内对象的内容和元数据。不能应用于对象。 | 表9obs_name_value | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | name | char \* | 可选 | **参数解释：** 属性的键。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无 | | value | char \* | 可选 | **参数解释：** 属性的值。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无 | 表10metadata_action_indicator | **常量名** | **原始值** | **说明** | |:---|:---|:---| | OBS_NO_METADATA_ACTION | - | 默认的无效值。 | | OBS_REPLACE | REPLACE | 表示使用当前请求中携带的头域完整替换，未指定的元数据会被删除。 | | OBS_REPLACE_NEW | REPLACE_NEW | 表示对于已经存在值的元数据进行替换，不存在值的元数据进行赋值，未指定的元数据保持不变（自定义元数据作替换处理）。 | 表11obs_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体支持的系统变量表](https://support.huaweicloud.com/api-obs/obs_04_0095.html#obs_04_0095__table695016242719)所示，自定义变量就是以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 #include 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上传](https://support.huaweicloud.com/api-obs/obs_04_0080.html)。 - 文本上传过程中返回的错误码含义、问题原因及处理措施可参考[OBS错误码](https://support.huaweicloud.com/api-obs/obs_04_0115.html#section1)。