C初始化 - 对象存储 OSS

使用OSS C SDK时，需要初始化请求选项（oss_request_options_t）并指定Endpoint。

初始化请求选项

V4签名（推荐）

推荐使用更安全的V4签名算法。使用V4签名初始化时，除指定Endpoint以外，您还需要指定阿里云通用Region ID作为发起请求地域的标识，示例值为cn-hangzhou。同时声明signature_version = 4。OSS C SDK 3.11.0及以上版本支持V4签名。

以使用OSS域名新建OSSClient时使用V4签名为例，其他通过自定义域名、STS等新建OSSClient的场景可参考以下示例执行相应修改。

#include "oss_api.h"
#include "aos_http_io.h"
/* yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。*/
const char *endpoint = "yourEndpoint";
/* yourRegion填写Bucket所在地域对应的Region。以华东1（杭州）为例，Region填写为cn-hangzhou。*/
const char *region = "yourRegion";

void init_options(oss_request_options_t *options)
{
    options->config = oss_config_create(options->pool);
    /* 用char*类型的字符串初始化aos_string_t类型。*/
    aos_str_set(&options->config->endpoint, endpoint);
    /* 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/  
    aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
    aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
    //需要额外配置以下两个参数
    aos_str_set(&options->config->region, region);
    options->config->signature_version = 4;
    /* 是否使用CNAME访问OSS服务。0表示不使用。*/
    options->config->is_cname = 0;
    /* 用于设置网络相关参数，其中这个函数的第二个参数表示ctl的归属，默认为0。*/
    options->ctl = aos_http_controller_create(options->pool, 0);
}
int main() {
    aos_pool_t *p;
    oss_request_options_t *options;
    /* 初始化全局变量，在程序生命周期内只需要调用一次。*/
    if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
        return -1;
    }
    /* 初始化内存池和options。*/
    aos_pool_create(&p, NULL);
    options = oss_request_options_create(p);
    init_options(options);
    /* 逻辑代码，此处省略。*/
    /* 释放内存池，相当于释放了请求过程中各资源分配的内存。*/
    aos_pool_destroy(p);
    /* 释放之前分配的全局资源，在程序生命周期内只需要调用一次。*/
    aos_http_io_deinitialize();
    return 0;
}

V1签名（不推荐）

重要

阿里云对象存储OSS自2025年03月01日起不再对新用户（即新UID ）开放使用V1签名，并将于2025年09月01日起停止更新与维护且不再对新增Bucket开放使用V1签名。请尽快切换到V4签名，避免影响服务。更多信息，请参见公告链接。

使用OSS域名初始化请求选项

以下代码用于OSS域名初始化请求选项。

#include "oss_api.h"
#include "aos_http_io.h"
/* yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。*/
const char *endpoint = "yourEndpoint";

void init_options(oss_request_options_t *options)
{
    options->config = oss_config_create(options->pool);
    /* 用char*类型的字符串初始化aos_string_t类型。*/
    aos_str_set(&options->config->endpoint, endpoint);
    /* 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/  
    aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
    aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
    /* 是否使用CNAME访问OSS服务。0表示不使用。*/
    options->config->is_cname = 0;
    /* 用于设置网络相关参数，其中这个函数的第二个参数表示ctl的归属，默认为0。*/
    options->ctl = aos_http_controller_create(options->pool, 0);
}
int main() {
    aos_pool_t *p;
    oss_request_options_t *options;
    /* 初始化全局变量，在程序生命周期内只需要调用一次。*/
    if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
        return -1;
    }
    /* 初始化内存池和options。*/
    aos_pool_create(&p, NULL);
    options = oss_request_options_create(p);
    init_options(options);
    /* 逻辑代码，此处省略。*/
    /* 释放内存池，相当于释放了请求过程中各资源分配的内存。*/
    aos_pool_destroy(p);
    /* 释放之前分配的全局资源，在程序生命周期内只需要调用一次。*/
    aos_http_io_deinitialize();
    return 0;
}

使用自定义域名初始化请求选项

以下代码用于自定义域名初始化请求选项。

#include "oss_api.h"
#include "aos_http_io.h"
/* 填写自定义域名。*/
const char *endpoint = "yourCustomEndpoint";

void init_options(oss_request_options_t *options) {
    options->config = oss_config_create(options->pool);
    /* 用char*类型的字符串初始化aos_string_t类型。*/
    aos_str_set(&options->config->endpoint, endpoint);
    /* 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/  
    aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
    aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
    /* 开启CNAME，将自定义域名绑定到存储空间上。*/
    options->config->is_cname = 1;
    options->ctl = aos_http_controller_create(options->pool, 0);
}
int main() {
    aos_pool_t *p;
    oss_request_options_t *options;
    /* 初始化全局变量，在程序生命周期内只需要调用一次。*/
    if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
        return -1;
    }
    /* 初始化内存池和options。*/
    aos_pool_create(&p, NULL);
    options = oss_request_options_create(p);
    init_options(options);
    /* 逻辑代码，此处省略。*/
    /* 释放内存池，相当于释放了请求过程中各资源分配的内存。*/
    aos_pool_destroy(p);
    /* 释放之前分配的全局资源，在程序生命周期内只需要调用一次。*/
    aos_http_io_deinitialize();
    return 0;
}

使用STS初始化请求选项

以下代码用于STS初始化请求选项。

#include "oss_api.h"
#include "aos_http_io.h"
/* yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。*/
const char *endpoint = "yourEndpoint";
/* 运行本代码示例之前，请确保已使用STS服务获取的临时访问密钥设置环境变量YOUR_ACCESS_KEY_ID和YOUR_ACCESS_KEY_SECRET。*/  
const char *access_key_id = getenv("YOUR_ACCESS_KEY_ID");
const char *access_key_secret = getenv("YOUR_ACCESS_KEY_SECRET");
/* 填写从STS服务获取的安全令牌（SecurityToken）。*/
const char *sts_token = "<yourSecurityToken>";
void init_options(oss_request_options_t *options)
{
    options->config = oss_config_create(options->pool);
    /* 用char*类型的字符串初始化aos_string_t类型。*/
    aos_str_set(&options->config->endpoint, endpoint);
    aos_str_set(&options->config->access_key_id, access_key_id);
    aos_str_set(&options->config->access_key_secret, access_key_secret);
    /* 设置STS。*/
    aos_str_set(&options->config->sts_token, sts_token);
    /* 是否使用CNAME访问OSS服务。0表示不使用。*/
    options->config->is_cname = 0;
    options->ctl = aos_http_controller_create(options->pool, 0);
}
int main() {
    aos_pool_t *p;
    oss_request_options_t *options;
    /* 初始化全局变量，在程序生命周期内只需要调用一次。*/
    if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
        return -1;
    }
    /* 初始化内存池和options。*/
    aos_pool_create(&p, NULL);
    options = oss_request_options_create(p);
    init_options(options);
    /* 逻辑代码，此处省略。*/
    /* 释放内存池，相当于释放了请求过程中各资源分配的内存。*/
    aos_pool_destroy(p);
    /* 释放之前分配的全局资源，在程序生命周期内只需要调用一次。*/
    aos_http_io_deinitialize();
    return 0;
}

配置参数

常见配置参数如下。

参数	说明
speed_limit	最低平均速度限制，单位为字节/秒。默认值为1024。
speed_time	最低平均速度持续时间，单位为秒。默认值为15。重要必须同时设置speed_limit和speed_time参数。表示在持续多长时间内速度低于某个值时中断请求，即请求的超时时间。
connect_timeout	建立连接的超时时间，单位为秒。默认为10秒。
dns_cache_timeout	DNS缓存的超时时间，单位为秒。默认为60秒。
max_memory_size	下载数据时写入内存的最大值，单位为字节，默认为1 GB。
enable_crc	是否开启CRC64校验。取值如下： 0：关闭CRC64校验。 1（默认值）：开启CRC64校验。
verify_ssl	是否开启SSL证书校验。取值如下： 0：关闭SSL证书校验。 1（默认值）：开启SSL证书校验。
ca_path	CA证书根路径。当verify_ssl为1时有效，默认为空。
ca_file	CA证书路径，当verify_ssl为1时有效，默认为空。
proxy_host	代理服务器的地址，格式为`host:port`。
proxy_auth	代理服务器验证密码，格式为`user:password`。

配置示例

设置超时时间

以下代码用于设置超时时间。

#include "oss_api.h"
#include "aos_http_io.h"
/* yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。*/
const char *endpoint = "yourEndpoint";

void init_options(oss_request_options_t *options)
{
    options->config = oss_config_create(options->pool);
    /* 用char*类型的字符串初始化aos_string_t类型。*/
    aos_str_set(&options->config->endpoint, endpoint);
    /* 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/  
    aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
    aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
    /* 是否使用CNAME访问OSS服务。0表示不使用。*/
    options->config->is_cname = 0;
    /* 用于设置网络相关参数，其中这个函数的第二个参数表示ctl的归属，默认为0。*/
    options->ctl = aos_http_controller_create(options->pool, 0);
    /* 设置链接超时，默认为10秒。*/
    options->ctl->options->connect_timeout = 10;
    /* 设置DNS超时，默认为60秒。*/
    options->ctl->options->dns_cache_timeout = 60;
    /* 
    设置请求超时。
    通过speed_limit设置可接受的最小速率，默认为1024，即1 KB/s。
    通过speed_time设置可接受的最长时间，默认为15秒。
    如果传输速率连续15秒小于1 KB/s，则表明请求超时。
    */
    options->ctl->options->speed_limit = 1024;
    options->ctl->options->speed_time = 15;
}
int main() {
    aos_pool_t *p;
    oss_request_options_t *options;
    /* 初始化全局变量，在程序生命周期内只需要调用一次。*/
    if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
        return -1;
    }
    /* 初始化内存池和options。*/
    aos_pool_create(&p, NULL);
    options = oss_request_options_create(p);
    init_options(options);
    /* 逻辑代码，此处省略。*/
    /* 释放内存池，相当于释放了请求过程中各资源分配的内存。*/
    aos_pool_destroy(p);
    /* 释放之前分配的全局资源，在程序生命周期内只需要调用一次。*/
    aos_http_io_deinitialize();
    return 0;
}

设置SSL证书校验

C SDK 3.9.2及以上版本默认开启SSL证书校验。如果出现SSL证书校验失败，您需要设置正确的SSL证书路径，或者关闭SSL证书验证功能。

以下代码用于设置SSL证书校验。

#include "oss_api.h"
#include "aos_http_io.h"
/* yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。*/
const char *endpoint = "yourEndpoint";

void init_options(oss_request_options_t *options)
{
    options->config = oss_config_create(options->pool);
    /* 用char*类型的字符串初始化aos_string_t类型。*/
    aos_str_set(&options->config->endpoint, endpoint);
    /* 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/  
    aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
    aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
    /* 是否使用了CNAME。0表示不使用。*/
    options->config->is_cname = 0;
    /* 用于设置网络相关参数，其中这个函数的第二个参数表示ctl的归属，默认为0。*/
    options->ctl = aos_http_controller_create(options->pool, 0);

    /* 设置SSL证书校验。*/
    通过verify_ssl设置是否开启SSL证书校验。可选值为1或0，默认值为1，即开启SSL证书校验。
    通过ca_path设置CA证书的根路径，当verify_ssl为1时有效，默认值为空。
    通过ca_file设置CA证书的路径，当verify_ssl为1时有效，默认值为空。*/
    /* 开启SSL证书校验，并设置CA证书路径。*/
    //options->ctl->options->verify_ssl = 1;
    //options->ctl->options->ca_path = "/etc/ssl/certs/";
    //options->ctl->options->ca_file = "/etc/ssl/certs/ca-certificates.crt";

    /* 关闭SSL证书校验。*/
    //options->ctl->options->verify_ssl = 0;
}
int main() {
    aos_pool_t *p;
    oss_request_options_t *options;
    /* 初始化全局变量，在程序生命周期内只需要调用一次。*/
    if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
        return -1;
    }
    /* 初始化内存池和options。*/
    aos_pool_create(&p, NULL);
    options = oss_request_options_create(p);
    init_options(options);
    /* 逻辑代码，此处省略。*/
    /* 释放内存池，相当于释放了请求过程中各资源分配的内存。*/
    aos_pool_destroy(p);
    /* 释放之前分配的全局资源，在程序生命周期内只需要调用一次。*/
    aos_http_io_deinitialize();
    return 0;
}