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

分页查询与等待异步任务

本页内容

列表查询使用游标分页;上传校验和签名通过异步任务处理。保存平台返回的 ID 和游标,可以在中断后继续已有工作。

分页读取列表

应用、版本和任务列表可能分多页返回。如果要同步全部记录,使用平台返回的游标逐页读取;只显示第一页时,无需主动遍历全部记录。

开始前,请按快速入门配置凭据,并确认具有目标列表所需的读取权限。下面以企业签名应用列表为例。

  1. 首次不传 cursor,设置 limit 和所需的业务筛选条件。
  2. 处理本页 data.items。如果 data.next_cursor 不为空,保存它并原样传入下一次请求。
  3. 下一页沿用相同筛选条件和每页条数。只有游标为空,才表示这次遍历已经完成。
  4. 为遍历设置页数和总时长上限。如果中途停止,保存游标及原筛选条件,稍后继续;遇到重复游标时停止并排查。

将 cloudsign_request.py 与 cloudsign_examples.py 保存在同一目录后,运行以下示例:

Python 标准库
from cloudsign_examples import iter_apps
for app in iter_apps("enterprise", limit=50, max_pages=20):
    print(app["id"], app["name"])

正常结束时,示例已经读取完列表;达到 max_pages 时会报告停止位置,不表示全部读取完成。遍历期间记录可能发生变化,长期同步时请按资源 ID 去重。分片列表使用 after / next_after,请以查询已声明分片的定义为准。遇到 InvalidCursor 时重新开始读取并去重,不自行解码或递增游标。

理解任务状态

上传和签名需要平台继续处理,查询请求返回 HTTP 200 时,业务任务可能还在运行。请根据任务状态决定是否进入下一步。

任务成功条件确认成功后
上传任务state=succeeded,并取得非空 version_id。保存原包版本 ID,用于后续签名或发布。文件传输到 100% 仍需等待校验。
签名任务terminal=true 且 status=succeeded。查询本次签名结果,使用其中的签名包版本。

failed、cancelled 和 superseded 都表示任务结束,但不代表成功。等待超时只说明客户端停止等待,不会自动取消服务端任务。

等待与中断恢复

  1. 保存创建任务时返回的业务应用 ID 和任务 ID,后续始终查询同一个任务。
  2. 设置轮询间隔、最大次数和总等待时长,避免一次请求一直占用业务进程。
  3. 读取结束状态。只有确认成功后,才继续签名、下载或发布。
  4. 达到等待上限时,把这次任务交给后续定时查询或 Webhook 处理,不重新创建相同业务任务。

下面使用已经保存的 app_id 和 task_id。签名任务 ID 以 J 开头,上传任务 ID 以 U 开头:

Python 标准库
from cloudsign_examples import wait_task
result = wait_task(app_id, task_id, interval=3, max_attempts=60, timeout=300)
state = result.get("status", result.get("state"))
if state != "succeeded":
    print("任务未成功,请检查状态与错误", state)

助手返回结束状态后,仍须检查业务是否成功。示例中的 429 按 Retry-After 等待,同时受次数和总时长限制;其他错误由调用方按错误处理说明决定下一步。收到结束通知时也应核对资源当前状态,不能把“通知已接收”当成“任务成功”。

查看分页与等待的完整实现
cloudsign_examples.py
"""Save beside cloudsign_request.py as cloudsign_examples.py. Uses read-only requests."""
import argparse
import re
import time

from cloudsign_request import ApiError, request


def iter_apps(module="enterprise", *, limit=50, max_pages=20):
    """Keep module/limit unchanged and send the returned cursor back verbatim."""
    if module not in ("enterprise", "distribution") or not 1 <= limit <= 100 or max_pages < 1:
        raise ValueError("Use a supported module, limit 1..100 and a positive max_pages")
    cursor = None
    seen = set()
    for _ in range(max_pages):
        params = {"module": module, "limit": limit}
        if cursor is not None:
            params["cursor"] = cursor
        data = request("GET", "/api/v1/apps", params)["data"]
        items, next_cursor = data.get("items"), data.get("next_cursor")
        if not isinstance(items, list) or (next_cursor is not None and
                (not isinstance(next_cursor, str) or not re.fullmatch(r"A[a-f0-9]{32}", next_cursor))):
            raise ValueError("Invalid application page")
        if next_cursor is not None and (not items or next_cursor in seen):
            raise ValueError("Pagination cursor did not advance")
        yield from items
        if next_cursor is None:
            return
        seen.add(next_cursor)
        cursor = next_cursor
    raise RuntimeError(f"Stopped at max_pages={max_pages}; next cursor={cursor}")


def wait_task(app_id, task_id, *, timeout=300, interval=3, max_attempts=60):
    """Returns every terminal result, including failures. Check status/state afterwards."""
    if not re.fullmatch(r"A[a-f0-9]{32}", app_id) or not re.fullmatch(r"[JU][a-f0-9]{32}", task_id):
        raise ValueError("Use the complete A ID and J (signing) or U (upload) ID")
    if timeout <= 0 or interval < 1 or max_attempts < 1:
        raise ValueError("Use positive time/attempt limits and interval >= 1 second")
    jobs = task_id.startswith("J")
    resource = f"/api/v1/apps/{app_id}/{'jobs' if jobs else 'uploads'}/{task_id}"
    deadline = time.monotonic() + timeout
    for attempt in range(max_attempts):
        remaining = deadline - time.monotonic()
        if remaining <= 0:
            break
        try:
            data = request("GET", resource, timeout=min(15, remaining))["data"]
        except ApiError as error:
            if error.status != 429:
                raise
            delay = max(interval, error.retry_after)
        else:
            if data.get("app_id") != app_id or data.get("id") != task_id:
                raise ValueError("Response belongs to another application or task")
            state = data.get("status" if jobs else "state")
            terminal = state in {"succeeded", "failed", "cancelled", "superseded"}
            if terminal and (not jobs or data.get("terminal") is True):
                return data
            delay = interval
        remaining = deadline - time.monotonic()
        if attempt + 1 >= max_attempts or delay >= remaining:
            break
        time.sleep(delay)
    raise TimeoutError(f"Polling stopped; query the saved task later: {app_id}/{task_id}")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description=__doc__)
    commands = parser.add_subparsers(dest="operation", required=True)
    apps = commands.add_parser("apps", help="Read all pages within a fixed page limit")
    apps.add_argument("--module", choices=["enterprise", "distribution"], default="enterprise")
    apps.add_argument("--max-pages", type=int, default=20)
    wait = commands.add_parser("wait", help="Wait for a saved J/U task without resubmitting it")
    wait.add_argument("app_id")
    wait.add_argument("task_id")
    args = parser.parse_args()
    try:
        if args.operation == "apps":
            for app in iter_apps(args.module, max_pages=args.max_pages):
                print(app["id"], app["name"])
        else:
            data = wait_task(args.app_id, args.task_id)
            state = data.get("status", data.get("state"))
            if state != "succeeded":
                raise SystemExit(f"Task finished with state={state}; inspect its error field in the console")
            print("succeeded", data["id"], data.get("version_id") or "")
    except (ApiError, ValueError, RuntimeError, TimeoutError) as error:
        raise SystemExit(str(error)) from None

C SDK 分页与等待

使用 C 0.8.0-preview.1 的分页助手可以逐页读取列表,等待助手可以查询一个已经存在的上传或签名任务。它们只发送查询请求,适合后台同步和任务进度检查。

准备运行环境

先按 C SDK 入门下载 C 源码 ZIP并完成编译准备。确保凭据具有对应产品的 ReadApps、ReadUploads 或 ReadJobs 权限,并能访问目标业务应用。示例文件为包内 helpers-example.c。

命令行示例需要哪些配置

这些变量由自己的进程安全配置注入,不把 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。

运行示例

  1. 读取列表时选择 pages;等待签名或上传时,分别选择 waitJob 或 waitUpload。
  2. 等待操作传入原业务应用 ID,以及创建时保存的 J 或 U 任务 ID。
  3. 运行后核对结果和退出码。达到上限时,保存已有 ID,稍后继续查询。
C CLI · 在源码 ZIP 根目录执行
cmake -S . -B build
cmake --build build -j2
./build/cloudsign_helpers_example pages
./build/cloudsign_helpers_example waitJob "<应用ID>" "<签名任务ID>"
./build/cloudsign_helpers_example waitUpload "<应用ID>" "<上传任务ID>"

示例 pages 默认查询企业签名,最多 10 页、总预算 60 秒。如需查询普通分发,将示例源码中的 module 改为 distribution 后重新编译。等待操作最多查询 60 次、间隔 2 秒、总预算 120 秒。这些示例不会提交新的上传、签名或付款,也不会取消服务端任务。

确认执行结果

结果含义下一步
退出码 0列表已遍历完成,或等待的任务已成功。列表结果按 ID 去重保存;任务按对应业务流程继续处理。
退出码 2等待的任务已经结束,但未成功。核对任务的 failed、cancelled 或 superseded 状态,不进入成功分支。
退出码 1 或客户端上限错误查询失败、配置无效,或达到等待上限。保留原资源 ID 和安全错误信息,排查后查询原任务。
分页、等待与内存管理的详细规则
接口用途与边界
cloudsign_pager_create / next支持应用、版本、签名任务和上传记录列表,复制原路径与筛选字符串。配置 1–1000 页、100–600000 ms 总预算;拒绝重复游标和超出 limit 的页。
cloudsign_pager_resume_cursor出错后分页停止,不会隐式重发。先复制返回的游标,再显式创建新 pager,保持原筛选;complete=true 时已完成。
cloudsign_wait_job / upload配置 1–300 次、1–30 秒间隔和最长 600 秒总预算;每次请求收紧到剩余预算。429 / 503 立即交给调用方处理,没有嵌套重试。
完成与成功等待返回 OK 仍可能是 failed、cancelled 或 superseded,须检查终态。示例 CLI 将这些终态以退出码 2 返回,成功为 0,配置 / 协议错误为 1。
取消与生命周期可选回调在请求之间及最长 100 ms 睡眠片段检查;正在执行的同步请求以单次超时和剩余预算为界。回调须有界;客户端须比 pager 存活更久,不可并发重入。

PageLimitExceeded / PollLimitExceeded / DeadlineExceeded 表示客户端停止等待,原资源仍保留。API 失败保留安全状态、错误码和 request_id,不保留错误原文或全量响应。完整 C 接口、释放规则和默认参数见 ZIP 内 README。

查看完整 C 分页与等待示例
helpers-example.c
/* Trusted-server, read-only CLI. Never print full API payloads or credentials. */
#include <cloudsign/openapi.h>
#include <cJSON.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

static int env_copy(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(int argc,char **argv) {
    cloudsign_credentials keys={0};cloudsign_client *client=NULL;
    cloudsign_result *result=NULL;cloudsign_pager *pager=NULL;
    cloudsign_status status=CLOUDSIGN_INVALID_INPUT;int initialized=0,exit_code=1;
    const char *origin=getenv("CLOUDSIGN_BASE_URL");
    int pages=argc==2&&!strcmp(argv[1],"pages");
    int job=argc==4&&!strcmp(argv[1],"waitJob");
    int upload=argc==4&&!strcmp(argv[1],"waitUpload");
    if(!pages&&!job&&!upload){fputs("Usage: cloudsign_helpers_example pages | waitJob APP_ID JOB_ID | waitUpload APP_ID UPLOAD_ID\n",stderr);goto done;}
    if(!origin||!env_copy(keys.access_key_id,sizeof(keys.access_key_id),"CLOUDSIGN_ACCESS_KEY_ID",1)
        ||!env_copy(keys.access_key_secret,sizeof(keys.access_key_secret),"CLOUDSIGN_ACCESS_KEY_SECRET",1)
        ||!env_copy(keys.security_token,sizeof(keys.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=&keys,.timeout_ms=15000};
    status=cloudsign_client_create(&options,&client);cloudsign_credentials_clear(&keys);if(status!=CLOUDSIGN_OK)goto done;
    if(pages){
        cloudsign_param query[]={{"module","enterprise"},{"limit","50"}};
        cloudsign_request request={.query=query,.query_count=2};
        cloudsign_page_options limits={10,60000,NULL,NULL};
        status=cloudsign_pager_create(client,CLOUDSIGN_OP_LIST_APPS,&request,&limits,&pager);if(status!=CLOUDSIGN_OK)goto done;
        while(!cloudsign_pager_is_complete(pager)){
            status=cloudsign_pager_next(pager,&result);if(status!=CLOUDSIGN_OK)goto done;
            puts(cloudsign_result_request_id(result));
            /* Consume the validated page here; do not log its sensitive data. */
            cloudsign_result_free(result);result=NULL;
        }
    }else{
        cloudsign_param path[]={{"app_id",argv[2]},{job?"job_id":"upload_id",argv[3]}};
        cloudsign_request request={.path=path,.path_count=2};
        cloudsign_wait_options limits={60,2000,120000,NULL,NULL};
        status=job?cloudsign_wait_job(client,&request,&limits,&result):cloudsign_wait_upload(client,&request,&limits,&result);
        if(status!=CLOUDSIGN_OK)goto done;
        cJSON *envelope=cJSON_ParseWithLength(cloudsign_result_json(result),cloudsign_result_json_length(result));
        const cJSON *data=cJSON_GetObjectItemCaseSensitive(envelope,"data");
        const cJSON *state=cJSON_GetObjectItemCaseSensitive(data,job?"status":"state");
        if(!cJSON_IsString(state)){cJSON_Delete(envelope);status=CLOUDSIGN_INVALID_RESPONSE;goto done;}
        printf("%s %s\n",cloudsign_result_request_id(result),state->valuestring);
        int succeeded=!strcmp(state->valuestring,"succeeded");cJSON_Delete(envelope);
        if(!succeeded){exit_code=2;goto done;} /* Terminal is not necessarily success. */
    }
    exit_code=0;
done:
    if(exit_code==1)fprintf(stderr,"%s %s; RequestId: %s\n",cloudsign_status_name(status),cloudsign_result_error_code(result),cloudsign_result_request_id(result));
    cloudsign_result_free(result);cloudsign_pager_free(pager);cloudsign_client_free(client);
    cloudsign_credentials_clear(&keys);if(initialized)cloudsign_global_cleanup();return exit_code;
}