跳转到主要内容
1签 (OneSign)

C SDK 入门

本页内容

在自己的服务端使用 C SDK 调用开放 API。按本教程下载源码、配置凭据并运行一个只读请求,确认接入后再继续上传、签名或分发。

运行环境与下载

准备 C11、CMake 3.20+,需原生依赖。下载C 源码包,核对包内 SHA256SUMS。需要固定接入版本时,保存所用源码包及其独立摘要。

当前 C 源码预览版本为 0.8.0-preview.1。还需要 libcurl 7.85+、OpenSSL 3+、cJSON 1.7.18+、PCRE2 10.42+ 和 pkg-config。文件传输助手的支持环境见下方专题;HTTP 客户端和辅助 CLI 的用途不同。

准备项目

在私有目录解压,将入口保存为 example.c。保留包内相对位置,不把源码目录和运行入口拆散。

保留根目录 CMakeLists.txt 与 cloudsign-sdk/c/,按包内依赖说明构建。首次调用的 cloudsign_api_example 只查当前身份。

配置凭据

变量填写方式
CLOUDSIGN_BASE_URLhttps://www.onesignios.com,完整 HTTPS 网站来源,不带 API 路径。
CLOUDSIGN_ACCESS_KEY_ID自己的 AccessKey ID。
CLOUDSIGN_ACCESS_KEY_SECRET对应 Secret,从服务端安全配置注入。
CLOUDSIGN_SECURITY_TOKEN临时凭据使用同一组令牌;长期凭据不填写。

本页先运行只读请求。需要写入时,再按幂等键准备说明配置对应业务,并核对所需权限。

运行只读示例

将下面代码保存为指定入口,再运行命令。SDK 正常返回后,从 data 核对账号、动作和应用范围,并保存 request_id 供排查。错误响应也包含请求 ID,不能仅凭它判断成功。响应约定见请求与响应约定。

C
/* C11, trusted server. Save as example.c in the source ZIP root. */
#include <cloudsign/openapi.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

static int copy_env(char *out, size_t capacity, const char *name, int required) {
    const char *value = getenv(name);
    if (!value || !*value) return !required;
    size_t length = strlen(value);
    if (length >= capacity) return 0;
    memcpy(out, value, length + 1);
    return 1;
}

int main(void) {
    cloudsign_credentials credentials = {0};
    cloudsign_client *client = NULL;
    cloudsign_result *result = NULL;
    cloudsign_decoded_response *decoded = NULL;
    cloudsign_built_request *built = NULL;
    cloudsign_status status = CLOUDSIGN_INVALID_CONFIGURATION;
    int initialized = 0, exit_code = 1;
    const char *origin = getenv("CLOUDSIGN_BASE_URL");
    if (!origin || !copy_env(credentials.access_key_id, sizeof(credentials.access_key_id), "CLOUDSIGN_ACCESS_KEY_ID", 1)
        || !copy_env(credentials.access_key_secret, sizeof(credentials.access_key_secret), "CLOUDSIGN_ACCESS_KEY_SECRET", 1)
        || !copy_env(credentials.security_token, sizeof(credentials.security_token), "CLOUDSIGN_SECURITY_TOKEN", 0)) goto done;
    status = cloudsign_global_init();
    if (status != CLOUDSIGN_OK) goto done;
    initialized = 1;
    cloudsign_options options = {.origin = origin, .credentials = &credentials, .timeout_ms = 15000};
    status = cloudsign_client_create(&options, &client);
    cloudsign_credentials_clear(&credentials);
    if (status != CLOUDSIGN_OK) goto done;
    const cloudsign_input_get_identity input = {0};
    status = cloudsign_build_get_identity(&input, &built);
    if (status != CLOUDSIGN_OK) goto done;
    status = cloudsign_send_built_request(client, built, &result);
    if (status == CLOUDSIGN_OK) {
        status = cloudsign_decode_get_identity(result, &decoded);
        if (status != CLOUDSIGN_OK) goto done;
        const cloudsign_model_get_identity_data *data = cloudsign_response_get_identity(decoded);
        if (!data) { status = CLOUDSIGN_INVALID_RESPONSE; goto done; }
        /* Read typed fields here; NULL/absent is distinct from zero/false. */
        (void)data;
        puts(cloudsign_decoded_request_id(decoded));
        exit_code = 0;
    }
done:
    if (exit_code) {
        if (status == CLOUDSIGN_API_ERROR) fprintf(stderr, "HTTP %ld %s; RequestId: %s\n", cloudsign_result_http_status(result), cloudsign_result_error_code(result), cloudsign_result_request_id(result));
        else fputs("Check SDK path, runtime, environment variables and business input.\n", stderr);
    }
    cloudsign_result_free(result);
    cloudsign_decoded_free(decoded);
    cloudsign_built_request_free(built);
    cloudsign_client_free(client);
    if (initialized) cloudsign_global_cleanup();
    cloudsign_credentials_clear(&credentials);
    return exit_code;
}
运行命令
cmake -S . -B build
cmake --build build -j2
./build/cloudsign_api_example

确认调用结果

示例正常运行后会输出请求标识。先确认程序没有抛出 SDK 或 HTTP 错误,再按下表读取成功响应,核对您实际接入的账号和资源范围。

字段怎样理解需要确认
request_id本次调用的请求标识。保存用于排查;错误响应也可能有这个字段。
data.owner_id当前凭据所属的平台账号。应是准备接入的本人账号。
data.actions当前身份可使用的授权动作。包含下一步所需的读取或写入动作。
data.resources当前授权的应用范围。覆盖准备操作的自有业务应用。

示例只输出请求标识时,按本语言的响应读取方式取得上述字段,不需要把完整响应或 Secret 写入日志。概念与 ID 的区别见基本概念;C 字段读取见强类型响应。

接入业务

从企业签名或应用分发开始。每个接口页均提供对应语言调用,替换为自己的真实 ID,并按先查询、再确认、后写入的业务顺序执行。

SDK 的本地输入检查不能代替服务器授权。上传、签名和付款各自确认结果;网络中断先恢复原操作。

需要组合多次调用时,请阅读上传、等待与下载助手;更新源码包前,请按升级前准备保存正在处理的任务。

常见问题

导入失败先检查目录与运行环境;401 检查凭据、网站主域名和时钟;403 / 404 检查账号及应用范围。不要把完整 Secret、短期 URL 或原始敏感响应输出到日志。

原生编译与文件助手的系统支持情况以包内 README 为准。当前 Linux 环境已有验证;其他系统需核对工具链与文件接口,不应以 HTTP 示例成功推断所有文件助手都可用。

C SDK:读取强类型响应

将成功响应转换成 C 结构体,并正确处理空值、数组和内存释放。 查看操作步骤与完整示例 →

C SDK:构造强类型请求

使用 C 结构体填写路径、查询和正文,构建完成后再明确发送请求。 查看操作步骤与完整示例 →

C SDK:下载并校验安装包

使用短期下载凭证取得指定版本,核对独立保存的预期摘要后再使用文件。 查看操作步骤与完整示例 →

C SDK:传输与确认单个分片

自行调度上传时,发送一个已声明分片,并由业务 API 确认其保存结果。 查看操作步骤与完整示例 →

C SDK:恢复完整安装包上传

保存上传检查点,在网络中断或进程重启后继续原任务,并确认最终版本。 查看操作步骤与完整示例 →

C SDK:验证通知与返回回执

在 C 接收端验证通知来源,保存业务处理结果,再向平台返回回执。 查看操作步骤与完整示例 →