figshare-skill

Figshare スキル

Figshare v2 REST API を利用して、研究成果を検索、ダウンロード、作成、アップロードします。

前提条件

• curl と jq が PATH 上で利用できること。

• 認証が必要なエンドポイント（/account/... 以下のすべてのエンドポイント、またはアップロード）では、https://figshare.com/account/applications から取得した個人用トークンを次の環境変数としてエクスポートします。

  export FIGSHARE_TOKEN=xxxxxxxxxxxxxxxx
  

• 公開エンドポイント（検索、公開記事、ダウンロード）にはトークンは必要ありません。

アカウント上で何かを作成、変更、公開、削除する前に、必ずユーザーに確認してください。これらの操作は元に戻すのが困難です。

更新チェック

インストールごとに24時間あたり1回までに制限し、ユーザーの明示的な同意なしにスキルディレクトリを変更しないでください。

1. <this-skill-dir>/.last_update が存在し、作成から24時間未満の場合は、この手順全体をスキップします。

2. それ以外の場合は、上流の最新タグを取得します。

   git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
     | awk '{print $2}' | sed 's|refs/tags/||' \
     | sort -V | tail -1
   

3. このスキルのフロントマターにある metadata.version と比較します。上流タグが（semver に従って）新しい場合は、ユーザーに一行で伝えて、次のように尋ねます。

   "このスキルの新しいバージョンが利用可能です：vX.Y.Z → vA.B.C。git pull しますか？"

   ユーザーが同意した場合は、git -C <this-skill-dir> pull --ff-only を実行します。どちらの場合も .last_update を更新し、24時間は確認が繰り返されないようにします。

4. 上流タグが同じか古い場合は、.last_update を通知せずに更新し、ユーザーのタスクを続けます。

5. 何らかのエラーが発生した場合（オフライン、Git チェックアウトではない場合（ClawHub からインストールされたコピーなど）、読み取り専用パス、権限がない場合）は、エラーを黙って無視し、ユーザーのタスクを続けます。エラーについて言及しないでください。

API の基本

• ベース URL： https://api.figshare.com/v2
• 認証ヘッダー： Authorization: token $FIGSHARE_TOKEN
• Content-Type： POST/PUT の本文には application/json
• レート制限： 不正利用によるスロットリングを避けるため、リクエストは約1秒に1回未満に抑えます
• エラー： message と code を含む JSON 本文。一般的なコードは 400/401/403/404/422 です

よく使うレシピ

公開記事を検索する

curl -s -X POST https://api.figshare.com/v2/articles/search \
  -H "Content-Type: application/json" \
  -d '{"search_for": ":title: single cell", "page_size": 20}' | jq

フィールド演算子：:title:、:author:、:tag:、:category:、:doi:、:resource_doi:。

公開記事を取得する（ID または DOI を指定）

curl -s https://api.figshare.com/v2/articles/{article_id} | jq
# or resolve from a figshare.com URL: the numeric tail is the article_id

公開記事のすべてのファイルをダウンロードする

ART=12345678
curl -s https://api.figshare.com/v2/articles/$ART/files \
  | jq -r '.[] | "\(.download_url)\t\(.name)"' \
  | while IFS=$'\t' read -r url name; do curl -L -o "$name" "$url"; done

自分の記事を一覧表示する

curl -s -H "Authorization: token $FIGSHARE_TOKEN" \
  "https://api.figshare.com/v2/account/articles?page=1&page_size=50" | jq

記事を作成する（下書き）

curl -s -X POST https://api.figshare.com/v2/account/articles \
  -H "Authorization: token $FIGSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My dataset",
    "description": "Full description here.",
    "defined_type": "dataset",
    "tags": ["demo"],
    "categories": [2]
  }' | jq

レスポンスは { "location": ".../account/articles/{id}", "entity_id": 123 } です。

記事を更新／公開する

# update metadata
curl -s -X PUT https://api.figshare.com/v2/account/articles/$ART \
  -H "Authorization: token $FIGSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New title"}'

# publish (becomes public, assigns DOI, version is frozen)
curl -s -X POST https://api.figshare.com/v2/account/articles/$ART/publish \
  -H "Authorization: token $FIGSHARE_TOKEN"

公開する前に必ず確認してください。そのバージョンについては公開を取り消せません。

コレクションとプロジェクト

# create collection that groups existing articles
curl -s -X POST https://api.figshare.com/v2/account/collections \
  -H "Authorization: token $FIGSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Collection", "articles": [123, 456]}'

# create project
curl -s -X POST https://api.figshare.com/v2/account/projects \
  -H "Authorization: token $FIGSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Research Project"}'

ファイルのアップロード（マルチパートの手順）

Figshare のアップロードは3段階です：開始 → 各パートを PUT → 完了。複雑な処理には、同梱のヘルパーを使用してください。

# upload a file to an existing draft article
./scripts/upload.sh <article_id> <path/to/file>

# batch-download every file from a public article (accepts id or figshare.com URL)
./scripts/download.sh <article_id_or_url> [output_dir]

# reserve + upload + publish a new version of an already-published article
./scripts/new-version.sh <article_id> <path/to/file>

必要に応じて応用できるよう、基本の手順も以下に示します。

1. 開始 — md5 とサイズを計算し、記事に POST します。

   SIZE=$(stat -f%z "$FILE" 2>/dev/null || stat -c%s "$FILE")
   MD5=$(md5sum "$FILE" | awk '{print $1}')   # or: md5 -q on macOS
   curl -s -X POST https://api.figshare.com/v2/account/articles/$ART/files \
     -H "Authorization: token $FIGSHARE_TOKEN" \
     -H "Content-Type: application/json" \
     -d "{\"md5\":\"$MD5\",\"name\":\"$(basename $FILE)\",\"size\":$SIZE}"
   

レスポンスには、/account/articles/$ART/files/$FILE_ID を指す location が含まれます。

2. アップロード情報を取得 — そのファイルレコードからアップロード情報を取得します。upload_url が含まれています。upload_url に GET を送信し、パートの構成（parts: [{partNo, startOffset, endOffset}]）を確認します。

3. パートをアップロード — 各パートについて、${upload_url}/${partNo} にバイト範囲を PUT します。

   dd if="$FILE" bs=1 skip=$START count=$((END-START+1)) 2>/dev/null \
     | curl -s -X PUT --data-binary @- "${upload_url}/${partNo}" \
       -H "Authorization: token $FIGSHARE_TOKEN"
   

4. 完了 — ファイルレコードに POST して確定します。

   curl -s -X POST https://api.figshare.com/v2/account/articles/$ART/files/$FILE_ID \
     -H "Authorization: token $FIGSHARE_TOKEN"
   

3段階に分かれている理由：Figshare は大きなファイルを別のアップロードサービス経由でストリーミングします。完了の呼び出しを省略すると、ファイルは保留状態のままとなり、記事に表示されません。

ページネーション

ほとんどの一覧エンドポイントでは、page+page_size または limit+offset を指定できます。page_size の最大値は通常1000です。大量のデータを取得する場合は、空のページが返されるまでループします。

page=1
while :; do
  out=$(curl -s "https://api.figshare.com/v2/articles?page=$page&page_size=100")
  [ "$(echo "$out" | jq 'length')" = "0" ] && break
  echo "$out" | jq -c '.[]'
  page=$((page+1))
  sleep 1
done

トラブルシューティング

• 401 — トークンがないか、有効期限が切れています。$FIGSHARE_TOKEN を再確認してください。
• /account/... での 403 — トークンに必要なスコープがありません。すべての権限を付与して再生成してください。
• 記事作成時の 422 — 必須フィールド（通常は title）がないか、categories／defined_type が不正です。
• アップロードパーツの不一致 — ステップ 1 の md5 またはサイズが、実際にアップロードしたバイト数と一致していません。再計算して最初からやり直してください。
• 公開済みの記事を更新できない — 公開するとバージョンが固定されます。代わりに新しいバージョンを作成してください。

参考資料

• API リファレンス：https://docs.figshare.com/
• トークン管理：https://figshare.com/account/applications
• カテゴリー ID：GET https://api.figshare.com/v2/categories
• ライセンス ID：GET https://api.figshare.com/v2/licenses