SDK Python - Devin Docs

Questa documentazione è destinata alle distribuzioni federali di Devin. Torna alla documentazione di Devin

L’SDK Python (windsurf_analytics.py) è un client da riga di comando per gli endpoint dell’API federale: report di utilizzo, consumo di ACU, gestione dei gruppi e limiti di ACU per utente. Contatta il tuo referente Cognition per ottenere lo script per la tua distribuzione.

Requisiti

Python 3
La libreria requests: pip install requests

Autenticazione

Ogni comando accetta i seguenti flag comuni:

Flag	Descrizione
`--service-key`	Chiave di servizio per l’autenticazione. Può essere impostata anche tramite la variabile d’ambiente `WINDSURF_SERVICE_KEY`.
`--api-url`	URL di base dell’API server della distribuzione (`https://<your-server>`). HTTPS è obbligatorio.

Il ruolo associato alla chiave di servizio deve disporre dell’autorizzazione richiesta da ciascun comando — consulta la tabella delle autorizzazioni. Tutti i comandi di analisi richiedono inoltre un tier del team con accesso alle API di analisi.

Comandi

Comando	Endpoint	Autorizzazione richiesta
`usage` (predefinito)	`/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

Se esegui lo script senza specificare un comando (l’invocazione originale), viene eseguito il report usage.

Output ed errori

Tutti i comandi stampano JSON su stdout. I risultati paginati (righe utente relative al consumo di ACU, list-groups, list-group-members) vengono recuperati automaticamente fino all’ultima pagina e uniti in un’unica risposta. Gli errori API vengono stampati su stderr nel formato code: message e lo script termina con stato 1.

Esempi

Report di utilizzo per utente

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 di ACU

# Totale ACU del team più righe per utente per il ciclo di fatturazione corrente
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --current-cycle --include-team-total --team-user-rows

# Ripartizione storica per gruppo (la finestra non può superare i 90 giorni),
# con righe per utente per un singolo gruppo
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

I flag di acu-consumption: --current-cycle o --start/--end selezionano il periodo; --include-team-total, --group-id ripetibile (max 100) e le opzioni mutuamente esclusive --team-user-rows / --group-user-rows GROUP_ID selezionano i dati; --page-size imposta la dimensione della pagina per richiesta (vengono comunque recuperate tutte le pagine). È obbligatorio specificare almeno un flag di selezione dei dati. Una chiave con ambito limitato a un gruppo può selezionare solo il gruppo a cui è assegnata e non può richiedere i totali del team né le righe utente del team.

Gestione dei gruppi

# Elenca i gruppi e leggi un singolo gruppo
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

# Crea un gruppo, configura i relativi modelli e il limite di 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

# Rimuovi la restrizione sui modelli o il limite di ACU di un gruppo. L'API del servizio richiede
# un valore positivo quando si imposta un limite di gruppo; la rimozione è un'operazione separata.
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID --clear-cascade-models --clear-cycle-acu-limit

# Gestisci l'appartenenza (email separate da virgola, max 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

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

Limiti ACU per utente

# Legge il limite configurato ed effettivo di un utente (selezione tramite --email o --user-id)
python windsurf_analytics.py get-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov

# Imposta un limite (0 blocca l'utente) oppure rimuove l'override
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

​Requisiti

​Autenticazione

​Comandi

​Output ed errori

​Esempi

​Report di utilizzo per utente

​Consumo di ACU

​Gestione dei gruppi

​Limiti ACU per utente

Requisiti

Autenticazione

Comandi

Output ed errori

Esempi

Report di utilizzo per utente

Consumo di ACU

Gestione dei gruppi

Limiti ACU per utente