benchling-integration

Benchling インテグレーション

概要

Benchling は、ライフサイエンス R&D 向けのクラウドプラットフォームです。Python SDK と REST API を通じて、レジストリエンティティ（DNA、タンパク質）、インベントリ、電子実験ノート、ワークフローにプログラムからアクセスできます。

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

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

• Benchling の Python SDK または REST API を扱う場合
• 生物学的配列（DNA、RNA、タンパク質）とレジストリエンティティを管理する場合
• インベントリ操作（サンプル、コンテナ、ロケーション、移送）を自動化する場合
• 電子実験ノートのエントリを作成または照会する場合
• ワークフローの自動化または Benchling Apps を構築する場合
• Benchling と外部システムの間でデータを同期する場合
• 分析のために Benchling Data Warehouse を照会する場合
• AWS EventBridge を使ったイベント駆動型インテグレーションを設定する場合

主な機能

1. 認証とセットアップ

Python SDK のインストール:

# Stable release
uv pip install benchling-sdk
# or with Poetry
poetry add benchling-sdk

認証方法:

API キー認証（スクリプト向けに推奨）:

from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.api_key_auth import ApiKeyAuth

benchling = Benchling(
    url="https://your-tenant.benchling.com",
    auth_method=ApiKeyAuth("your_api_key")
)

OAuth クライアント資格情報（アプリ向け）:

from benchling_sdk.auth.client_credentials_oauth2 import ClientCredentialsOAuth2

auth_method = ClientCredentialsOAuth2(
    client_id="your_client_id",
    client_secret="your_client_secret"
)
benchling = Benchling(
    url="https://your-tenant.benchling.com",
    auth_method=auth_method
)

重要なポイント:

• API キーは Benchling の Profile Settings から取得します
• 資格情報は安全に保管してください（環境変数またはパスワードマネージャーを使用）
• すべての API リクエストには HTTPS が必要です
• 認証の権限は UI 上のユーザー権限と一致します

OIDC やセキュリティのベストプラクティスを含む詳細な認証情報については、references/authentication.md を参照してください。

2. レジストリとエンティティの管理

レジストリエンティティには、DNA 配列、RNA 配列、AA 配列、カスタムエンティティ、混合物が含まれます。SDK は、これらのエンティティを作成・管理するための型付きクラスを提供します。

DNA 配列の作成:

from benchling_sdk.models import DnaSequenceCreate

sequence = benchling.dna_sequences.create(
    DnaSequenceCreate(
        name="My Plasmid",
        bases="ATCGATCG",
        is_circular=True,
        folder_id="fld_abc123",
        schema_id="ts_abc123",  # optional
        fields=benchling.models.fields({"gene_name": "GFP"})
    )
)

レジストリへの登録:

エンティティの作成時に直接登録するには、次のようにします。

sequence = benchling.dna_sequences.create(
    DnaSequenceCreate(
        name="My Plasmid",
        bases="ATCGATCG",
        is_circular=True,
        folder_id="fld_abc123",
        entity_registry_id="src_abc123",  # Registry to register in
        naming_strategy="NEW_IDS"  # or "IDS_FROM_NAMES"
    )
)

重要: entity_registry_id と naming_strategy のどちらか一方のみを使用し、両方は使用しないでください。

エンティティの更新:

from benchling_sdk.models import DnaSequenceUpdate

updated = benchling.dna_sequences.update(
    sequence_id="seq_abc123",
    dna_sequence=DnaSequenceUpdate(
        name="Updated Plasmid Name",
        fields=benchling.models.fields({"gene_name": "mCherry"})
    )
)

指定されていないフィールドは変更されないため、部分的な更新が可能です。

一覧取得とページネーション:

# List all DNA sequences (returns a generator)
sequences = benchling.dna_sequences.list()
for page in sequences:
    for seq in page:
        print(f"{seq.name} ({seq.id})")

# Check total count
total = sequences.estimated_count()

主な操作:

• 作成: benchling.<entity_type>.create()
• 読み取り: benchling.<entity_type>.get(id) または .list()
• 更新: benchling.<entity_type>.update(id, update_object)
• アーカイブ: benchling.<entity_type>.archive(id)

エンティティタイプ: dna_sequences、rna_sequences、aa_sequences、custom_entities、mixtures

SDK の包括的なリファレンスと高度なパターンについては、references/sdk_reference.md を参照してください。

3. インベントリ管理

Benchling のインベントリシステム内で、物理的なサンプル、コンテナ、ボックス、ロケーションを管理します。

コンテナの作成:

from benchling_sdk.models import ContainerCreate

container = benchling.containers.create(
    ContainerCreate(
        name="Sample Tube 001",
        schema_id="cont_schema_abc123",
        parent_storage_id="box_abc123",  # optional
        fields=benchling.models.fields({"concentration": "100 ng/μL"})
    )
)

ボックスの管理:

from benchling_sdk.models import BoxCreate

box = benchling.boxes.create(
    BoxCreate(
        name="Freezer Box A1",
        schema_id="box_schema_abc123",
        parent_storage_id="loc_abc123"
    )
)

アイテムの移送:

# Transfer a container to a new location
transfer = benchling.containers.transfer(
    container_id="cont_abc123",
    destination_id="box_xyz789"
)

主なインベントリ操作:

• コンテナ、ボックス、ロケーション、プレートの作成
• インベントリアイテムのプロパティの更新
• アイテムをロケーション間で移送
• アイテムのチェックイン/チェックアウト
• 一括移送のためのバッチ操作

4. ノートブックとドキュメント

電子実験ノート（ELN）のエントリ、プロトコル、テンプレートを操作します。

ノートブックエントリの作成:

from benchling_sdk.models import EntryCreate

entry = benchling.entries.create(
    EntryCreate(
        name="Experiment 2025-10-20",
        folder_id="fld_abc123",
        schema_id="entry_schema_abc123",
        fields=benchling.models.fields({"objective": "Test gene expression"})
    )
)

エンティティのエントリへのリンク:

# Add references to entities in an entry
entry_link = benchling.entry_links.create(
    entry_id="entry_abc123",
    entity_id="seq_xyz789"
)

主なノートブック操作:

• 実験ノートのエントリの作成と更新
• エントリテンプレートの管理
• エンティティと結果をエントリにリンク
• ドキュメント用にエントリをエクスポート

5. ワークフローと自動化

Benchling のワークフローシステムを使用して、ラボのプロセスを自動化します。

ワークフロータスクの作成:

from benchling_sdk.models import WorkflowTaskCreate

task = benchling.workflow_tasks.create(
    WorkflowTaskCreate(
        name="PCR Amplification",
        workflow_id="wf_abc123",
        assignee_id="user_abc123",
        fields=benchling.models.fields({"template": "seq_abc123"})
    )
)

タスクステータスの更新:

from benchling_sdk.models import WorkflowTaskUpdate

updated_task = benchling.workflow_tasks.update(
    task_id="task_abc123",
    workflow_task=WorkflowTaskUpdate(
        status_id="status_complete_abc123"
    )
)

非同期操作:

一部の操作は非同期で、タスクを返します。

# Wait for task completion
from benchling_sdk.helpers.tasks import wait_for_task

result = wait_for_task(
    benchling,
    task_id="task_abc123",
    interval_wait_seconds=2,
    max_wait_seconds=300
)

主なワークフロー操作:

• ワークフロータスクの作成と管理
• タスクのステータスと担当者の更新
• 一括操作を非同期で実行
• タスクの進捗を監視

6. イベントと連携

AWS EventBridge を使用して、リアルタイム連携のために Benchling のイベントをサブスクライブします。

イベントの種類:

• エンティティの作成、更新、アーカイブ
• 在庫の移動
• ワークフロータスクのステータス変更
• エントリの作成と更新
• 結果の登録

連携パターン:

1. Benchling の設定で、AWS EventBridge へのイベントルーティングを構成します
2. EventBridge ルールを作成して、イベントをフィルタリングします
3. イベントを Lambda 関数やその他のターゲットにルーティングします
4. イベントを処理し、外部システムを更新します

ユースケース:

• Benchling のデータを外部データベースに同期する
• ワークフローの完了時に後続のプロセスをトリガーする
• エンティティの変更時に通知を送信する
• 監査証跡のロギング

イベントスキーマと構成については、Benchling のイベントドキュメントを参照してください。

7. データウェアハウスと分析

データウェアハウスを通じて、SQL を使用して Benchling の過去のデータを照会します。

アクセス方法: Benchling データウェアハウスは、分析とレポート作成のために Benchling データへの SQL アクセスを提供します。提供された認証情報を使用して、標準の SQL クライアントから接続します。

一般的なクエリ:

• 実験結果を集計する
• 在庫の傾向を分析する
• コンプライアンスレポートを生成する
• 外部分析用にデータをエクスポートする

分析ツールとの連携:

• 対話型分析のための Jupyter ノートブック
• BI ツール（Tableau、Looker、PowerBI）
• カスタムダッシュボード

ベストプラクティス

エラーハンドリング

SDK は失敗したリクエストを自動的に再試行します:

# Automatic retry for 429, 502, 503, 504 status codes
# Up to 5 retries with exponential backoff
# Customize retry behavior if needed
from benchling_sdk.retry import RetryStrategy

benchling = Benchling(
    url="https://your-tenant.benchling.com",
    auth_method=ApiKeyAuth("your_api_key"),
    retry_strategy=RetryStrategy(max_retries=3)
)

ページネーションの効率化

メモリ効率の良いページネーションには、ジェネレーターを使用します:

# Generator-based iteration
for page in benchling.dna_sequences.list():
    for sequence in page:
        process(sequence)

# Check estimated count without loading all pages
total = benchling.dna_sequences.list().estimated_count()

スキーマフィールドヘルパー

カスタムスキーマフィールドには fields() ヘルパーを使用します:

# Convert dict to Fields object
custom_fields = benchling.models.fields({
    "concentration": "100 ng/μL",
    "date_prepared": "2025-10-20",
    "notes": "High quality prep"
})

前方互換性

SDK は未知の列挙値や型を適切に処理します:

• 未知の列挙値は保持されます
• 認識されない多態型は UnknownType を返します
• 新しい API バージョンでも動作します

セキュリティに関する考慮事項

• API キーをバージョン管理にコミットしないでください
• 認証情報には環境変数を使用してください
• 漏えいした場合はキーをローテーションしてください
• アプリには必要最小限の権限のみを付与してください
• 複数ユーザーのシナリオでは OAuth を使用してください

リソース

references/

詳細な情報を提供するリファレンスドキュメント:

• authentication.md - OIDC、セキュリティのベストプラクティス、認証情報管理を含む包括的な認証ガイド
• sdk_reference.md - 高度なパターン、例、すべてのエンティティ型を含む詳細な Python SDK リファレンス
• api_endpoints.md - SDK を使用せずに直接 HTTP 呼び出しを行うための REST API エンドポイントリファレンス

特定の連携要件に応じて、必要に応じてこれらのリファレンスを読み込んでください。

scripts/

このスキルには現在、サンプルスクリプトが含まれています。これらは削除するか、特定の Benchling ワークフロー向けのカスタム自動化スクリプトに置き換えることができます。

一般的なユースケース

1. 一括エンティティインポート:

# Import multiple sequences from FASTA file
from Bio import SeqIO

for record in SeqIO.parse("sequences.fasta", "fasta"):
    benchling.dna_sequences.create(
        DnaSequenceCreate(
            name=record.id,
            bases=str(record.seq),
            is_circular=False,
            folder_id="fld_abc123"
        )
    )

2. 在庫監査:

# List all containers in a specific location
containers = benchling.containers.list(
    parent_storage_id="box_abc123"
)

for page in containers:
    for container in page:
        print(f"{container.name}: {container.barcode}")

3. ワークフローの自動化:

# Update all pending tasks for a workflow
tasks = benchling.workflow_tasks.list(
    workflow_id="wf_abc123",
    status="pending"
)

for page in tasks:
    for task in page:
        # Perform automated checks
        if auto_validate(task):
            benchling.workflow_tasks.update(
                task_id=task.id,
                workflow_task=WorkflowTaskUpdate(
                    status_id="status_complete"
                )
            )

4. データエクスポート:

# Export all sequences with specific properties
sequences = benchling.dna_sequences.list()
export_data = []

for page in sequences:
    for seq in page:
        if seq.schema_id == "target_schema_id":
            export_data.append({
                "id": seq.id,
                "name": seq.name,
                "bases": seq.bases,
                "length": len(seq.bases)
            })

# Save to CSV or database
import csv
with open("sequences.csv", "w") as f:
    writer = csv.DictWriter(f, fieldnames=export_data[0].keys())
    writer.writeheader()
    writer.writerows(export_data)

追加リソース

• 公式ドキュメント: https://docs.benchling.com
• Python SDK リファレンス: https://benchling.com/sdk-docs/
• API リファレンス: https://benchling.com/api/reference
• サポート: [email protected]