Gestione dei gruppi - Devin Docs

Questa documentazione riguarda le distribuzioni federali di Devin. Torna alla documentazione di Devin

Gestisci i gruppi a livello programmatico: crea, leggi, aggiorna ed elimina gruppi, gestiscine l’appartenenza e configura la relativa disponibilità dei modelli e i limiti ACU. Questi endpoint sono disponibili solo nelle distribuzioni federali multi-tenant. Tutti gli endpoint utilizzano richieste JSON POST. Ogni corpo della richiesta include service_key; consulta la panoramica dell’API per informazioni su autenticazione, definizione dell’ambito, paginazione ed errori. Gli endpoint di lettura richiedono Teams Read-Only; quelli di scrittura richiedono Teams Update. Questi handler prevedono il controllo per distribuzioni self-hosted multi-tenant, ma non applicano il controllo separato del livello di accesso all’analisi utilizzato da /Analytics. L’oggetto gruppo restituito dagli endpoint di lettura e scrittura:

Campo	Descrizione
`group_id`	L’ID del gruppo.
`name`	Il nome del gruppo.
`member_count`	Numero di membri attuali.
`cascade_model_uids`	UID dei modelli consentiti per Cascade. Un elenco vuoto indica che il gruppo non impone alcuna restrizione per Cascade.
`command_model_uids`	UID dei modelli consentiti per Command. Un elenco vuoto indica che il gruppo non impone alcuna restrizione per Command.
`configured_cycle_acu_limit`	Il limite ACU configurato per membro del gruppo. Omesso se non è configurato alcun limite. È sempre positivo quando presente.
`effective_cycle_acu_limit`	Il limite effettivamente applicato al gruppo dopo la combinazione con i limiti del team. Omesso se non si applica alcun limite.

Elencare i gruppi

POST /api/v1/ListGroups

Elenca i gruppi visibili alla chiave di servizio. Le chiavi con ambito team elencano tutti i gruppi del team; quelle con ambito gruppo elencano solo il gruppo a cui sono assegnate. Richiede Teams Read-Only. Supporta page_size / page_token.

curl -X POST https://<your-server>/api/v1/ListGroups \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key"}'

{
  "groups": [
    {"groupId": "group_a", "name": "Engineering", "memberCount": 24},
    {"groupId": "group_b", "name": "Data Science", "memberCount": 9}
  ],
  "nextPageToken": ""
}

Ottieni un gruppo

POST /api/v1/GetGroup

Recupera un gruppo, incluse le allowlist dei modelli associate e il limite ACU configurato ed effettivo. Richiede Teams Read-Only. Per i gruppi inesistenti, di altri team o esterni all’ambito viene restituito not_found.

curl -X POST https://<your-server>/api/v1/GetGroup \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "group_id": "group_a"}'

{
  "group": {
    "groupId": "group_a",
    "name": "Engineering",
    "memberCount": 24,
    "cascadeModelUids": ["model-uid-1", "model-uid-2"],
    "commandModelUids": [],
    "configuredCycleAcuLimit": 50,
    "effectiveCycleAcuLimit": 50
  }
}

Crea un gruppo

POST /api/v1/CreateGroup

Crea un gruppo con il name specificato nel team effettivo. Richiede Teams Update. Le chiavi con ambito gruppo non possono creare gruppi.

curl -X POST https://<your-server>/api/v1/CreateGroup \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "name": "Engineering"}'

La risposta contiene l’oggetto group creato.

Aggiorna gruppo

POST /api/v1/UpdateGroup

Applica una patch atomica a un gruppo. Vengono modificati solo i campi presenti nella richiesta; quelli omessi rimangono invariati. Una richiesta senza campi da aggiornare restituisce invalid_argument. Richiede Teams Update.

string

obbligatorio

Il gruppo da aggiornare.

string

Il nuovo nome del gruppo.

object

{"model_uids": [...]} — sostituisce l’allowlist dei modelli Cascade del gruppo. Il passaggio di un elenco vuoto rimuove la restrizione Cascade del gruppo. Per informazioni su come vengono combinate le allowlist dei gruppi, consulta Provisioning dei modelli.

object

{"model_uids": [...]} — sostituisce l’allowlist dei modelli Command del gruppo. Il passaggio di un elenco vuoto rimuove la restrizione Command del gruppo.

number

Imposta il limite di ACU per membro del gruppo per ciclo di fatturazione. Deve essere positivo. Non può essere usato insieme a clear_cycle_acu_limit.

boolean

Rimuove il limite di ACU del gruppo, ripristinando il comportamento del team o predefinito. In questa API basata su chiave di servizio, set_cycle_acu_limit deve essere finito e positivo; usa questa operazione di rimozione esplicita per eliminare l’override del gruppo. Il controllo del limite ACU del gruppo nel portale accetta cycle_acu_limit: 0 come richiesta di rimozione.

curl -X POST https://<your-server>/api/v1/UpdateGroup \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "group_id": "group_a",
    "cascade_models": {"model_uids": ["model-uid-1", "model-uid-2"]},
    "set_cycle_acu_limit": 50
  }'

La risposta contiene l’oggetto group aggiornato.

Elimina gruppo

POST /api/v1/DeleteGroup

Elimina un gruppo tramite group_id. L’eliminazione di un gruppo già assente dall’ambito possibile della key viene considerata un’operazione riuscita senza effetti. Richiede Teams Update.

curl -X POST https://<your-server>/api/v1/DeleteGroup \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "group_id": "group_a"}'

Elencare i membri di un gruppo

POST /api/v1/ListGroupMembers

Elenca i membri attuali di un gruppo. Richiede l’autorizzazione Teams Read-Only. Supporta page_size / page_token.

curl -X POST https://<your-server>/api/v1/ListGroupMembers \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "group_id": "group_a"}'

{
  "members": [
    {"userId": "user_abc", "email": "dev@agency.gov"}
  ],
  "nextPageToken": ""
}

Aggiungi membri al gruppo

POST /api/v1/AddGroupMembers

Aggiunge al gruppo gli utenti del team corrente tramite email (user_emails, 1–1.000 voci). Richiede Teams Update.

Idempotente: l’aggiunta di un membro già esistente è un’operazione riuscita senza effetti.
Gli indirizzi email vengono privati degli spazi iniziali e finali e deduplicati senza distinzione tra maiuscole e minuscole.
Tutto o niente: se un indirizzo email è sconosciuto o appartiene a un altro team, l’intera richiesta viene rifiutata e non viene effettuata alcuna scrittura.

curl -X POST https://<your-server>/api/v1/AddGroupMembers \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "group_id": "group_a",
    "user_emails": ["dev@agency.gov", "lead@agency.gov"]
  }'

Rimuovi i membri del gruppo

POST /api/v1/RemoveGroupMembers

Rimuove utenti da un gruppo tramite email (user_emails, da 1 a 1.000 voci). Richiede Teams Update. La convalida è tutto o niente, come per Aggiungi membri al gruppo; la rimozione di un utente valido che non appartiene al gruppo è un’operazione riuscita senza effetti.

curl -X POST https://<your-server>/api/v1/RemoveGroupMembers \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "group_id": "group_a",
    "user_emails": ["dev@agency.gov"]
  }'

​Elencare i gruppi

​Ottieni un gruppo

​Crea un gruppo

​Aggiorna gruppo

​Elimina gruppo

​Elencare i membri di un gruppo

​Aggiungi membri al gruppo

​Rimuovi i membri del gruppo

Elencare i gruppi

Ottieni un gruppo

Crea un gruppo

Aggiorna gruppo

Elimina gruppo

Elencare i membri di un gruppo

Aggiungi membri al gruppo

Rimuovi i membri del gruppo