threads-api

Threads API スキル

Threads ソーシャルプラットフォームと連携するアプリケーションの構築に向けて、Meta の Threads API 開発を包括的に支援します。

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

次の作業を行うときに、このスキルを利用してください。

• Threads との連携を構築する - Threads への投稿や Threads からの読み取りを行うアプリを作成する
• 認証を実装する - Threads API にアクセスするための OAuth フローを設定する
• メディアのアップロードに取り組む - 画像、動画、またはカルーセル投稿を Threads にアップロードする
• ユーザーコンテンツを管理する - Threads の投稿を公開、取得、または管理する
• インサイトを取得する - Threads コンテンツのインサイトや指標を取得する
• Webhook を処理する - Threads からのリアルタイム更新を処理する
• API エラーをトラブルシューティングする - 認証、レート制限、API レスポンスをデバッグする
• Threads プロフィールを読み取る - ユーザープロフィールのデータや投稿を取得する

クイックリファレンス

認証 - アクセストークンの取得

// Step 1: Redirect user to authorization endpoint
const authUrl = `https://threads.net/oauth/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&scope=threads_basic,threads_content_publish&response_type=code`;

// Step 2: Exchange authorization code for access token
const response = await fetch('https://graph.threads.net/oauth/access_token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    grant_type: 'authorization_code',
    redirect_uri: REDIRECT_URI,
    code: authorizationCode
  })
});

const { access_token } = await response.json();

テキスト投稿の公開

// Create a simple text post
const response = await fetch(`https://graph.threads.net/v1.0/me/threads`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    media_type: 'TEXT',
    text: 'Hello from Threads API! 🎉'
  })
});

const data = await response.json();
console.log('Post ID:', data.id);

画像投稿の公開

import requests

# Upload and publish an image
url = "https://graph.threads.net/v1.0/me/threads"
headers = {"Authorization": f"Bearer {access_token}"}

data = {
    "media_type": "IMAGE",
    "image_url": "https://example.com/image.jpg",
    "text": "Check out this image! #API"
}

response = requests.post(url, headers=headers, json=data)
post_id = response.json()["id"]
print(f"Posted image with ID: {post_id}")

動画投稿の公開

// Step 1: Create a video container
const container = await fetch(`https://graph.threads.net/v1.0/me/threads`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}` },
  body: JSON.stringify({
    media_type: 'VIDEO',
    video_url: 'https://example.com/video.mp4',
    text: 'Check out this video!'
  })
});

const { id: containerId } = await container.json();

// Step 2: Publish the container
await fetch(`https://graph.threads.net/v1.0/me/threads_publish`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}` },
  body: JSON.stringify({ creation_id: containerId })
});

ユーザープロフィールの取得

import requests

# Get authenticated user's profile
url = f"https://graph.threads.net/v1.0/me"
headers = {"Authorization": f"Bearer {access_token}"}
params = {
    "fields": "id,username,name,threads_profile_picture_url,threads_biography"
}

response = requests.get(url, headers=headers, params=params)
profile = response.json()

print(f"Username: {profile['username']}")
print(f"Bio: {profile['threads_biography']}")

ユーザーの Threads 投稿の取得

// Get user's recent threads with pagination
const response = await fetch(
  `https://graph.threads.net/v1.0/me/threads?fields=id,text,timestamp,media_url&limit=25`,
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

const { data, paging } = await response.json();
data.forEach(thread => {
  console.log(`${thread.timestamp}: ${thread.text}`);
});

// Use paging.next for next page

カルーセル投稿の公開

import requests

# Create a carousel with multiple images
url = "https://graph.threads.net/v1.0/me/threads"
headers = {"Authorization": f"Bearer {access_token}"}

data = {
    "media_type": "CAROUSEL",
    "children": [
        {"media_type": "IMAGE", "image_url": "https://example.com/img1.jpg"},
        {"media_type": "IMAGE", "image_url": "https://example.com/img2.jpg"},
        {"media_type": "IMAGE", "image_url": "https://example.com/img3.jpg"}
    ],
    "text": "Swipe through these images! 📸"
}

response = requests.post(url, headers=headers, json=data)
carousel_id = response.json()["id"]

インサイト（分析データ）の取得

// Get insights for a specific thread
const threadId = '123456789';
const response = await fetch(
  `https://graph.threads.net/v1.0/${threadId}/insights?metric=views,likes,replies,reposts`,
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

const { data } = await response.json();
data.forEach(metric => {
  console.log(`${metric.name}: ${metric.values[0].value}`);
});

エラー処理のパターン

import requests

def make_threads_request(url, access_token, method='GET', **kwargs):
    """Robust error handling for Threads API requests"""
    headers = kwargs.pop('headers', {})
    headers['Authorization'] = f"Bearer {access_token}"

    try:
        response = requests.request(method, url, headers=headers, **kwargs)
        response.raise_for_status()
        return response.json()

    except requests.exceptions.HTTPError as e:
        error_data = e.response.json()
        error_code = error_data.get('error', {}).get('code')
        error_msg = error_data.get('error', {}).get('message')

        if error_code == 190:
            raise Exception(f"Invalid access token: {error_msg}")
        elif error_code == 32:
            raise Exception(f"Rate limit exceeded: {error_msg}")
        else:
            raise Exception(f"API Error {error_code}: {error_msg}")

    except requests.exceptions.RequestException as e:
        raise Exception(f"Network error: {str(e)}")

主な概念

アクセストークンと権限

• アクセストークン：すべての API リクエストに必要な OAuth 2.0 トークン
• スコープ：アプリがアクセスできる対象を定義します（例：threads_basic、threads_content_publish、threads_manage_insights）
• トークンの有効期限：長期有効トークン（60 日）と、アクセスを延長するためのリフレッシュトークン

メディアタイプ

• TEXT：シンプルなテキスト投稿
• IMAGE：キャプションを付けることもできる単一画像
• VIDEO：キャプションを付けることもできる単一動画
• CAROUSEL：スワイプして表示できる形式の複数の画像または動画

公開フロー

1. コンテナーの作成：コンテンツを含むメディアコンテナーを作成します
2. 公開：コンテナーを公開し、表示可能にします
3. 2 段階のプロセス：動画やカルーセルでは、処理時間を確保するために必要です

レート制限

• レート制限はエンドポイントとアクセスレベルによって異なります
• 標準のレート制限：ユーザーあたり 1 時間に 200 回の呼び出し
• レスポンス内の X-Business-Use-Case-Usage ヘッダーを監視します
• レート制限エラーには指数バックオフを実装します

Webhook

• メンション、返信、新しいフォロワーなどのイベントに関するリアルタイム通知
• 通知を受信するには HTTPS エンドポイントが必要です
• セキュリティのため、Webhook 署名を検証する必要があります

リファレンスファイル

このスキルには、references/ 内に包括的なドキュメントが含まれています。

• other.md - 次の内容を含む Threads API の完全なドキュメント：
  • 認証と認可のフロー
  • API エンドポイントのリファレンス
  • リクエストとレスポンスの形式
  • エラーコードとトラブルシューティング
  • ベストプラクティスとガイドライン

特定の API エンドポイント、パラメーター、高度な機能について詳しく知りたい場合は、スキルのリファレンスファイルを参照してください。

このスキルの利用方法

初心者向け

まず認証フローを理解しましょう。これは、すべての Threads API 連携の基盤です。次の内容に重点を置いてください。

1. Meta 開発者アカウントとアプリを設定する
2. OAuth 2.0 認可を実装する
3. ユーザープロフィールを取得する最初の API リクエストを送信する
4. シンプルなテキスト投稿を公開する

中級ユーザー向け

次の内容を確認して、基本機能を発展させましょう。

1. メディアのアップロード（画像と動画）
2. 複数画像コンテンツ向けのカルーセル投稿
3. リアルタイム更新のための Webhook 連携
4. エラー処理と再試行ロジック
5. レート制限の管理

上級ユーザー向け

次の内容を活用して、連携を最適化しましょう。

1. インサイトと分析データ
2. 効率化のためのバッチ処理
3. 高度なコンテンツスケジューリング
4. カスタム Webhook イベント処理
5. 複数アカウントの管理

ナビゲーションのヒント

• クイックリファレンス：一般的なタスクには、上記のコード例を使用してください
• リファレンスファイル：完全な API ドキュメントについては、references/other.md を参照してください
• まずは認証：常に適切な認証設定から始めてください
• サンドボックスでテスト：開発中は Meta のテストユーザーとサンドボックス環境を使用してください

一般的なワークフロー

投稿公開の一連の流れ

1. OAuth フローでアクセストークンを取得します
2. メディアコンテナーを作成します（画像や動画を使用する場合）
3. コンテナーの処理が完了するまで待ちます（動画の場合）
4. コンテナーを公開します
5. 投稿 ID とインサイトを取得します

ユーザーデータ取得の流れ

1. ユーザーを認証します
2. 必要なフィールドを指定してユーザープロフィールを取得します
3. ページネーションを使用してユーザーのスレッドを取得します
4. コンテンツを処理して表示します

Webhook 統合の流れ

1. HTTPS エンドポイントを設定します
2. Webhook サブスクリプションを登録します
3. Webhook 署名を検証します
4. 受信イベントを処理します
5. 200 OK ステータスで応答します

ベストプラクティス

1. セキュリティ

   • アクセストークンをクライアント側のコードで公開しないでください
   • Webhook 署名を必ず検証してください
   • 機密データには環境変数を使用してください
   • 有効期限が切れる前にトークンを更新する処理を実装してください

2. パフォーマンス

   • 適切な場合は API レスポンスをキャッシュしてください
   • 複数の操作にはバッチリクエストを使用してください
   • 大量の結果にはページネーションを実装してください
   • レート制限を監視し、遵守してください

3. ユーザーエクスペリエンス

   • ユーザーにわかりやすいエラーメッセージを表示してください
   • API 呼び出し中は読み込み状態を表示してください
   • ネットワーク障害を適切に処理してください
   • 必要な権限のみをリクエストしてください

4. コンテンツの公開

   • アップロード前にメディア URL を検証してください
   • メディア形式の要件を確認してください
   • アップロード失敗時に適切なエラー処理を追加してください
   • アクセシビリティのために代替テキストの使用を検討してください

リソース

公式ドキュメント

• Meta for Developers：https://developers.facebook.com/docs/threads
• API リファレンス：references/other.md で確認できます

開発者ツール

• Meta App Dashboard：アプリを設定し、権限を管理します
• Graph API Explorer：API 呼び出しを対話的にテストします
• Webhook Testing：本番環境への移行前に Webhook エンドポイントをテストします

トラブルシューティング

よくある問題

認証エラー（コード 190）

• アクセストークンの有効性を確認してください
• トークンの有効期限が切れていないことを確認してください
• 正しい権限／スコープが設定されていることを確認してください

レート制限エラー（コード 32）

• 指数バックオフを実装してください
• API の使用状況を監視してください
• レスポンスのキャッシュを検討してください

メディアのアップロード失敗

• メディア URL に誰でもアクセスできることを確認してください
• ファイル形式とサイズの要件を確認してください
• media_type パラメーターが正しく設定されていることを確認してください

Webhook でイベントを受信できない

• エンドポイントが HTTPS であることを確認してください
• Webhook 署名の検証を確認してください
• エンドポイントが速やかに 200 OK で応答することを確認してください

注記

• このスキルは Meta の公式 Threads API ドキュメントをもとに生成されました
• Threads API は Meta の Graph API ファミリーの一部です
• Meta により API の機能やエンドポイントが更新される場合があります。最新の変更については公式ドキュメントを参照してください
• 一部の機能には、Meta による追加のアプリレビューや権限が必要な場合があります

更新

このスキルを更新されたドキュメントで再生成するには：

1. 最新情報について https://developers.facebook.com/docs/threads にアクセスします
2. 更新された設定でドキュメントスクレイパーを再実行します
3. 最新の API 情報をもとにスキルが再構築されます