Python SDK - Devin Docs

Diese Dokumentation gilt für die Federal Deployments von Devin. Zurück zur Devin-Dokumentation

Das Python SDK (windsurf_analytics.py) ist ein Befehlszeilen-Client für die Endpunkte der Federal API: Nutzungsberichte, ACU-Verbrauch, Gruppenverwaltung und ACU-Obergrenzen für Nutzer. Wenden Sie sich an Ihre Cognition-Ansprechperson, um das Skript für Ihr Deployment zu erhalten.

Voraussetzungen

Python 3
Die Bibliothek requests: pip install requests

Authentifizierung

Jeder Befehl unterstützt die folgenden gemeinsamen Flags:

Flag	Beschreibung
`--service-key`	Service-Schlüssel zur Authentifizierung. Kann auch über die Umgebungsvariable `WINDSURF_SERVICE_KEY` festgelegt werden.
`--api-url`	Basis-URL des API-Servers Ihres Deployments (`https://<your-server>`). HTTPS ist erforderlich.

Die Rolle des Service-Schlüssels muss über die für den jeweiligen Befehl erforderliche Berechtigung verfügen – siehe Berechtigungstabelle. Alle Analytics-Befehle erfordern außerdem eine Team-Ebene mit Zugriff auf die Analytics-API.

Befehle

Befehl	Endpunkt	Erforderliche Berechtigung
`usage` (Standard)	`/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

Wenn Sie das Skript ohne Befehl ausführen (der ursprüngliche Aufruf), wird der Bericht usage ausgeführt.

Ausgabe und Fehler

Alle Befehle geben JSON auf stdout aus. Paginierte Ergebnisse (Nutzerzeilen zum ACU-Verbrauch, list-groups, list-group-members) werden automatisch bis zur letzten Seite abgerufen und zu einer einzigen Antwort zusammengeführt. API-Fehler werden als code: message auf stderr ausgegeben, und das Skript wird mit Status 1 beendet.

Beispiele

Nutzungsbericht pro Nutzer

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

ACU-Verbrauch

# ACU-Gesamtwert des Teams sowie Zeilen pro Nutzer für den aktuellen Abrechnungszeitraum
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --current-cycle --include-team-total --team-user-rows

# Historische Aufschlüsselung pro Gruppe (Zeitfenster darf maximal 90 Tage umfassen),
# mit Zeilen pro Nutzer für eine Gruppe
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

acu-consumption-Flags: --current-cycle oder --start/--end legen den Zeitraum fest; --include-team-total, wiederholbare --group-id (max. 100) und die sich gegenseitig ausschließenden Optionen --team-user-rows / --group-user-rows GROUP_ID legen die Daten fest; --page-size passt die Seitengröße pro Anfrage an (alle Seiten werden unabhängig davon abgerufen). Mindestens ein Flag zur Datenauswahl ist erforderlich. Ein auf eine Gruppe beschränkter Schlüssel kann nur die ihm zugewiesene Gruppe auswählen und weder Team-Gesamtwerte noch Team-Nutzerzeilen anfordern.

Gruppenverwaltung

# Gruppen auflisten und eine einzelne Gruppe abrufen
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

# Gruppe erstellen sowie deren Modelle und ACU-Obergrenze konfigurieren
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

# Modellbeschränkung oder ACU-Obergrenze einer Gruppe aufheben. Die Service-API verlangt beim
# Setzen einer Gruppen-Obergrenze einen positiven Wert; das Aufheben ist ein separater Vorgang.
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID --clear-cascade-models --clear-cycle-acu-limit

# Mitgliedschaften verwalten (kommagetrennte E-Mail-Adressen, 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

# Gruppe löschen (idempotent)
python windsurf_analytics.py delete-group --api-url https://your-server.com \
    --group-id GROUP_ID

ACU-Obergrenzen für Nutzer

# Konfigurierte und effektive Obergrenze eines Nutzers abrufen (Auswahl über --email oder --user-id)
python windsurf_analytics.py get-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov

# Obergrenze festlegen (0 sperrt den Nutzer) oder den Override entfernen
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

​Voraussetzungen

​Authentifizierung

​Befehle

​Ausgabe und Fehler

​Beispiele

​Nutzungsbericht pro Nutzer

​ACU-Verbrauch

​Gruppenverwaltung

​ACU-Obergrenzen für Nutzer

Voraussetzungen

Authentifizierung

Befehle

Ausgabe und Fehler

Beispiele

Nutzungsbericht pro Nutzer

ACU-Verbrauch

Gruppenverwaltung

ACU-Obergrenzen für Nutzer