Gli amministratori Enterprise federali possono recuperare programmaticamente il consumo di ACU e gestire gruppi, disponibilità dei modelli e limiti ACU tramite un’API con chiave di servizio. Un SDK Python fornisce un wrapper per ogni endpoint descritto in questa sezione.
Gli endpoint per la gestione dei gruppi e i limiti ACU sono disponibili solo nelle distribuzioni federali self-hosted multi-tenant. Non sono esposti nelle distribuzioni commerciali. Gli endpoint di analisi (/Analytics, /UserPageAnalytics e /CascadeAnalytics) verificano anche il livello di accesso all’analisi della distribuzione; un team senza accesso all’analisi riceve permission_denied.
Tutte le richieste JSON POST vengono inviate al server API della tua distribuzione:
Sostituisci <your-server> con il dominio dell’API della tua distribuzione federale.
Ogni richiesta viene autenticata con una chiave di servizio inclusa nel corpo della richiesta:
Per creare una chiave di servizio, accedi al portale federale come amministratore del team e vai a Settings → Service Keys, quindi crea una chiave con le autorizzazioni richieste dagli endpoint che intendi chiamare.
Conserva le chiavi di servizio in modo sicuro. Non esporle mai nel codice lato client né includerle nei commit ai repository.
Chiavi con ambito team e gruppo
- Le chiavi con ambito team possono recuperare dati dell’intero team e gestire tutti i gruppi del team.
- Le chiavi con ambito gruppo sono limitate al gruppo assegnato. Possono leggere il totale aggregato di ACU del gruppo e le righe degli utenti, elencare e leggere solo quel gruppo, nonché leggere o aggiornare i limiti di ACU solo per i membri attuali di quel gruppo. Non possono leggere i totali dell’intero team o le righe degli utenti, visualizzare altri gruppi né creare gruppi.
L’elenco dei gruppi, dei membri dei gruppi e delle righe ACU per utente è suddiviso in pagine:
page_size — facoltativo; il valore predefinito è 100, con un massimo di 1.000. Se omesso o impostato su 0, viene usato il valore predefinito.next_page_token — restituito quando sono disponibili altri risultati. Passalo come page_token in una richiesta per il resto identica (incluso lo stesso page_size) per recuperare la pagina successiva.
I token di pagina sono opachi e crittografati. Scadono dopo 24 ore. I token relativi al consumo di ACU sono associati all’endpoint, al team, all’ambito, al periodo, alla selezione dei gruppi e alla dimensione della pagina. I token per l’elenco dei gruppi e dei membri sono associati all’endpoint, al team, all’ambito e alla dimensione della pagina. La modifica di un valore associato tra una pagina e l’altra restituisce un errore invalid_argument.
Gli errori vengono restituiti in formato JSON con un codice e un messaggio:
