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

C SDK:构造强类型请求

本页内容

使用 C 结构体填写路径、查询和正文,构建完成后再明确发送请求。

适用场景

请求构建器把 C 结构体中的参数转换成接口请求,适合减少手工拼接路径、查询和 JSON 时的错误。构建只在本地进行,显式发送后才会访问平台。

建议先用只读 getApp 示例跑通“填写参数 → 构建 → 发送 → 读取结果”,再接入上传或付款等写操作。

前提条件

  • 已完成 C SDK 入门。请求结构体和构建函数位于 cloudsign/requests.h,主头文件已包含它。
  • 准备自己的业务应用 ID。下方只读示例按产品需要 enterprise:ReadApps 或 distribution:ReadApps。
  • 准备写操作时,先向使用者确认业务意图,并持久保存本次幂等键与原始输入。

操作步骤

  1. 把输入结构体清零,填写路径 ID 和业务字段。每个已填写字段的 presence 设置为 CLOUDSIGN_FIELD_VALUE。
  2. 未填写的可选字段保持 ABSENT。零、false 和空字符串是否有效,按接口字段定义判断。
  3. 调用对应 cloudsign_build_* 构建函数,接收请求对象的指针先设为 NULL。失败时不要发送。
  4. 构建成功后,显式调用 cloudsign_send_built_request。发送仍需当前账号的权限与业务条件。
  5. 读取响应并释放结果,最后调用 cloudsign_built_request_free 释放请求对象。

运行示例

配置网站主域名和服务端凭据,将 APP_ID 替换为本人业务应用 ID。此示例只查询应用,不执行写入。

命令行示例需要哪些配置

这些变量由自己的进程安全配置注入,不把 Secret 写进命令历史或源码。它们只配置客户端,不选择平台存储厂商。

变量如何填写
CLOUDSIGN_BASE_URL网站 HTTPS 主域名 https://www.onesignios.com。
CLOUDSIGN_ACCESS_KEY_ID示例使用的长期 AccessKey ID。
CLOUDSIGN_ACCESS_KEY_SECRET同一组长期凭据的 Secret。
CLOUDSIGN_API_CA_FILE可选的 API CA 文件;默认使用系统 CA。
构建并运行示例
cmake -S . -B build
cmake --build build -j2
./build/cloudsign_requests_example "$APP_ID"
查看完整 requests-example.c 源码
C11 · requests-example.c
/* One authorized GET using an owned typed request and an owned typed response. */
#include <cloudsign/openapi.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
static int env(char *out,size_t capacity,const char *name){const char *v=getenv(name);if(!v||!*v||strlen(v)>=capacity)return 0;memcpy(out,v,strlen(v)+1);return 1;}
int main(int argc,char **argv){
    cloudsign_credentials keys={0};cloudsign_client *client=NULL;cloudsign_result *result=NULL;cloudsign_decoded_response *decoded=NULL;cloudsign_built_request *built=NULL;
    cloudsign_status status=CLOUDSIGN_INVALID_INPUT;int initialized=0,exit_code=1;char app_id[34]={0};
    if(argc!=2||strlen(argv[1])>=sizeof(app_id)){fputs("Usage: cloudsign_requests_example APP_ID\n",stderr);goto done;}
    memcpy(app_id,argv[1],strlen(argv[1])+1);
    cloudsign_input_get_app input={.presence_id=CLOUDSIGN_FIELD_VALUE,.id=app_id};
    status=cloudsign_build_get_app(&input,&built);if(status!=CLOUDSIGN_OK)goto done;
    /* The builder copied path strings; the original storage can now be released. */
    memset(app_id,0,sizeof(app_id));
    const char *origin=getenv("CLOUDSIGN_BASE_URL");status=CLOUDSIGN_INVALID_CONFIGURATION;
    if(!origin||!env(keys.access_key_id,sizeof(keys.access_key_id),"CLOUDSIGN_ACCESS_KEY_ID")||!env(keys.access_key_secret,sizeof(keys.access_key_secret),"CLOUDSIGN_ACCESS_KEY_SECRET"))goto done;
    status=cloudsign_global_init();if(status!=CLOUDSIGN_OK)goto done;initialized=1;
    cloudsign_options options={.origin=origin,.credentials=&keys,.ca_file=getenv("CLOUDSIGN_API_CA_FILE"),.timeout_ms=15000};status=cloudsign_client_create(&options,&client);cloudsign_credentials_clear(&keys);if(status!=CLOUDSIGN_OK)goto done;
    status=cloudsign_send_built_request(client,built,&result);if(status!=CLOUDSIGN_OK)goto done;
    cloudsign_built_request_free(built);built=NULL;
    status=cloudsign_decode_get_app(result,&decoded);if(status!=CLOUDSIGN_OK)goto done;
    cloudsign_result_free(result);result=NULL;cloudsign_client_free(client);client=NULL;cloudsign_global_cleanup();initialized=0;
    const cloudsign_model_app *data=cloudsign_response_get_app(decoded);if(!data){status=CLOUDSIGN_INVALID_RESPONSE;goto done;}
    (void)data;puts(cloudsign_decoded_request_id(decoded));exit_code=0;
done:
    if(exit_code)fprintf(stderr,"%s %s; RequestId: %s\n",cloudsign_status_name(status),cloudsign_result_error_code(result),decoded?cloudsign_decoded_request_id(decoded):cloudsign_result_request_id(result));
    cloudsign_built_request_free(built);cloudsign_decoded_free(decoded);cloudsign_result_free(result);cloudsign_client_free(client);cloudsign_credentials_clear(&keys);if(initialized)cloudsign_global_cleanup();return exit_code;
}

确认结果

情况怎样判断下一步
退出 0请求构建、应用查询和响应读取均成功。保存输出的 request_id,继续接入自己的业务。
构建失败本地输入缺失或格式不符,尚未发送请求。核对字段类型、presence 与固定值。
发送后失败平台或网络未完成本次请求。按错误码和原请求判断,写入重试保留原幂等键。

构建成功不表示服务端已受理,HTTP 成功也不表示异步业务已经完成。付款、核销与退款的确认字段须由使用者明确确认。

参数与详细规则

先区分输入数据与构建后的请求对象,再查具体字段规则。构建器不会替您补业务确认或生成幂等键。

参数或对象表示什么使用要点
输入结构体在同步构建期间提供字段、数组和字符串。构建成功后已复制,可释放原输入。
built 请求对象保存准备发送的完整请求。只读视图使用期间保留对象,不单独释放视图。
幂等键与确认字段由调用方按实际业务提供。重试保持原键和正文,不把响应直接当作新的付款确认。
查看完整参数、内存管理与运行边界
类型 / 边界接入规则
输入与请求对象输入字符串 / 子对象 / 数组在同步 build 期间借用,不能并发改动。成功后已复制为独立请求,调用方可释放原输入。view 返回只读借用 cloudsign_request,须保留请求对象 到发送或分页 / 等待助手完成;不能修改、单独 free 或释放后使用。
字段存在性ABSENT 不发该字段,不自动展开默认值;VALUE 才读取其值。未知 presence 拒绝;必填缺失、NULL、未知枚举、错误修订号和范围不符都会在构建阶段拒绝。构建成功只代表协议合法,服务端仍检查账号审批、实际权限、权益、预算和资源归属。
整数、金额、布尔整数用 int64_t 和精确十进制序列化,不经浮点打印;金额原样保留字符串(例如 "0.10"),不自动换汇。布尔只接受 0 / 1;密钥核销的确认字段必须显式为 true,false 不能因非空而变成确认。
枚举、数组、联合枚举使用具名 CLOUDSIGN_INPUT_* 常量,不能把底层 C 值当作 JSON 中的实际取值。数组用 count / items,count 与真实可读长度一致;空数组可为 0 / NULL。上传 body 的 oneOf 是带标签联合:VARIANT_1 为 UploadInput,VARIANT_2 为 MultipartUploadInput,按所选分支传正确对象;没有自动分支推断。
正文与限额对象按当前生成契约固定字段顺序输出,自动转义引号、反斜杠与控制字符,保留有效 UTF-8。正文编码后最多 16 KiB、JSON 深度最多 32;路径 / 查询沿用每组最多 20 项、值最多 512 字节及 8192 字节 URL 限制。业务 API 还要求实际路径与查询串合计不超过 2048 字节。拒绝不安全整数、过大数组、空指针、错误标签和不符合原契约的输出,不返回部分请求对象。
幂等与生命周期同版本、相同输入的输出稳定。交易重试须保留原正文和原键,固定 SDK 版本;不承诺跨预览版本重建后字节完全相同。查看 view 仍可能接触开通码或私密筛选,不能整体记录。free 会尽力擦除自有正文、参数和键,原输入及调用方副本由调用方清理。
C11 · 只构建签名任务请求,不发送、不自动签名
const cloudsign_input_job_input body = {
    .presence_source_version_id = CLOUDSIGN_FIELD_VALUE,
    .source_version_id = source_version_id
};
const cloudsign_input_create_job input = {
    .presence_app_id = CLOUDSIGN_FIELD_VALUE, .app_id = app_id,
    .presence_body = CLOUDSIGN_FIELD_VALUE, .body = &body,
    .presence_idempotency_key = CLOUDSIGN_FIELD_VALUE,
    .idempotency_key = saved_idempotency_key
};
cloudsign_built_request *built = NULL;
cloudsign_status status = cloudsign_build_create_job(&input, &built);
/* 到此无网络或签名副作用。发送前先核对业务意图及稳定幂等状态。 */
cloudsign_built_request_free(built);
运行限制与错误处理

构建器纯本地,无需 global_init、API 客户端或凭据。可识别的分配失败返回 OutOfMemory,错误输入 / 契约 / 限额失败返回 InvalidInput;out 保持 NULL。发送前仍按原流程初始化客户端,结果按原 SDK 状态 / request_id 判断;HTTP 成功不等于上传、签名或付款业务已经完成。

失败后如何继续

情况怎样判断下一步
InvalidInput输入或构建后的内容不符合接口要求。核对必填项、枚举、范围及实际字符串。
OutOfMemory本机构建请求所需内存不足。修复资源问题后重新构建,不当作已发送。
写入响应丢失原请求可能已被处理。先查询原任务或回执,再按原键和原内容恢复。