LimeSurvey RemoteControl 2 API

通过 RemoteControl 2 JSON-RPC API 自动化 LimeSurvey 调查管理。

前提条件

必需的环境变量：

• - LIMESURVEYURL — RemoteControl 端点的完整 URL（例如 https://survey.example.com/index.php/admin/remotecontrol）
• LIMESURVEYUSER — 服务账户用户名
• LIMESURVEY_PASSWORD — 服务账户密码

安全建议：

1. 1. 使用最小权限服务账户，而非完整管理员凭据
2. 创建具有最小必要权限的专用 LimeSurvey 用户（仅限调查管理，无系统管理权限）
3. 使用强且唯一的密码；初始使用后定期轮换
4. 切勿将凭据提交到版本控制——仅使用环境变量或安全保管库
5. 确保 RemoteControl API 仅可从受信任网络访问

设置：
bash
export LIMESURVEY_URL=https://survey.example.com/index.php/admin/remotecontrol
export LIMESURVEYUSER=serviceaccount_username
export LIMESURVEYPASSWORD=secureservice_password

快速开始

设置

设置环境变量：

bash
export LIMESURVEY_URL=https://survey.example.com/index.php/admin/remotecontrol
export LIMESURVEY_USER=admin
export LIMESURVEYPASSWORD=yourpassword

CLI 使用

bash

列出所有调查

python3 scripts/limesurvey.py list-surveys

导出回复

python3 scripts/limesurvey.py export-responses 123456 --format csv -o responses.csv

列出参与者

python3 scripts/limesurvey.py list-participants 123456 --limit 100

从 JSON 添加参与者

python3 scripts/limesurvey.py add-participants 123456 --file participants.json

发送邀请

python3 scripts/limesurvey.py invite-participants 123456

激活调查

python3 scripts/limesurvey.py activate-survey 123456

获取调查统计信息

python3 scripts/limesurvey.py get-summary 123456

Python API 使用

python
from scripts.limesurvey_client import LimeSurveySession

url = https://survey.example.com/index.php/admin/remotecontrol

with LimeSurveySession(url, admin, password) as client:
# 列出调查
surveys = client.call(listsurveys, client.sessionkey)

# 导出回复
encoded = client.call(exportresponses, client.sessionkey,
survey_id, csv)
csvdata = client.decodebase64(encoded)

常见工作流

调查管理

列出所有调查：
python
surveys = client.call(listsurveys, client.sessionkey)

激活调查：
python
result = client.call(activatesurvey, client.sessionkey, survey_id)

获取调查统计信息：
python
stats = client.call(getsummary, client.sessionkey, survey_id, all)

返回：completedresponses, incompleteresponses, token_count 等

复制调查：
python
result = client.call(copysurvey, client.sessionkey,
source_id, New Survey Name)
new_id = result[newsid]

参与者管理

初始化参与者表：
python

使用自定义属性创建表

client.call(activatetokens, client.sessionkey, survey_id, [1, 2, 3])

添加参与者：
python
participants = [
{email: user@example.com, firstname: John, lastname: Doe},
{email: user2@example.com, firstname: Jane, lastname: Smith}
]
result = client.call(addparticipants, client.sessionkey,
survey_id, participants, True)

发送邀请：
python

发送给特定令牌

token_ids = [1, 2, 3]
result = client.call(inviteparticipants, client.sessionkey,
surveyid, tokenids)

或发送给所有待处理

result = client.call(inviteparticipants, client.sessionkey, survey_id, None)

使用过滤器列出参与者：
python

查找未使用的令牌

participants = client.call(listparticipants, client.sessionkey,
survey_id, 0, 100, True)

按自定义属性查找

participants = client.call(listparticipants, client.sessionkey, survey_id, 0, 1000, False, False, {attribute_1: ACME Corp})

回复操作

导出所有回复：
python
encoded = client.call(exportresponses, client.sessionkey,
survey_id, csv)
csvdata = client.decodebase64(encoded)

with open(responses.csv, w) as f:
f.write(csv_data)

仅导出已完成回复：
python
encoded = client.call(exportresponses, client.sessionkey,
survey_id, csv, None, complete)

按令牌导出：
python
encoded = client.call(exportresponsesbytoken, client.sessionkey,
survey_id, json, [token1, token2])

以编程方式添加回复：
python
response_data = {
G1Q1: Answer text,
G1Q2: 3, # 多选题值
token: xyz123
}
responseid = client.call(addresponse, client.session_key,
surveyid, responsedata)

题目与分组操作

列出分组：
python
groups = client.call(listgroups, client.sessionkey, survey_id)

添加题目分组：
python
groupid = client.call(addgroup, client.sessionkey, surveyid,
Demographics, Basic information)

列出题目：
python

调查中的所有题目

questions = client.call(listquestions, client.sessionkey, survey_id)

特定分组中的题目

questions = client.call(listquestions, client.sessionkey, surveyid, groupid)

获取题目详情：
python
props = client.call(getquestionproperties, client.session_key,
question_id, [question, type, mandatory])

导出与报告

生成统计信息 PDF：
python
encoded = client.call(exportstatistics, client.sessionkey,
survey_id, pdf, None, 1) # 包含图表

import base64
pdf_data = base64.b64decode(encoded)

with open(stats.pdf, wb) as f:
f.write(pdf_data)

获取提交时间线：
python
timeline = client.call(exporttimeline, client.sessionkey,
survey_id, day, 2024-01-01, 2024-12-31)

for entry in timeline:
print(f{entry[period]}: {entry[count]} submissions)

获取调查字段映射：
python
fieldmap = client.call(getfieldmap, client.sessionkey, survey_id)

将题目代码映射到元数据

错误处理

所有 API 函数在出错时返回状态对象：

python
result = client.call(activatesurvey, client.sessionkey, survey_id)

if isinstance(result, dict) and status in result:
print(fError: {result[status]})
# 常见错误：
# - 无效的会话密钥
# - 无权限
# - 无效的调查 ID
# - 调查已激活
else:
print(Success!)

对连接错误使用 try/except：

python
from scripts.limesurvey_client import LimeSurveyError

try:
with LimeSurveySession(url, username, password) as client:
result = client.call(listsurveys, client.sessionkey)
except LimeSurveyError as e:
print(fAPI error: {e})

参考文档

• - API 参考 — 包含参数和返回值的完整函数参考
• 示例 — 常见任务的实际代码示例

可用函数

会话

• - getsessionkey(username, password) — 创建会话
• releasesessionkey(session_key) — 关闭会话

调查

• - listsurveys(sessionkey) — 列出所有调查
• getsurveyproperties(sessionkey, surveyid, properties) — 获取属性
• setsurveyproperties(sessionkey, surveyid, properties) — 更新属性
• activatesurvey(sessionkey, surveyid) — 激活调查
• deletesurvey(sessionkey, surveyid) — 删除调查

-