alterlab-labarchive

LabArchives 集成

概述

LabArchives 是一个用于研究文档记录和数据管理的电子实验记录本平台。其 REST API（返回 XML，使用 HMAC 签名请求）提供笔记本、页面树、条目、附件和备份的访问能力。

何时使用此技能

在以下情况下应使用此技能：

• 使用 LabArchives REST API 自动化笔记本操作
• 以编程方式备份笔记本
• 创建文本条目或向笔记本页面上传附件
• 将 LabArchives 与第三方工具（Protocols.io、Jupyter、REDCap）集成
• 自动向电子实验记录本上传数据
• 生成机构（Enterprise）使用情况报告

不适用的情况

场景	改用
Benchling 注册表、库存、ELN 条目或工作流任务	alterlab-benchling
在 protocols.io 上搜索、编写或发布协议	alterlab-protocolsio
设计 REDCap 工具或数据字典，或进行 CDISC 映射	alterlab-redcap-cdisc
选择数据存储库（Zenodo、Dryad、OSF）或 FAIR 数据共享计划	alterlab-open-science

核心功能

1. 客户端和身份验证

有两种 Python 客户端；请根据任务选择：

客户端	安装	用途
labapi（NIMH DSST；PyPI，当前版本 1.2.0，Python >=3.10）	uv pip install "labapi[dotenv]"	新项目推荐：签名、XML 解析、页面树导航、文本条目、附件和备份
labarchives-py（导入名为 labarchivespy；仅限 git）	uv pip install "git+https://github.com/mcmero/labarchives-py"	精简的签名 GET 封装（make_call）；随附脚本使用此封装

前提条件：

• 已为所在机构启用 API 访问（Enterprise 许可证）；访问密钥 ID 和密码由 LabArchives 管理员提供，或联系 [email protected] 获取
• 用户的邮箱地址和 LA App authentication 令牌（在 LabArchives 中点击右上角的姓名 → “LA App authentication”）。该令牌是 users/user_access_info 的 password，而非登录密码。

区域 API 端点（labarchives-py 的 api_url；labapi 的 API_URL 不包含末尾的 /api）：

• 美国/国际：https://api.labarchives.com/api
• 澳大利亚：https://auapi.labarchives.com/api
• 英国：https://ukapi.labarchives.com/api

使用 python3 scripts/setup_config.py 创建随附脚本所需的 config.yaml（输入密钥时不会回显，并以权限模式 600 写入文件）：

api_url: https://api.labarchives.com/api  # or regional endpoint
access_key_id: YOUR_ACCESS_KEY_ID
access_password: YOUR_ACCESS_PASSWORD
user_email: [email protected]
user_external_password: YOUR_LA_APP_AUTH_TOKEN

每次调用都会进行签名：客户端会附加 akid、expires（毫秒时间戳）和 sig（以访问密码为密钥，对 akid + method name + expires 进行 HMAC 后生成的 base64 值），因此密码本身不会发送。有关详细设置和故障排除，请参阅 references/authentication_guide.md。

2. 用户和笔记本发现

users/user_access_info 会返回用户 ID（UID）以及该用户可以打开的笔记本（包含 <id>、<name>、<is-default> 的 <notebook> 元素）：

# labapi
import os
from labapi import Client

with Client() as client:  # reads API_URL, ACCESS_KEYID, ACCESS_PWD
    user = client.login(os.environ["LA_EMAIL"], os.environ["LA_APP_TOKEN"])
    print(list(user.notebooks))                       # notebook names
    page = user.notebooks["Lab Notebook"].traverse("Experiments/2026/Run-12")

# labarchives-py (signed GET)
import xml.etree.ElementTree as ET
from labarchivespy.client import Client

client = Client(api_url, access_key_id, access_password)
response = client.make_call('users', 'user_access_info',
                            params={'login_or_email': user_email, 'password': auth_token})
root = ET.fromstring(response.content)
uid = root[0].text
notebooks = [(nb.findtext('id'), nb.findtext('name')) for nb in root.iter('notebook')]

labarchives-py 封装不会对参数值进行 URL 编码，因此通过 make_call 传递的值应简单明了（或改用 labapi）。

3. 笔记本备份

notebooks/notebook_backup（参数 uid、nbid，可选参数 json=true、no_attachments=true）会将笔记本作为 7-Zip 归档文件返回；只有笔记本的所有者才能下载（否则会报错 4547）。

# Back up one notebook (credentials come from config.yaml)
python3 scripts/notebook_operations.py backup --nbid NOTEBOOK_ID

# Without attachments, JSON data inside the archive
python3 scripts/notebook_operations.py backup --nbid NOTEBOOK_ID --json --no-attachments

# List notebooks, or back up every notebook you can open
python3 scripts/notebook_operations.py list
python3 scripts/notebook_operations.py backup-all --output backups/

使用 labapi：user.notebooks["Lab Notebook"].backup("backups/lab_notebook.7z")。

有关 API 方法的参考信息，请参阅 references/api_reference.md。

4. 条目和附件

条目位于笔记本树的页面上，因此写入时需要笔记本 ID（nbid）和页面树 ID（pid）：

操作	API 方法	备注
创建页面或文件夹	tree_tools/insert_node	parent_tree_id、display_text、is_folder
添加文本条目	entries/add_entry（POST）	表单字段 entry_data；part_type = text entry（HTML）、plain text entry 或 heading
添加附件	entries/add_attachment（POST）	请求正文为原始文件字节；filename、caption、change_description
更新文本条目	entries/update_entry（POST）	eid + entry_data
列出页面上的条目	tree_tools/get_entries_for_page

# labapi: text entry + attachment on a page
from labapi import Attachment, AttachmentEntry, TextEntry

page.entries.create(TextEntry, "<p>Run 12 complete; see attached plate map.</p>")
page.entries.create(AttachmentEntry, Attachment.from_file("plate_map.pdf"))

# Bundled script (labarchives-py signing, POSTs issued by the script)
python3 scripts/entry_operations.py create --nbid NOTEBOOK_ID --pid PAGE_ID --content "Results from today's experiment..."
python3 scripts/entry_operations.py upload --nbid NOTEBOOK_ID --pid PAGE_ID --file /path/to/file.pdf --caption "Raw data"
python3 scripts/entry_operations.py batch-upload --nbid NOTEBOOK_ID --pid PAGE_ID --directory ./experiment_data/

这两个客户端都不支持评论；编写脚本前，请在 LabArchives API 笔记本中查找评论方法。请在附件说明或文本条目中记录来源信息（仪器、软件版本、时间戳）。大文件上传前，请检查每个文件的大小限制（users/max_file_size）。

5. 站点报告（Enterprise）

LabArchives 在 site_reports 类下为 Enterprise 管理员提供机构级报告文档（详细使用情况、笔记本清单、PDF/离线生成、成员、设置）。此处未验证 references/api_reference.md 中的方法名称；使用前请在所在机构的 API 文档中确认。

6. 第三方集成

LabArchives 可与 Protocols.io、GraphPad Prism（8+）、SnapGene、Geneious、Jupyter、REDCap、Qeios 和 SciSpace 集成，大多通过应用内导出功能实现；较新的集成使用 OAuth。程序化桥接（Jupyter → 条目、REDCap 导出 → 条目、协议导入）位于 references/integrations.md。

常见工作流

完整备份笔记本

1. 配置凭据（scripts/setup_config.py）
2. python3 scripts/notebook_operations.py backup-all --output backups/
3. 确认每个归档都能打开（7-Zip），并连同时间戳一起存储；按计划重复执行

自动上传数据

1. 确定目标页面（在 labapi 中使用 notebook.traverse("Experiments/2026/Run-12")，或使用其树 ID）
2. 将数据文件作为附件上传
3. 添加文本条目，描述来源信息（仪器、软件版本、参数、时间戳）

Jupyter → LabArchives

1. 将已执行的笔记本导出为 HTML（nbconvert）
2. 在实验页面上将 HTML 添加为文本条目，并将 .ipynb 添加为附件
3. 将环境详情（requirements.txt/environment.yml）作为第二个附件添加

最佳实践

1. 凭据： 将访问密码和应用令牌保存在环境变量或权限模式为 600 的配置文件中，切勿将其写入代码或笔记本
2. 速率限制： 在批处理循环中加入短暂延迟，遇到错误时逐步延长等待时间；LabArchives 未在此处公布固定配额
3. 备份验证： 每次备份后打开归档并抽查
4. 区域端点： 使用所在 LabArchives 区域的 API 主机
5. 合规性： ELN 记录可能受监管（21 CFR Part 11、HIPAA）；除非笔记本已获准处理，否则请勿上传可识别患者身份的数据

故障排除

• 401 / 签名错误： 检查访问密钥 ID/密码，以及机器时钟是否正确（签名会过期）
• 备份时出现 4547： 只有笔记本所有者才能下载备份
• 404 / 空响应： 确认 nbid/pid 存在，且用户可以打开该笔记本
• 上传失败： 检查 users/max_file_size 和文件类型

如需更多支持，请联系 LabArchives：[email protected]。

资源

scripts/

• setup_config.py：交互式配置文件生成器（隐藏敏感信息的提示，权限模式为 600）
• notebook_operations.py：列出笔记本并进行备份（单个或全部）
• entry_operations.py：向页面添加文本条目并上传附件

references/

• api_reference.md：API 类、方法和参数
• authentication_guide.md：身份验证设置和配置
• integrations.md：第三方集成设置指南和代码

属于 AlterLab Academic Skills 套件的一部分。