Integração com Benchling

Quando usar

Use esta habilidade para entidades de registro do Benchling, importações de sequências, inventário, entradas de ELN, tarefas de fluxo de trabalho, aplicativos, integrações orientadas por eventos e análises de data warehouse.

Revisado em 30/09/2026: os exemplos visam o benchling-sdk 1.25.0 lançado e seus modelos de API v2 estáveis. O guia de autenticação atual recomenda a V3 para desenvolvimento novo, enquanto o guia V3 ainda descreve acesso antecipado específico de endpoint. Confirme a disponibilidade e estabilidade da V3 em seu tenant antes de migrar; estes exemplos do SDK v2 não devem ser reescritos mecanicamente para V3.

Importações de SDK, serialização de modelos e construção de requisições foram verificadas localmente com a versão 1.25.0. Exemplos dependentes de tenant são ilustrativos: nenhuma requisição autenticada, mutação, implantação AWS ou conexão de data warehouse foi executada.

Fluxo de trabalho

1. Identifique o tenant, a versão da API, a identidade e as permissões. Use credenciais de aplicativo OAuth para integrações em segundo plano; use autorização delegada ao agir como um usuário individual. Veja autenticação.
2. Leia o schema relevante e resolva os IDs reais de pasta, registro, status e dropdown. Preserve o alfabeto/topologia da sequência e as unidades de amostra. Um modelo Python válido não estabelece correção biológica ou satisfação dos campos obrigatórios de um tenant.
3. Leia uma pequena página filtrada antes de escrever. Use métodos de SDK tipados e verifique seus nomes de parâmetros reais; nem todos os serviços compartilham a mesma convenção de nomenclatura CRUD.
4. Construa e serialize um payload representativo. Para importações, retenha IDs externos e IDs do Benchling retornados para que uma nova tentativa possa reconciliar uma execução parcial sem duplicatas.
5. Execute a operação solicitada e leia o resultado. Verifique o status assíncrono terminal; o polling concluído ainda pode significar FAILED.

Configuração e uma consulta somente leitura

uv pip install "benchling-sdk==1.25.0"

import os
from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.client_credentials_oauth2 import ClientCredentialsOAuth2

tenant_url = os.environ["BENCHLING_TENANT_URL"].rstrip("/")
benchling = Benchling(
    url=tenant_url,
    auth_method=ClientCredentialsOAuth2(
        client_id=os.environ["BENCHLING_CLIENT_ID"],
        client_secret=os.environ["BENCHLING_CLIENT_SECRET"],
        token_url=f"{tenant_url}/oauth/token",
    ),
)
for page in benchling.dna_sequences.list(page_size=10, name_includes="plasmid"):
    for sequence in page:
        print(sequence.id, sequence.name)
    break  # deliberate first-page connectivity/permission check

Uma página vazia bem-sucedida é um resultado de conectividade válido. Não implica acesso a todos os projetos. Não há rota users/me ou users.get_me() de SDK v2 documentada.

Convenções importantes do SDK

• Importe fields de benchling_sdk.helpers.serialization_helpers. Sua entrada é {"field_name": {"value": value}}, incluindo o mapeamento interno value.
• Use dna_sequence_id para atualizações de DNA e workflow_task_id para atualizações de fluxo de trabalho. A criação de tarefas de fluxo de trabalho requer um workflow_task_group_id.
• Métodos de entrada são create_entry, get_entry_by_id, list_entries e update_entry.
• list() geralmente retorna páginas; itere duas vezes para alcançar os objetos. estimated_count é uma propriedade que pode gerar NotImplementedError, não um método ou contagem garantida.
• Mover um tubo usa ContainerUpdate(parent_storage_id=...). A transferência de material é uma operação separada; ela altera conteúdos e quantidades.
• Registre na criação com registry_id mais um de entity_registry_id (um identificador de registro humano) ou naming_strategy. Não confunda esses com o ID do registro.

Casos de uso comuns

Importar sequências FASTA

Instale Biopython separadamente (uv pip install biopython). Esta importação ilustrativa cria DNA linear não registrado; escolha a topologia e resolva colisões antes de executar.

from Bio import SeqIO
from benchling_sdk.models import DnaSequenceCreate

for record in SeqIO.parse("sequences.fasta", "fasta"):
    payload = DnaSequenceCreate(
        name=record.id,
        bases=str(record.seq),
        is_circular=False,
        folder_id="lib_example",
    )
    created = benchling.dna_sequences.create(payload)
    print(record.id, created.id)  # persist this mapping for restart/reconciliation

Auditar inventário sob uma localização

…