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

开放 API 快速入门

本页内容

从一次只读请求开始接入。完成本教程后,您可以确认调用身份、查询自己的应用,并继续接入企业签名或应用分发。

选择接入方式

本教程先运行一个只读请求,确认身份和授权,再查询自己的应用。还不清楚 API 应用、业务应用和任务之间的关系时,先阅读基本概念。

服务端项目优先使用对应语言的 SDK,由 SDK 处理请求签名。只想先验证接入时,可以使用本页 Python 标准库示例。网页和手机应用请阅读终端接入指南。

准备账号与凭据

  1. 进入开发者中心,完成 API 接入申请,并创建代表这套接入程序的 API 应用。
  2. 为 API 应用选择需要读取的业务和自己的应用范围。例如,企业签名列表使用 enterprise:ReadApps,普通分发列表使用 distribution:ReadApps。
  3. 创建长期 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.py
Windows 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")

仅保存在终端变量中无法支持进程重启后的恢复。写入前请先阅读目标接口的操作说明;扣款、核销、删除和签名都是真实业务操作。