Qiitaの画面操作だけでは過去の全記事(Markdown本文・限定共有記事含む)を一括エクスポートする機能が存在しません。大切な知識資産を守るためには、Qiita API v2を活用して自分自身の投稿データを自動取得・保存する仕組みを構築する必要があります。
- Qiita標準のWeb UIには記事データの一括ダウンロード機能がないため、ローカルへのデータバックアップにはQiita API v2の活用が必須となる。
- 自分の投稿記事(限定共有記事を含む)を漏れなく取得するには、アクセストークンを発行し
GET /api/v2/authenticated_user/itemsを利用する。 - 取得時にはページネーションの制御(
page/per_page)や、1時間あたり1,000回(認証時)のレート制限および各種エラー(401, 403, 429)に対応するプログラム設計が重要となる。
Qiitaにおける記事バックアップの現状とAPI利用の必然性
Qiita上で執筆・公開した記事は、開発ノウハウやトラブルシューティングの記録として非常に貴重な資産です。しかし、Qiitaの標準Web UI画面では、記事を1件ずつ編集画面からコピーするか、ブラウザの印刷機能等を使って個別に保存するしか方法がありません。
仮に数十件~数百件の記事を投稿している場合、UI操作だけで手動バックアップを行うのは非現実的です。また、編集画面からコピペする手法では、記事の投稿日時、タグ情報、ストック数、いいね数、限定共有の設定状態などのメタデータを正確に保持して保存することが困難です。
そこで必要となるのが、Qiitaが公式に提供している REST API(Qiita API v2)の活用です。API経由であれば、Markdown形式の本文(body)だけでなく、レンダリング済みのHTML(rendered_body)や付随する詳細なメタデータをJSON形式で一括取得できます。
| 項目 | Web UIでの操作 | Qiita API v2での取得 |
|---|---|---|
| 一括ダウンロード | 不可能(1記事ずつ手動コピーが必要) | 可能(スクリプトで全自動取得) |
| 取得できる本文形式 | 画面上のテキスト(コピー&ペースト) | Raw Markdown(body) / HTML(rendered_body) |
| 限定共有・下書きの取得 | 画面上で個別に開く必要あり | 認証用トークンで一括取得可能 |
| メタデータの保存 | 不可(記事IDや投稿日時を手動記録) | 完璧(作成日時、更新日時、タグ、LGTM数等を取得) |
| 自動化・定期実行 | 不可能 | 可能(GitHub ActionsやCron等で自動バックアップ) |
このように、技術記事の完全なバックアップ環境を構築するにはAPIの利用が避けられません。次に、APIを利用するための事前準備について解説します。
事前準備:個人アクセストークンの発行とスコープ設定
Qiita API v2を利用して「自分自身の全記事データ」を取得するには、個人アクセストークン(Personal Access Token)の発行が必要です。未認証のAPIリクエストでは、他人の公開記事しか取得できず、自分自身の限定共有記事や下書き状態の記事にアクセスできません。
1. 個人アクセストークンの発行手順
- Qiitaにログインし、右上のユーザーアイコンから「設定」を開く。
- 左側メニューの「アプリケーション」を選択する。
- 「個人用アクセストークン」のセクションにある「新しく指示を発行する」ボタンをクリックする。
- アクセストークンの「説明(例:
backup-script)」を入力する。 - 必要なスコープ(スコープの詳細は後述)にチェックを入れ、「発行する」をクリックする。
- 生成された文字列(アクセストークン)をコピーする。※このトークンは再表示されないため、安全な場所に保管してください。
2. アクセストークンの4つのスコープ仕様
Qiita API v2で提供されているアクセストークンのスコープは、以下の4種類に限定されています。権限は最小限にする原則(最小権限の原則)に基づき、バックアップ目的であれば read_qiita のみを選択するのが安全です。
| スコープ名 | 対象サービス | 概要・許可される操作 |
|---|---|---|
read_qiita |
Qiita | 認証ユーザーに紐づくデータ(記事、ストック、ユーザー情報等)の読み取り |
write_qiita |
Qiita | 記事の投稿・編集・削除、いいね・ストック操作などの書き込み権限 |
read_qiita_team |
Qiita Team | Qiita Team上のデータ(グループ、記事、コメント等)の読み取り |
write_qiita_team |
Qiita Team | Qiita Team上での記事投稿・編集・グループ操作等の書き込み権限 |
3. 環境変数 QIITA_TOKEN の設定
ソースコード内にアクセストークンを直接ハードコードすることは、セキュリティ上の重大なリスク(誤ってGitリポジトリへコミットして漏洩するなど)に繋がります。トークンは必ず環境変数経由でプログラムに渡す設計にします。
Linux / macOS の場合:
export QIITA_TOKEN="your_access_token_here"
Windows(PowerShell)の場合:
$env:QIITA_TOKEN="your_access_token_here"
Qiita API v2の基本仕様(エンドポイント・ページネーション・レート制限)
バックアップスクリプトを実装する前に、公式ドキュメントに基づくAPIの基本仕様を正しく理解しておく必要があります。
自分の記事を取得するエンドポイント
Qiita APIには記事一覧を取得するエンドポイントが複数存在します。バックアップの目的によって使い分ける必要があります。
-
GET /api/v2/authenticated_user/items- 認証中のユーザー(アクセストークンの所有者)が投稿した記事一覧を取得する。
- 限定共有記事も含めて取得できるため、自分のバックアップ用途には本エンドポイントを使用する。
-
GET /api/v2/items- Qiita上の全体公開記事を投稿日時の新しい順に取得する。
-
GET /api/v2/users/:user_id/items- 指定した特定のユーザーが投稿した公開記事一覧を取得する。※自分以外のユーザーの公開記事バックアップなどに利用可能。
ページネーション(Pagination)の仕様
1回のリクエストで全記事を取得できるわけではありません。Qiita API v2のページネーション仕様に従い、繰り返しリクエストを送る必要があります。
-
page: 取得するページ番号。1から100まで指定可能(デフォルト: 1)。 -
per_page: 1ページあたりの取得件数。1から100まで指定可能(デフォルト: 20)。
最大件数を効率よく取得するには、per_page=100 を指定します。また、APIレスポンスのHTTPヘッダーには以下の情報が含まれます。
-
Total-Count: 該当条件にマッチする総レコード数(記事の総数)。 -
Link: ページ移動用のURLヘッダー(rel="first",rel="next",rel="prev",rel="last")。
レート制限(Rate Limit)の仕様
Qiita APIではサービスの安定運用のため、クライアントからのリクエスト回数に上限を設定しています。
-
認証済みリクエスト(
Authorization: Bearer <TOKEN>ヘッダーあり): 1時間あたり 1,000回 - 未認証リクエスト(トークンなし): 1時間あたり 60回(接続元IPアドレス単位)
バックアップスクリプトを動かす際は、必ず認証済みリクエストを用います。未認証の60回制限では、記事数が多い場合にすぐに制限を超過してしまいます。
Pythonで自分の全記事を一括取得・保存する実装コード
それでは、Pythonの requests ライブラリを使用して、自分の全記事を取得しローカルにJSONファイルおよびMarkdownファイルとして保存する実装例を紹介します。
以下のコードはコピーしてそのまま実行できる最小構成になっています。環境変数 QIITA_TOKEN が正しく設定されていることを確認して実行してください。
import json
import os
import sys
import requests
def backup_qiita_items():
# 1. 環境変数からトークンを取得
token = os.environ.get("QIITA_TOKEN")
if not token:
print("エラー: 環境変数 QIITA_TOKEN が設定されていません。", file=sys.stderr)
sys.exit(1)
# 2. リクエストヘッダーの設定(Authorization: Bearer)
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
base_url = "https://qiita.com/api/v2/authenticated_user/items"
page = 1
per_page = 100
all_items = []
# 記事出力用フォルダの作成
os.makedirs("qiita_backup/markdown", exist_ok=True)
print("Qiita APIから記事データの取得を開始します...")
while True:
params = {
"page": page,
"per_page": per_page
}
# 3. 公式エンドポイントへのGETリクエスト送信
try:
response = requests.get(base_url, headers=headers, params=params, timeout=10)
except requests.RequestException as e:
print(f"通信エラーが発生しました: {e}", file=sys.stderr)
break
# 4. ステータスコードの判定
status_code = response.status_code
print(f"Page {page} 取得中... (Status Code: {status_code})")
if status_code == 200:
items = response.json()
if not items:
# 取得データが空になれば終了
break
all_items.extend(items)
# Markdownファイルとして個別保存する処理
for item in items:
item_id = item.get("id")
title = item.get("title", "no_title").replace("/", "_") # ファイル名として安全な文字列に置換
body = item.get("body", "")
# ファイル名に記事IDを含めて保存
filename = f"qiita_backup/markdown/{item_id}_{title}.md"
with open(filename, "w", encoding="utf-8") as f:
f.write(f"# {item.get('title')}\n\n")
f.write(f"- 記事ID: {item_id}\n")
f.write(f"- 作成日: {item.get('created_at')}\n")
f.write(f"- 更新日: {item.get('updated_at')}\n")
f.write(f"- URL: {item.get('url')}\n")
f.write(f"- 限定共有: {item.get('private')}\n\n")
f.write("---\n\n")
f.write(body)
# 全件取得完了チェック(Total-Countヘッダーまたは取得件数による判定)
total_count = int(response.headers.get("Total-Count", 0))
if len(all_items) >= total_count:
break
page += 1
if page > 100:
# APIのページ上限(100ページ)に達した場合は終了
print("ページ上限(100ページ)に到達しました。")
break
elif status_code == 401:
print("エラー 401: 認証に失敗しました。アクセストークンが無効または期限切れです。", file=sys.stderr)
sys.exit(1)
elif status_code == 403:
print("エラー 403: アクセスが拒否されました。スコープ(read_qiita)が不十分な可能性があります。", file=sys.stderr)
sys.exit(1)
elif status_code == 429:
print("エラー 429: レート制限(1時間あたり1000回)を超過しました。時間をおいて再実行してください。", file=sys.stderr)
sys.exit(1)
else:
print(f"予期しないエラーが発生しました (Status Code: {status_code})", file=sys.stderr)
print(f"レスポンス: {response.text}", file=sys.stderr)
sys.exit(1)
# 5. 全メタデータを1つのJSONファイルとして保存
with open("qiita_backup/all_items.json", "w", encoding="utf-8") as f:
json.dump(all_items, f, ensure_ascii=False, indent=2)
print(f"\nバックアップ完了! 合計 {len(all_items)} 件の記事を保存しました。")
print("保存先: qiita_backup/ フォルダ")
if __name__ == "__main__":
backup_qiita_items()
スクリプトの解説
-
環境変数の利用:
os.environ.get("QIITA_TOKEN")を使い、認証情報をセキュアに取得します。 -
Authorization: Bearerヘッダー: Qiita API v2の標準仕様に従い、トークンをセットします。 -
ページネーションループ:
per_page=100でリクエストし、レスポンスヘッダーTotal-Countと比較しながら全ページを巡回します。 -
データの分割保存: JSON全件保存(
all_items.json)に加え、記事本文(body)を個別ファイル(.md)として保存するため、エディタやローカルのMarkdown検索ツールで閲覧可能になります。
レート制限監視とエラーハンドリング(401/403/429)の堅牢な実装
定期実行スクリプトや大規模なバックアップ処理を行う場合、HTTPステータスコードに応じたエラーハンドリングと、レスポンスヘッダーに含まれるレート制限(Rate Limit)情報の監視が不可欠です。
発生する主なHTTPステータスコードと原因
Qiita API v2で返却されるステータスコードの概要と原因は以下の通りです。
| ステータスコード | 意味 | 主な発生原因と対処法 |
|---|---|---|
| 200 OK | 成功 | GETリクエストが正常に処理された。 |
| 400 Bad Request | リクエスト不正 | パラメータの値が正しくない(例: page に0や文字列を指定した)。 |
| 401 Unauthorized | 認証エラー | トークンが設定されていない、または無効・失効している。 |
| 403 Forbidden | 権限不足 | アクセストークンのスコープが不足している、または制限対象リソースへのアクセス。 |
| 404 Not Found | 存在しないパス | 指定したURLエンドポイントやリソースが存在しない。 |
| 429 Too Many Requests | レート制限超過 | 1時間あたりのAPI呼び出し上限(認証時1,000回)を超えた。 |
| 500 Internal Server Error | サーバー内部エラー | Qiita側の障害。時間を置いて再試行する必要がある。 |
レート制限情報の取得とヘッダー監視
Qiita APIのレスポンスヘッダーには、現在の利用状況を示すヘッダーが含まれる場合があります。これらを出力・監視することで、プログラム側で一時待機(time.sleep)を入れるなどの制御が可能になります。
以下は、レスポンスヘッダーを読み取り、429エラー発生時に自動リトライを行う高度なバックアップ実装例です。
import os
import sys
import time
import requests
def fetch_with_rate_limit_handling(url, headers, params):
"""
レート制限(429)や一時的なエラーをハンドリングして安全にAPIを呼び出す関数
"""
max_retries = 3
for attempt in range(max_retries):
try:
response = requests.get(url, headers=headers, params=params, timeout=15)
except requests.RequestException as e:
print(f"ネットワークエラー (試行 {attempt + 1}/{max_retries}): {e}")
time.sleep(5)
continue
status_code = response.status_code
# レート制限ヘッダーの確認(存在する場合)
rate_limit = response.headers.get("Rate-Limit")
rate_remaining = response.headers.get("Rate-Remaining")
rate_reset = response.headers.get("Rate-Reset")
if rate_remaining is not None:
print(f"[API残回数: {rate_remaining}/{rate_limit}]")
if status_code == 200:
return response
elif status_code == 429:
# 429 Too Many Requests の場合は待機して再試行
wait_time = 60 # デフォルトで60秒待機
print(f"警告: 429 Too Many Requests が発生しました。{wait_time}秒間待機します...")
time.sleep(wait_time)
elif status_code in (401, 403):
# 認証・権限エラーは再試行しても解決しないため即時エラーレスポンスを返す
return response
elif status_code >= 500:
# 5xx サーバーエラーはバックオフを入れて再試行
wait_time = (attempt + 1) * 10
print(f"サーバーエラー ({status_code})。{wait_time}秒後にリトライします...")
time.sleep(wait_time)
else:
return response
return None
def robust_backup():
token = os.environ.get("QIITA_TOKEN")
if not token:
print("エラー: QIITA_TOKEN が設定されていません。", file=sys.stderr)
sys.exit(1)
headers = {"Authorization": f"Bearer {token}"}
endpoint = "https://qiita.com/api/v2/authenticated_user/items"
params = {"page": 1, "per_page": 20}
response = fetch_with_rate_limit_handling(endpoint, headers, params)
if response and response.status_code == 200:
print("記事の正常取得に成功しました。")
data = response.json()
print(f"取得件数: {len(data)} 件")
elif response:
print(f"取得失敗: Status Code {response.status_code}")
print(f"エラー詳細: {response.text}")
else:
print("リトライ上限を超過したため処理を中断しました。")
if __name__ == "__main__":
robust_backup()
この実装をベースにすることで、APIの制限に達した場合でも即座に落とさず、安全かつ確実にデータをバックアップすることができます。
注意点:Qiita Team専用エンドポイントと廃止済みAPIの取り扱い
Qiita API v2のドキュメントには、通常の個人向け「Qiita」と、組織向けサービス「Qiita Team」の仕様が混在しています。バックアップスクリプトを実装・運用する際には、機能の対象範囲と過去に廃止されたAPIエンドポイントについて正しく把握しておく必要があります。
1. Qiita Team専用機能とアクセストークンの区別
以下の機能やエンドポイントは Qiita Team 専用機能であり、通常の個人アカウント(qiita.com)に対して使用することはできません。
-
グループ機能(Group):
/api/v2/groupsなどのグループ管理エンドポイント -
拡張テンプレート(Expanded template):
/api/v2/expanded_templates -
絵文字リアクション(Emoji reaction):
/api/v2/items/:item_id/reactionsなどの絵文字追加・削除 -
記事リアクション一覧:
GET /api/v2/items/reactions(Qiita Team上の閲覧数やリアクション数を取得するエンドポイント) -
Team用アクセストークン:
/api/v2/team_access_tokens(Qiita Team専用のトークン生成) - SSO(シングルサインオン)認証: SSOのみが許可されたチーム環境でのアクセストークン利用制限
※個人向けQiitaで記事に対する反応を取得したい場合は、Item オブジェクトに含まれる likes_count(LGTM数)や stocks_count(ストック数)を参照してください。
2. 廃止・非推奨となっている旧機能
APIドキュメントおよび過去の改定により、すでに廃止されているエンドポイントが存在します。古い記事や過去のコード例を参照する際は注意が必要です。
-
プロジェクト機能(Project API)の廃止
- エンドポイント:
/api/v2/projects関連(GET,POST,PATCH,DELETE) - 2022年10月1日をもって完全に廃止されました。現行のAPIではプロジェクト機能に関するデータを呼び出すことはできません。
- エンドポイント:
-
Thank機能 / Team Like機能の廃止
- エンドポイント:
/api/v2/comments/:comment_id/thank(PUT,DELETE) - 2020年11月4日をもって廃止されています。
- エンドポイント:
-
旧認可ページ(
/oauth/authorize)の改定-
read_qiita_teamやwrite_qiita_teamを使用する場合のOAuth認可ページは、2020年6月5日以降/oauth/team_authorizeを利用する仕様に変更されています。
-
自身のバックアップ用コードを構築する際は、現役のエンドポイント(GET /api/v2/authenticated_user/items など)のみを使用し、廃止済みの機能を呼び出さないように注意してください。
まとめ
Qiitaに蓄積した技術記事は、開発者にとって重要なキャリア・知識のデータです。しかし、Qiitaの標準UIには記事データを一括エクスポートする機能が提供されていないため、万が一の事態に備えたバックアップにはQiita API v2の利用が不可欠となります。
バックアップ環境を構築する際の要点は以下の通りです。
-
適切なアクセス権限の設定: 設定画面からアクセストークンを発行し、環境変数
QIITA_TOKENに保存した上で、スコープはread_qiitaを指定する。 -
正しいエンドポイントの選定: 自身の全記事(限定共有含む)を取得するため、
GET /api/v2/authenticated_user/itemsを使用する。 -
ページネーション処理の実装:
per_page=100を設定し、Total-Countヘッダーやレスポンス配列の件数を確認しながら全ページを巡回取得する。 - 堅牢なエラーハンドリング: 1時間あたり1,000回(認証時)のレート制限を意識し、401(認証エラー)、403(権限エラー)、429(レート制限超過)に対応できるプログラムを組む。
-
仕様の確認: Qiita Team専用機能や過去に廃止されたエンドポイント(Project API等)を誤って使用しないよう、公式ドキュメント(
https://qiita.com/api/v2/docs)を優先して参照する。
本記事で紹介したPythonスクリプトを活用し、自身の大切な記事データを安全かつ定期的にローカルへバックアップする仕組みを整えておきましょう。