tweetsmash-api

TweetSmash API

現在のエンドポイント情報に基づいて、TweetSmash REST API を直接操作するには、このスキルを使用してください。このタスクで検証済みのドキュメントは再利用し、見当たらない場合、古くなっている場合、または API の情報と食い違う場合は更新してください。エンドポイントを選ぶ前に references/api-reference.md を読みます。ブックマークのフィルタリングが必要な場合に限り、references/bookmarks-filters.md を読みます。

手順

Step 1: 認証情報とスコープを確認する

1. リクエストを送信する前に、TweetSmash API キーが利用可能であることを確認します。シェル環境の TWEETSMASH_API_KEY を優先してください。
2. 現在のエンドポイント、必須ヘッダー、レート制限、ステータスコードを確認するため、references/api-reference.md を読みます。
3. タスクでブックマークのフィルタリングやページネーションが必要な場合は、references/bookmarks-filters.md を読みます。

Step 2: リクエストを作成する

1. すべてのリクエストで Authorization: Bearer $TWEETSMASH_API_KEY を使用します。
2. このスキル内のすべての例で Content-Type: application/json を使用します。ベース URL は https://api.tweetsmash.com/v1 のままにします。
3. タスクでフィルター付きのブックマークを取得する場合は、必要なフラグを指定して python3 <tweetsmash-api-dir>/scripts/build-bookmarks-url.py を実行し、適切にエンコードされた URL を生成します。
4. ラベルを追加する場合は、assets/add-labels-body.json を基にして、tweet_ids と label_id または label_name のいずれかを入力します。
5. ラベルを削除する場合は、assets/remove-labels-body.json を基にして、tweet_ids と label_name を入力します。

Step 3: 適切なエンドポイントを実行する

1. GET /bookmarks でブックマークを取得します。フィルター、検索、またはカーソルがある場合は、scripts/build-bookmarks-url.py の URL を使用します。
2. 現在のラベル ID、ラベル名、または使用回数が必要な場合は、GET /labels でラベルを一覧表示します。
3. ブックマークしたツイートを1件以上整理する必要がある場合は、POST /labels/add でラベルを追加します。
4. ブックマークしたツイートを整理または再分類する必要がある場合は、POST /labels/remove でラベルを削除します。
5. 手早く実行するには cURL を使用します。エンドポイントとペイロードを確認してから、必要に応じて同じリクエストを呼び出し元のランタイム向けに変換します。

Step 4: レスポンスを確認する

1. 成功を報告する前に、レスポンス JSON に "status": true が含まれていることを確認します。
2. ブックマークの読み取りでページネーションが重要な場合は、meta.next_cursor、meta.limit、meta.total_count を確認します。
3. ラベルの変更では、成功メッセージが意図した操作と一致することを確認します。
4. ラベルの存在がタスクの前提となっており、変更のレスポンスだけでは確認できない場合は、GET /labels を呼び出して変更後の状態を確認します。

Step 5: 利用可能な結果を返す

1. 使用したリクエストメソッド、エンドポイント、有効なフィルターまたはペイロードのフィールドを要約します。
2. 呼び出し元が求める出力形式に応じて、レスポンス本文または構造化された要約を返します。
3. 後続のページネーションが可能な場合は、次のリクエストで前のページから続けられるように meta.next_cursor を提示します。

エラー処理

• 認証に 401 で失敗した場合は、Bearer トークンが存在し、空ではなく、正しい TweetSmash アカウントのものであることを確認します。
• API が 402 を返した場合は、リクエストされた API アクセスが現在のプランでは許可されていないことを報告し、処理を中止します。
• API が 429 を返した場合は、リクエストの送信を中止し、Retry-After または現在のレート制限ヘッダーに従います。付属のリファレンスには過去の制限が記録されていますが、普遍的な制限として扱ったり、短い間隔で繰り返しリトライしたりしないでください。
• ブックマークのクエリを手作業で組み立てるのが難しい場合は、python3 <tweetsmash-api-dir>/scripts/build-bookmarks-url.py --help を再実行し、クエリ文字列を手動で連結せずに URL を組み立て直してください。
• ラベルの変更が不明瞭な場合は、まず GET /labels でラベルを一覧表示し、確認済みのラベル ID またはラベル名を使って変更を再実行します。