Python API自动化操作eLabFTW：信息查询与实验创建实战指南

eLabFTW作为一个开源的电子实验记录本（ELN），提供了功能完善的API接口，允许开发者进行自动化操作，从而极大地提升实验室数据管理的效率。其官方提供了Python客户端库 elabapi-python，我们可以通过它来便捷地与eLabFTW实例进行交互。本文将基于官方示例，演示如何使用Python进行基础的信息查询与实验条目的创建、读取、更新和删除（CRUD）操作。

前置准备与客户端配置

在运行示例代码前，你需要完成 elabapi-python 库的安装，并正确配置客户端。通常，你需要准备一个 client.py 配置文件，其中设置API的访问地址（host）和认证令牌（api_key）。官方示例目录下提供了该文件的模板。

安装依赖

pip install elabapi-python

配置客户端

创建 client.py 文件：

import elabapi_python
from elabapi_python.rest import ApiException

# 配置API客户端
configuration = elabapi_python.Configuration()
configuration.api_key['api_key'] = 'YOUR_API_KEY_HERE'
configuration.api_key_prefix['api_key'] = 'Authorization'
configuration.host = 'https://your-lab.com/api/v2'
configuration.debug = False
configuration.verify_ssl = True

# 创建API客户端实例
api_client = elabapi_python.ApiClient(configuration)

---

实战一：获取eLabFTW实例信息

我们首先从一个简单的只读接口开始，验证连接并获取实例的全局信息，这对应API的 /info 端点。

#!/usr/bin/env python
"""
获取eLabFTW实例信息示例
"""
import elabapi_python
from client import api_client  # 导入已配置好的客户端
from pprint import pprint

def get_instance_info():
    """
    获取eLabFTW实例的概要信息
    """
    # 实例化Info API客户端
    info_client = elabapi_python.InfoApi(api_client)

    # 发起GET请求
    api_response = info_client.get_info()

    print("[请求] GET /info")
    print("-" * 60)

    # 美观地打印完整的JSON响应
    pprint(api_response)
    print()

    # 提取并展示关键信息
    print(f"
 实例地址 {api_client.configuration.host}")
    print(f"    共有 {api_response.teams_count} 个团队")
    print(f"    共有 {api_response.all_users_count} 名用户")
    print(f"
 eLabFTW 版本: {api_response.elabftw_version}")
    print(f"
 实验条目数: {api_response.experiments_count}")
    print(f"
 数据库条目数: {api_response.items_count}")
    print(f"
 上传文件总大小: {api_response.uploads_filesize_sum_formatted}")

if __name__ == "__main__":
    get_instance_info()

执行结果示例

[请求] GET /info
------------------------------------------------------------
{'active_users_count': 5,
 'all_users_count': 17,
 'elabftw_version': '5.3.6',
 'experiments_count': 451,
 'items_count': 1119,
 'teams_count': 3,
 'uploads_filesize_sum_formatted': '881.21 MiB'}

 实例地址 https://your-lab.com/api/v2
    共有 3 个团队
    共有 17 名用户
 eLabFTW 版本: 5.3.6
 实验条目数: 451
 数据库条目数: 1119
 上传文件总大小: 881.21 MiB

通过这个简单的接口，我们可以快速了解eLabFTW实例的规模、版本和资源使用情况，是进行自动化操作前良好的连通性测试。

---

实战二：实验条目的完整CRUD操作

接下来，我们将使用 ExperimentsApi 客户端对实验条目进行完整的生命周期管理，包括创建、读取、更新和删除。这通常涉及与数据库的交互，通过API作为数据接口。

#!/usr/bin/env python
"""
实验条目CRUD操作示例
"""
import elabapi_python
from client import api_client
from elabapi_python.rest import ApiException

def crud_experiment():
    """
    实验条目的创建、读取、更新与删除操作演示
    """
    exp_client = elabapi_python.ExperimentsApi(api_client)

    # ========================================
    # 1. 创建一个空实验
    # ========================================
    print("[步骤 1] 创建空实验")
    print("[请求] POST /experiments")

    try:
        # 使用 _with_http_info 方法以获取包含响应头的完整信息
        data, status, headers = exp_client.post_experiment_with_http_info()

        if status == 201:  # 201 Created 表示成功
            location = headers['Location']
            exp_id = int(location.split('/').pop())  # 从URL中提取新实验的ID
            print(f"[✓] 成功创建实验")
            print(f"    状态码: {status}")
            print(f"    实验ID: {exp_id}")
            print(f"    地址: {location}")
            print()
    except ApiException as e:
        print(f"[✗] 创建实验失败: {e}")
        return

    # ========================================
    # 2. 删除刚刚创建的空实验
    # ========================================
    print("[步骤 2] 删除空实验")
    print(f"[请求] DELETE /experiments/{exp_id}")

    try:
        data, status, headers = exp_client.delete_experiment_with_http_info(exp_id)

        if status == 204:  # 204 No Content 表示删除成功
            print(f"[✓] 已删除实验 ID: {exp_id}")
            print()
    except ApiException as e:
        print(f"[✗] 删除实验失败: {e}")

    # ========================================
    # 3. 创建包含详细内容的实验
    # ========================================
    print("[步骤 3] 创建包含详细内容的实验")
    print("[请求] POST /experiments (带数据)")

    new_exp_data = {
        "title": "通过Python API创建的实验！",
        "body": "<h1>实验概述</h1><p>这是通过脚本自动创建的第一段内容。</p>",
        "tags": ["api创建", "python", "自动化测试"],
    }

    try:
        data, status, headers = exp_client.post_experiment_with_http_info(
            body=new_exp_data
        )
        new_exp_id = int(headers['Location'].split('/').pop())
        print(f"[✓] 成功创建带详情的实验")
        print(f"    实验ID: {new_exp_id}")
        print(f"    标题: {new_exp_data['title']}")
        print(f"    标签: {', '.join(new_exp_data['tags'])}")
        print()
    except ApiException as e:
        print(f"[✗] 创建实验失败: {e}")
        return

    # ========================================
    # 4. 读取（GET）实验内容
    # ========================================
    print("[步骤 4] 读取实验内容")
    print(f"[请求] GET /experiments/{new_exp_id}")

    try:
        experiment = exp_client.get_experiment(new_exp_id)  # 返回结构化的Entity对象
        print(f"[✓] 成功读取实验")
        print(f"    标题: {experiment.title}")
        print(f"    创建时间: {experiment.created_at}")
        print(f"    修改时间: {experiment.modified_at}")
        print()
    except ApiException as e:
        print(f"[✗] 读取实验失败: {e}")
        return

    # ========================================
    # 5. 更新（PATCH）实验标题
    # ========================================
    print("[步骤 5] 更新实验标题")
    print(f"[请求] PATCH /experiments/{new_exp_id}")

    try:
        updated_exp = exp_client.patch_experiment(
            new_exp_id, 
            body={"title": "标题已通过API更新！"}
        )
        print(f"[✓] 成功更新实验")
        print(f"    原标题: {experiment.title}")
        print(f"    新标题: {updated_exp.title}")
        print(f"    Web查看: {updated_exp.sharelink}")
        print()
    except ApiException as e:
        print(f"[✗] 更新实验失败: {e}")

    # ========================================
    # 6. 可选：最终清理（删除测试实验）
    # ========================================
    print("[步骤 6] 清理测试数据（可选）")
    cleanup = input("是否删除测试实验？(y/N): ").strip().lower()

    if cleanup == 'y':
        try:
            exp_client.delete_experiment(new_exp_id)
            print(f"[✓] 已删除测试实验 ID: {new_exp_id}")
        except ApiException as e:
            print(f"[✗] 删除失败: {e}")
    else:
        print(f"
 保留实验 ID: {new_exp_id}，可在Web界面查看")

if __name__ == "__main__":
    crud_experiment()

执行结果示例

[步骤 1] 创建空实验
[请求] POST /experiments
[✓] 成功创建实验
    状态码: 201
    实验ID: 547
    地址: https://your-lab.com/api/v2/experiments/547

[步骤 2] 删除空实验
[请求] DELETE /experiments/547
[✓] 已删除实验 ID: 547

[步骤 3] 创建包含详细内容的实验
[请求] POST /experiments (带数据)
[✓] 成功创建带详情的实验
    实验ID: 548
    标题: 通过Python API创建的实验！
    标签: api创建, python, 自动化测试

[步骤 4] 读取实验内容
[请求] GET /experiments/548
[✓] 成功读取实验
    标题: 通过Python API创建的实验！
    创建时间: 2025-12-10T10:15:30+00:00
    修改时间: 2025-12-10T10:15:30+00:00

[步骤 5] 更新实验标题
[请求] PATCH /experiments/548
[✓] 成功更新实验
    原标题: 通过Python API创建的实验！
    新标题: 标题已通过API更新！
    Web查看: https://your-lab.com/experiments.php?mode=view&id=548

[步骤 6] 清理测试数据（可选）
是否删除测试实验？(y/N): n
 保留实验 ID: 548，可在Web界面查看

Web界面效果

通过Web界面查看，新创建并更新的实验如下所示：

---

进阶应用场景

基于以上基础操作，你可以实现更多自动化场景：

1. 批量创建实验模板

def create_experiment_template(title, body, tags):
    """创建标准化的实验模板"""
    exp_client = elabapi_python.ExperimentsApi(api_client)

    template_data = {
        "title": title,
        "body": body,
        "tags": tags,
        "category": 1,  # 设置实验类别
    }

    response = exp_client.post_experiment(body=template_data)
    return response.id

2. 自动上传实验附件

def upload_attachment(experiment_id, file_path):
    """为实验上传附件"""
    exp_client = elabapi_python.ExperimentsApi(api_client)

    with open(file_path, 'rb') as file:
        response = exp_client.post_upload(
            experiment_id, 
            file=file
        )

    print(f"[✓] 已上传附件: {response.real_name}")
    return response.id

3. 搜索和筛选实验

def search_experiments(query, tags=None):
    """搜索实验条目"""
    exp_client = elabapi_python.ExperimentsApi(api_client)

    # 构建查询参数
    params = {"q": query}
    if tags:
        params["tags[]"] = tags

    results = exp_client.read_experiments(**params)

    print(f"
 找到 {len(results)} 条实验记录")
    for exp in results:
        print(f"    - [{exp.id}] {exp.title}")

    return results

---

错误处理最佳实践

在实际应用中，建议添加完善的错误处理机制：

from elabapi_python.rest import ApiException
import logging

# 配置日志
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def safe_api_call(func, *args, **kwargs):
    """安全的API调用包装器"""
    try:
        return func(*args, **kwargs)
    except ApiException as e:
        logger.error(f"API调用失败: {e.status} - {e.reason}")
        logger.error(f"响应体: {e.body}")
        raise
    except Exception as e:
        logger.error(f"未预期的错误: {str(e)}")
        raise

# 使用示例
def create_experiment_safely(title):
    exp_client = elabapi_python.ExperimentsApi(api_client)
    return safe_api_call(
        exp_client.post_experiment,
        body={"title": title}
    )

---

总结

本文演示了利用 elabapi-python 库进行HTTP请求，与eLabFTW交互的两个基础场景：

1. 查询实例信息 - 验证连接并获取系统概况
2. 操作实验条目 - 完整的CRUD操作流程

你可以在此基础上，进一步探索API文档，实现如：

• 上传和管理附件
• 管理实验模板
• 操作数据库条目（Items）
• 团队和用户管理
• 导出实验数据

等更复杂的自动化工作流，从而将Python的自动化能力深度融入实验室的日常数据管理之中。

---

参考资源

• 官方文档: eLabFTW API Documentation
• Python客户端: elabapi-python on PyPI
• GitHub仓库: elabftw/elabapi-python

---

注意事项 运行以上所有代码前，请确保已根据 examples 目录下的模板正确配置 client.py 文件，填入你eLabFTW实例的地址和有效的API密钥。API密钥可在eLabFTW用户设置页面中生成。