C初始化 - Object Storage Service

使用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簽名（不推薦）

重要

阿里雲Object Storage Service自2024年12月1日起不再對新使用者（即新UID ）開放使用V1簽名，並將於2025年06月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	Proxy 伺服器的地址，格式為`host:port`。
proxy_auth	Proxy 伺服器驗證密碼，格式為`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;
}