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']:
        ...