labarchive-integration

LabArchives 統合

概要

LabArchives は、研究記録とデータ管理のための電子実験ノートプラットフォームです。REST API を介してプログラムからノートブックへのアクセス、エントリーや添付ファイルの管理、レポートの生成を行い、サードパーティツールと統合できます。

このスキルを使用するタイミング

このスキルは、次の場合に使用してください:

• ノートブックの自動化のために LabArchives REST API を操作する場合
• ノートブックをプログラムからバックアップする場合
• ノートブックのエントリーや添付ファイルを作成または管理する場合
• サイトレポートや分析を生成する場合
• LabArchives をサードパーティツール（Protocols.io、Jupyter、REDCap）と統合する場合
• 電子実験ノートへのデータアップロードを自動化する場合
• ユーザーのアクセス権限をプログラムから管理する場合

主な機能

1. 認証と設定

LabArchives API 統合のために、API アクセス認証情報とリージョン別エンドポイントを設定します。

前提条件:

• API アクセスが有効な Enterprise 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. サイトレポートと分析

ノートブックの利用状況、アクティビティ、コンプライアンスに関する機関向けレポートを生成します（Enterprise 機能）。

利用可能なレポート:

• 詳細利用レポート: ユーザーのアクティビティ指標とエンゲージメント統計
• 詳細ノートブックレポート: ノートブックのメタデータ、メンバー一覧、設定
• 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: 分析結果と図をエクスポート（バージョン 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 パッケージのインストール

簡易的な API アクセスのために labarchives-py ラッパーをインストールします:

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

または、独自の実装を行う場合は、Python の requests ライブラリを使用して直接 HTTP リクエストを送信することもできます。

ベストプラクティス

1. レート制限: スロットリングを避けるため、API 呼び出しの間に適切な待機時間を設ける
2. エラー処理: API 呼び出しは必ず、適切なログ出力を伴う try-except ブロックで囲む
3. 認証情報の安全な管理: 認証情報は環境変数または安全な設定ファイルに保存する（コードに直接書かない）
4. バックアップの検証: ノートブックのバックアップ後に、ファイルの整合性と完全性を確認する
5. 増分処理: 大規模なノートブックでは、ページネーションとバッチ処理を使用する
6. リージョン別エンドポイント: 最適なパフォーマンスを得るために、正しいリージョンの API エンドポイントを使用する

トラブルシューティング

よくある問題:

• 401 Unauthorized: アクセスキー ID とパスワードが正しいか確認する。アカウントで API アクセスが有効になっているか確認する
• 404 Not Found: ノートブック ID (nbid) が存在し、ユーザーにアクセス権があるか確認する
• 403 Forbidden: 要求された操作に対するユーザーの権限を確認する
• 空のレスポンス: 必須パラメータ（uid、nbid）が正しく指定されているか確認する
• 添付ファイルのアップロード失敗: ファイルサイズの上限と形式の互換性を確認する

その他のサポートについては、[email protected] までお問い合わせください。

リソース

このスキルには、LabArchives API 連携をサポートするためのリソースが含まれています:

scripts/

• setup_config.py: API 認証情報の設定ファイルを対話形式で生成するツール
• notebook_operations.py: ノートブックの一覧表示、バックアップ、管理を行うユーティリティ
• entry_operations.py: エントリーの作成と添付ファイルのアップロードを行うツール

references/

• api_reference.md: パラメータと例を含む、API エンドポイントの包括的なドキュメント
• authentication_guide.md: 認証のセットアップと設定に関する詳細な手順
• integrations.md: サードパーティ連携のセットアップガイドとユースケース