Intégration LabArchives

Aperçu

LabArchives est une plateforme de carnet de laboratoire électronique pour la documentation de recherche et la gestion de données. Accédez aux carnets, gérez les entrées et pièces jointes, générez des rapports et intégrez-vous à des outils tiers via une API REST.

Quand utiliser cette compétence

Cette compétence doit être utilisée quand :

Travailler avec l'API REST LabArchives pour l'automatisation des carnets
Sauvegarder les carnets par programmation
Créer ou gérer les entrées et pièces jointes des carnets
Générer des rapports et analyses du site
Intégrer LabArchives avec des outils tiers (Protocols.io, Jupyter, REDCap)
Automatiser le chargement de données vers des carnets de laboratoire électroniques
Gérer l'accès utilisateur et les permissions par programmation

Capacités principales

1. Authentification et configuration

Configurez les identifiants d'accès API et les points d'accès régionaux pour l'intégration de l'API LabArchives.

Prérequis :

Licence LabArchives Enterprise avec accès API activé
ID de clé d'accès et mot de passe depuis l'administrateur LabArchives
Identifiants d'authentification utilisateur (email et mot de passe des applications externes)

Configuration :

Utilisez le script scripts/setup_config.py pour créer un fichier de configuration :

python3 scripts/setup_config.py

Cela crée un fichier config.yaml avec la structure suivante :

api_url: https://api.labarchives.com/api  # ou point d'accès régional
access_key_id: YOUR_ACCESS_KEY_ID
access_password: YOUR_ACCESS_PASSWORD

Points d'accès régionaux de l'API :

États-Unis/International : https://api.labarchives.com/api
Australie : https://auapi.labarchives.com/api
Royaume-Uni : https://ukapi.labarchives.com/api

Pour des instructions d'authentification détaillées et le dépannage, consultez references/authentication_guide.md.

2. Récupération des informations utilisateur

Obtenez l'ID utilisateur (UID) et les informations d'accès nécessaires pour les opérations API ultérieures.

Flux de travail :

Appelez la méthode API users/user_access_info avec les identifiants de connexion
Analysez la réponse XML/JSON pour extraire l'ID utilisateur (UID)
Utilisez l'UID pour récupérer les informations utilisateur détaillées via users/user_info_via_id

Exemple utilisant le wrapper Python :

from labarchivespy.client import Client

# Initialiser le client
client = Client(api_url, access_key_id, access_password)

# Obtenir les infos d'accès utilisateur
login_params = {'login_or_email': user_email, 'password': auth_token}
response = client.make_call('users', 'user_access_info', params=login_params)

# Extraire l'UID de la réponse
import xml.etree.ElementTree as ET
uid = ET.fromstring(response.content)[0].text

# Obtenir les infos utilisateur détaillées
params = {'uid': uid}
user_info = client.make_call('users', 'user_info_via_id', params=params)

3. Opérations sur les carnets

Gérez l'accès aux carnets, la sauvegarde et la récupération des métadonnées.

Opérations principales :

Lister les carnets : Récupérez tous les carnets accessibles à un utilisateur
Sauvegarder les carnets : Téléchargez les données complètes du carnet avec inclusion optionnelle des pièces jointes
Obtenir les ID des carnets : Récupérez les identifiants des carnets définis par l'institution pour l'intégration avec les systèmes de gestion de projets/subventions
Obtenir les membres du carnet : Listez tous les utilisateurs ayant accès à un carnet spécifique
Obtenir les paramètres du carnet : Récupérez la configuration et les permissions des carnets

Exemple de sauvegarde du carnet :

Utilisez le script scripts/notebook_operations.py :

# Sauvegarder avec pièces jointes (par défaut, crée une archive 7z)
python3 scripts/notebook_operations.py backup --uid USER_ID --nbid NOTEBOOK_ID

# Sauvegarder sans pièces jointes, format JSON
python3 scripts/notebook_operations.py backup --uid USER_ID --nbid NOTEBOOK_ID --json --no-attachments

Format du point d'accès API :

https://<api_url>/notebooks/notebook_backup?uid=<UID>&nbid=<NOTEBOOK_ID>&json=true&no_attachments=false

Pour la documentation complète des méthodes API, consultez references/api_reference.md.

4. Gestion des entrées et pièces jointes

Créez, modifiez et gérez les entrées des carnets et les pièces jointes.

Opérations sur les entrées :

Créer des entrées dans les carnets
Ajouter des commentaires aux entrées existantes
Créer des parties/composants d'entrée
Charger des pièces jointes vers les entrées

Flux de travail des pièces jointes :

Utilisez le script scripts/entry_operations.py :

# Charger une pièce jointe vers une entrée
python3 scripts/entry_operations.py upload --uid USER_ID --nbid NOTEBOOK_ID --entry-id ENTRY_ID --file /path/to/file.pdf

# Créer une nouvelle entrée avec contenu texte
python3 scripts/entry_operations.py create --uid USER_ID --nbid NOTEBOOK_ID --title "Experiment Results" --content "Results from today's experiment..."

Types de fichiers supportés :

Documents (PDF, DOCX, TXT)
Images (PNG, JPG, TIFF)
Fichiers de données (CSV, XLSX, HDF5)
Formats scientifiques (CIF, MOL, PDB)
Archives (ZIP, 7Z)

5. Rapports du site et analyses

Générez des rapports institutionnels sur l'utilisation, l'activité et la conformité des carnets (fonctionnalité Enterprise).

Rapports disponibles :

Rapport d'utilisation détaillé : Métriques d'activité utilisateur et statistiques d'engagement
Rapport détaillé du carnet : Métadonnées du carnet, listes de membres et paramètres
Rapport de génération de carnet PDF/Hors ligne : Suivi des exports pour la conformité
Rapport des membres du carnet : Contrôle d'accès et analyses de collaboration
Rapport des paramètres du carnet : Audit de la configuration et des permissions

Génération de rapports :

# Générer un rapport d'utilisation détaillé
response = client.make_call('site_reports', 'detailed_usage_report',
                           params={'start_date': '2025-01-01', 'end_date': '2025-10-20'})

6. Intégrations tierces

LabArchives s'intègre à de nombreuses plateformes de logiciels scientifiques. Cette compétence fournit des conseils pour exploiter ces intégrations par programmation.

Intégrations supportées :

Protocols.io : Exportez les protocoles directement vers les carnets LabArchives
GraphPad Prism : Exportez les analyses et figures (Version 8+)
SnapGene : Intégration directe du flux de travail de biologie moléculaire
Geneious : Export d'analyses de bioinformatique
Jupyter : Intégrez les carnets Jupyter comme entrées
REDCap : Intégration de capture de données cliniques
Qeios : Plateforme de publication de recherche
SciSpace : Gestion de la littérature

Authentification OAuth : LabArchives utilise désormais OAuth pour toutes les nouvelles intégrations. Les intégrations héritées peuvent utiliser l'authentification par clé API.

Pour des instructions de configuration détaillées et des cas d'usage, consultez references/integrations.md.

Flux de travail courants

Flux de travail complet de sauvegarde du carnet

S'authentifier et obtenir l'ID utilisateur
Lister tous les carnets accessibles
Itérer parmi les carnets et sauvegarder chacun
Stocker les sauvegardes avec métadonnées d'horodatage

# Script de sauvegarde complet
python3 scripts/notebook_operations.py backup-all --email user@example.edu --password AUTH_TOKEN

Flux de travail de chargement de données automatisé

S'authentifier avec l'API LabArchives
Identifier le carnet et l'entrée cible
Charger les fichiers de données expérimentales
Ajouter des commentaires de métadonnées aux entrées
Générer un rapport d'activité

Exemple de flux de travail d'intégration (Jupyter → LabArchives)

Exporter le carnet Jupyter en HTML ou PDF
Utiliser entry_operations.py pour charger dans LabArchives
Ajouter un commentaire avec horodatage d'exécution et infos d'environnement
Étiqueter l'entrée pour une récupération facile

Installation du package Python

Installez le wrapper labarchives-py pour un accès API simplifié :

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

Sinon, utilisez les requêtes HTTP directes via la bibliothèque requests de Python pour les implémentations personnalisées.

Bonnes pratiques

Limitation de débit : Implémentez des délais appropriés entre les appels API pour éviter la limitation
Gestion des erreurs : Enveloppez toujours les appels API dans des blocs try-except avec une journalisation appropriée
Sécurité de l'authentification : Stockez les identifiants dans des variables d'environnement ou des fichiers de configuration sécurisés (jamais dans le code)
Vérification de la sauvegarde : Après la sauvegarde du carnet, vérifiez l'intégrité et l'exhaustivité du fichier
Opérations incrémentielles : Pour les grands carnets, utilisez la pagination et le traitement par lots
Points d'accès régionaux : Utilisez le point d'accès régional correct de l'API pour des performances optimales

Dépannage

Problèmes courants :

401 Non autorisé : Vérifiez que l'ID de clé d'accès et le mot de passe sont corrects ; vérifiez que l'accès API est activé pour votre compte
404 Non trouvé : Confirmez que l'ID du carnet (nbid) existe et que l'utilisateur dispose des permissions d'accès
403 Interdit : Vérifiez les permissions utilisateur pour l'opération demandée
Réponse vide : Assurez-vous que les paramètres requis (uid, nbid) sont fournis correctement
Échecs du chargement de pièces jointes : Vérifiez les limites de taille de fichier et la compatibilité du format

Pour une assistance supplémentaire, contactez LabArchives à support@labarchives.com.

Ressources

Cette compétence inclut des ressources intégrées pour soutenir l'intégration de l'API LabArchives :

scripts/

setup_config.py : Générateur interactif de fichier de configuration pour les identifiants API
notebook_operations.py : Utilitaires pour lister, sauvegarder et gérer les carnets
entry_operations.py : Outils pour créer des entrées et charger des pièces jointes

references/

api_reference.md : Documentation complète des points d'accès API avec paramètres et exemples
authentication_guide.md : Instructions détaillées de configuration et d'authentification
integrations.md : Guides de configuration d'intégration tierce et cas d'usage

labarchive-integration