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

Rust SDK 入门

本页内容

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

运行环境与下载

准备 1.88+,使用 Tokio。下载Rust 源码包,核对包内 SHA256SUMS。需要固定接入版本时,保存所用源码包及其独立摘要。

准备项目

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

使用包内原项目与 Cargo.lock,在指定 examples 目录保存示例。首次编译需要取得锁定依赖;不要通过重建一个空 Cargo 项目丢失原依赖约束。

配置凭据

变量填写方式
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,不能仅凭它判断成功。响应约定见请求与响应约定。

Rust
// Rust 1.88+, trusted server. Save as cloudsign-sdk/rust/examples/example.rs.
use cloudsign_openapi::{Client, Credentials, GetIdentity};
use serde_json::json;
use std::{env, error::Error};

async fn run() -> Result<(), Box<dyn Error>> {
    let origin = env::var("CLOUDSIGN_BASE_URL")?;
    let credentials = Credentials::new(
        env::var("CLOUDSIGN_ACCESS_KEY_ID")?,
        env::var("CLOUDSIGN_ACCESS_KEY_SECRET")?,
        env::var("CLOUDSIGN_SECURITY_TOKEN").ok().filter(|v| !v.is_empty()),
        None,
    )?;
    let client = Client::new(&origin, credentials)?;
    let input: GetIdentity = serde_json::from_value(json!({}))?;
    let result = client.get_identity(&input).await?;
    println!("{}", result.request_id);
    Ok(())
}

#[tokio::main]
async fn main() {
    if let Err(error) = run().await {
        if let Some(api) = error.downcast_ref::<cloudsign_openapi::Error>() {
            eprintln!("HTTP {} {}; RequestId: {}", api.status, api.code, api.request_id.as_deref().unwrap_or(""));
        } else {
            eprintln!("Check SDK path, runtime, environment variables and business input.");
        }
        std::process::exit(1);
    }
}
运行命令
cargo run --locked --manifest-path cloudsign-sdk/rust/Cargo.toml --example 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 示例成功推断所有文件助手都可用。