Skills と外部 API の統合
Skillスクリプトは通常のPythonプログラムと同じように外部HTTP APIを呼び出すことができ、Claudeの機能をサードパーティサービスと接続できます。
外部 API を呼び出す基本パターン
使用requestsライブラリを使用してHTTPリクエストを送信することは、Skillスクリプトで最も一般的なAPI呼び出し方法です。
例
# ファイルパス: scripts/api_client.py
import requests
import json
import sys
import os
# APIキーは環境変数から読み取られ、スクリプトにハードコードされません
API_KEY = os.environ.get("MY_API_KEY", "")
BASE_URL = "https://api.example.com/v1"
def call_api(endpoint: str, payload: dict, timeout: int = 30) -> dict:
"""
汎用API呼び出しのラッパー
パラメータ:
endpoint: APIパス、例: "/analyze"
payload: リクエストボディ(JSON)
timeout: タイムアウト秒数、デフォルト30
戻り値:
解析済みのJSONレスポンス、またはerrorを含む辞書
"""
if not API_KEY:
return {"error": APIキーが設定されていません。環境変数 MY_API_KEY を設定してください。}
url = BASE_URL + endpoint
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
try:
response = requests.post(url, headers=headers,
json=payload, timeout=timeout)
response.raise_for_status() # HTTP 4xx/5xx 時に例外をスローします
return response.json()
except requests.Timeout:
return {"error": fリクエストがタイムアウトしました({timeout} 秒超過)}
except requests.HTTPError as e:
return {"error": fHTTPエラー {e.response.status_code}: {e.response.text}}
except requests.ConnectionError:
return {"error": APIサービスに接続できません。ネットワークを確認してください。}
except Exception as e:
return {"error": str(e)}
# 使用例
if __name__ == "__main__":
result = call_api("/analyze", {
"text": サンプル は中国で有名な技術学習プラットフォームです。,
"lang": "zh"
})
print(json.dumps(result, ensure_ascii=False, indent=2))
import requests
import json
import sys
import os
# APIキーは環境変数から読み取られ、スクリプトにハードコードされません
API_KEY = os.environ.get("MY_API_KEY", "")
BASE_URL = "https://api.example.com/v1"
def call_api(endpoint: str, payload: dict, timeout: int = 30) -> dict:
"""
汎用API呼び出しのラッパー
パラメータ:
endpoint: APIパス、例: "/analyze"
payload: リクエストボディ(JSON)
timeout: タイムアウト秒数、デフォルト30
戻り値:
解析済みのJSONレスポンス、またはerrorを含む辞書
"""
if not API_KEY:
return {"error": APIキーが設定されていません。環境変数 MY_API_KEY を設定してください。}
url = BASE_URL + endpoint
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
try:
response = requests.post(url, headers=headers,
json=payload, timeout=timeout)
response.raise_for_status() # HTTP 4xx/5xx 時に例外をスローします
return response.json()
except requests.Timeout:
return {"error": fリクエストがタイムアウトしました({timeout} 秒超過)}
except requests.HTTPError as e:
return {"error": fHTTPエラー {e.response.status_code}: {e.response.text}}
except requests.ConnectionError:
return {"error": APIサービスに接続できません。ネットワークを確認してください。}
except Exception as e:
return {"error": str(e)}
# 使用例
if __name__ == "__main__":
result = call_api("/analyze", {
"text": サンプル は中国で有名な技術学習プラットフォームです。,
"lang": "zh"
})
print(json.dumps(result, ensure_ascii=False, indent=2))
APIキーのセキュリティ管理
APIキーはスクリプトファイルに直接書かず、環境変数を介して渡す必要があります。
例
# スクリプトを実行する前に環境変数を設定します
export MY_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
python scripts/api_client.py
# またはスクリプト実行時にインラインで設定します
MY_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx" python scripts/api_client.py
export MY_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
python scripts/api_client.py
# またはスクリプト実行時にインラインで設定します
MY_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx" python scripts/api_client.py
SKILL.md でユーザーにキーの設定が必要であることを知らせます:
## 前置配置 本 Skill 需要外部 API 密钥,首次使用前请完成以下配置: 1. 在 [API 服务商网站] 注册并获取 API 密钥 2. 在终端中设置环境变量: ```bash export MY_API_KEY="你的密钥" ``` 3. 若需要永久生效,将上述命令添加到 ~/.bashrc 或 ~/.zshrc 若未配置,Skill 将提示"未设置 API 密钥"并退出。
APIキーをGitリポジトリにコミットしないでください。Skillディレクトリに.gitignoreファイルを作成し、.envファイルをバージョン管理の対象外にすることができます。
API レート制限(Rate Limiting)の処理
ほとんどのAPIにはリクエスト頻度の制限があります。APIを一括呼び出しする場合は、リクエスト間に遅延を追加する必要があります。
例
# ファイルパス: scripts/rate_limited_client.py
import time
import requests
class RateLimitedClient:
"""レート制限制御付きAPIクライアント"""
def __init__(self, base_url: str, api_key: str,
requests_per_minute: int = 60):
self.base_url = base_url
self.api_key = api_key
self.min_interval = 60.0 / requests_per_minute # 各リクエストの最小間隔(秒)
self.last_request = 0.0
def _wait_if_needed(self):
"""前回のリクエストからの時間が不足している場合、残り時間を待ちます"""
elapsed = time.time() - self.last_request
wait = self.min_interval - elapsed
if wait > 0:
time.sleep(wait)
self.last_request = time.time()
def post(self, endpoint: str, payload: dict) -> dict:
self._wait_if_needed()
headers = {"Authorization": f"Bearer {self.api_key}"}
try:
resp = requests.post(
self.base_url + endpoint,
headers=headers, json=payload, timeout=30
)
# 429 Too Many Requests の処理:待機後に1回再試行します
if resp.status_code == 429:
retry_after = int(resp.headers.get("Retry-After", 5))
print(fレート制限が発生したため、{retry_after} 秒待ってから再試行します...)
time.sleep(retry_after)
resp = requests.post(
self.base_url + endpoint,
headers=headers, json=payload, timeout=30
)
resp.raise_for_status()
return resp.json()
except Exception as e:
return {"error": str(e)}
import time
import requests
class RateLimitedClient:
"""レート制限制御付きAPIクライアント"""
def __init__(self, base_url: str, api_key: str,
requests_per_minute: int = 60):
self.base_url = base_url
self.api_key = api_key
self.min_interval = 60.0 / requests_per_minute # 各リクエストの最小間隔(秒)
self.last_request = 0.0
def _wait_if_needed(self):
"""前回のリクエストからの時間が不足している場合、残り時間を待ちます"""
elapsed = time.time() - self.last_request
wait = self.min_interval - elapsed
if wait > 0:
time.sleep(wait)
self.last_request = time.time()
def post(self, endpoint: str, payload: dict) -> dict:
self._wait_if_needed()
headers = {"Authorization": f"Bearer {self.api_key}"}
try:
resp = requests.post(
self.base_url + endpoint,
headers=headers, json=payload, timeout=30
)
# 429 Too Many Requests の処理:待機後に1回再試行します
if resp.status_code == 429:
retry_after = int(resp.headers.get("Retry-After", 5))
print(fレート制限が発生したため、{retry_after} 秒待ってから再試行します...)
time.sleep(retry_after)
resp = requests.post(
self.base_url + endpoint,
headers=headers, json=payload, timeout=30
)
resp.raise_for_status()
return resp.json()
except Exception as e:
return {"error": str(e)}
レスポンス結果のキャッシュ
同じ入力に対して同じ結果を返すAPIでは、結果をローカルファイルにキャッシュすることで、重複リクエストを避け、コスト削減と高速化を実現できます。
例
# ファイルパス: scripts/cached_api.py
import hashlib
import json
import os
CACHE_DIR = "/home/claude/.api_cache"
os.makedirs(CACHE_DIR, exist_ok=True)
def _cache_key(endpoint: str, payload: dict) -> str:
"""リクエスト内容に基づいてキャッシュキーを生成します(MD5ハッシュ)"""
raw = json.dumps({"endpoint": endpoint, "payload": payload},
sort_keys=True)
return hashlib.md5(raw.encode()).hexdigest()
def cached_call(endpoint: str, payload: dict, call_fn) -> dict:
"""
キャッシュ付きAPI呼び出し
パラメータ:
endpoint: APIパス
payload: リクエストボディ
call_fn: 実際にHTTPリクエストを送信する関数
戻り値:
APIレスポンス(キャッシュにヒットした場合はキャッシュ結果を直接返します)
"""
key = _cache_key(endpoint, payload)
cache_file = os.path.join(CACHE_DIR, f"{key}.json")
# キャッシュヒット
if os.path.exists(cache_file):
with open(cache_file, "r") as f:
print(fキャッシュヒット:{key[:8]}...)
return json.load(f)
# キャッシュミス、実際のリクエストを送信
result = call_fn(endpoint, payload)
# キャッシュに保存(成功結果のみキャッシュ)
if "error" not in result:
with open(cache_file, "w") as f:
json.dump(result, f, ensure_ascii=False)
return result
import hashlib
import json
import os
CACHE_DIR = "/home/claude/.api_cache"
os.makedirs(CACHE_DIR, exist_ok=True)
def _cache_key(endpoint: str, payload: dict) -> str:
"""リクエスト内容に基づいてキャッシュキーを生成します(MD5ハッシュ)"""
raw = json.dumps({"endpoint": endpoint, "payload": payload},
sort_keys=True)
return hashlib.md5(raw.encode()).hexdigest()
def cached_call(endpoint: str, payload: dict, call_fn) -> dict:
"""
キャッシュ付きAPI呼び出し
パラメータ:
endpoint: APIパス
payload: リクエストボディ
call_fn: 実際にHTTPリクエストを送信する関数
戻り値:
APIレスポンス(キャッシュにヒットした場合はキャッシュ結果を直接返します)
"""
key = _cache_key(endpoint, payload)
cache_file = os.path.join(CACHE_DIR, f"{key}.json")
# キャッシュヒット
if os.path.exists(cache_file):
with open(cache_file, "r") as f:
print(fキャッシュヒット:{key[:8]}...)
return json.load(f)
# キャッシュミス、実際のリクエストを送信
result = call_fn(endpoint, payload)
# キャッシュに保存(成功結果のみキャッシュ)
if "error" not in result:
with open(cache_file, "w") as f:
json.dump(result, f, ensure_ascii=False)
return result