alterlab-benchling

Benchling 統合

概要

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

このスキルを使用する場面

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

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

対象外

シナリオ	代わりに使用
LabArchives のノートブック、エントリ、添付ファイル、バックアップ	alterlab-labarchive
protocols.io でのプロトコルの検索、作成、公開	alterlab-protocolsio
LaminDB を使用した FAIR データセットレジストリ、オントロジーのキュレーション、系譜管理	alterlab-lamindb
Benchling 以外での配列解析と操作（FASTA/GenBank I/O）	alterlab-biopython
DNAnexus または LatchBio でのバイオインフォマティクスパイプラインの実行	alterlab-dnanexus / alterlab-latchbio

主な機能

1. 認証とセットアップ

Python SDK のインストール：

# Stable release (benchling-sdk 1.x; current 1.25.0, requires Python >= 3.9)
uv add "benchling-sdk>=1.25,<2"
# or for a throwaway script env
uv pip install benchling-sdk

SDK は API のバージョンではなく、SDK レベルのセマンティックバージョニングに従います。そのため、メジャーバージョンを上げる前に変更履歴を確認してください。

認証方法：

API キー認証（スクリプトに推奨）：

import os
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(os.environ["BENCHLING_API_KEY"])
)

OAuth クライアント認証情報（アプリ向け）：

from benchling_sdk.auth.client_credentials_oauth2 import ClientCredentialsOAuth2

auth_method = ClientCredentialsOAuth2(
    client_id="your_client_id",
    client_secret=os.environ["BENCHLING_CLIENT_SECRET"]
)
benchling = Benchling(
    url="https://your-tenant.benchling.com",
    auth_method=auth_method
)

重要なポイント：

• API キーは Benchling のプロフィール設定から取得します
• 認証情報は環境変数またはシークレットマネージャーに保管し、コードやノートブックには決して記載しないでください
• すべての API リクエストで HTTPS が必要です
• 認証権限は UI でのユーザー権限と同じです

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

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

レジストリエンティティには、DNA 配列、RNA 配列、AA 配列、カスタムエンティティ、混合物が含まれます。SDK には、これらのエンティティを作成および管理するための型付きクラスが用意されています。

DNA 配列の作成：

from benchling_sdk.models import DnaSequenceCreate
from benchling_sdk.helpers.serialization_helpers import fields

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

レジストリへの登録：

エンティティの作成時に直接登録するには、registry_id（登録先のレジストリ）と naming_strategy（レジストリ ID の割り当て方法）を設定します。 naming_strategy には NamingStrategy 列挙型を指定する必要があります。通常の文字列を指定すると、リクエストのシリアライズ時に失敗します：

from benchling_sdk.models import DnaSequenceCreate, NamingStrategy

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

重要： 登録を実行するのは registry_id です。特定のレジストリ ID を直接割り当てるための entity_registry_id フィールドも別にあります。ただし、entity_registry_id と naming_strategy は同時に設定できません（ID の割り当てにはどちらか一方を使用してください）。

エンティティの更新：

from benchling_sdk.models import DnaSequenceUpdate
from benchling_sdk.helpers.serialization_helpers import fields

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

指定されていないフィールドは変更されないため、一部のフィールドのみを更新できます。

一覧表示とページネーション：

# List DNA sequences (a PageIterator that yields pages lazily)
sequences = benchling.dna_sequences.list(schema_id="ts_abc123")  # server-side filters
for page in sequences:
    for seq in page:
        print(f"{seq.name} ({seq.id})")

# Check total count
total = sequences.estimated_count()

主な操作（メソッド名とパラメータ名はエンティティごとに異なります。references/sdk_reference.md を参照してください）：

• 作成：benchling.<entity_type>.create(<CreateModel>)
• 読み取り：benchling.<entity_type>.get_by_id(<entity>_id=...) または .list(...)
• 更新：benchling.<entity_type>.update(<entity>_id=..., <entity>=<UpdateModel>)
• アーカイブ：benchling.<entity_type>.archive(<entity>_ids=[...], reason=EntityArchiveReason.MADE_IN_ERROR)（一括）

エンティティの種類：dna_sequences、rna_sequences、aa_sequences、custom_entities、mixtures

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

3. 在庫管理

Benchling の在庫システムで、物理サンプル、コンテナ、ボックス、ロケーションを管理します。

コンテナの作成：

from benchling_sdk.models import ContainerCreate
from benchling_sdk.helpers.serialization_helpers import fields

container = benchling.containers.create(
    ContainerCreate(
        name="Sample Tube 001",
        schema_id="cont_schema_abc123",
        parent_storage_id="box_abc123",  # optional
        fields=fields({"concentration": {"value": "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"
    )
)

アイテムの移動：

containers.transfer(...) という便利メソッドはありません。ContainerTransfer リクエストオブジェクトを渡し、transfer_into_container（単一）または transfer_into_containers（一括、TaskHelper を返します）を使って、コンテナ間で内容物を移動します。

from benchling_sdk.models import ContainerTransfer

benchling.containers.transfer_into_container(
    destination_container_id="cont_xyz789",
    transfer_request=ContainerTransfer(...),  # source_entity_id/source_container_id, transfer_quantity, ...
)

内容物を移動するのではなく、保管場所内でコンテナを移動するには、containers.update(...) で parent_storage_id を更新します。チェックイン／チェックアウトは一括呼び出しです。containers.checkout(ContainersCheckout(container_ids=[...], assignee_id=...)) と containers.checkin(ContainersCheckin(container_ids=[...])) を使います。

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

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

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

from benchling_sdk.models import EntryCreate
from benchling_sdk.helpers.serialization_helpers import fields

entry = benchling.entries.create_entry(
    EntryCreate(
        name="Experiment 2026-09-23",
        folder_id="fld_abc123",
        schema_id="entry_schema_abc123",
        fields=fields({"objective": {"value": "Test gene expression"}})
    )
)

エントリーへのエンティティのリンク：

v2 API では、既存のエントリーにノートのテキストや @-メンションを書き込むことはできません。 EntryUpdate で変更できるのはメタデータのみです（name、folder_id、schema_id、fields、author_ids）。次のいずれかの方法で、エンティティをエントリーに関連付けます。

• エントリーのスキーマにエンティティリンクフィールドを追加して設定します。 benchling.entries.update_entry(entry_id="entry_abc123", entry=EntryUpdate(fields=fields({"plasmid": {"value": "seq_xyz789"}})))
• テンプレートからエントリーを作成し、作成時にテーブルに値を事前入力します。 EntryCreate(..., entry_template_id="TEMPLATE_ID", initial_tables=[InitialTable(template_table_id="TABLE_ID", csv_data="...")])
• エンティティに対してアッセイの結果／実行を記録します（references/api_endpoints.md を参照）。

主なノートブック操作：

• ラボノートブックのエントリーを作成・更新します（create_entry、update_entry、get_entry_by_id、list_entries）
• エントリーテンプレートを管理します（list_entry_templates、update_entry_template）
• スキーマフィールドまたはテンプレートテーブルを通じてエンティティをリンクします
• ドキュメント用にエントリーをエクスポートします

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

Benchling のワークフローシステムを使用して、ラボのプロセスを自動化します。v2 API では、ワークフローはワークフロータスクグループです。タスクはグループ内で作成され、スキーマで定義されたフィールドを持ちます。

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

from benchling_sdk.models import WorkflowTaskCreate
from benchling_sdk.helpers.serialization_helpers import fields

task = benchling.workflow_tasks.create(
    WorkflowTaskCreate(
        workflow_task_group_id="WORKFLOW_TASK_GROUP_ID",
        assignee_id="USER_ID",            # optional
        fields=fields({"template": {"value": "seq_abc123"}})
    )
)

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

from benchling_sdk.models import WorkflowTaskUpdate

updated_task = benchling.workflow_tasks.update(
    workflow_task_id="WORKFLOW_TASK_ID",
    workflow_task=WorkflowTaskUpdate(
        status_id="COMPLETE_STATUS_ID"
    )
)

非同期操作：

一括／長時間実行の操作は TaskHelper（benchling-sdk 1.x）を返します。タスクが成功するまで待機するには wait_for_response() を呼び出します（生のタスクの場合は wait_for_completion() を呼び出します）。

# A bulk call returns a TaskHelper, not a plain task id
task = benchling.dna_sequences.bulk_create(...)
result = task.wait_for_response(
    interval_wait_seconds=2,
    max_wait_seconds=300,
)

1.x にはトップレベルの wait_for_task(benchling, task_id=...) 関数はありません。ヘルパーは返されたタスクオブジェクトに付属しています。

主なワークフロー操作：

• ワークフロータスクを作成・管理します
• タスクのステータスと割り当てを更新します
• 一括操作を非同期で実行します
• タスクの進行状況を監視します

6. イベントと統合

AWS EventBridge を通じて Benchling のイベント（エンティティの作成／更新／アーカイブ、在庫の移動、ワークフロータスクのステータス変更、エントリーの変更、結果の登録）をサブスクライブします。Benchling の設定でイベントルーティングを構成し、イベントをフィルタリングする EventBridge ルールを作成して、Lambda 関数やその他のターゲットにルーティングします。これらのターゲットで外部システムを更新できます（データベースとの同期、後続プロセスのトリガー、通知、監査ログの記録）。イベントスキーマについては、Benchling のイベントドキュメントを参照してください。

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

Benchling Data Warehouse は、分析やレポート作成（結果の集計、在庫の傾向、コンプライアンスレポート、エクスポート）に使用できる、テナントデータへの読み取り専用 SQL アクセスを提供します。ユーザーごとに発行されるウェアハウスの認証情報を使い、標準的な PostgreSQL クライアントまたは BI ツール（Jupyter、Tableau、Looker、Power BI）で接続します（benchling.users.get_warehouse_logins(user_id) で一覧表示できます）。

ベストプラクティス

エラー処理

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.helpers.retry_helpers import RetryStrategy

benchling = Benchling(
    url="https://your-tenant.benchling.com",
    auth_method=ApiKeyAuth(os.environ["BENCHLING_API_KEY"]),
    retry_strategy=RetryStrategy(max_tries=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
from benchling_sdk.helpers.serialization_helpers import fields

custom_fields = fields({
    "concentration": {"value": "100 ng/μL"},
    "date_prepared": {"value": "2026-09-23"},
    "notes": {"value": "High quality prep"}
})

前方互換性

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

• 未知の列挙値は保持されます
• 認識されないポリモーフィック型は UnknownType を返します
• より新しい API バージョンでも使用できます

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

• キーが侵害された場合はローテーションし、アプリには必要な権限のみを付与してください
• 複数ユーザー向けの連携やサービス連携では、個人用 API キーより OAuth アプリを優先してください
• レジストリやノートブックのデータには、未公開の知的財産や規制対象データが含まれることがあります。エクスポートする前に、所属機関のデータ取り扱い規則に従ってください

リソース

必要に応じて references/ を読み込んでください。authentication.md（OIDC、セキュリティのベストプラクティス、認証情報の管理）、sdk_reference.md（高度な SDK パターン、すべてのエンティティ型）、api_endpoints.md（直接 HTTP を呼び出すための REST エンドポイント）。

一般的なユースケース

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

多数のレコードを扱う場合は、レコードごとの create ループではなく、単一の bulk_create（TaskHelper を返します）を使用してください。これは N 件のリクエストではなく、1 件の非同期ジョブです。一括呼び出しでは DnaSequenceCreate ではなく、DnaSequenceBulkCreate オブジェクトを受け取る点に注意してください。

# Import multiple sequences from a FASTA file in one bulk job
from Bio import SeqIO
from benchling_sdk.models import DnaSequenceBulkCreate

to_create = [
    DnaSequenceBulkCreate(
        name=record.id,
        bases=str(record.seq),
        is_circular=False,
        folder_id="fld_abc123",
    )
    for record in SeqIO.parse("sequences.fasta", "fasta")
]

task = benchling.dna_sequences.bulk_create(to_create)
task.wait_for_response()  # blocks until the bulk job finishes

（少数のレコードであれば、DnaSequenceCreate を使った通常の benchling.dna_sequences.create(...) ループで問題ありません。）

2. 在庫監査：

# List all containers stored anywhere under a box or location
containers = benchling.containers.list(
    ancestor_storage_id="box_abc123"
)

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

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

from benchling_sdk.models import WorkflowTaskUpdate

# Update all pending tasks in a workflow task group.
# Filter by status via status_ids (a list of status IDs, not a status name)
tasks = benchling.workflow_tasks.list(
    workflow_task_group_ids=["WORKFLOW_TASK_GROUP_ID"],
    status_ids=["PENDING_STATUS_ID"]
)

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

4. データのエクスポート：

# Export all sequences of one schema (filtered server-side)
export_data = []
for page in benchling.dna_sequences.list(schema_id="ts_target_schema"):
    for seq in page:
        export_data.append({
            "id": seq.id,
            "name": seq.name,
            "bases": seq.bases,
            "length": seq.length,
        })

# Then write export_data to CSV/database as needed (e.g. csv.DictWriter).

追加リソース

• 公式ドキュメント： https://docs.benchling.com
• Python SDK リファレンス： https://benchling.com/sdk-docs/
• API リファレンス： https://benchling.com/api/reference
• ヘルプセンター／サポート： https://help.benchling.com

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