protocolsio-integration

Protocols.io 統合

概要

Protocols.io は、科学的プロトコルの開発、共有、管理のための包括的なプラットフォームです。このスキルは protocols.io API v3 との完全な統合を提供し、プロトコル、ワークスペース、ディスカッション、ファイル管理、コラボレーション機能へのプログラムによるアクセスを可能にします。

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

protocols.io で以下のいずれかのシナリオに取り組む場合は、このスキルを使用してください:

• プロトコルの検索: キーワード、DOI、カテゴリによる既存プロトコルの検索
• プロトコルの管理: 科学的プロトコルの作成、更新、公開
• ステップの管理: プロトコルのステップや手順の追加、編集、整理
• 共同開発: 共有プロトコルでチームメンバーと作業する
• ワークスペースの整理: ラボや研究機関のプロトコルリポジトリを管理する
• ディスカッションとフィードバック: プロトコルへのコメントの追加や返信
• ファイル管理: プロトコルへのデータファイル、画像、ドキュメントのアップロード
• 実験の追跡: プロトコルの実行と結果の記録
• データエクスポート: プロトコルコレクションのバックアップや移行
• 統合プロジェクト: protocols.io と連携するツールの構築

主な機能

このスキルは、5 つの主要な機能領域にわたる包括的なガイダンスを提供します:

1. 認証とアクセス

アクセストークンと OAuth フローを使用して API 認証を管理します。個人のコンテンツ向けのクライアントアクセストークンと、複数ユーザーのアプリケーション向けの OAuth トークンの両方を含みます。

主な操作:

• OAuth フロー用の認可リンクの生成
• 認可コードのアクセストークンへの交換
• 期限切れトークンの更新
• レート制限と権限の管理

参照: 詳細な認証手順、OAuth の実装、セキュリティのベストプラクティスについては references/authentication.md を読んでください。

2. プロトコル操作

作成から公開まで、プロトコルのライフサイクル全体を管理します。

主な操作:

• キーワード、フィルター、DOI によるプロトコルの検索と発見
• すべてのステップを含む詳細なプロトコル情報の取得
• メタデータとタグを使用した新規プロトコルの作成
• プロトコル情報と設定の更新
• プロトコルステップの管理（作成、更新、削除、並べ替え）
• プロトコルの材料と試薬の管理
• DOI 発行を伴うプロトコルの公開
• クイックアクセスのためのプロトコルのブックマーク
• プロトコル PDF の生成

参照: API エンドポイント、パラメーター、一般的なワークフロー、例を含む包括的なプロトコル管理のガイダンスについては references/protocols_api.md を読んでください。

3. ディスカッションとコラボレーション

コメントとディスカッションを通じてコミュニティの関与を促進します。

主な操作:

• プロトコルレベルおよびステップレベルのコメントの閲覧
• 新規コメントとスレッド形式の返信の作成
• 自分のコメントの編集または削除
• ディスカッションのパターンとフィードバックの分析
• ユーザーからの質問や問題への対応

参照: ディスカッション管理、コメントのスレッド化、コラボレーションのワークフローについては references/discussions.md を読んでください。

4. ワークスペース管理

ロールベースの権限を使用して、チームワークスペース内でプロトコルを整理します。

主な操作:

• ユーザーのワークスペースの一覧表示とアクセス
• ワークスペースの詳細とメンバーリストの取得
• ワークスペースへのアクセスのリクエストまたは参加
• ワークスペース固有のプロトコルの一覧表示
• ワークスペース内でのプロトコルの作成
• ワークスペースの権限とコラボレーションの管理

参照: ワークスペースの整理、権限管理、チームコラボレーションのパターンについては references/workspaces.md を読んでください。

5. ファイル操作

プロトコルに関連付けられたファイルのアップロード、整理、管理を行います。

主な操作:

• ワークスペースのファイルとフォルダーの検索
• メタデータとタグを使用したファイルのアップロード
• ファイルのダウンロードとアップロードの検証
• ファイルのフォルダー階層への整理
• ファイルメタデータの更新
• ファイルの削除と復元
• ストレージと整理の管理

参照: ファイルのアップロード手順、整理戦略、ストレージ管理については references/file_manager.md を読んでください。

6. 追加機能

プロフィール、通知、エクスポートを含む補助的な機能です。

主な操作:

• ユーザープロフィールと設定を管理する
• 最近公開されたプロトコルを照会する
• 実験記録を作成して追跡する
• 通知を受信して管理する
• アーカイブ用に組織データをエクスポートする

参照: プロフィール管理、公開物の検索、実験追跡、データエクスポートについては references/additional_features.md を読んでください。

はじめに

ステップ 1: 認証の設定

protocols.io API の機能を使用する前に:

1. アクセストークン（CLIENT_ACCESS_TOKEN または OAUTH_ACCESS_TOKEN）を取得します
2. 詳細な認証手順については references/authentication.md を読んでください
3. トークンを安全に保管します
4. すべてのリクエストに次の形式で含めます: Authorization: Bearer YOUR_TOKEN

ステップ 2: ユースケースを特定する

どの機能領域がニーズに合うかを判断してください:

• プロトコルを扱いたい場合 → references/protocols_api.md を読んでください
• チームのプロトコルを管理したい場合 → references/workspaces.md を読んでください
• コメントやフィードバックを扱いたい場合 → references/discussions.md を読んでください
• ファイルやデータをアップロードしたい場合 → references/file_manager.md を読んでください
• 実験やプロフィールを追跡したい場合 → references/additional_features.md を読んでください

ステップ 3: 統合を実装する

関連する参照ファイルの指針に従ってください:

• 各リファレンスには詳細なエンドポイントのドキュメントが含まれています
• API のパラメーターとリクエスト/レスポンスの形式が規定されています
• 一般的なユースケースとワークフローが例とともに示されています
• ベストプラクティスとエラー処理のガイダンスも含まれています

ベース URL とリクエスト形式

すべての API リクエストは次のベース URL を使用します:

https://protocols.io/api/v3

すべてのリクエストには Authorization ヘッダーが必要です:

Authorization: Bearer YOUR_ACCESS_TOKEN

ほとんどのエンドポイントは Content-Type: application/json を指定した JSON のリクエスト/レスポンス形式をサポートしています。

コンテンツ形式のオプション

多くのエンドポイントは、プロトコルのコンテンツをどの形式で返すかを制御する content_format パラメーターをサポートしています:

• json: Draft.js JSON 形式（デフォルト）
• html: HTML 形式
• markdown: Markdown 形式

クエリパラメーターとして指定します: ?content_format=html

レート制限

API のレート制限にご注意ください:

• 標準エンドポイント: ユーザーごとに毎分 100 リクエスト
• PDF エンドポイント: 5 リクエスト/分（サインイン済み）、3 リクエスト/分（未サインイン）

レート制限エラー（HTTP 429）に対しては、指数バックオフを実装してください。

一般的なワークフロー

ワークフロー 1: プロトコルのインポートと分析

protocols.io 上の既存のプロトコルを分析するには:

1. 検索: キーワードを指定して GET /protocols を使用し、関連するプロトコルを探します
2. 取得: GET /protocols/{protocol_id} で詳細をすべて取得します
3. 抽出: 分析のためにステップ、材料、メタデータを解析します
4. ディスカッションの確認: GET /protocols/{id}/comments でユーザーからのフィードバックを確認します
5. エクスポート: オフラインで参照する必要がある場合は PDF を生成します

参照ファイル: protocols_api.md、discussions.md

ワークフロー 2: プロトコルの作成と公開

新しいプロトコルを作成し、DOI 付きで公開するには:

1. 認証: 有効なアクセストークンがあることを確認します（authentication.md を参照）
2. 作成: タイトルと説明を指定して POST /protocols を使用します
3. ステップの追加: 各ステップについて POST /protocols/{id}/steps を使用します
4. 材料の追加: ステップの構成要素として試薬を記載します
5. レビュー: すべてのコンテンツが完全かつ正確であることを確認します
6. 公開: POST /protocols/{id}/publish で DOI を発行します

参照ファイル: protocols_api.md、authentication.md

ワークフロー 3: 共同研究室ワークスペース

チームのプロトコル管理を設定するには、次の手順を実行します。

1. ワークスペースの作成／参加: ワークスペースへのアクセスまたはメンバーシップをリクエストします（workspaces.md を参照）
2. 構造の整理: 研究室のプロトコル用にフォルダー階層を作成します（file_manager.md を参照）
3. プロトコルの作成: チーム用のプロトコルには POST /workspaces/{id}/protocols を使用します
4. ファイルのアップロード: 実験データと画像を追加します
5. ディスカッションの有効化: チームメンバーがコメントやフィードバックを提供できるようにします
6. 実験の追跡: 実験記録でプロトコルの実行を記録します

参照ファイル: workspaces.md、file_manager.md、protocols_api.md、discussions.md、additional_features.md

ワークフロー 4: 実験記録

プロトコルの実行と結果を追跡するには、次の手順を実行します。

1. プロトコルの実行: 研究室でプロトコルを実施します
2. データのアップロード: File Manager API を使用して結果をアップロードします（file_manager.md を参照）
3. 記録の作成: POST /protocols/{id}/runs で実行内容を記録します
4. ファイルのリンク: 実験記録でアップロードしたデータファイルを参照します
5. 変更点の記録: プロトコルからの逸脱や最適化内容を記録します
6. 分析: 複数回の実行結果を確認し、再現性を評価します

参照ファイル: additional_features.md、file_manager.md、protocols_api.md

ワークフロー 5: プロトコルの発見と引用

研究でプロトコルを検索して引用するには、次の手順を実行します。

1. 検索: GET /publications で公開済みプロトコルを検索します
2. 絞り込み: カテゴリーとキーワードのフィルターを使用して関連するプロトコルを絞り込みます
3. 確認: プロトコルの詳細とコミュニティのコメントを確認します
4. ブックマーク: POST /protocols/{id}/bookmarks で有用なプロトコルを保存します
5. 引用: 出版物でプロトコルの DOI を使用します（適切な出典表記のため）
6. PDF のエクスポート: オフライン参照用に整形された PDF を生成します

参照ファイル: protocols_api.md、additional_features.md

Python リクエストの例

基本的なプロトコル検索

import requests

token = "YOUR_ACCESS_TOKEN"
headers = {"Authorization": f"Bearer {token}"}

# Search for CRISPR protocols
response = requests.get(
    "https://protocols.io/api/v3/protocols",
    headers=headers,
    params={
        "filter": "public",
        "key": "CRISPR",
        "page_size": 10,
        "content_format": "html"
    }
)

protocols = response.json()
for protocol in protocols["items"]:
    print(f"{protocol['title']} - {protocol['doi']}")

新規プロトコルの作成

import requests

token = "YOUR_ACCESS_TOKEN"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Create protocol
data = {
    "title": "CRISPR-Cas9 Gene Editing Protocol",
    "description": "Comprehensive protocol for CRISPR gene editing",
    "tags": ["CRISPR", "gene editing", "molecular biology"]
}

response = requests.post(
    "https://protocols.io/api/v3/protocols",
    headers=headers,
    json=data
)

protocol_id = response.json()["item"]["id"]
print(f"Created protocol: {protocol_id}")

ワークスペースへのファイルアップロード

import requests

token = "YOUR_ACCESS_TOKEN"
headers = {"Authorization": f"Bearer {token}"}

# Upload file
with open("data.csv", "rb") as f:
    files = {"file": f}
    data = {
        "folder_id": "root",
        "description": "Experimental results",
        "tags": "experiment,data,2025"
    }

    response = requests.post(
        "https://protocols.io/api/v3/workspaces/12345/files/upload",
        headers=headers,
        files=files,
        data=data
    )

file_id = response.json()["item"]["id"]
print(f"Uploaded file: {file_id}")

エラー処理

API リクエストには堅牢なエラー処理を実装してください。

import requests
import time

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers)

            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:  # Rate limit
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
                continue
            elif response.status_code >= 500:  # Server error
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            else:
                response.raise_for_status()

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

    raise Exception("Max retries exceeded")

参照ファイル

タスクに応じて適切な参照ファイルを読み込んでください。

• authentication.md: OAuth フロー、トークン管理、レート制限
• protocols_api.md: プロトコルの CRUD、ステップ、材料、公開、PDF
• discussions.md: コメント、返信、コラボレーション
• workspaces.md: チームワークスペース、権限、組織管理
• file_manager.md: ファイルのアップロード、フォルダー、ストレージ管理
• additional_features.md: プロフィール、出版物、実験、通知

参照ファイルを読み込むには、特定の機能が必要になった時点で references/ ディレクトリからファイルを読み込んでください。

ベストプラクティス

1. 認証: トークンは安全に保管し、コードやバージョン管理には決して含めないでください
2. レート制限: 指数バックオフを実装し、レート制限を遵守してください
3. エラー処理: すべての HTTP エラーコードに適切に対処してください
4. データ検証: API 呼び出しの前に入力を検証してください
5. ドキュメント化: プロトコルの手順を丁寧に記述してください
6. コラボレーション: チームのコミュニケーションにはコメントとディスカッションを活用してください
7. 整理: 一貫した命名規則とタグ付けのルールを維持してください
8. バージョン管理: プロトコルを更新する際はバージョンを追跡してください
9. 出典表記: DOI を使用して、プロトコルを適切に引用してください
10. バックアップ: 重要なプロトコルとワークスペースのデータを定期的にエクスポートしてください

追加リソース

• 公式 API ドキュメント: https://apidoc.protocols.io/
• Protocols.io プラットフォーム: https://www.protocols.io/
• サポート: API アクセスや技術的な問題については protocols.io のサポートに問い合わせてください
• コミュニティ: ベストプラクティスについては protocols.io のコミュニティに参加してください

トラブルシューティング

認証の問題:

• トークンが有効であり、期限切れでないことを確認する
• Authorization ヘッダーの形式（Bearer YOUR_TOKEN）を確認する
• 適切なトークンの種類（CLIENT または OAUTH）を使用していることを確認する

レート制限:

• 429 エラーに対して指数バックオフを実装する
• リクエストの頻度を監視する
• 頻繁に行うリクエストのキャッシュを検討する

権限エラー:

• ワークスペースやプロトコルへのアクセス権限を確認する
• ワークスペース内でのユーザーのロールを確認する
• 権限なしでアクセスする場合、プロトコルが非公開でないことを確認する

ファイルアップロードの失敗:

• ファイルサイズがワークスペースの上限内であることを確認する
• ファイルの種類がサポートされていることを確認する
• multipart/form-data エンコーディングが正しいことを確認する

より詳細なトラブルシューティングについては、各機能領域を扱う個別のリファレンスファイルを参照してください。