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 limite ACU per utente. Scarica lo script dalla pagina Analytics del portale della tua distribuzione selezionando Download SDK, oppure contatta il tuo referente Cognition.

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 Error calling <endpoint> (HTTP <status>): code: message e lo script termina con stato 1. Le combinazioni di flag non valide vengono rifiutate prima dell’invio di qualsiasi richiesta, con stato di uscita 2.

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