Skills et intégration des API externes
Les scripts Skill peuvent appeler des API HTTP externes comme des programmes Python ordinaires, ce qui permet de connecter les capacités de Claude à des services tiers.
Modèle de base pour appeler des API externes
L'utilisation de la bibliothèquerequestspour envoyer des requêtes HTTP est la manière la plus courante d'appeler des API dans les scripts Skill.
Exemple
import requests
import json
import sys
import os
# La clé API est lue depuis les variables d'environnement, et non codée en dur dans le script
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:
"""
Wrapper générique d'appel API
Paramètres :
endpoint: chemin d'API, par exemple, "/analyze"
payload: corps de la requête (JSON)
timeout: délai d'attente en secondes, par défaut 30
Retourne :
Réponse JSON analysée, ou un dictionnaire contenant une erreur
"""
if not API_KEY:
return {"error": "Clé API non définie, veuillez définir la variable d'environnement 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() # Lève une exception sur HTTP 4xx/5xx
return response.json()
except requests.Timeout:
return {"error": f"Délai d'attente de la requête dépassé ({timeout} secondes)"}
except requests.HTTPError as e:
return {"error": f"Erreur HTTP {e.response.status_code} : {e.response.text}"}
except requests.ConnectionError:
return {"error": "Impossible de se connecter au service API, veuillez vérifier le réseau"}
except Exception as e:
return {"error": str(e)}
# Exemple d'utilisation
if __name__ == "__main__":
result = call_api("/analyze", {
"text": "example est une plateforme d'apprentissage technique bien connue en Chine",
"lang": "zh"
})
print(json.dumps(result, ensure_ascii=False, indent=2))
Gestion sécurisée des clés API
Les clés API ne doivent pas être écrites directement dans les fichiers de script ; elles doivent être transmises via des variables d'environnement.
Exemple
export MY_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
python scripts/api_client.py
# Ou les définir directement lors de l'exécution du script
MY_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx" python scripts/api_client.py
Dans SKILL.md, informez les utilisateurs qu'ils doivent configurer la clé :
## 前置配置 本 Skill 需要外部 API 密钥,首次使用前请完成以下配置: 1. 在 [API 服务商网站] 注册并获取 API 密钥 2. 在终端中设置环境变量: ```bash export MY_API_KEY="你的密钥" ``` 3. 若需要永久生效,将上述命令添加到 ~/.bashrc 或 ~/.zshrc 若未配置,Skill 将提示"未设置 API 密钥"并退出。
Ne validez jamais de clés API dans un dépôt Git. Vous pouvez créer un fichier .gitignore dans le répertoire de la Skill pour exclure le fichier .env du contrôle de version.
Gestion de la limitation de débit des API
La plupart des API ont des limites de fréquence de requêtes. Lorsque vous appelez des API par lots, vous devez ajouter des délais entre les requêtes.
Exemple
import time
import requests
class RateLimitedClient:
"""Client API avec contrôle de la limitation de débit"""
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 # Intervalle minimum entre les requêtes (secondes)
self.last_request = 0.0
def _wait_if_needed(self):
"""Si le temps écoulé depuis la dernière requête n'est pas suffisant, attendre le temps restant"""
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
)
# Gérer 429 Too Many Requests: attendre et réessayer une fois
if resp.status_code == 429:
retry_after = int(resp.headers.get("Retry-After", 5))
print(f"Limite de débit atteinte, attente de {retry_after} secondes avant de réessayer...")
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)}
Mise en cache des réponses
Pour les API qui renvoient le même résultat pour la même entrée, vous pouvez mettre en cache les résultats dans des fichiers locaux afin d'éviter les requêtes en double, ce qui permet d'économiser de l'argent et d'améliorer la vitesse.
Exemple
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:
"""Générer une clé de cache en fonction du contenu de la requête (hash 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:
"""
Appel API avec mise en cache
Paramètres :
endpoint : chemin de l'API
payload : corps de la requête
call_fn : la fonction qui effectue réellement la requête HTTP
Retourne :
Réponse API (renvoie directement le résultat mis en cache lorsque le cache est atteint)
"""
key = _cache_key(endpoint, payload)
cache_file = os.path.join(CACHE_DIR, f"{key}.json")
# Succès du cache
if os.path.exists(cache_file):
with open(cache_file, "r") as f:
print(f"Cache trouvé : {key[:8]}...")
return json.load(f)
# Défaut de cache, effectuer une vraie requête
result = call_fn(endpoint, payload)
# Enregistrer dans le cache (ne mettre en cache que les résultats réussis)
if "error" not in result:
with open(cache_file, "w") as f:
json.dump(result, f, ensure_ascii=False)
return result