如何使用Python调用API将Excel数据导入REDCap

前置准备 #

• 提前找所在机构的REDCap管理员开通项目API权限，拿到专属API Token，Token等同于项目操作密钥，严禁泄露，医疗数据操作全程需符合数据安全合规要求
• 本地Python环境安装3个依赖库，执行命令：pip install pandas requests openpyxl
• 提前对齐字段映射：把Excel里的列名和REDCap项目的字段名（注意是字段变量名，不是字段显示的中文标签）一一对应，比如Excel的“患者姓名”对应REDCap字段patient_name、“年龄”对应age、“合并症”对应comorbidity，字段名大小写、拼写必须完全一致，建议先从REDCap导出空数据字典逐列核对

步骤1：Excel数据预处理 #

直接用pandas读文件、改列名、处理格式问题，代码每一步都加了注释，改对应参数就行：

import pandas as pd

# 把引号里的路径替换成你本地Excel文件的实际存储路径
df = pd.read_excel(r"C:\本地路径\你的医疗数据文件.xlsx")

# 按照你自己的字段对应关系修改列名，有多少字段加多少行
df = df.rename(columns={
    "患者姓名": "patient_name",
    "年龄": "age",
    "合并症": "comorbidity"
})

# 把空值替换成空字符串，避免pandas的NaN值导致API报错
df = df.fillna("")

# 转成REDCap API要求的记录格式
import_records = df.to_dict("records")

注意：如果合并症是REDCap里的多选字段，必须提前把值改成选项编码用英文逗号分隔的格式，比如高血压编码是1、糖尿病编码是2，同时患两种病就存1,2，不能直接传中文选项文本，否则会识别失败。

步骤2：调用API上传数据 #

用requests发POST请求就行，新手不要随便改overwriteBehavior参数，避免误覆盖已有医疗数据：

import requests

# 替换成你所在机构的REDCap API地址，一般是REDCap域名加/api后缀
api_url = "https://你机构的redcap地址/api/"
# 替换成你自己拿到的API Token
api_token = "你的专属API_TOKEN"

# 构造请求参数，除了token、url、data部分，其他新手默认不用改
payload = {
    "token": api_token,
    "content": "record",
    "action": "import",
    "format": "json",
    "type": "flat",
    "overwriteBehavior": "normal",  # 固定用normal模式：仅新建记录，不覆盖已有数据，防误操作
    "forceAutoNumber": "false",
    "data": str(import_records).replace("'", '"'),  # 转成JSON兼容格式
    "returnContent": "count",
    "returnFormat": "json"
}

# 发送导入请求
resp = requests.post(api_url, data=payload)
# 打印返回结果，成功会显示成功导入的记录条数，失败会显示具体错误原因
print("导入返回结果：", resp.json())

新手避坑提示 #

• 第一次导入不要直接传全量数据，先挑2-3条测试记录跑通流程，确认字段映射、数据格式完全正确后再导全量，医疗数据回溯成本很高
• 年龄、检验值这类数值字段不要带单位，比如不要存“62岁”“120mmHg”，只存纯数字即可，否则会报格式错误
• 如果返回403错误，先检查自己的API Token是否正确、有没有对应项目的导入权限
• 如果返回字段错误，直接看响应里的报错信息，会明确提示哪个字段不存在、格式不符合要求，对着调整Excel数据即可
• 不要在公共WiFi等不安全网络环境下传输患者敏感数据，操作前最好对Excel里的敏感字段做去标识化处理（如果项目允许的话）

内容的提问来源于stack exchange，提问作者alwakeel88