zenodo-skill

Zenodo スキル

Zenodo REST API を利用して、研究成果物の登録、公開、バージョン管理、検索を行います。Zenodo では、公開されたすべてのレコードに引用可能な DOI が付与されます。

使用する場面

• ユーザーがデータセット、コードリリース、論文、ポスター、その他の成果物を Zenodo にアップロードしたい場合
• ユーザーが研究成果の DOI を取得したい場合
• ユーザーが既存の登録内容を更新したり、新しいバージョンを公開したりしたい場合
• ユーザーが Zenodo のレコードを検索したい場合

更新の確認

インストールごとに 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 と比較します。上流のタグがセマンティックバージョニング上で新しい場合は、ユーザーに 1 行で伝えて、次のように尋ねます。

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

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

4. 上流のバージョンが同じか古い場合は、.last_update を通知なしで更新し、続行します。

5. 失敗した場合（オフライン、Git チェックアウトではない場合（例：ClawHub からインストールされたコピー）、読み取り専用パス、権限なしなど）は、エラーを通知せずに処理を続行し、ユーザーのタスクに進みます。失敗については触れないでください。

セットアップ

環境は 2 つあります。セッション中はどちらか 1 つを選び、使い続けてください。

環境	ベース URL	トークンページ
本番環境	https://zenodo.org/api	https://zenodo.org/account/settings/applications/tokens/new/
サンドボックス（テスト用）	https://sandbox.zenodo.org/api	https://sandbox.zenodo.org/account/settings/applications/tokens/new/

サンドボックスのアカウントとトークンは、本番環境とは別です。新しいワークフローは必ず最初にサンドボックスでテストしてください。本番環境で公開したレコードは削除できません。

必要なトークンスコープ：deposit:write と deposit:actions。

コマンドを実行する前にトークンをエクスポートします。

export ZENODO_TOKEN=...        # never inline the token in commands you show the user
export ZENODO_BASE=https://sandbox.zenodo.org/api   # or https://zenodo.org/api

ZENODO_TOKEN が設定されていない場合は、続行する前にユーザーにトークンと使用する環境を尋ねてください。

基本的なワークフロー：新しい成果物を登録する

登録のライフサイクルは、作成 → ファイルをアップロード → メタデータを設定 → 公開です。各手順は個別の API 呼び出しなので、順番に実行してください。

1. 空の登録を作成する

curl -sS -X POST "$ZENODO_BASE/deposit/depositions" \
  -H "Authorization: Bearer $ZENODO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

レスポンス JSON には、覚えておく必要がある情報が 2 つ含まれています。

• id — 登録 ID。メタデータ、公開、バージョン管理の操作に使用します
• links.bucket — ファイルのアップロード先となるバケット URL（新しいファイル API）

たとえば、jq を使って取得します。

RESP=$(curl -sS -X POST "$ZENODO_BASE/deposit/depositions" \
  -H "Authorization: Bearer $ZENODO_TOKEN" -H "Content-Type: application/json" -d '{}')
DEPOSIT_ID=$(echo "$RESP" | jq -r .id)
BUCKET=$(echo "$RESP" | jq -r .links.bucket)

2. ファイルをアップロードする（バケット API — 推奨）

バケット API は、レコードあたり合計最大 50 GB、最大 100 ファイルに対応しています。--upload-file（HTTP PUT）を使用してください。マルチパート形式のフォームアップロードは使用しないでください。URL 内のファイル名が、レコード上に表示される名前になります。

curl -sS --upload-file ./data.csv \
  -H "Authorization: Bearer $ZENODO_TOKEN" \
  "$BUCKET/data.csv"

ファイルごとに繰り返します。ファイル数が多い場合は、シェルでループしてください。従来の /files マルチパートエンドポイントは 1 ファイルあたり 100 MB に制限されているため、使用を避けてください。

3. メタデータを設定する

メタデータは、登録に対する PUT で設定します。必須フィールドは upload_type、title、creators、description です。スキーマ、使用可能な upload_type の値、ライセンスコード、条件付きフィールド（例：publication_type、embargo_date）の全一覧は references/metadata.md を参照してください。

最小限の例：

curl -sS -X PUT "$ZENODO_BASE/deposit/depositions/$DEPOSIT_ID" \
  -H "Authorization: Bearer $ZENODO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "title": "My dataset",
      "upload_type": "dataset",
      "description": "<p>A short description (HTML allowed).</p>",
      "creators": [{"name": "Doe, Jane", "affiliation": "Example Univ.", "orcid": "0000-0002-1825-0097"}]
    }
  }'

レスポンスを確認してください。この段階で Zenodo による検証が行われ、不足または不正な形式のフィールドがある場合は、フィールド単位のエラーを含む 400 が返されます。公開する前に修正して再試行してください。

4. 公開する

本番環境での公開は取り消せません（後からメタデータを編集することはできますが、ファイルの削除やレコードの削除はできません）。サンドボックスを使用している場合を除き、この手順の前にユーザーの確認を得てください。

curl -sS -X POST "$ZENODO_BASE/deposit/depositions/$DEPOSIT_ID/actions/publish" \
  -H "Authorization: Bearer $ZENODO_TOKEN"

レスポンスには doi と links.record_html が含まれています。両方をユーザーに提示してください。

既存レコードの新しいバージョン

ユーザーが以前に公開したレコードの更新データやコードを、同じ concept-DOI でリリースする場合に使用します。

# 1. Create new version draft (returns links.latest_draft)
curl -sS -X POST "$ZENODO_BASE/deposit/depositions/$DEPOSIT_ID/actions/newversion" \
  -H "Authorization: Bearer $ZENODO_TOKEN"

次に、新しい下書きのバケット（links.latest_draft → GET で取得 → links.bucket を使用）に従って、変更したファイルをアップロードし、メタデータを更新して、上記の手順 2～4 と同様に公開します。新しいバージョンはデフォルトで前のバージョンのファイルを引き継ぎます。置き換えるファイルは DELETE $BUCKET/<filename> で削除してください。

下書きを破棄する

curl -sS -X POST "$ZENODO_BASE/deposit/depositions/$DEPOSIT_ID/actions/discard" \
  -H "Authorization: Bearer $ZENODO_TOKEN"

公開済みレコードを検索する

公開検索にはトークンは必要ありません。

curl -sS "$ZENODO_BASE/records?q=climate+model&size=10&sort=mostrecent"

クエリ構文は Elasticsearch です。creators.name:"Doe, Jane"、communities:zenodo、resource_type.type:dataset のようなフィールド指定クエリがすべて使用できます。クエリのパターンについては references/search.md を参照してください。

規約と注意事項

• HTTP ステータスを必ず確認してください。 201 = 作成済み、202 = 公開を受け付けました、400 = メタデータエラー（レスポンス本文を確認してください）、401 = トークンが無効、403 = スコープが不適切、429 = レート制限中です。
• レート制限： 認証済みユーザーは 100 req/min、5000 req/hour です。X-RateLimit-Remaining を確認してください。
• 表示するコマンドにトークンを直接記述しないでください。$ZENODO_TOKEN を使用してください。トークンをファイルに書き込まないでください。
• まずサンドボックスを使用してください。 初めてのワークフローではサンドボックスを提案し、ユーザーが明示的に確認した場合にのみ本番環境に切り替えてください。
• 公開前に確認してください。 本番環境で actions/publish を呼び出す前に、GET で入手したデポジションのファイルとメタデータをユーザーと一緒に確認してください。
• 大容量のアップロード： ファイルサイズが数百 MB を超える場合は、--progress-bar を指定して curl でアップロードすることを検討し、時間や帯域幅に関する注意をユーザーに伝えてください。

参考資料

• references/metadata.md — メタデータの完全なスキーマ、upload_type の値、ライセンスコード、条件付きフィールド
• references/search.md — 検索クエリの構文と便利なフィルター
• references/examples.md — よくあるシナリオの、最初から最後まで実行できるシェルスクリプト（データセットのアップロード、ソフトウェアのリリース、新しいバージョン）