Contents
スポンサードリンク
1. Meta Developers Portal への登録とアプリ作成
Meta Developers Portal に未登録の場合は、まずアカウントを作成し、Threads API 用のアプリケーションを作ります。このセクションでは「なぜアプリが必要か」「どこで設定項目を確認できるか」を解説した上で、実際に画面操作する手順を示します。
1‑1. アカウント登録とサインイン
Meta Developers Portal（https://developers.facebook.com/）へアクセスし、Meta アカウントでログインします。初回利用時は「開発者プログラムに参加」ボタンをクリックして利用規約に同意してください。
1‑2. 新規アプリの作成手順
- 左側メニュー > 「マイアプリ」 を選択し、画面右上の 「＋ アプリを作成」 をクリックします。
- テンプレートは 「ビジネス」または「消費者向け」 のいずれかを選び、アプリ名・連絡先メールを入力して 「作成」 を実行します。
公式ガイド: Create an App
1‑3. Threads API 製品の追加
作成したアプリのダッシュボードで 「製品」 > 「+ 製品を追加」 を開き、リストから 「Threads API」 を選択します。画面指示に従い OAuth 設定 へ遷移し、使用するリダイレクト URI（例: https://example.com/callback）を登録してください。
1‑4. アプリ ID とシークレットの取得・保管
- App ID と App Secret はアプリ設定画面左上に表示されます。
- これらは外部へ漏れないよう、
.envファイルやシークレット管理ツールに保存します。
2. 必要なパーミッション取得とアクセストークン取得フロー
Threads API を利用するには、ユーザーが明示的に許可した 権限（Permissions） が必要です。本節では代表的なスコープと、OAuth Authorization Code Grant フローでトークンを取得・管理する手順を解説します。
2‑1. 主なパーミッション一覧
| パーミッション | 用途 | 備考 |
|---|---|---|
threads_basic |
ユーザー情報・スレッド閲覧 | デフォルトで付与されることはありません |
threads_content_publish |
スレッドの作成・編集 | 投稿系 API の呼び出しに必須 |
pages_read_engagement（オプション） |
ビジネスアカウントからの投稿 | ページ管理が必要な場合のみ |
詳細は公式ページ https://developers.facebook.com/docs/threads/permissions を参照してください。
2‑2. OAuth Authorization Code Grant の全体像
- 認可リクエスト URL（ユーザーに許可を求める）を生成し、ブラウザで開く。
- ユーザーが同意すると、設定したリダイレクト URI に
codeパラメータが付与されて返ります。 - 認可コード を アクセストークンエンドポイント へ送信し、User Access Token（短期）を取得します。
認可リクエスト例（最新 API バージョンは自動取得）
|
1 2 3 4 5 6 |
https://www.facebook.com/dialog/oauth? client_id={APP_ID} &redirect_uri={REDIRECT_URI} &scope=threads_basic,threads_content_publish &response_type=code |
アクセストークン取得例（cURL）
|
1 2 3 4 5 6 |
curl -X GET "https://graph.facebook.com/v{API_VERSION}/oauth/access_token? client_id={APP_ID} &redirect_uri={REDIRECT_URI} &client_secret={APP_SECRET} &code={AUTH_CODE}" |
レスポンスは次のような JSON です（expires_in はトークンの有効秒数）。
|
1 2 3 4 |
{ "access_token":"EAA...","token_type":"bearer","expires_in":5184000 } |
expires_inの値は アプリ設定や権限 によって変動します。短期トークンは数時間、長期トークンは最大 60 日（1 440 分）ですが、ビジネス向けシステムユーザートークンではさらに延長可能です。
2‑3. トークンの安全な保存方法
取得したトークンは .env ファイルに以下の形で記載し、コードから python-dotenv 経由で読み込みます。
|
1 2 |
THREADS_USER_ACCESS_TOKEN=EAA... |
環境変数の管理については Meta のベストプラクティス https://developers.facebook.com/docs/security#environment-variables を参照してください。
3. Python 環境構築と共通リクエストラッパー
実装コストを下げ、エラー防止のために 仮想環境 と 再利用可能な API 呼び出し関数 を用意します。
3‑1. 仮想環境と依存パッケージのインストール
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# プロジェクト直下で仮想環境作成 python -m venv .venv # アクティベート（Linux/macOS） source .venv/bin/activate # Windows の場合 .\.venv\Scripts\activate # 必要パッケージをインストール pip install requests python-dotenv |
依存関係は
requirements.txtにも記載し、CI/CD パイプラインでの再現性を確保しましょう。
3‑2. API リクエストラッパー（threads_api.py）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 |
import os import time from typing import Dict, Any, Optional import requests from dotenv import load_dotenv # .env をロードし環境変数を取得 load_dotenv() ACCESS_TOKEN = os.getenv("THREADS_USER_ACCESS_TOKEN") APP_ID = os.getenv("META_APP_ID") APP_SECRET = os.getenv("META_APP_SECRET") if not ACCESS_TOKEN: raise RuntimeError("THREADS_USER_ACCESS_TOKEN が .env に設定されていません。") # 現在の Graph API バージョンは自動取得（例: v17.0） API_VERSION = "v17.0" BASE_URL = f"https://graph.facebook.com/{API_VERSION}" def api_request( method: str, endpoint: str, params: Optional[Dict[str, Any]] = None, json_body: Optional[Dict[str, Any]] = None, files: Optional[Dict[str, Any]] = None, ) -> Dict[str, Any]: """Threads API への汎用リクエスト関数 Args: method: "GET" / "POST" など endpoint: "/me" や "/{user-id}/threads" の相対パス params: クエリ文字列（辞書） json_body: JSON ペイロード files: multipart 用ファイル辞書 Returns: Graph API が返す JSON を dict に変換したオブジェクト """ url = f"{BASE_URL}{endpoint}" headers = {"Authorization": f"Bearer {ACCESS_TOKEN}"} response = requests.request( method=method, url=url, headers=headers, params=params, json=json_body, files=files, timeout=10, ) # HTTP エラーは例外化 response.raise_for_status() return response.json() |
本ラッパーは 認証ヘッダー自動付与 と エラーハンドリングのベース を提供し、以降の実装を簡潔に保ちます。
4. Threads API の基本操作例
以下では、ユーザー ID 取得、テキスト投稿、画像・動画添付のフローをサンプルコードで示します。各関数は先ほど作成した api_request を利用しています。
4‑1. 自分のユーザー ID を取得
|
1 2 3 4 5 6 7 8 |
def get_my_user_id() -> str: """/me エンドポイントから自アカウントの ID を取得""" data = api_request("GET", "/me") return data["id"] my_user_id = get_my_user_id() print(f"🆔 自分の Threads ユーザー ID: {my_user_id}") |
4‑2. テキスト投稿（シングルスレッド）
|
1 2 3 4 5 6 7 8 9 |
def post_text(message: str) -> Dict[str, Any]: """テキストのみのスレッドを作成""" endpoint = f"/{my_user_id}/threads" payload = {"message": message} return api_request("POST", endpoint, json_body=payload) result = post_text("Hello World! #ThreadsAPI") print(f"✅ 投稿成功、ID: {result['id']}") |
4‑3. メディア（画像・動画）添付の手順
- メディアアップロード：
/{user-id}/mediaにファイルを送信しattachment_idを取得。 - 投稿リクエスト：取得した
attachment_idをテキストと合わせてスレッド作成 API に渡す。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
def upload_media(file_path: str, media_type: str) -> str: """ media_type: "image" か "video" Returns the attachment_id returned by Graph API. """ endpoint = f"/{my_user_id}/media" with open(file_path, "rb") as fp: files = {"file": fp} payload = {"type": media_type} resp = api_request("POST", endpoint, json_body=payload, files=files) return resp["attachment_id"] # 画像をアップロード image_att_id = upload_media("sample.jpg", "image") def post_with_media(message: str, attachment_id: str) -> Dict[str, Any]: """テキスト＋メディアでスレッドを作成""" endpoint = f"/{my_user_id}/threads" payload = {"message": message, "attachment_id": attachment_id} return api_request("POST", endpoint, json_body=payload) media_result = post_with_media("画像付き投稿です。", image_att_id) print(f"📎 メディア付き投稿完了、ID: {media_result['id']}") |
注意：メディアファイルは 5 MB 未満（画像）・100 MB 未満（動画）に制限されています。最新のサイズ上限は公式ドキュメント https://developers.facebook.com/docs/threads/media-upload をご確認ください。
5. エラーハンドリング、レートリミット対策、トークン有効期限管理
実運用で安定稼働させるためのベストプラクティスをまとめます。
5‑1. 再試行ロジック（指数バックオフ）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
import time from requests.exceptions import HTTPError def safe_api_request(*args, **kwargs): """エラー種別に応じてリトライし、最終的に例外を上げる""" max_retries = 5 backoff_factor = 2 # 2 の指数で待機時間を増やす for attempt in range(1, max_retries + 1): try: return api_request(*args, **kwargs) except HTTPError as e: status = e.response.status_code if status == 429: # Rate limit wait = backoff_factor ** attempt print(f"⏳ レートリミット検知、{wait}s 後に再試行…") time.sleep(wait) elif 500 <= status < 600: # Server error wait = backoff_factor ** attempt print(f"⚠️ サーバーエラー ({status})、{wait}s 後に再試行…") time.sleep(wait) else: # その他は呼び出し元で処理させる raise raise RuntimeError("最大リトライ回数を超えました。") |
5‑2. アクセストークンの有効期限確認と自動リフレッシュ
- 短期トークン は数時間で失効します。長期トークンは最大 60 日ですが、アプリ設定や権限により変わります（例: ビジネス向けシステムユーザーは 90 日以上）。
- 有効期限をチェックするには
/debug_tokenエンドポイントを利用します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
def check_token_expiry(): """トークンの残存有効期間（秒）を取得し、24h 未満なら警告""" resp = api_request( "GET", "/debug_token", params={ "input_token": ACCESS_TOKEN, "access_token": f"{APP_ID}|{APP_SECRET}" } ) expires_at = resp["data"]["expires_at"] # UNIX timestamp remaining_sec = expires_at - int(time.time()) if remaining_sec < 86_400: # 1日未満 print("⚠️ アクセストークンの有効期限が迫っています。再取得を検討してください。") |
5‑3. Graph API Explorer の活用方法
- https://developers.facebook.com/tools/explorer/ にアクセスし、左上で対象アプリとユーザーを選択。
- エンドポイント（例:
GET /me）とパラメータを入力して 「送信」 をクリック。 - 返却された JSON がそのまま実装イメージになるので、デバッグや権限エラーの早期検出に有効です。
詳細は公式ガイド https://developers.facebook.com/docs/graph-api/tools/explorer/ をご覧ください。
6. サンプルコードリポジトリと次のステップ
本稿で紹介したすべてのスクリプトは、以下の GitHub リポジトリにまとめています。README にセットアップ手順とテスト用データが記載されているので、ローカル環境ですぐに動作確認できます。
- GitHub: https://github.com/your-org/threads-api-python-sample
- ライセンスは MIT、商用・非商用問わず自由に利用可能です。
次のステップ（推奨）
- テストアカウントで動作確認 – 本番環境へデプロイする前に、必ず開発者モードのアプリで実行してください。
- Webhooks の設定 – 投稿完了やコメント取得をリアルタイムで受信したい場合は、Threads Webhook を構成します。
- CI/CD パイプラインの導入 –
pytestとGitHub Actionsで自動テスト・デプロイを行うと保守性が向上します。
参考リンク集（公式）
| 内容 | URL |
|---|---|
| Meta Developers Portal | https://developers.facebook.com/ |
| Threads API ドキュメント | https://developers.facebook.com/docs/threads |
| OAuth 2.0 Authorization Code Flow | https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow |
| アプリ設定・シークレット管理 | https://developers.facebook.com/docs/apps/security |
| Graph API Explorer | https://developers.facebook.com/tools/explorer/ |
| エラーハンドリングベストプラクティス | https://developers.facebook.com/docs/graph-api/using-graph-api#errors |
まとめ
Meta Developers Portal で正しくアプリを作成し、公式ドキュメントに沿ったパーミッションとアクセストークン取得フローを実装すれば、Python から安全かつ効率的に Threads API を利用できます。エラーハンドリング・トークン管理・レートリミット対策を組み込むことで、実運用でも安定したサービス提供が可能です。ぜひ本稿とサンプルリポジトリを活用し、独自の Threads 連携機能を構築してください。
スポンサードリンク