提交任务事件接口
<p>[toc]</p>
<h2>简要描述</h2>
<ul>
<li>获取任务接口</li>
<li>接口统一使用的编码为:UTF-8</li>
</ul>
<h2>使用流程</h2>
<p>1、管理任务事件
在控制台中创建、编辑、删除任务事件。
<img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=e39db21fad617e957b63c67ab4b5b446&amp;file=file.png" alt="" />
2、绑定任务事件
在创建任务的时候,绑定好任务事件;一个任务事件可以绑定多个任务,一个任务只能绑定一个事件。每个任务增加了计次项,即调用提交接口n次时,才能获取到积分。
<img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=e71987cb4c1cc16e64e0c46805822e93&amp;file=file.png" alt="" /></p>
<p>3、提交任务事件
通过submitTaskEvent接口提交任务事件,该接口会筛选出已上线(不包括删除、下线、过期)的任务,并判断其是否可以进行提交,当任务事件下的所有任务都具备提交条件的时候,会同时对这些任务进行提交。</p>
<h2>接口描述</h2>
<h3>异步执行和同步执行</h3>
<h4>同步执行</h4>
<p>请求后,如果是同步执行,会在系统执行完提交任务操作后,再返回对应的结果。</p>
<h4>异步执行</h4>
<p>请求后,如果是异步执行且参数正确无误,会立即返回任务请求成功,但是不会返回执行任务的结果。由<strong>异步执行结果通知地址</strong>通知提交任务结果,如果通知地址无效,将会导致任务通知失败。</p>
<h4>如何选择</h4>
<ul>
<li>事务性比较强,选同步</li>
<li>对并发要求高,选异步</li>
</ul>
<h3>请求URL</h3>
<ul>
<li>/ext/submitTaskEvent(任务事件接口)
测试环境域名是https://testgmall.m.qq.com 正式环境域名是https://gmall.m.qq.com (正式环境未发布)</li>
</ul>
<p>签名规则:<a href='<a href="https://www.showdoc.cc/1procedure2develop?page_id=3125189450329585'>签名<a/>">https://www.showdoc.cc/1procedure2develop?page_id=3125189450329585'>签名<a/></a>;
注意本接口签名requestBody参数要进行<strong>字典排序</strong>之后参与签名。</p>
<p><strong> querystring参数:</strong></p>
<table>
<thead>
<tr>
<th style="text-align: left;">参数名</th>
<th style="text-align: left;">必选</th>
<th style="text-align: left;">类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">appid</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">int</td>
<td>产品id</td>
</tr>
<tr>
<td style="text-align: left;">timestamp</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">int</td>
<td>时间戳</td>
</tr>
<tr>
<td style="text-align: left;">sign</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">string</td>
<td>参考签名规则,32位小写</td>
</tr>
</tbody>
</table>
<h3>请求方式</h3>
<ul>
<li>post
<strong>参数:</strong></li>
</ul>
<table>
<thead>
<tr>
<th>参数名</th>
<th>必选</th>
<th>类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>account_id</td>
<td>string(45)</td>
<td>是</td>
<td>账号ID</td>
</tr>
<tr>
<td>device_id</td>
<td>string(45)</td>
<td>是</td>
<td>设备ID,无设备ID可用账号ID</td>
</tr>
<tr>
<td>order_id</td>
<td>string(45)</td>
<td>是</td>
<td>订单ID,需保证所有任务提交的订单ID不重复</td>
</tr>
<tr>
<td>code</td>
<td>string(10)</td>
<td>是</td>
<td>任务事件code</td>
</tr>
<tr>
<td>async</td>
<td>int</td>
<td>否</td>
<td>是否异步执行,如果值为0,则是同步执行;如果值为1,则是异步执行,异步执行需要填写<strong>异步执行结果通知地址</strong>;若不填该参数,默认是同步执行</td>
</tr>
<tr>
<td>notify_url</td>
<td>int</td>
<td>否</td>
<td>异步执行结果通知地址,异步执行的时候会调用该地址传递提交任务的结果。通知URL必须为直接可访问的URL,不允许携带查询串,要求必须为https地址。</td>
</tr>
</tbody>
</table>
<p><em>备注:和原来的接口相比,不需要<code>order_data</code>,<code>login_key</code>,<code>activity_type</code>和<code>task</code>等参数,对于对接方来说,提交任务只需要accountId和deviceId以及taskId</em></p>
<h3>请求示例</h3>
<pre><code>{
account_id: 'littleMing',
device_id: 'HUAWEI',
order_id: '90e4bc93-24d9-490d-8004-a51efce60686',
code: &quot;1&quot;,
async: 0,
notify_url: 'https://testgmall.m.qq.com/ext/testReceiveTaskNotify',
}</code></pre>
<h3>返回参数</h3>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>必填</th>
<th>备注</th>
</tr>
</thead>
<tbody>
<tr>
<td>ret</td>
<td>int</td>
<td>是</td>
<td>提交任务事件接口状态码。0为提交成功,非0值为异常</td>
</tr>
<tr>
<td>msg</td>
<td>string</td>
<td>是</td>
<td>任务事件结果提示信息</td>
</tr>
<tr>
<td>order_id</td>
<td>string</td>
<td>是</td>
<td>提交任务时的order_id的参数</td>
</tr>
<tr>
<td>data</td>
<td>array</td>
<td>是</td>
<td>提交后返回的数据</td>
</tr>
</tbody>
</table>
<p>data数据:</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>必填</th>
<th>备注</th>
</tr>
</thead>
<tbody>
<tr>
<td>ret</td>
<td>int</td>
<td>是</td>
<td>任务状态。0为提交成功,非0值为异常</td>
</tr>
<tr>
<td>msg</td>
<td>string</td>
<td>是</td>
<td>任务结果提示信息</td>
</tr>
<tr>
<td>task_order_id</td>
<td>string</td>
<td>是</td>
<td>完成或正在完成的任务订单ID,和请求时的订单ID不一样 。异步执行不返回。</td>
</tr>
<tr>
<td>attach</td>
<td>string</td>
<td>否</td>
<td>附加数据,一些透传的信息,作用为透传附加数据,并不是可执行代码块,长度为256,如果要传超过长度的数据,请自行做映射数据处理。</td>
</tr>
<tr>
<td>done_times</td>
<td>int</td>
<td>否</td>
<td>计次任务:当前已完成次数。</td>
</tr>
<tr>
<td>total_times</td>
<td>int</td>
<td>否</td>
<td>计次任务:单个任务完成需要次数。</td>
</tr>
<tr>
<td>task_ret</td>
<td>int</td>
<td>否</td>
<td>任务订单提交的状态码,此值等于0,任务完成,否则未完成。异步执行不返回。</td>
</tr>
<tr>
<td>task_coin_num</td>
<td>int</td>
<td>否</td>
<td>完成任务获得积分。异步执行不返回。</td>
</tr>
<tr>
<td>task_id</td>
<td>int</td>
<td>否</td>
<td>完成任务的ID。异步执行不返回。</td>
</tr>
<tr>
<td>task_type</td>
<td>int</td>
<td>否</td>
<td>完成任务的类型。异步执行不返回。</td>
</tr>
<tr>
<td>total_coin</td>
<td>int</td>
<td>否</td>
<td>积分总数。异步执行不返回。</td>
</tr>
<tr>
<td>grow_score</td>
<td>int</td>
<td>否</td>
<td>成长值。异步执行不返回。</td>
</tr>
<tr>
<td>type</td>
<td>string</td>
<td>否</td>
<td>任务类型,积分任务“Coin”或成长值任务“Grow”。异步执行不返回。</td>
</tr>
</tbody>
</table>
<h3>返回示例</h3>
<p>成功示例</p>
<pre><code>{
ret: 0,
msg: 'success',
order_id: 'f1584754-f6f8-4da7-92be-91fdcf17a32b',
data: [
{
ret: 0,
type: 'Coin',
msg: '该任务完成次数 3 / 6',
done_times: 3,
total_times: 6,
task_id: 41349,
task_order_id: '3692689696071883811',
attach: 'function () {...}',
},
{
ret: 0,
type: 'Grow',
msg: '任务完成',
task_order_id: '3692675471149112355',
task_ret: 0,
task_coin_num: 1,
task_id: 41350,
task_type: 9,
total_coin: 1,
grow_score: 0,
attach: 'function () {...}',
}
]
}</code></pre>
<p>失败示例1(参数不符)</p>
<pre><code>{
ret: 9501,
msg: '&quot;order_id&quot; length must be less than or equal to 45 characters long'
}</code></pre>
<p>失败示例2(事件中存在获取失败的任务)</p>
<pre><code>{
ret: -1,
msg: '任务事件获取失败',
order_id: 'f1584754-f6f8-4da7-92be-91fdcf17a32b',
data: [
{
ret: -1,
msg: '内部错误',
task_id: 40347,
},
{
ret: -1,
msg: '该任务不存在',
task_id: 41348,
},
{
ret: 0,
msg: '任务获取成功',
task_id: 40349,
}
]
}</code></pre>
<p>msg提示
任务事件:</p>
<table>
<thead>
<tr>
<th>ret</th>
<th>msg</th>
<th>备注</th>
</tr>
</thead>
<tbody>
<tr>
<td>9501</td>
<td>"order_id" length must be less than or equal to 45 characters long</td>
<td>参数不符合规定</td>
</tr>
<tr>
<td>-1</td>
<td>过期请求</td>
<td>请求时间需要为5分钟以内</td>
</tr>
<tr>
<td>-1</td>
<td>重复请求</td>
<td>同一product_id、order_id只能请求一次</td>
</tr>
<tr>
<td>-1</td>
<td>notify_url不合法</td>
<td>URL检验不通过</td>
</tr>
<tr>
<td>-1</td>
<td>notify_url校验失败</td>
<td>URL无法解析</td>
</tr>
<tr>
<td>-1</td>
<td>获取锁失败</td>
<td>同一product、code、account_id加锁</td>
</tr>
<tr>
<td>-1</td>
<td>内部错误</td>
<td>(联系开发者)</td>
</tr>
<tr>
<td>-1</td>
<td>任务事件获取失败</td>
<td>该任务事件存在获取失败的任务</td>
</tr>
<tr>
<td>-1</td>
<td>任务事件无对应任务</td>
<td>该任务事件code无对应任务</td>
</tr>
<tr>
<td>-1</td>
<td>存在提交失败任务</td>
<td>有提交失败的任务</td>
</tr>
</tbody>
</table>
<p>任务:</p>
<table>
<thead>
<tr>
<th>ret</th>
<th>msg</th>
<th>备注</th>
</tr>
</thead>
<tbody>
<tr>
<td>-1</td>
<td>该任务不存在</td>
<td>任务不存在或无法获取</td>
</tr>
<tr>
<td>-1</td>
<td>任务提交失败</td>
<td>任务提交失败</td>
</tr>
<tr>
<td>0</td>
<td>任务获取成功</td>
<td>该任务获取成功,但是该任务事件下包含无法完成的任务(如示例2)</td>
</tr>
<tr>
<td>0</td>
<td>无可做任务</td>
<td>该任务已完成</td>
</tr>
<tr>
<td>0</td>
<td>该任务完成次数 3 / 6</td>
<td>选择计次任务以后,未完全完成时,返回完成的次数提示</td>
</tr>
</tbody>
</table>
<h2>异步通知接口文档</h2>
<h3>接口名</h3>
<p>通知URL必须为直接可访问的URL,不允许携带查询串,要求必须为https地址。</p>
<h3>请求方式</h3>
<p>POST</p>
<h3>签名方式</h3>
<p><a href='<a href="https://www.showdoc.com.cn/1procedure2develop/4613304376289731'>签名<a/>">https://www.showdoc.com.cn/1procedure2develop/4613304376289731'>签名<a/></a>;
加签后的url形如:<a href="https://testgmall.m.qq.com/ext/testReceiveTaskNotify?appid=7999&sign=xxxxxx&timestamp=xxxxxx">https://testgmall.m.qq.com/ext/testReceiveTaskNotify?appid=7999&sign=xxxxxx&timestamp=xxxxxx</a>;</p>
<h3>请求参数</h3>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>必填</th>
<th>备注</th>
</tr>
</thead>
<tbody>
<tr>
<td>ret</td>
<td>int</td>
<td>是</td>
<td>提交任务事件接口状态码。0为提交成功,非0值为异常</td>
</tr>
<tr>
<td>msg</td>
<td>string</td>
<td>是</td>
<td>任务事件结果提示信息</td>
</tr>
<tr>
<td>order_id</td>
<td>string</td>
<td>是</td>
<td>提交任务时的order_id的参数</td>
</tr>
<tr>
<td>data</td>
<td>array</td>
<td>是</td>
<td>提交后返回的数据</td>
</tr>
</tbody>
</table>
<p>data数据:</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>必填</th>
<th>备注</th>
</tr>
</thead>
<tbody>
<tr>
<td>ret</td>
<td>int</td>
<td>是</td>
<td>任务状态。0为提交成功,非0值为异常</td>
</tr>
<tr>
<td>msg</td>
<td>string</td>
<td>是</td>
<td>任务结果提示信息</td>
</tr>
<tr>
<td>task_order_id</td>
<td>string</td>
<td>是</td>
<td>完成或正在完成的任务订单ID,和请求时的订单ID不一样 。</td>
</tr>
<tr>
<td>attach</td>
<td>string</td>
<td>否</td>
<td>附加数据,一些透传的信息,作用为透传附加数据,并不是可执行代码块,长度为256,如果要传超过长度的数据,请自行做映射数据处理。</td>
</tr>
<tr>
<td>done_times</td>
<td>int</td>
<td>否</td>
<td>计次任务:当前已完成次数。</td>
</tr>
<tr>
<td>total_times</td>
<td>int</td>
<td>否</td>
<td>计次任务:单个任务完成需要次数。</td>
</tr>
<tr>
<td>task_ret</td>
<td>int</td>
<td>否</td>
<td>任务订单提交的状态码,此值等于0,任务完成,否则未完成。</td>
</tr>
<tr>
<td>task_coin_num</td>
<td>int</td>
<td>否</td>
<td>完成任务获得积分。</td>
</tr>
<tr>
<td>task_id</td>
<td>int</td>
<td>否</td>
<td>完成任务的ID。</td>
</tr>
<tr>
<td>task_type</td>
<td>int</td>
<td>否</td>
<td>完成任务的类型。</td>
</tr>
<tr>
<td>total_coin</td>
<td>int</td>
<td>否</td>
<td>积分总数。</td>
</tr>
<tr>
<td>grow_score</td>
<td>int</td>
<td>否</td>
<td>成长值。</td>
</tr>
<tr>
<td>type</td>
<td>string</td>
<td>否</td>
<td>任务类型,积分任务“Coin”或成长值任务“Grow”。</td>
</tr>
</tbody>
</table>
<h3>请求示例</h3>
<pre><code>{
ret: 0,
msg: 'success',
order_id: 'f1584754-f6f8-4da7-92be-91fdcf17a32b',
data: [
{
ret: 0,
type: 'Coin',
msg: '该任务完成次数 3 / 6',
task_id: 41349,
attach: 'function () {...}',
done_times: 3,
total_times: 6,
task_order_id: '3692689696071883811',
},
{
ret: 0,
type: 'Grow',
msg: '任务完成',
task_id: 41350,
attach: 'function () {...}',
task_order_id: '3692675471149112355',
task_ret: 0,
task_coin_num: 1,
task_type: 9,
total_coin: 1,
grow_score: 10,
},
{
ret: 0,
type: 'Grow',
msg: '无可做任务',
task_id: 41355,
attach: 'abc',
}
]
}</code></pre>
<pre><code>{
ret: 9501,
msg: '&quot;order_id&quot; length must be less than or equal to 45 characters long'
}</code></pre>
<pre><code>{
ret: -1,
order_id: 'f1584754-f6f8-4da7-92be-91fdcf17a32b',
msg: '任务事件获取失败',
data: [
{
ret: -1,
msg: '该任务不存在',
task_id: 41348,
},
{
ret: -1,
msg: '内部错误',
}
]
}</code></pre>
<h3>返回参数</h3>
<p>成功接受通知后请返回字符串success</p>
<pre><code>'success'</code></pre>