SDK de Python - Devin Docs

Esta documentación corresponde a los despliegues federales de Devin. Volver a la documentación de Devin

El SDK de Python (windsurf_analytics.py) es un cliente de línea de comandos para los endpoints de la API federal: informes de uso, consumo de ACU, gestión de grupos y límites de ACU por usuario. Descarga el script desde la página Analytics del portal de tu despliegue seleccionando Download SDK, o ponte en contacto con tu representante de Cognition.

Requisitos

Python 3
La biblioteca requests: pip install requests

Autenticación

Todos los comandos aceptan estas opciones compartidas:

Opción	Descripción
`--service-key`	Clave de servicio para la autenticación. También se puede configurar mediante la variable de entorno `WINDSURF_SERVICE_KEY`.
`--api-url`	URL base del servidor de API de tu despliegue (`https://<your-server>`). Se requiere HTTPS.

El rol de la clave de servicio debe contar con el permiso requerido por cada comando; consulta la tabla de permisos. Todos los comandos de analytics también requieren un tier de equipo con acceso a la Analytics API.

Comandos

Comando	Endpoint	Permiso requerido
`usage` (predeterminado)	`/UserPageAnalytics` + `/CascadeAnalytics`	Teams de solo lectura
`acu-consumption`	`/Analytics`	Analytics Read
`list-groups`	`/ListGroups`	Teams de solo lectura
`get-group`	`/GetGroup`	Teams de solo lectura
`create-group`	`/CreateGroup`	Teams Update
`update-group`	`/UpdateGroup`	Teams Update
`delete-group`	`/DeleteGroup`	Teams Update
`list-group-members`	`/ListGroupMembers`	Teams de solo lectura
`add-group-members`	`/AddGroupMembers`	Teams Update
`remove-group-members`	`/RemoveGroupMembers`	Teams Update
`get-user-acu-cap`	`/GetUserAcuCap`	Teams de solo lectura
`update-user-acu-cap`	`/UpdateUserAcuCap`	Teams Update

Al ejecutar el script sin especificar un comando (la invocación original), se ejecuta el informe de usage.

Salida y errores

Todos los comandos imprimen JSON en stdout. Los resultados paginados (filas de usuarios de consumo de ACU, list-groups, list-group-members) se recuperan automáticamente hasta la última página y se combinan en una única respuesta. Los errores de la API se imprimen en stderr con el formato Error calling <endpoint> (HTTP <status>): code: message y el script finaliza con el código de estado 1. Las combinaciones de opciones no válidas se rechazan antes de enviar cualquier solicitud, con código de salida 2.

Ejemplos

Informe de uso por usuario

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

Consumo de ACU

# Total de ACU del equipo más filas por usuario del ciclo de facturación actual
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --current-cycle --include-team-total --team-user-rows

# Desglose histórico por grupo (la ventana no puede abarcar más de 90 días),
# con filas por usuario para un grupo
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

Opciones de acu-consumption: --current-cycle o --start/--end seleccionan el período; --include-team-total, --group-id repetible (máx. 100) y las opciones mutuamente excluyentes --team-user-rows / --group-user-rows GROUP_ID seleccionan los datos; --page-size ajusta el tamaño de página por solicitud (se recuperan todas las páginas de todos modos). Se requiere al menos una opción de selección de datos. Una clave limitada a un grupo solo puede seleccionar el grupo que tiene asignado y no puede solicitar totales del equipo ni filas de usuarios del equipo.

Gestión de grupos

# Listar grupos y consultar un grupo
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

# Crear un grupo y configurar sus modelos y su límite de 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

# Quitar la restricción de modelos o el límite de ACU de un grupo. La API del servicio
# exige un valor positivo al establecer el límite de un grupo; quitarlo es una operación aparte.
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID --clear-cascade-models --clear-cycle-acu-limit

# Gestionar la membresía (correos separados por comas, máx. 1000)
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

# Eliminar un grupo (idempotente)
python windsurf_analytics.py delete-group --api-url https://your-server.com \
    --group-id GROUP_ID

Límites de ACU por usuario

# Consulta el límite configurado y el efectivo de un usuario (selecciónalo con --email o --user-id)
python windsurf_analytics.py get-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov

# Establece un límite (0 bloquea al usuario) o elimina la anulación
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

​Requisitos

​Autenticación

​Comandos

​Salida y errores

​Ejemplos

​Informe de uso por usuario

​Consumo de ACU

​Gestión de grupos

​Límites de ACU por usuario

Requisitos

Autenticación

Comandos

Salida y errores

Ejemplos

Informe de uso por usuario

Consumo de ACU

Gestión de grupos

Límites de ACU por usuario