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 クライアントは 2 種類あります。タスクに応じて選択してください。

クライアント	インストール	用途
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 では、Enterprise 管理者向けに、組織レベルのレポート（詳細な使用状況、ノートブックの一覧、PDF／オフライン生成、メンバー、設定）を site_reports クラスで提供しています。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）を 2 つ目の添付ファイルとして追加する

ベストプラクティス

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 とファイル形式を確認してください

追加のサポートについては、[email protected] の LabArchives にお問い合わせください。

リソース

scripts/

• setup_config.py：対話式の設定ファイル生成ツール（シークレットの入力は非表示、モード 600）
• notebook_operations.py：ノートブックの一覧表示とバックアップ（単一またはすべて）
• entry_operations.py：ページへのテキストエントリの追加と添付ファイルのアップロード

references/

• api_reference.md：API クラス、メソッド、パラメーター
• authentication_guide.md：認証の設定と構成
• integrations.md：サードパーティとの連携設定ガイドとコード

AlterLab Academic Skills スイートの一部です。