快速开始指南

集智数据简介

集智数据提供弹性、快速的劳动力来解决机器无法完成的任务。透过我们的 API 接口,你可以用程序发布大量任务,快速得到你想要的结果,并且仅需要对你满意的结果付费。

集智数据有许多应用场景,只要该任务人能表现的比机器好,基本上你都能透过集智来提升现有的解决方案。常见的应用场景有:

  • 图像标注:由人来识别图像中的物件。
  • 信息收集:在网站中取得电话、邮箱等联系资讯。
  • 软文写作:为电影、餐厅、店家、或商品写评论。
  • 情感分析:判断文本内容所表达的情绪。

基本概念

请求者 (Requester)

请求者指的是在集智数据的平台上发布任务的企业或个人。集智的 API 接口让请求者可以用程序来发布大量任务,得到并验证结果。请求者可以在其他应用中结合集智的劳动力,让应用做到机器无法单独完成的任务。

集智任务 (Job)

集智任务是指请求者提交到平台上给工作者完成的任务。请求者可以在任务中嵌入自己的网页,或在 http request 中定义任务由我们的网站呈现。请求者可以设定希望多少不同的工作者来完成集智任务,该任务有多少酬劳,以及任务多久会失效,详情请见发布集智任务的 API 文档

工作者 (Contributor)

工作者是指在平台上做集智任务的用户。工作者在平台上寻找自己感兴趣的任务,接受任务后提交结果给请求者审核。

指定工作 (Task)

当工作者接受集智任务后,系统会分配给该工作者针对该任务的一个指定工作。这个指定工作仅属于接受任务的工作者,只有该工作者可以提交结果及获得报酬。请求者可以根据这个指定工作,追踪工作者的进度以及取得工作的结果。因为一个集智任务可能有超过一个工作者来完成,所以一个集智任务可能对应多个指定工作。

酬劳 (Reward)

当请求者决定接受工作者所提交的结果,请求者会付给工作者酬劳。酬劳的金额在请求者发布集智任务时设定。

开始之前

创建请求者账户

在能够发布任务之前,请求者必须在集智数据建立一个请求者账户,流程如下:

  1. https://account.crowdsdom.com
  2. 填写用户名、邮箱与密码
  3. 根据指示完成邮箱验证

API 密钥 (API key & API secret)

完成注册后登入系统,便能查看有关 API 密钥的相关信息(见下图):

API 密钥可以视为你使用 API 时的用户名与密码,在与 API 接口交互前你必须使用这些资讯来换取访问令牌 (access token)。因此,请妥善保存你的 API 密钥,并且不要随便将 API 密钥泄露给别人。当使用这些密钥之后,你就有权限向我们的API服务器 做各种请求,下面的例子会有更详细的介绍。

开发测试环境 (Sandbox)

在实际发布任务之前,你可以先在开发测试环境下测试。https://account.sandbox.crowdsdom.com/ 是实际网站的一个镜像。你可以在这个网站上注册一个开发者账号,并透过这个网站上的密钥向测试环境的API服务器请求,如此你所发布的任务不会让平台上的工作者直接看到,你的账户也不会被扣款。你可以再注册一个工作者账号登录,搜索你的任务,查看你的任务是否如你所想象的呈现。

(请注意,在开发测试环境中的API请求都需要将接口变换至 http://api.sandbox.crowdsdom.com)

支付宝充值

当你发布任务的时候,系统会从你的账户中预扣该任务所需的金额。若你账户的余额不足,你便没有办法发布任务。如果你是我们一开始邀请的内测用户,你将会得到¥1000的体验额度,当你将这些额度用完之后,你就需要使用支付宝充值。充值的过程相当简易,与线上购买商品的流程类似。当你完成付款后,系统便会增加你账户中的余额。

安装开发者工具 (SDK)

为了让你更方便的与我们的 API 接口交互,我们也提供了数个开发者工具,你可以选择合适的开发工具与你的专案结合。

任务流程

完成注册后,仅需简单四个步骤,你就可以在我们的平台上发布专属的集智任务,让全国各地的工作者帮你完成任务。

  1. 身份验证:透过 API 密钥取得访问令牌 (access token),在接下来的 http request 都需要附上访问令牌的 id 来验证你的身份。

  2. 发布任务:向系统提交发布任务的 http request,在 request 描述你的任务,需要多少工作者,以及相应的报酬。

  3. 取得任务的工作:在发布任务后,根据任务的 id 以 http request 取得跟该任务相关的工作结果。

  4. 接受/拒绝工作:在取得任务的工作结果后,请求者可以判断对工作结果是否满意。满意的话,可以接受该工作并付款。如果不满意的话可以拒绝该工作,系统会重新让别的工作者接受。

接下来我们将会介绍如何用 http request 及开发者工具在集智上完成任务。

身份验证

在使用我们的 API 之前,你必须用身份验证的 API 取得访问令牌 (access token)。身份验证能让我们确保使用 API 的用户为本人,避免别人盗用你的账号。

Python 直接调用

在这里,我们示范怎么透过 Python requests 直接向身份验证的API接口发送请求。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# -*- encoding: utf-8 -*-
import json
import requests

API_URL = "https://account.crowdsdom.com/oauth/token"

headers = {"Content-Type": "application/json"}

data = json.dumps({"grant_type": "client_credentials"})

auth = ("YOUR_API_KEY","YOUR_API_SECRET")

response = requests.post(API_URL, headers=headers, data=data, auth=auth)

print json.dumps(response.json(), indent=2, ensure_ascii=False)

#####
#{
# "access_token": {
# "created": "2015-09-23T08:16:08.456Z",
# "userId": "55fffdbc220c681700f5eaca",
# "id": "SynbNS5BY7v0nxyEWR6m8Nq5A1xB9cL7ewIhgBCuiNkSCuvZSjpSYMzfDc634bw6",
# "clientId": "d83859fbe3306fe2f91876fe0acde3ed",
# "ttl": 1800
# },
# "token_type": "Bearer"
#}
#####

PHP SDK

1
2
3
4
5
6
use Crowdsdom\Crowdsdom;

$apiKey = '[YOUR API KEY]';
$apiSecret = '[YOUR API SECRET]';

$crowdsdom = new Crowdsdom($apiKey, $apiSecret);

Python SDK

1
2
3
4
5
6
7
8
9
10
11
12
13
# -*- encoding: utf-8 -*-
from jizhi import Client

APP_KEY = 'YOUR_API_KEY'
APP_SECRET = 'YOUR_API_SECRET'

c = Client(APP_KEY, APP_SECRET)
access_token = c.get_access_token()
print('access_token: %s' % access_token)

#####
#access_token: SynbNS5BY7v0nxyEWR6m8Nq5A1xB9cL7ewIhgBCuiNkSCuvZSjpSYMzfDc634bw6
#####

发布任务

下面我们将会用一个案例示范如何用API接口或开发者工具来发布任务。

在这里我们假设请求者要发布一个简单的文本分析任务。

判断下面这段话所表达的情绪是正面、负面、还是中性:

“黄山温泉太啃外地人了一张票298而本地人却58太不合理了!”

在本质上,请求者透过 RESTful API request 与我们的系统交互。在发布集智任务的请求中必须附上访问令牌,以及任务的设定及内容。以下我们将示范如何用 API 接口及开发者工具发布范例任务,请在这里查看详细的 API 文档。

Python 直接调用

在这里,我们示范怎么透过 Python requests 直接向发布任务的API接口发送请求。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
# -*- encoding: utf-8 -*-
import json
import requests

API_URL = "https://api.crowdsdom.com/v1/jobs"

headers = {
"Authorization": "YOUR_ACCESS_TOKEN",
"Content-Type": "application/json"}

job_settings = {
"title":"微博情感分析",
"description":"判断博文中所表达的情绪",
"keywords": ["情感分析","微博"],
"questionsType":"internalQuestionsForm",
"internalQuestionsForm": {
"questions": [{
"id":"sentiment",
"title":"黄山温泉太啃外地人了一张票298而本地人却58太不合理了!",
"isRequired": True,
"answerType": "selectionAnswer",
"selectionAnswerSpec": {
"minSelectionCount": 1,
"maxSelectionCount": 1,
"style": "radiobutton",
"optionSpecs": [
{"id":"positive","text":"正面"},
{"id":"negative","text":"负面"},
{"id":"neutral","text":"中性"}
]
}
}]
},
"reward": {"amount": 0.1, "currencyCode": "CNY"}
}

data = json.dumps(job_settings)

response = requests.post(API_URL, headers=headers, data=data)

print json.dumps(response.json(), indent=2, ensure_ascii=False)

#####
#系统将回复根据集智任务的数据结构返回一个物件,详细的数据结构请见集智任务的数据结构文档。
#####

PHP SDK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
use Crowdsdom\Crowdsdom;

$apiKey = '[YOUR API KEY]';
$apiSecret = '[YOUR API SECRET]';
$jobSettings = [
'title' => '微博情感分析',
'description' => '判断博文中所表达的情绪',
'keywords' =>
[
'情感分析',
'微博',
],
'questionsType' => 'internalQuestionsForm',
'internalQuestionsForm' =>
[
'questions' =>
[
[
'id' => 'sentiment',
'title' => '黄山温泉太啃外地人了一张票298而本地人却58太不合理了!',
'isRequired' => true,
'answerType' => 'selectionAnswer',
'selectionAnswerSpec' =>
[
'minSelectionCount' => 1,
'maxSelectionCount' => 1,
'style' => 'radiobutton',
'optionSpecs' =>
[
[
'id' => 'positive',
'text' => '正面',
],
[
'id' => 'negative',
'text' => '负面',
],
[
'id' => 'neutral',
'text' => '中性',
],
],
],
],
],
],
'reward' =>
[
'amount' => 0.1,
'currencyCode' => 'CNY',
],
];

$crowdsdom = new Crowdsdom($apiKey, $apiSecret);
$labor = $crowdsdom->labor();
$labor->job()->create($jobSettings);

Python SDK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
# -*- encoding: utf-8 -*-
from jizhi import POST, Client

APP_KEY = 'YOUR_API_KEY'
APP_SECRET = 'YOUR_API_SECRET'

c = Client(APP_KEY, APP_SECRET)
c.set_access_token("YOUR_ACCESS_TOKEN")

job_settings = {
"title":"微博情感分析",
"description":"判断博文中所表达的情绪",
"keywords": ["情感分析","微博"],
"questionsType":"internalQuestionsForm",
"internalQuestionsForm": {
"questions": [{
"id":"sentiment",
"title":"黄山温泉太啃外地人了一张票298而本地人却58太不合理了!",
"isRequired": True,
"answerType": "selectionAnswer",
"selectionAnswerSpec": {
"minSelectionCount": 1,
"maxSelectionCount": 1,
"style": "radiobutton",
"optionSpecs": [
{"id":"positive","text":"正面"},
{"id":"negative","text":"负面"},
{"id":"neutral","text":"中性"}
]
}
}]
},
"reward": {"amount": 0.1, "currencyCode": "CNY"}
}

Jobs = c['Jobs']
job = POST(Jobs, body=job_settings)
print('job:', job)

得到工作结果

发布任务之后,平台上的工作者便可以接受你的任务并完成工作。你可以根据发布任务的 id,透过 API 接口查看得到工作者对该任务所提供的结果。假设我们刚刚发布的任务之 id 为 507f191e810c19729de860ea,有一个工作者已提交答案,则透过 API 及开发者工具取得工作结果的范例如下,:

Python 直接调用

在这里,我们示范怎么透过 Python requests 直接向取得任务工作结果的API接口发送请求。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# -*- encoding: utf-8 -*-
import json
import requests

API_URL = 'https://api.crowdsdom.com/v1/jobs/507f191e810c19729de860ea/tasks'

headers = {'Authorization': 'YOUR_ACCESS_TOKEN'}

response = requests.get(API_URL, headers=headers)
print json.dumps(response.json(), indent=2, ensure_ascii=False)

#####
#[
# {
# id: '507f191e810c19729devxbbx',
# status: 'submitted',
# answers: [
# {
# questionId: 'sentiment',
# answer: ['negative']
#
# }
# ],
# jobId: '507f191e810c19729de860ea',
# contributorId: '507f191e810c19729de8adfaf'
# }
#]
#####

PHP SDK

1
2
3
4
5
6
7
8
9
use Crowdsdom\Crowdsdom;

$apiKey = '[YOUR API KEY]';
$apiSecret = '[YOUR API SECRET]';
$jobId = '507f191e810c19729devxbbx';

$crowdsdom = new Crowdsdom($apiKey, $apiSecret);
$labor = $crowdsdom->labor();
$tasks = $labor->job()->tasks($jobId);

Python SDK

1
2
3
4
5
6
7
8
9
10
11
12
13
# -*- encoding: utf-8 -*-
from jizhi import GET, Client

APP_KEY = 'YOUR_API_KEY'
APP_SECRET = 'YOUR_API_SECRET'

c = Client(APP_KEY, APP_SECRET)
c.set_access_token("YOUR_ACCESS_TOKEN")

Jobs = c['Jobs']
job_id = '507f191e810c19729devxbbx'
tasks = GET(Jobs[job_id].tasks)
print(tasks)

批准工作

在获得工作结果后,如果你对结果满意,你可以该工作的 id 依照下面的示例透过 API 或开发者工具批准该工作(文档)。你批准工作后,用户能得到你在发布任务时指定的报酬。相对的,如果你对工作的结果不满,你也可以选择拒绝工作(文档)。在你拒绝该工作后,工作者不会得到报酬,系统会将任务重新发布给其他人接受。

Python 直接调用

在这里,我们示范怎么透过 Python requests 直接向取得批准工作的API接口发送请求。

1
2
3
4
5
6
7
8
9
10
11
# -*- encoding: utf-8 -*-
import json
import requests

API_URL = 'https://api.crowdsdom.com/v1/tasks/507f191e810c19729devxbbx/approve'

headers = {'Authorization': 'YOUR_ACCESS_TOKEN'}

response = requests.post(API_URL, headers=headers)

print json.dumps(response.json(), indent=2, ensure_ascii=False)

PHP SDK

1
2
3
4
5
6
7
8
9
use Crowdsdom\Crowdsdom;

$apiKey = '[YOUR API KEY]';
$apiSecret = '[YOUR API SECRET]';
$taskId = '507f191e810c19729devxbbx';

$crowdsdom = new Crowdsdom($apiKey, $apiSecret);
$labor = $crowdsdom->labor();
$labor->task()->approve($taskId);

Python SDK

1
2
3
4
5
6
7
8
9
10
11
12
13
# -*- encoding: utf-8 -*-
from jizhi import POST, Client

APP_KEY = 'YOUR_API_KEY'
APP_SECRET = 'YOUR_API_SECRET'

c = Client(APP_KEY, APP_SECRET)
c.set_access_token("YOUR_ACCESS_TOKEN")

Tasks = c['Tasks']
task_id = '507f191e810c19729devxbbx'
result = POST(Tasks[task_id].approve)
print(result)

大功告成

恭喜!你已经学会如何发布集智任务及获取工作者的工作结果,现在你可以透过集智建立自己独特的应用。为了让你更方便的开始使用我们的服务,现在注册就可得到¥1000的免费额度。如果想了解更多有关 API 接口的更多细节,请看详细的 API 文档