开放 API 快速入门
本页内容
从一次只读请求开始接入。完成本教程后,您可以确认调用身份、查询自己的应用,并继续接入企业签名或应用分发。
选择接入方式
本教程先运行一个只读请求,确认身份和授权,再查询自己的应用。还不清楚 API 应用、业务应用和任务之间的关系时,先阅读基本概念。
服务端项目优先使用对应语言的 SDK,由 SDK 处理请求签名。只想先验证接入时,可以使用本页 Python 标准库示例。网页和手机应用请阅读终端接入指南。
准备账号与凭据
- 进入开发者中心,完成 API 接入申请,并创建代表这套接入程序的 API 应用。
- 为 API 应用选择需要读取的业务和自己的应用范围。例如,企业签名列表使用
enterprise:ReadApps,普通分发列表使用distribution:ReadApps。 - 创建长期 AccessKey,安全保存 ID 与仅展示一次的 Secret。配置来源 IP 时,填写程序实际使用的出口 IP。
API 应用代表接入程序,企业签名或分发应用代表要管理的业务对象,两者的 ID 不能混用。具体说明见访问权限与资源 ID。
发送第一次请求
下载 cloudsign_request.py 到受信电脑或服务端,在该目录运行下面的命令。示例只查询当前身份,不会创建应用或扣款。
Bash
export CLOUDSIGN_HOST=www.onesignios.com
read -rp 'AccessKey ID: ' CLOUDSIGN_ACCESS_KEY_ID
read -rsp 'AccessKey Secret: ' CLOUDSIGN_ACCESS_KEY_SECRET
printf '\n'
export CLOUDSIGN_ACCESS_KEY_ID CLOUDSIGN_ACCESS_KEY_SECRET
python3 cloudsign_request.pyWindows PowerShell
PowerShell
$env:CLOUDSIGN_HOST = "www.onesignios.com"
$env:CLOUDSIGN_ACCESS_KEY_ID = Read-Host 'AccessKey ID'
$secret = Read-Host 'AccessKey Secret' -AsSecureString
$env:CLOUDSIGN_ACCESS_KEY_SECRET = [System.Net.NetworkCredential]::new('', $secret).Password
python cloudsign_request.py返回 data.owner_id 后,核对账号、data.actions 和 data.resources。出现 401 时,先检查凭据和网站主域名,再按签名指南排查。
查询自己的应用
将下面代码与下载的请求脚本放在同一目录。查询普通分发时,把 module 改为 distribution。
Python 标准库
from cloudsign_request import request
page = request("GET", "/api/v1/apps", {"module": "enterprise", "limit": 10})
for app in page["data"]["items"]:
print(app["id"], app["name"], app["bundle_id"])
# next_cursor 非空时,保持原筛选条件继续查询。开始写入操作
读取正常后,再授予本次业务需要的写入权限。每次独立写操作在首次请求前生成幂等键,并把键、路径和请求内容持久化到业务记录。重试这一次操作时恢复原值,下一项操作使用新值。
Bash:只在开始一项新操作时执行
export CLOUDSIGN_IDEMPOTENCY_KEY="$(python3 -c 'import secrets; print(secrets.token_hex(16))')"PowerShell:只在开始一项新操作时执行
$env:CLOUDSIGN_IDEMPOTENCY_KEY = [guid]::NewGuid().ToString("N")仅保存在终端变量中无法支持进程重启后的恢复。写入前请先阅读目标接口的操作说明;扣款、核销、删除和签名都是真实业务操作。