REST¶
oTree有一个REST API使得外部程序(如其他网站)可与oTree通信,具体有:
- 创建session
- 添加participant vars
- 添加session vars
REST API是一个在你的服务器上被设计用来被其他程序使用的URL,而不是用于在浏览器中手动打开的。
使用REST API只需向下面这些URL发送请求。
“Create sessions” REST endpoint¶
POST URL: /api/sessions/
下面是一些”create sessions”路径应当如何使用的例子:
- 其他网站可自动创建oTree会话
- 你可以自己创造一个更好看的oTree 配置会话 界面(例如加上侧边栏和控件)
- 在某些固定时刻创建oTree会话的进程
- 创建自定义会话的命令行脚本(如果
otree create_session
不够用的话)
例子¶
import requests # pip3 install requests
def create_session(**payload):
resp = requests.post(SERVER_URL + '/api/sessions/', json=payload)
resp.raise_for_status() # ensure it succeeded
return resp
resp = create_session(session_config_name='trust', room_name='econ101', num_participants=4, modified_session_config_fields=dict(num_apples=10, abc=[1, 2, 3]))
print(resp.text) # returns the session code
注解
“这些代码应当放在哪里”
这些代码无需包含在你的oTree项目文件夹中。由于REST API的关键就在于使得外部程序和服务器可以与oTree通过网络通信,你应当将这些代码放在其他程序中。这意味着你可以使用在其他服务器上适用的任何语言来编写程序。本页面上的例子使用的是Python,但是使用其他编程语言进行HTTP请求也很简单,如webhooks工具或者cURL。
“Participant vars” REST endpoint¶
POST URL: /api/participant_vars/
这一路径让你能够设置 participant.vars
.主要的目的是使得其他网站/应用传递有关参与人的信息到oTree,通过web服务/webhooks。例如如果用户在Qualtrics上参与了连接到oTree的问卷调查,你就可以将问卷数据(如性别,年龄等等)存为participant vars。(Qualtrics允许通过他们的 web service 特性发送POST请求。)
例子¶
import requests
def set_participant_vars(**payload):
resp = requests.post(SERVER_URL + '/api/participant_vars/', json=payload)
return resp
resp = set_participant_vars(room_name='qualtrics_study', participant_label='albert_e', vars=dict(age=25, is_male=True, x=[3,6,9]))
print(resp.text)
参数¶
room_name
(必要)participant_label
(必要)vars
(必要): 用于加入participant vars的字典, 其中值必须是可被JSON序列化的数据类型, 甚至可以是嵌套的字典/列表。
此特性要求你必须使用房间。参与人被房间名与参与人标签的组合唯一地确定。故你需要给参与人一个带 participant_label
的链接,尽管它不必包含在 participant_label_file
中。
“Session vars” REST endpoint¶
POST URL: /api/session_vars/
这一路径使你可以设置 session.vars
。一种用途是实验输入。举例来说,如果实验中有一次抽奖,就可以通过运行下面的脚本来输入结果。
例子¶
def set_session_vars(**payload):
return requests.post(SERVER_URL + "/api/session_vars/", json=payload)
resp = set_session_vars(
room_name="my_room",
vars=dict(dice_roll=4),
)
注意¶
如果你使用此方法在实验中进行输入,你可能也会想要使用 error_message:
def error_message(player, values):
session = player.session
if 'dice_roll' not in session.vars:
return 'You must wait until the dice roll before proceeding'
认证¶
如果你将你的验证等级从DEMO改为STUDY,你必须验证你的REST API请求。
在服务器上创建一个环境变量(即 Heroku config var) OTREE_REST_KEY
。将其设置为某个秘密值。
在发送请求时,在HTTP header里将其添加为 otree-rest-key
。例如:
import requests
REST_KEY = 'your_key'
def create_session(**payload):
resp = requests.post(SERVER_URL + '/api/sessions/', json=payload,
headers={'otree-rest-key': REST_KEY}
)
return resp
resp = create_session(session_config_name='trust', room_name='econ101', num_participants=4, modified_session_config_fields=dict(num_apples=10, abc=[1, 2, 3]))
print(resp.text) # returns the session code
演示 & 测试¶
为在开发时更便利,你可以在一个真实的会话中生成假的vars来模拟从REST API获得的数据。
在你的session config中,添加参数 mock_exogenous_data=True
(称其为 exogenous(外源性) 数据是因为其是在oTree外部生成的。)
然后在你的项目的shared_out.py中(如果你使用的是文本编辑器,你可能需要创建此文件)定义一个同名函数(mock_exogenous_data
)。
下面是一个例子:
def mock_exogenous_data(session):
participants = session.get_participants()
for pp in participants:
pp.vars.update(age=20, is_male=True) # or make it random
你也可以在此处设置参与人标签。
当你的会话运行在demo模式下,或者使用bot, mock_exogenous_data()
会在 creating_session
之后自动运行。然而,如果是在房间里创建的会话则不会运行。
如果你有多个session config需要不同的外源性数据,你可以像下面这样区分它们:
def mock_exogenous_data(session):
if session.config['name'] == 'whatever':
...
if 'xyz' in session.config['app_sequence']:
...