> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Python

> Consulta le analisi e gestisci gruppi e limiti di ACU dalla riga di comando con l'SDK Python.

<Info>
  Questa documentazione è destinata alle distribuzioni federali di Devin. [Torna alla documentazione di Devin](/it/get-started/devin-intro)
</Info>

L'SDK Python (`windsurf_analytics.py`) è un client da riga di comando per gli endpoint dell'[API federale](/it/federal/api/overview): report di utilizzo, [consumo di ACU](/it/federal/api/acu-consumption), [gestione dei gruppi](/it/federal/api/group-management) e [limiti di ACU per utente](/it/federal/api/acu-caps). Contatta il tuo referente Cognition per ottenere lo script per la tua distribuzione.

<div id="requirements">
  ## Requisiti
</div>

* Python 3
* La libreria `requests`: `pip install requests`

<div id="authentication">
  ## Autenticazione
</div>

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](/it/federal/api/overview#required-permissions). Tutti i comandi di analisi richiedono inoltre un tier del team con accesso alle API di analisi.

<div id="commands">
  ## Comandi
</div>

| 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`.

<div id="output-and-errors">
  ## Output ed errori
</div>

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`.

<div id="examples">
  ## Esempi
</div>

<div id="per-user-usage-report">
  ### Report di utilizzo per utente
</div>

```bash theme={null}
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
```

<div id="acu-consumption">
  ### Consumo di ACU
</div>

```bash theme={null}
# 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.

<div id="group-management">
  ### Gestione dei gruppi
</div>

```bash theme={null}
# 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
```

<div id="user-acu-caps">
  ### Limiti ACU per utente
</div>

```bash theme={null}
# 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
```