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。

参数

  • session_config_name (必要)
  • num_participants (必要)
  • modified_session_config_fields: 一个可选的包含session config参数的字典,详见 配置会话.
  • room_name 如果你想在房间中创建session。

“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),
)

参数

  • room_name (必要)
  • vars (必要): 用于添加的一个session vars的字典。

此特性要求你使用房间。

注意

如果你使用此方法在实验中进行输入,你可能也会想要使用 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']:
        ...