使用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校验。取值如下:
|
verify_ssl | 是否开启SSL证书校验。取值如下:
|
ca_path | CA证书根路径。当verify_ssl为1时有效,默认为空。 |
ca_file | CA证书路径,当verify_ssl为1时有效,默认为空。 |
proxy_host | 代理服务器的地址,格式为 |
proxy_auth | 代理服务器验证密码,格式为 |
配置示例
设置超时时间
以下代码用于设置超时时间。
#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;
}