分页查询与等待异步任务
本页内容
列表查询使用游标分页;上传校验和签名通过异步任务处理。保存平台返回的 ID 和游标,可以在中断后继续已有工作。
分页读取列表
应用、版本和任务列表可能分多页返回。如果要同步全部记录,使用平台返回的游标逐页读取;只显示第一页时,无需主动遍历全部记录。
开始前,请按快速入门配置凭据,并确认具有目标列表所需的读取权限。下面以企业签名应用列表为例。
- 首次不传
cursor,设置limit和所需的业务筛选条件。 - 处理本页
data.items。如果data.next_cursor不为空,保存它并原样传入下一次请求。 - 下一页沿用相同筛选条件和每页条数。只有游标为空,才表示这次遍历已经完成。
- 为遍历设置页数和总时长上限。如果中途停止,保存游标及原筛选条件,稍后继续;遇到重复游标时停止并排查。
将 cloudsign_request.py 与 cloudsign_examples.py 保存在同一目录后,运行以下示例:
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 都表示任务结束,但不代表成功。等待超时只说明客户端停止等待,不会自动取消服务端任务。
等待与中断恢复
- 保存创建任务时返回的业务应用 ID 和任务 ID,后续始终查询同一个任务。
- 设置轮询间隔、最大次数和总等待时长,避免一次请求一直占用业务进程。
- 读取结束状态。只有确认成功后,才继续签名、下载或发布。
- 达到等待上限时,把这次任务交给后续定时查询或 Webhook 处理,不重新创建相同业务任务。
下面使用已经保存的 app_id 和 task_id。签名任务 ID 以 J 开头,上传任务 ID 以 U 开头:
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 等待,同时受次数和总时长限制;其他错误由调用方按错误处理说明决定下一步。收到结束通知时也应核对资源当前状态,不能把“通知已接收”当成“任务成功”。
查看分页与等待的完整实现
"""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。 |
运行示例
- 读取列表时选择
pages;等待签名或上传时,分别选择waitJob或waitUpload。 - 等待操作传入原业务应用 ID,以及创建时保存的 J 或 U 任务 ID。
- 运行后核对结果和退出码。达到上限时,保存已有 ID,稍后继续查询。
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 分页与等待示例
/* 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;
}