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

创建上传任务

本页内容

创建上传任务,用于向指定应用上传一个安装包。

适用场景

首次上传或更新安装包时使用。任务创建后,再申请上传凭证并传输文件。

选择上传方式

推荐直接调用 SDK 上传助手,提交应用 ID、文件和本次操作的幂等键即可。平台自动选择文件传输服务,SDK 自动申请上传凭证、切分文件并确认结果;业务代码无需判断存储厂商或填写后台存储配置。

上传助手使用通用分片流程,小文件只传一片,大文件按接口返回的大小分片。需要自行实现 HTTP 客户端时,按下表选择传输方式。

上传方式适用场景处理方式
分片上传(推荐)首次接入、小文件、大文件和断点续传。创建分片上传任务,按返回指令传输并确认。SDK 上传助手会自动完成这些步骤。
整包上传(可选)已有整包上传集成,且当前接口支持此方式。申请整包上传凭证并发送整个文件。若返回 StorageUnsupported,改用通用分片流程,无需识别底层存储。

一个上传任务对应一个安装包。可上传的大小以账号限额和接口返回值为准。创建成功后立即保存上传任务 ID,即响应中的 data.id。中断后保留原文件和幂等键,继续处理同一个上传任务。

首次接入可先阅读上传安装包,了解完整流程。

开始前

请先在开发者中心完成 API 接入配置,并为目标应用授予本次操作所需的权限。尚未完成首次调用时,请先阅读快速开始。

  • 保留创建或更新所需的应用 ID,确认安装包未再变化。整包上传准备整个文件的大小、MD5 和 SHA-256。
  • 选择分片上传时,先读取任务返回的分片大小和数量,再按此切片;不要自行假定分片布局。
所需权限
enterprise:UploadVersions 或 distribution:UploadVersions,账号须已开放写入
认证方式
长期 AccessKey(AKP),或获独立终端写入授权的 OAuth Bearer。OAuth 仅操作已存在且已获用户授权的应用

权限、应用范围和来源 IP 均需符合接入配置。详细说明见访问权限。

调用步骤

  1. 确定上传方式,并准备文件信息。
  2. 提交请求后,立即保存上传任务 ID 和本次幂等键。
  3. 使用同一上传任务申请上传凭证并完成文件传输。

文件传输结束后调用 提交安装包校验,再查询任务确认版本已经保存。

请求方式

POST /api/v1/apps/{app_id}/uploads
操作标识
createUpload
请求域名
https://www.onesignios.com
频率限制
账号与 API 应用的额度同时生效。达到限额时按 Retry-After 等待。

请求参数

字段必填说明
app_id 是

业务应用的完整 ID,来自列出应用或预留新应用的响应。

类型:string · 位置:Path

查看取值约束
  • 格式 ^A[a-f0-9]{32}$

示例:A11111111111111111111111111111111

AccessKey 认证请求头

下表适用于 AccessKey 调用,由服务端 SDK 自动生成。使用长期或临时凭据自行实现 HTTP 调用时,请按照请求签名说明处理。

字段必填说明
Authorization 是

AccessKey 调用的认证签名,格式为 CS1-HMAC-SHA256 Credential=密钥ID,Signature=签名。使用 SDK 时自动生成。

类型:string · 位置:Header

Content-Type 是

传 application/json,可附 charset=utf-8。

类型:string · 位置:Header

X-Api-Date 是

UTC 时间,格式 YYYY-MM-DDTHH:mm:ssZ。与服务器的时间偏差最多 300 秒。

类型:string · 位置:Header

查看取值约束
  • 数据格式 date-time
X-Api-Nonce 是

每次请求生成 16 个随机字节,转为 32 位小写十六进制。重试时重新生成。

类型:string · 位置:Header

查看取值约束
  • 格式 ^[a-f0-9]{32}$
X-Api-Content-Sha256 是

实际发送的正文原始字节的 SHA-256 小写十六进制。GET 计算空字节串。

类型:string · 位置:Header

查看取值约束
  • 格式 ^[a-f0-9]{64}$
X-Api-Environment 是

生产环境传 production。

类型:string · 位置:Header

查看取值约束
  • 固定值 production
X-Api-Idempotency-Key 是

同一次业务重试保持原值及原始请求体,更换 nonce 重新签名。有效记录保留 90 天。

类型:string · 位置:Header

查看取值约束
  • 格式 ^[A-Za-z0-9_-]{16,64}$

使用获准的 OAuth 调用时,发送 Authorization: Bearer <access_token>,不发送 AccessKey 的日期、nonce、正文摘要、环境或安全令牌头。POST 仍需 JSON 和幂等键,具体范围以本接口的认证要求为准。查看认证方式对照。

请求体

请求体使用 application/json,最多 16 KiB。请为本次操作保存幂等键,重试时复用原值。

分片上传

字段必填说明
file_name 是

原始安装包的文件名,扩展名应与目标应用平台一致。

类型:string

查看取值约束

IPA 文件名

  • 最多字符 160
  • 格式 ^[^/\\:]+\.(?:ipa|apk)$

示例:example.apk

size_bytes 是

文件大小,单位为字节。

类型:integer

查看取值约束
  • 最小值 22
  • 最大值 17179869184

示例:1000

transfer_mode 是

固定填写 multipart,使用通用分片上传流程,无需根据底层存储选择其他值。

类型:string

查看取值约束
  • 固定值 multipart

示例:multipart

整包上传

字段必填说明
file_name 是

原始安装包的文件名,扩展名应与目标应用平台一致。

类型:string

查看取值约束

IPA 文件名

  • 最多字符 160
  • 格式 ^[^/\\:]+\.(?:ipa|apk)$

示例:测试.ipa

size_bytes 是

文件大小,单位为字节。

类型:integer

查看取值约束
  • 最小值 22
  • 最大值 5368709120

示例:1000

sha256 是

整个安装包实际字节的 SHA-256,使用 64 位小写十六进制文本。

类型:string

查看取值约束
  • 格式 ^[a-f0-9]{64}$

示例:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

md5 是

整个安装包 MD5 的原始 16 字节经标准 Base64 编码后的值,不传十六进制文本。

类型:string

查看取值约束

16 字节 MD5 的标准 Base64

示例:YmJiYmJiYmJiYmJiYmJiYg==

成功响应

HTTP 200 返回 JSON。请记录 request_id,排查问题时可提供此值。查看成功、失败与异步结果的区别。

如何判断结果

立即保存上传任务 ID,即响应中的 data.id,以及 transfer_mode 和 expires_at。创建上传任务尚未保存安装包版本。

推荐调用 SDK 上传助手,自动完成分片、传输和确认,无需选择或配置存储。自行实现 HTTP 时,整包上传继续申请 获取整包上传凭证,分片上传逐片申报和传输。

返回字段

字段按对象层级列出,[] 表示数组元素。“必返”指该对象出现时字段是否必须存在,值仍可能允许为 null;具体类型见展开说明。

字段必返说明
request_id 是

平台生成的请求标识。排查问题时请提供此值。

类型:string

查看取值约束
  • 格式 ^[a-f0-9]{32}$

示例:00000000000000000000000000000000

data 是

本次调用的业务结果,结构取决于操作。

类型:object

data.id 是

上传任务 ID,与创建上传任务响应中的 data.id 相同。创建后立即保存;查询进度、申请上传凭证和恢复上传都使用这个完整 ID。

类型:string

查看取值约束
  • 格式 ^U[a-f0-9]{32}$

示例:U88888888888888888888888888888888

data.app_id 是

业务应用的完整 ID,来自列出应用或预留新应用的响应。

类型:string

查看取值约束
  • 格式 ^A[a-f0-9]{32}$

示例:A11111111111111111111111111111111

data.state 是

当前记录的处理状态或请求筛选的状态。

类型:string

查看取值约束
  • 可选值 uploading / validating / succeeded / failed / cancelled
  • uploading — 等待或正在上传
  • validating — 后台校验中
  • succeeded — 处理成功
  • failed — 处理失败
  • cancelled — 已取消

示例:uploading

data.size_bytes 是

文件大小,单位为字节。

类型:integer

查看取值约束
  • 最小值 22

示例:1000

data.expires_at 是

上传任务的有效截止时间,Unix 秒;上传凭证还有自己的有效期。

类型:integer

查看示例

示例:1794000000

data.version_id 是

上传校验成功后保存的版本 ID。尚未成功时按返回的空值处理。

类型:string | null

查看取值约束
  • 格式 ^V[a-f0-9]{32}$

示例:null

data.error_code 是

上传任务失败的业务原因。查询请求可正常返回 HTTP 200,仍需检查 state。

类型:string | null

查看示例

示例:null

data.transfer_mode 否

single 为整包上传,multipart 为分片上传。

类型:string

查看取值约束
  • 可选值 single / multipart
  • single — 整包上传
  • multipart — 分片上传

示例:multipart

data.format 否

接口返回的文件格式。

类型:string

查看取值约束
  • 可选值 ipa / apk

示例:apk

data.part_size_bytes 否

分片字节数。按此大小切分文件,最后一片使用剩余字节。

类型:integer

查看取值约束
  • 最小值 0

示例:33554432

data.part_count 否

分片总数,整包上传为 0。

类型:integer

查看取值约束
  • 最小值 0
  • 最大值 1024

示例:1

调用示例

请把示例中的应用 ID、上传任务 ID和业务数据替换为自己账号的真实返回值,再选择一种语言运行。安装、文件放置和 CLOUDSIGN_BASE_URL 等配置见SDK 使用说明。

下载示例依赖

Python 标准库示例使用 cloudsign_request.py;使用 SDK 时仅需准备所选语言。长期 Secret 保存在服务端,浏览器和移动端使用OAuth 授权。

运行前先配置 CLOUDSIGN_IDEMPOTENCY_KEY 并持久保存,它代表这一次写入。网络重试沿用原值,开始另一项操作时生成新值。查看生成命令与运行准备 →

分片上传
HTTP 请求
POST /api/v1/apps/A11111111111111111111111111111111/uploads HTTP/1.1
Host: www.onesignios.com
Authorization: CS1-HMAC-SHA256 Credential=<AccessKey ID>,Signature=<签名>
X-Api-Date: <当前 UTC 时间>
X-Api-Nonce: <新生成的 32 位十六进制值>
X-Api-Content-Sha256: <正文摘要>
X-Api-Environment: production
Content-Type: application/json
X-Api-Idempotency-Key: <本次业务保存的幂等键>

{
    "file_name": "example.apk",
    "size_bytes": 1000,
    "transfer_mode": "multipart"
}
Python 标准库调用
Python
from cloudsign_request import request
import os

result = request(
    'POST',
    '/api/v1/apps/A11111111111111111111111111111111/uploads',
    payload={'file_name': 'example.apk', 'size_bytes': 1000, 'transfer_mode': 'multipart'},
    idempotency_key=os.environ["CLOUDSIGN_IDEMPOTENCY_KEY"],
)
print(result["request_id"])
Python SDK 调用
Python SDK
import os
from cloudsign import Client

client = Client(
    "https://www.onesignios.com",
    os.environ["CLOUDSIGN_ACCESS_KEY_ID"],
    os.environ["CLOUDSIGN_ACCESS_KEY_SECRET"],
    os.environ.get("CLOUDSIGN_SECURITY_TOKEN", ""),
)

result = client.create_multipart_upload(
    app='A11111111111111111111111111111111',
    file_name='example.apk',
    size_bytes=1000,
    idempotency_key=os.environ["CLOUDSIGN_IDEMPOTENCY_KEY"],
)
print(result["request_id"])
PHP SDK 调用
PHP SDK
<?php
declare(strict_types=1);

// Extract the PHP SDK source ZIP beside this file. Keep credentials on your server.
require_once __DIR__ . '/cloudsign-sdk/php/Client.php';
$requiredEnv = static function (string $name): string {
    $value = getenv($name);
    if ($value === false || $value === '') { throw new RuntimeException('Missing environment variable'); }
    return $value;
};
try {
    $client = new \Cloudsign\Sdk\Client(
        $requiredEnv('CLOUDSIGN_BASE_URL'),
        $requiredEnv('CLOUDSIGN_ACCESS_KEY_ID'),
        $requiredEnv('CLOUDSIGN_ACCESS_KEY_SECRET'),
        getenv('CLOUDSIGN_SECURITY_TOKEN') ?: '',
    );
    $result = $client->createMultipartUpload(
        'A11111111111111111111111111111111',
        'example.apk',
        1000,
        $requiredEnv('CLOUDSIGN_IDEMPOTENCY_KEY')
    );
    echo $result['request_id'], PHP_EOL;
} catch (\Cloudsign\Sdk\ApiError $error) {
    fwrite(STDERR, 'HTTP ' . $error->status . ' ' . $error->apiCode . '; RequestId: ' . $error->requestId . PHP_EOL);
    exit(1);
} catch (Throwable $error) {
    fwrite(STDERR, "Check SDK path, runtime and environment variables.\n");
    exit(1);
}
Node.js SDK 调用
Node.js SDK
// Node.js 20+ on a trusted server. Do not bundle this SDK in browsers or Vue.
import { ApiError, Client } from './cloudsign-sdk/node/client.mjs';

const requiredEnv = name => {
    const value = process.env[name];
    if (!value) throw new Error('Missing environment variable');
    return value;
};
try {
    const client = new Client(
        requiredEnv('CLOUDSIGN_BASE_URL'),
        requiredEnv('CLOUDSIGN_ACCESS_KEY_ID'),
        requiredEnv('CLOUDSIGN_ACCESS_KEY_SECRET'),
        process.env.CLOUDSIGN_SECURITY_TOKEN || '',
    );
    const result = await client.createMultipartUpload(
        "A11111111111111111111111111111111",
        { fileName: "example.apk", sizeBytes: 1000 },
        requiredEnv('CLOUDSIGN_IDEMPOTENCY_KEY')
    );
    console.log(result.request_id);
} catch (error) {
    if (error instanceof ApiError) console.error(`HTTP ${error.status} ${error.code}; RequestId: ${error.requestId}`);
    else console.error('Check SDK path, runtime and environment variables.');
    process.exitCode = 1;
}
Go SDK 调用
Go SDK
// Go 1.22+, trusted server. Extract the Go SDK ZIP beside example.go.
package main

import (
    "context"
    "errors"
    "fmt"
    "os"
    "time"

    cloudsign "cloudsign/sdk"
)

func main() {
    fail := func(err error) {
        var api *cloudsign.APIError
        if errors.As(err, &api) {
            fmt.Fprintf(os.Stderr, "HTTP %d %s; RequestId: %s\n", api.Status, api.Code, api.RequestID)
        } else {
            fmt.Fprintln(os.Stderr, "Check SDK path, runtime and environment variables.")
        }
        os.Exit(1)
    }
    client, err := cloudsign.New(
        os.Getenv("CLOUDSIGN_BASE_URL"),
        os.Getenv("CLOUDSIGN_ACCESS_KEY_ID"),
        os.Getenv("CLOUDSIGN_ACCESS_KEY_SECRET"),
        os.Getenv("CLOUDSIGN_SECURITY_TOKEN"),
    )
    if err != nil { fail(err); return }
    ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
    defer cancel()
    result, err := client.CreateMultipartUpload(
		ctx,
		"A11111111111111111111111111111111",
		"example.apk",
		1000,
		os.Getenv("CLOUDSIGN_IDEMPOTENCY_KEY"),
	)
    if err != nil { fail(err); return }
    fmt.Println(result.RequestID)
}
Java SDK 调用
Java SDK
// Java 17+, server-side. Extract the Java SDK ZIP beside Example.java.
import com.cloudsign.openapi.Client;
import java.util.*;

public class Example {
    private static String env(String name) {
        String value = System.getenv(name);
        if (value == null || value.isEmpty()) throw new IllegalArgumentException("Missing environment variable");
        return value;
    }
    private static Map<String,Object> object(Object... pairs) {
        var result = new LinkedHashMap<String,Object>();
        for (int i = 0; i < pairs.length; i += 2) result.put((String)pairs[i], pairs[i+1]);
        return result;
    }
    public static void main(String[] args) {
        try {
            var client = new Client(
                env("CLOUDSIGN_BASE_URL"),
                env("CLOUDSIGN_ACCESS_KEY_ID"),
                env("CLOUDSIGN_ACCESS_KEY_SECRET"),
                System.getenv().getOrDefault("CLOUDSIGN_SECURITY_TOKEN", "")
            );
            var result = client.createMultipartUpload(
                "A11111111111111111111111111111111",
                "example.apk",
                1000,
                env("CLOUDSIGN_IDEMPOTENCY_KEY")
            );
            System.out.println(result.requestId());
        } catch (Client.ApiException error) {
            System.err.printf("HTTP %d %s; RequestId: %s%n", error.status, error.code, error.requestId);
            System.exit(1);
        } catch (Exception error) {
            if (error instanceof InterruptedException) Thread.currentThread().interrupt();
            System.err.println("Check SDK path, runtime and environment variables.");
            System.exit(1);
        }
    }
}
Rust SDK 调用
Rust SDK
// Rust 1.88+, trusted server. Save as cloudsign-sdk/rust/examples/example.rs.
use cloudsign_openapi::{Client, Credentials, CreateUpload};
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: CreateUpload = serde_json::from_value(json!({
        "app_id": "A11111111111111111111111111111111",
        "body": {"file_name": "example.apk", "size_bytes": 1000i64, "transfer_mode": "multipart"},
        "idempotency_key": env::var("CLOUDSIGN_IDEMPOTENCY_KEY")?
    }))?;
    let result = client.create_upload(&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);
    }
}
C SDK 调用

请求对象和响应对象的使用方式见C SDK 请求与响应。

C SDK
/* 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_multipart_upload_input input_value_3 = {.presence_file_name = CLOUDSIGN_FIELD_VALUE, .file_name = "example.apk", .presence_size_bytes = CLOUDSIGN_FIELD_VALUE, .size_bytes = INT64_C(1000), .presence_transfer_mode = CLOUDSIGN_FIELD_VALUE, .transfer_mode = "multipart"};
    const cloudsign_input_create_upload_body input_value_2 = {.kind = CLOUDSIGN_INPUT_CREATE_UPLOAD_BODY_VARIANT_2, .value.variant_2 = &input_value_3};
    const cloudsign_input_create_upload input = {.presence_app_id = CLOUDSIGN_FIELD_VALUE, .app_id = "A11111111111111111111111111111111", .presence_body = CLOUDSIGN_FIELD_VALUE, .body = &input_value_2, .presence_idempotency_key = CLOUDSIGN_FIELD_VALUE, .idempotency_key = getenv("CLOUDSIGN_IDEMPOTENCY_KEY")};
    status = cloudsign_build_create_upload(&input, &built);
    if (status != CLOUDSIGN_OK) goto done;
    status = cloudsign_send_built_request(client, built, &result);
    if (status == CLOUDSIGN_OK) {
        status = cloudsign_decode_create_upload(result, &decoded);
        if (status != CLOUDSIGN_OK) goto done;
        const cloudsign_model_upload *data = cloudsign_response_create_upload(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;
}
JSON 响应
{
    "request_id": "00000000000000000000000000000000",
    "data": {
        "id": "U88888888888888888888888888888888",
        "app_id": "A11111111111111111111111111111111",
        "state": "uploading",
        "size_bytes": 1000,
        "expires_at": 1794000000,
        "version_id": null,
        "error_code": null,
        "transfer_mode": "multipart",
        "format": "apk",
        "part_size_bytes": 33554432,
        "part_count": 1
    }
}
整包上传
HTTP 请求
POST /api/v1/apps/A11111111111111111111111111111111/uploads HTTP/1.1
Host: www.onesignios.com
Authorization: CS1-HMAC-SHA256 Credential=<AccessKey ID>,Signature=<签名>
X-Api-Date: <当前 UTC 时间>
X-Api-Nonce: <新生成的 32 位十六进制值>
X-Api-Content-Sha256: <正文摘要>
X-Api-Environment: production
Content-Type: application/json
X-Api-Idempotency-Key: <本次业务保存的幂等键>

{
    "file_name": "测试.ipa",
    "size_bytes": 1000,
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "md5": "YmJiYmJiYmJiYmJiYmJiYg=="
}
Python 标准库调用
Python
from cloudsign_request import request
import os

result = request(
    'POST',
    '/api/v1/apps/A11111111111111111111111111111111/uploads',
    payload={'file_name': '测试.ipa',
 'size_bytes': 1000,
 'sha256': 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
 'md5': 'YmJiYmJiYmJiYmJiYmJiYg=='},
    idempotency_key=os.environ["CLOUDSIGN_IDEMPOTENCY_KEY"],
)
print(result["request_id"])
Python SDK 调用
Python SDK
import os
from cloudsign import Client

client = Client(
    "https://www.onesignios.com",
    os.environ["CLOUDSIGN_ACCESS_KEY_ID"],
    os.environ["CLOUDSIGN_ACCESS_KEY_SECRET"],
    os.environ.get("CLOUDSIGN_SECURITY_TOKEN", ""),
)

result = client.create_upload(
    app='A11111111111111111111111111111111',
    file_name='测试.ipa',
    size_bytes=1000,
    sha256='aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
    md5='YmJiYmJiYmJiYmJiYmJiYg==',
    idempotency_key=os.environ["CLOUDSIGN_IDEMPOTENCY_KEY"],
)
print(result["request_id"])
PHP SDK 调用
PHP SDK
<?php
declare(strict_types=1);

// Extract the PHP SDK source ZIP beside this file. Keep credentials on your server.
require_once __DIR__ . '/cloudsign-sdk/php/Client.php';
$requiredEnv = static function (string $name): string {
    $value = getenv($name);
    if ($value === false || $value === '') { throw new RuntimeException('Missing environment variable'); }
    return $value;
};
try {
    $client = new \Cloudsign\Sdk\Client(
        $requiredEnv('CLOUDSIGN_BASE_URL'),
        $requiredEnv('CLOUDSIGN_ACCESS_KEY_ID'),
        $requiredEnv('CLOUDSIGN_ACCESS_KEY_SECRET'),
        getenv('CLOUDSIGN_SECURITY_TOKEN') ?: '',
    );
    $result = $client->createUpload(
        'A11111111111111111111111111111111',
        '测试.ipa',
        1000,
        'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
        'YmJiYmJiYmJiYmJiYmJiYg==',
        $requiredEnv('CLOUDSIGN_IDEMPOTENCY_KEY')
    );
    echo $result['request_id'], PHP_EOL;
} catch (\Cloudsign\Sdk\ApiError $error) {
    fwrite(STDERR, 'HTTP ' . $error->status . ' ' . $error->apiCode . '; RequestId: ' . $error->requestId . PHP_EOL);
    exit(1);
} catch (Throwable $error) {
    fwrite(STDERR, "Check SDK path, runtime and environment variables.\n");
    exit(1);
}
Node.js SDK 调用
Node.js SDK
// Node.js 20+ on a trusted server. Do not bundle this SDK in browsers or Vue.
import { ApiError, Client } from './cloudsign-sdk/node/client.mjs';

const requiredEnv = name => {
    const value = process.env[name];
    if (!value) throw new Error('Missing environment variable');
    return value;
};
try {
    const client = new Client(
        requiredEnv('CLOUDSIGN_BASE_URL'),
        requiredEnv('CLOUDSIGN_ACCESS_KEY_ID'),
        requiredEnv('CLOUDSIGN_ACCESS_KEY_SECRET'),
        process.env.CLOUDSIGN_SECURITY_TOKEN || '',
    );
    const result = await client.createUpload(
        "A11111111111111111111111111111111",
        { fileName: "测试.ipa", sizeBytes: 1000, sha256: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", md5: "YmJiYmJiYmJiYmJiYmJiYg==" },
        requiredEnv('CLOUDSIGN_IDEMPOTENCY_KEY')
    );
    console.log(result.request_id);
} catch (error) {
    if (error instanceof ApiError) console.error(`HTTP ${error.status} ${error.code}; RequestId: ${error.requestId}`);
    else console.error('Check SDK path, runtime and environment variables.');
    process.exitCode = 1;
}
Go SDK 调用
Go SDK
// Go 1.22+, trusted server. Extract the Go SDK ZIP beside example.go.
package main

import (
    "context"
    "errors"
    "fmt"
    "os"
    "time"

    cloudsign "cloudsign/sdk"
)

func main() {
    fail := func(err error) {
        var api *cloudsign.APIError
        if errors.As(err, &api) {
            fmt.Fprintf(os.Stderr, "HTTP %d %s; RequestId: %s\n", api.Status, api.Code, api.RequestID)
        } else {
            fmt.Fprintln(os.Stderr, "Check SDK path, runtime and environment variables.")
        }
        os.Exit(1)
    }
    client, err := cloudsign.New(
        os.Getenv("CLOUDSIGN_BASE_URL"),
        os.Getenv("CLOUDSIGN_ACCESS_KEY_ID"),
        os.Getenv("CLOUDSIGN_ACCESS_KEY_SECRET"),
        os.Getenv("CLOUDSIGN_SECURITY_TOKEN"),
    )
    if err != nil { fail(err); return }
    ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
    defer cancel()
    result, err := client.CreateUpload(
		ctx,
		"A11111111111111111111111111111111",
		"测试.ipa",
		1000,
		"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
		"YmJiYmJiYmJiYmJiYmJiYg==",
		os.Getenv("CLOUDSIGN_IDEMPOTENCY_KEY"),
	)
    if err != nil { fail(err); return }
    fmt.Println(result.RequestID)
}
Java SDK 调用
Java SDK
// Java 17+, server-side. Extract the Java SDK ZIP beside Example.java.
import com.cloudsign.openapi.Client;
import java.util.*;

public class Example {
    private static String env(String name) {
        String value = System.getenv(name);
        if (value == null || value.isEmpty()) throw new IllegalArgumentException("Missing environment variable");
        return value;
    }
    private static Map<String,Object> object(Object... pairs) {
        var result = new LinkedHashMap<String,Object>();
        for (int i = 0; i < pairs.length; i += 2) result.put((String)pairs[i], pairs[i+1]);
        return result;
    }
    public static void main(String[] args) {
        try {
            var client = new Client(
                env("CLOUDSIGN_BASE_URL"),
                env("CLOUDSIGN_ACCESS_KEY_ID"),
                env("CLOUDSIGN_ACCESS_KEY_SECRET"),
                System.getenv().getOrDefault("CLOUDSIGN_SECURITY_TOKEN", "")
            );
            var result = client.createUpload(
                "A11111111111111111111111111111111",
                "测试.ipa",
                1000,
                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                "YmJiYmJiYmJiYmJiYmJiYg==",
                env("CLOUDSIGN_IDEMPOTENCY_KEY")
            );
            System.out.println(result.requestId());
        } catch (Client.ApiException error) {
            System.err.printf("HTTP %d %s; RequestId: %s%n", error.status, error.code, error.requestId);
            System.exit(1);
        } catch (Exception error) {
            if (error instanceof InterruptedException) Thread.currentThread().interrupt();
            System.err.println("Check SDK path, runtime and environment variables.");
            System.exit(1);
        }
    }
}
Rust SDK 调用
Rust SDK
// Rust 1.88+, trusted server. Save as cloudsign-sdk/rust/examples/example.rs.
use cloudsign_openapi::{Client, Credentials, CreateUpload};
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: CreateUpload = serde_json::from_value(json!({
        "app_id": "A11111111111111111111111111111111",
        "body": {"file_name": "测试.ipa", "size_bytes": 1000i64, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "md5": "YmJiYmJiYmJiYmJiYmJiYg=="},
        "idempotency_key": env::var("CLOUDSIGN_IDEMPOTENCY_KEY")?
    }))?;
    let result = client.create_upload(&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);
    }
}
C SDK 调用

请求对象和响应对象的使用方式见C SDK 请求与响应。

C SDK
/* 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_upload_input input_value_3 = {.presence_file_name = CLOUDSIGN_FIELD_VALUE, .file_name = "测试.ipa", .presence_size_bytes = CLOUDSIGN_FIELD_VALUE, .size_bytes = INT64_C(1000), .presence_sha256 = CLOUDSIGN_FIELD_VALUE, .sha256 = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", .presence_md5 = CLOUDSIGN_FIELD_VALUE, .md5 = "YmJiYmJiYmJiYmJiYmJiYg=="};
    const cloudsign_input_create_upload_body input_value_2 = {.kind = CLOUDSIGN_INPUT_CREATE_UPLOAD_BODY_VARIANT_1, .value.variant_1 = &input_value_3};
    const cloudsign_input_create_upload input = {.presence_app_id = CLOUDSIGN_FIELD_VALUE, .app_id = "A11111111111111111111111111111111", .presence_body = CLOUDSIGN_FIELD_VALUE, .body = &input_value_2, .presence_idempotency_key = CLOUDSIGN_FIELD_VALUE, .idempotency_key = getenv("CLOUDSIGN_IDEMPOTENCY_KEY")};
    status = cloudsign_build_create_upload(&input, &built);
    if (status != CLOUDSIGN_OK) goto done;
    status = cloudsign_send_built_request(client, built, &result);
    if (status == CLOUDSIGN_OK) {
        status = cloudsign_decode_create_upload(result, &decoded);
        if (status != CLOUDSIGN_OK) goto done;
        const cloudsign_model_upload *data = cloudsign_response_create_upload(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;
}
JSON 响应
{
    "request_id": "00000000000000000000000000000000",
    "data": {
        "id": "U88888888888888888888888888888888",
        "app_id": "A11111111111111111111111111111111",
        "state": "uploading",
        "size_bytes": 1000,
        "expires_at": 1794000000,
        "version_id": null,
        "error_code": null
    }
}

错误处理

失败或中断后

创建响应丢失时用原参数和原幂等键恢复,或通过 列出应用上传任务 查找原任务。文件内容变了应开始新任务,不沿用旧摘要。

相关错误码

HTTP错误码处理方式
429UploadLimit上传并发名额用尽。先完成已有上传,按退避时间重试。
422QuotaExceeded文件大小或账号可用空间不足。核对上传上限和剩余空间。
422StorageUnsupported当前请求的文件传输方式不可用。上传请使用 SDK 上传助手或通用分片流程,无需选择存储厂商;下载请保留 request_id 联系平台。
409CreationConflict应用预留已过期、已完成或已有上传任务。先查询应用创建状态与原上传任务,再决定是否重新创建应用预留。
409IdempotencyConflict同一个幂等键用于不同请求。恢复原请求的正文与路径。独立的新业务操作使用新键。
401InvalidCredentials凭据无效、已停用,或请求签名不匹配。核对 AK、环境、正文摘要和签名头。
429Throttled请求达到限额,按 Retry-After 返回的秒数等待,再以新 nonce 发起请求。
公共错误、重试与幂等说明 →