SDK Python - Devin Docs

Cette documentation concerne les déploiements fédéraux de Devin. Retour à la documentation Devin

Le SDK Python (windsurf_analytics.py) est un client en ligne de commande pour les endpoints de l’API fédérale : rapports d’utilisation, consommation d’ACU, gestion des groupes et plafonds d’ACU par utilisateur. Contactez votre représentant Cognition pour obtenir le script correspondant à votre déploiement.

Prérequis

Python 3
La bibliothèque requests : pip install requests

Authentification

Chaque commande accepte les indicateurs communs suivants :

Indicateur	Description
`--service-key`	Clé de service pour l’authentification. Peut également être définie à l’aide de la variable d’environnement `WINDSURF_SERVICE_KEY`.
`--api-url`	URL de base du serveur d’API de votre déploiement (`https://<your-server>`). HTTPS est requis.

Le rôle associé à la clé de service doit disposer de l’autorisation requise pour chaque commande ; consultez le tableau des autorisations. Toutes les commandes d’analyse nécessitent également un niveau Team donnant accès à l’API d’analyse.

Commandes

Commande	Endpoint	Autorisation requise
`usage` (par défaut)	`/UserPageAnalytics` + `/CascadeAnalytics`	Teams Read-Only
`acu-consumption`	`/Analytics`	Analytics Read
`list-groups`	`/ListGroups`	Teams Read-Only
`get-group`	`/GetGroup`	Teams Read-Only
`create-group`	`/CreateGroup`	Teams Update
`update-group`	`/UpdateGroup`	Teams Update
`delete-group`	`/DeleteGroup`	Teams Update
`list-group-members`	`/ListGroupMembers`	Teams Read-Only
`add-group-members`	`/AddGroupMembers`	Teams Update
`remove-group-members`	`/RemoveGroupMembers`	Teams Update
`get-user-acu-cap`	`/GetUserAcuCap`	Teams Read-Only
`update-user-acu-cap`	`/UpdateUserAcuCap`	Teams Update

L’exécution du script sans spécifier de commande (l’invocation d’origine) génère le rapport usage.

Sortie et erreurs

Toutes les commandes écrivent du JSON sur stdout. Les résultats paginés (lignes de consommation d’ACU par utilisateur, list-groups, list-group-members) sont automatiquement récupérés jusqu’à la dernière page et regroupés en une seule réponse. Les erreurs d’API sont écrites sur stderr au format code: message, et le script se termine avec le code de sortie 1.

Exemples

Rapport d’utilisation par utilisateur

python windsurf_analytics.py \
    --service-key YOUR_SERVICE_KEY \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z \
    --end 2025-03-31T23:59:59Z

Consommation d’ACU

# Total d'ACU de la Team, plus les lignes par utilisateur, pour le cycle de facturation en cours
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --current-cycle --include-team-total --team-user-rows

# Répartition historique par groupe (la fenêtre ne doit pas dépasser 90 jours),
# avec les lignes par utilisateur pour un groupe
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z --end 2025-03-31T23:59:59Z \
    --group-id GROUP_A_ID --group-user-rows GROUP_A_ID

Options de acu-consumption : --current-cycle ou --start/--end sélectionnent la période ; --include-team-total, --group-id répétable (100 maximum) et --team-user-rows / --group-user-rows GROUP_ID, qui s’excluent mutuellement, sélectionnent les données ; --page-size règle la taille des pages par requête (toutes les pages sont récupérées dans tous les cas). Au moins une option de sélection des données est requise. Une clé limitée à un groupe ne peut sélectionner que le groupe qui lui est attribué et ne peut pas demander les totaux de l’équipe ni les lignes par utilisateur de l’équipe.

Gestion des groupes

# Lister les groupes et consulter un groupe
python windsurf_analytics.py list-groups --api-url https://your-server.com
python windsurf_analytics.py get-group --api-url https://your-server.com \
    --group-id GROUP_ID

# Créer un groupe, configurer ses modèles et son plafond d'ACU
python windsurf_analytics.py create-group --api-url https://your-server.com \
    --name Engineering
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID \
    --cascade-models MODEL_UID_1,MODEL_UID_2 \
    --set-cycle-acu-limit 50

# Supprimer la restriction de modèles ou le plafond d'ACU d'un groupe. L'API du service exige
# une valeur positive lors de la définition d'un plafond de groupe ; la suppression est une opération distincte.
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID --clear-cascade-models --clear-cycle-acu-limit

# Gérer les membres (e-mails séparés par des virgules, 1000 max.)
python windsurf_analytics.py add-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov,lead@agency.gov
python windsurf_analytics.py remove-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov

# Supprimer un groupe (idempotent)
python windsurf_analytics.py delete-group --api-url https://your-server.com \
    --group-id GROUP_ID

Plafonds d’ACU par utilisateur

# Lire le plafond configuré et effectif d'un utilisateur (sélection par --email ou --user-id)
python windsurf_analytics.py get-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov

# Définir un plafond (0 bloque l'utilisateur) ou supprimer la dérogation
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --set-cycle-acu-limit 25
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --clear-cycle-acu-limit

​Prérequis

​Authentification

​Commandes

​Sortie et erreurs

​Exemples

​Rapport d’utilisation par utilisateur

​Consommation d’ACU

​Gestion des groupes

​Plafonds d’ACU par utilisateur

Prérequis

Authentification

Commandes

Sortie et erreurs

Exemples

Rapport d’utilisation par utilisateur

Consommation d’ACU

Gestion des groupes

Plafonds d’ACU par utilisateur