labarchive-integration

LabArchives 集成

概述

LabArchives 是一个用于研究文档记录和数据管理的电子实验记录本平台。可通过 REST API 以编程方式访问实验记录本、管理条目和附件、生成报告，并与第三方工具集成。

何时使用此技能

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

• 使用 LabArchives REST API 实现实验记录本自动化
• 以编程方式备份实验记录本
• 创建或管理实验记录本条目和附件
• 生成站点报告和分析数据
• 将 LabArchives 与第三方工具（Protocols.io、Jupyter、REDCap）集成
• 自动将数据上传到电子实验记录本
• 以编程方式管理用户访问权限

核心功能

1. 身份验证和配置

设置 API 访问凭据和区域端点，以便集成 LabArchives API。

先决条件：

• 启用了 API 访问权限的 LabArchives 企业许可证
• LabArchives 管理员提供的 API 访问密钥 ID 和密码
• 用户身份验证凭据（电子邮件和外部应用程序密码）

配置设置：

使用 scripts/setup_config.py 脚本创建配置文件：

python3 scripts/setup_config.py

这会创建一个 config.yaml 文件，其结构如下：

api_url: https://api.labarchives.com/api  # or regional endpoint
access_key_id: YOUR_ACCESS_KEY_ID
access_password: YOUR_ACCESS_PASSWORD

区域 API 端点：

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

有关详细的身份验证说明和故障排除方法，请参阅 references/authentication_guide.md。

2. 用户信息检索

获取后续 API 操作所需的用户 ID（UID）和访问信息。

工作流：

1. 使用登录凭据调用 users/user_access_info API 方法
2. 解析 XML／JSON 响应，提取用户 ID（UID）
3. 使用 UID 通过 users/user_info_via_id 获取详细用户信息

使用 Python 封装程序的示例：

from labarchivespy.client import Client

# Initialize client
client = Client(api_url, access_key_id, access_password)

# Get user access info
login_params = {'login_or_email': user_email, 'password': auth_token}
response = client.make_call('users', 'user_access_info', params=login_params)

# Extract UID from response
import xml.etree.ElementTree as ET
uid = ET.fromstring(response.content)[0].text

# Get detailed user info
params = {'uid': uid}
user_info = client.make_call('users', 'user_info_via_id', params=params)

3. 实验记录本操作

管理实验记录本访问权限、备份和元数据检索。

主要操作：

• 列出实验记录本： 获取用户可访问的所有实验记录本
• 备份实验记录本： 下载完整的实验记录本数据，可选择是否包含附件
• 获取实验记录本 ID： 获取机构定义的实验记录本标识符，以便与资助／项目管理系统集成
• 获取实验记录本成员： 列出有权访问特定实验记录本的所有用户
• 获取实验记录本设置： 获取实验记录本的配置和权限

实验记录本备份示例：

使用 scripts/notebook_operations.py 脚本：

# Backup with attachments (default, creates 7z archive)
python3 scripts/notebook_operations.py backup --uid USER_ID --nbid NOTEBOOK_ID

# Backup without attachments, JSON format
python3 scripts/notebook_operations.py backup --uid USER_ID --nbid NOTEBOOK_ID --json --no-attachments

API 端点格式：

https://<api_url>/notebooks/notebook_backup?uid=<UID>&nbid=<NOTEBOOK_ID>&json=true&no_attachments=false

如需完整的 API 方法文档，请参阅 references/api_reference.md。

4. 条目和附件管理

创建、修改和管理实验记录本条目及文件附件。

条目操作：

• 在实验记录本中创建新条目
• 为现有条目添加评论
• 创建条目部分／组件
• 将文件附件上传到条目

附件工作流：

使用 scripts/entry_operations.py 脚本：

# Upload attachment to an entry
python3 scripts/entry_operations.py upload --uid USER_ID --nbid NOTEBOOK_ID --entry-id ENTRY_ID --file /path/to/file.pdf

# Create a new entry with text content
python3 scripts/entry_operations.py create --uid USER_ID --nbid NOTEBOOK_ID --title "Experiment Results" --content "Results from today's experiment..."

支持的文件类型：

• 文档（PDF、DOCX、TXT）
• 图像（PNG、JPG、TIFF）
• 数据文件（CSV、XLSX、HDF5）
• 科学格式（CIF、MOL、PDB）
• 归档文件（ZIP、7Z）

5. 站点报告和分析

生成有关实验记录本使用情况、活动和合规性的机构报告（企业版功能）。

可用报告：

• 详细使用情况报告：用户活动指标和参与度统计
• 详细实验记录本报告：实验记录本元数据、成员列表和设置
• PDF／离线实验记录本生成报告：用于合规审查的导出跟踪记录
• 实验记录本成员报告：访问控制和协作分析
• 实验记录本设置报告：配置和权限审计

报告生成：

# Generate detailed usage report
response = client.make_call('site_reports', 'detailed_usage_report',
                           params={'start_date': '2025-01-01', 'end_date': '2025-10-20'})

6. 第三方集成

LabArchives 与众多科学软件平台集成。本技能提供了以编程方式利用这些集成的指南。

支持的集成：

• Protocols.io： 将协议直接导出到 LabArchives 笔记本
• GraphPad Prism： 导出分析结果和图表（Version 8+）
• SnapGene： 直接集成分子生物学工作流
• Geneious： 导出生物信息学分析结果
• Jupyter： 将 Jupyter 笔记本嵌入为条目
• REDCap： 临床数据采集集成
• Qeios： 研究出版平台
• SciSpace： 文献管理

OAuth 身份验证： LabArchives 现在对所有新集成都使用 OAuth。旧版集成可能使用 API 密钥身份验证。

如需详细了解集成设置说明和使用场景，请参阅 references/integrations.md。

常见工作流

完整的笔记本备份工作流

1. 进行身份验证并获取用户 ID
2. 列出所有可访问的笔记本
3. 遍历笔记本并逐个备份
4. 使用时间戳元数据存储备份

# Complete backup script
python3 scripts/notebook_operations.py backup-all --email [email protected] --password AUTH_TOKEN

自动化数据上传工作流

1. 使用 LabArchives API 进行身份验证
2. 确定目标笔记本和条目
3. 上传实验数据文件
4. 为条目添加元数据注释
5. 生成活动报告

集成工作流示例（Jupyter → LabArchives）

1. 将 Jupyter 笔记本导出为 HTML 或 PDF
2. 使用 entry_operations.py 将其上传到 LabArchives
3. 添加注释，注明执行时间戳和环境信息
4. 为条目添加标签，以便轻松检索

Python 包安装

安装 labarchives-py 封装库，以简化 API 访问：

git clone https://github.com/mcmero/labarchives-py
cd labarchives-py
uv pip install .

或者，使用 Python 的 requests 库直接发送 HTTP 请求，以进行自定义实现。

最佳实践

1. 速率限制： 在 API 调用之间设置适当的延迟，避免请求被限流
2. 错误处理： 始终使用 try-except 块封装 API 调用，并进行适当的日志记录
3. 身份验证安全： 将凭据存储在环境变量或安全配置文件中（切勿写入代码）
4. 备份验证： 备份笔记本后，验证文件的完整性和完整程度
5. 增量操作： 对于大型笔记本，使用分页和批处理
6. 区域端点： 使用正确的区域 API 端点，以获得最佳性能

故障排除

常见问题：

• 401 Unauthorized： 确认访问密钥 ID 和密码正确；检查账户是否已启用 API 访问
• 404 Not Found： 确认笔记本 ID（nbid）存在，且用户具有访问权限
• 403 Forbidden： 检查用户是否具有执行所请求操作的权限
• 响应为空： 确保正确提供所需参数（uid、nbid）
• 附件上传失败： 检查文件大小限制和格式兼容性

如需其他支持，请通过 [email protected] 联系 LabArchives。

资源

此技能包含用于支持 LabArchives API 集成的附带资源：

scripts/

• setup_config.py：用于生成 API 凭据配置文件的交互式工具
• notebook_operations.py：用于列出、备份和管理笔记本的实用工具
• entry_operations.py：用于创建条目和上传附件的工具

references/

• api_reference.md：完整的 API 端点文档，包含参数和示例
• authentication_guide.md：详细的身份验证设置和配置说明
• integrations.md：第三方集成设置指南和使用场景