<h1 style="text-align:left;" size="0" _root="undefined" __ownerid="undefined" __hash="undefined" __altered="false">通用签名步骤详细说明</h1>一个完整的创宇 API 请求需要两类请求参数：公共请求参数和接口请求参数。本文将介绍创宇 API 请求需要用到的5个公共请求参数，有关接口请求参数的详细说明请参见具体服务接口章节。公共请求参数是每个接口都需要使用到的请求参数，开发者每次使用创宇 API 发送请求时都需要携带这些公共请求参数，否则会导致请求失败。<h2>1.前言</h2> a. 线上对接地址：https://tianyu.yunaq.com/ b.涉及变量解释<table ><tr><td style="text-align:left;" colSpan="1" rowSpan="1">appid</td><td style="text-align:left;" colSpan="1" rowSpan="1">用戶唯一 appid ,用户在<a href="https://console.yunaq.com/profile/config" target="_blank">控制台</a>上传 RSA 公钥时生成</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">nonce_str</td><td style="text-align:left;" colSpan="1" rowSpan="1">用户可自定义随机字符串，与 timestamp 联合起来， 用于防止重放攻击。</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">timestamp</td><td style="text-align:left;" colSpan="1" rowSpan="1">毫秒级时间戳,若与服务器当前时间相差 5 分钟则无效</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">content</td><td style="text-align:left;" colSpan="1" rowSpan="1">业务参数 JSON 序列化后得到的字符串</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">sign</td><td style="text-align:left;" colSpan="1" rowSpan="1">请求签名，用来验证此次请求的合法性，需要用户根据实际的输入参数计算得出。计算方法可参考签名章节</td></tr></table><h2>完整服务请求示例：</h2><pre><code>curl --request POST &#x27;https://sec.yunaq.com/api/*&#x27; \ --header &#x27;sign: your sign&#x27; \ --header &#x27;Content-Type: application/json&#x27; \ --data-raw &#x27;{ &quot;appid&quot;:&quot;&quot;, &quot;nonce_str&quot;: &quot;&quot;, &quot;timestamp&quot;: &quot;&quot;, &quot;content&quot;: &quot;contentStr&quot;, }&#x27;</code></pre><h2>2.准备工作</h2>1. 本地生成一对秘钥( RSA2048 以上) 例：<pre><code>#生成私钥 $ openssl genrsa -out rsa_private_key.pem 2048 #生成公钥 $ openssl rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem</code></pre>2. 上传用戶本地公钥 请在<a href="https://console.yunaq.com/profile/config">用户控制台</a>中完成密钥上传部分，上传你您的 RSA 公钥。3. JSON序列化业务参数（序列化后，应无“：”“，”空格与unicode字符串）<pre><code>const content = &quot;{\&quot;name\&quot;:\&quot;kl\&quot;,\&quot;age\&quot;:18}&quot;; // 将业务参数 JSON 序列化得到 content</code></pre>注：py需要使用OrderDict使序列化按照key-value顺序，并且dumps含ensure_ascii= False防止unicode<h2>3.签名</h2> 准备参数<table ><tr><td style="text-align:left;" colSpan="1" rowSpan="1">参数</td><td style="text-align:left;" colSpan="1" rowSpan="1">类型</td><td style="text-align:left;" colSpan="1" rowSpan="1">是否必要</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">appid</td><td style="text-align:left;" colSpan="1" rowSpan="1">string</td><td style="text-align:left;" colSpan="1" rowSpan="1">是</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">nonce_str</td><td style="text-align:left;" colSpan="1" rowSpan="1">string</td><td style="text-align:left;" colSpan="1" rowSpan="1">是</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">timestamp</td><td style="text-align:left;" colSpan="1" rowSpan="1">string</td><td style="text-align:left;" colSpan="1" rowSpan="1">是</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">content</td><td style="text-align:left;" colSpan="1" rowSpan="1">string</td><td style="text-align:left;" colSpan="1" rowSpan="1">是</td></tr></table>将以上参数按顺序依次拼接,并使用用戶本地私钥根据 SHA256WithRSA 进行签名,以 base64 编码 例：<pre><code>const { createSign } = require(&#x27;crypto&#x27;); const str = appid + nonce_str + timestamp + content; // 拼接后字符串 const signature = createSign(&#x27;RSA-SHA256&#x27;); signature.update(str); const sign = signature.sign(privateKey, &#x27;base64&#x27;); // 得到签名</code></pre><h2>4.调用</h2>将 sign 放置请求头, appid 、 nonce_str 、 timestamp 、 content 放置请求体 Body 进行具 体接口调用。通用响应<table ><tr><td style="text-align:left;" colSpan="1" rowSpan="1">status</td><td style="text-align:left;" colSpan="1" rowSpan="1">message</td><td style="text-align:left;" colSpan="1" rowSpan="1">描述</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">200</td><td style="text-align:left;" colSpan="1" rowSpan="1">success</td><td style="text-align:left;" colSpan="1" rowSpan="1">正常响应</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">204</td><td style="text-align:left;" colSpan="1" rowSpan="1">already request</td><td style="text-align:left;" colSpan="1" rowSpan="1">已经请求过了,同用户同接口下流水号重复</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">422</td><td style="text-align:left;" colSpan="1" rowSpan="1">appid invalid</td><td style="text-align:left;" colSpan="1" rowSpan="1">appid 不存在</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">422</td><td style="text-align:left;" colSpan="1" rowSpan="1">timestamp invalid</td><td style="text-align:left;" colSpan="1" rowSpan="1">时间戳无效,与服务器当前时间前后相差超过 5 分钟</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">422</td><td style="text-align:left;" colSpan="1" rowSpan="1">sign invalid</td><td style="text-align:left;" colSpan="1" rowSpan="1">签名无效</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">422</td><td style="text-align:left;" colSpan="1" rowSpan="1">content json format invalid</td><td style="text-align:left;" colSpan="1" rowSpan="1">业务参数字段 json 格式有误</td></tr></table>调试接口<table ><tr><td style="text-align:left;" colSpan="1" rowSpan="1">接口描述</td><td style="text-align:left;" colSpan="1" rowSpan="1">生成签名,供开发者调试使用</td><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1"></td></tr><tr><td colSpan="1" rowSpan="1">请求地址</td><td colSpan="1" rowSpan="1">/api/v1/sign-check</td><td colSpan="1" rowSpan="1"></td><td colSpan="1" rowSpan="1"></td><td colSpan="1" rowSpan="1"></td><td colSpan="1" rowSpan="1"></td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">请求方法</td><td style="text-align:left;" colSpan="1" rowSpan="1">POST</td><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1"></td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1">参数</td><td style="text-align:left;" colSpan="1" rowSpan="1">类型</td><td style="text-align:left;" colSpan="1" rowSpan="1">是否必填</td><td style="text-align:left;" colSpan="1" rowSpan="1">参数说明</td><td style="text-align:left;" colSpan="1" rowSpan="1">示例</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">请求参数( body )</td><td style="text-align:left;" colSpan="1" rowSpan="1">appid</td><td style="text-align:left;" colSpan="1" rowSpan="1">string</td><td style="text-align:left;" colSpan="1" rowSpan="1">是</td><td style="text-align:left;" colSpan="1" rowSpan="1">用户appid</td><td style="text-align:left;" colSpan="1" rowSpan="1">LBoytobidDG5KMjEF9KXD</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1">nonce_str</td><td style="text-align:left;" colSpan="1" rowSpan="1">string</td><td style="text-align:left;" colSpan="1" rowSpan="1">是</td><td style="text-align:left;" colSpan="1" rowSpan="1">流水号</td><td style="text-align:left;" colSpan="1" rowSpan="1"></td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1">private_key</td><td style="text-align:left;" colSpan="1" rowSpan="1">string</td><td style="text-align:left;" colSpan="1" rowSpan="1">是</td><td style="text-align:left;" colSpan="1" rowSpan="1">用戶本地私钥</td><td style="text-align:left;" colSpan="1" rowSpan="1"></td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1">content</td><td style="text-align:left;" colSpan="1" rowSpan="1">string</td><td style="text-align:left;" colSpan="1" rowSpan="1">是</td><td style="text-align:left;" colSpan="1" rowSpan="1">序列化后的内容</td><td style="text-align:left;" colSpan="1" rowSpan="1">&quot;{&quot;name&quot;:&quot;kl&quot;,&quot;age&quot;:18}&quot;</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1">timestamp</td><td style="text-align:left;" colSpan="1" rowSpan="1">string</td><td style="text-align:left;" colSpan="1" rowSpan="1">否</td><td style="text-align:left;" colSpan="1" rowSpan="1">时间戳,不填为当前 时间</td><td style="text-align:left;" colSpan="1" rowSpan="1">1553591059672</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1"></td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1">响应参数</td><td style="text-align:left;" colSpan="1" rowSpan="1">sign</td><td style="text-align:left;" colSpan="1" rowSpan="1">string</td><td style="text-align:left;" colSpan="1" rowSpan="1">是</td><td style="text-align:left;" colSpan="1" rowSpan="1">返回签名，用以比对用户本地生成 sign是否正确</td><td style="text-align:left;" colSpan="1" rowSpan="1">Tm67ptebe8nf+WNEqxdRTPs9L/+...</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1">timestamp</td><td style="text-align:left;" colSpan="1" rowSpan="1">string</td><td style="text-align:left;" colSpan="1" rowSpan="1">是</td><td style="text-align:left;" colSpan="1" rowSpan="1">时间戳</td><td style="text-align:left;" colSpan="1" rowSpan="1">1602314939865</td></tr><tr><td style="text-align:left;" colSpan="1" rowSpan="1"></td><td style="text-align:left;" colSpan="1" rowSpan="1">sign_str</td><td style="text-align:left;" colSpan="1" rowSpan="1">string</td><td style="text-align:left;" colSpan="1" rowSpan="1">是</td><td style="text-align:left;" colSpan="1" rowSpan="1">签名所需字符串</td><td style="text-align:left;" colSpan="1" rowSpan="1">LBoytobidDG5KMjEF9KXD12312...</td></tr></table>调试示例：<pre><code>curl --location --request POST &#x27;https://tianyu.yunaq.com/api/v1/sign-check&#x27; \ --header &#x27;Content-Type: application/json&#x27; \ --data-raw &#x27;{ &quot;appid&quot;:&quot;myAppid&quot;, &quot;nonce_str&quot;: &quot;WmdsrLvN1h7PLXaZTNB&quot;, &quot;timestamp&quot;: &quot;1602314939865&quot;, &quot;content&quot;: &quot;{\&quot;name\&quot;:\&quot;kl\&quot;}&quot;, &quot;private_key&quot;:&quot;-----BEGIN RSA PRIVATE KEY-----\nMY PRIVATE KEY\n-----END RSA PRIVATE KEY-----&quot; }&#x27;</code></pre>该接口返回签名 sign 和签名的字符串 sign_str 用以与本地签名计算进行比对，如果一致，则签名形式正确。后续服务接口不需要调用此接口，只需要正常生成 sign 即可。补充说明：C#、Java调试demo请下载附件。

本文将介绍创宇 API 请求需要用到的5个公共请求参数，有关接口请求参数的详细说明请参见具体服务接口章节。

通用签名步骤说明

创宇信用

热门搜索词

热门文章

关注知道创宇云安全

完善信息下载白皮书

热门搜索词

热门文章

关注知道创宇云安全