Opzioni di Configurazione SDK

L'SDK Aruba Cloud per Go è configurato mediante un'API fluente che consente di concatenare i setter di opzioni per costruire una configurazione client. Questa guida dettaglia tutte le opzioni disponibili, raggruppate per argomento.

Iniziare

Il modo più semplice per configurare il client è utilizzare DefaultOptions, che fornisce una configurazione pronta per la produzione per il caso d'uso più comune (autenticazione Client Credentials).

Setter Opzione	Descrizione	Note
DefaultOptions(clientID, clientSecret)	Crea una configurazione standard per l'ambiente di produzione utilizzando il Client ID e il Secret API.	Questo è il punto di partenza consigliato per la maggior parte delle applicazioni. Imposta l'API di produzione e gli URL dei token e configura l'autenticazione.
NewOptions()	Crea un nuovo builder di configurazione vuoto. È necessario configurare manualmente tutte le impostazioni richieste, inclusa l'autenticazione.	Usa questa opzione se hai bisogno di controllo completo sulla configurazione da zero.

Configurazione Generale

Setter Opzione	Descrizione	Note
WithBaseURL(baseURL)	Sovrascrive l'URL API Aruba Cloud predefinito.	Il valore predefinito è https://api.arubacloud.com. Modificalo solo se devi puntare a un ambiente diverso.
WithDefaultBaseURL()	Helper che imposta l'URL API al valore predefinito di produzione.	Chiamato da DefaultOptions().

Autenticazione

L'autenticazione è una parte critica della configurazione. È necessario scegliere uno dei seguenti metodi.

Setter Opzione	Descrizione	Note
WithDefaultTokenManagerSchema(clientID, clientSecret)	Configura l'autenticazione Client Credentials standard con l'URL del token issuer predefinito e senza caching persistente. Chiamato internamente da DefaultOptions().	Da usare quando si vuole ripristinare il token manager alle impostazioni di fabbrica prima di applicare sovrascritture selettive.
WithClientCredentials(clientID, clientSecret)	(Consigliato) Configura l'SDK per utilizzare il flusso OAuth2 Client Credentials. L'SDK gestirà automaticamente il recupero e il rinnovo del token di accesso.	Esclusione reciproca: non può essere usato con WithToken() o WithVaultCredentialsRepository(). È il metodo standard e più sicuro per l'autenticazione service-to-service.
WithToken(token)	Configura l'SDK per utilizzare un token di accesso OAuth2 statico preesistente.	Esclusione reciproca: non può essere usato con nessun'altra opzione di autenticazione o token issuer. Avviso: L'SDK non rinnoverà questo token. Una volta scaduto, tutte le chiamate API falliranno. Questo metodo è consigliato solo per client di breve durata o script semplici e atomici.
WithVaultCredentialsRepository(...)	Configura l'SDK per recuperare clientID e clientSecret da un'istanza HashiCorp Vault. L'SDK utilizzerà poi queste credenziali per gestire il token di accesso.	Esclusione reciproca: non può essere usato con WithClientCredentials() o WithToken(). Parametri: vaultURI, kvMount, kvPath, namespace, rolePath, roleID, secretID.
WithTokenIssuerURL(url)	Sovrascrive l'URL predefinito per l'endpoint del token OAuth2.	Il valore predefinito è https://mylogin.aruba.it/auth/realms/cmp-new-apikey/protocol/openid-connect/token. Modificalo solo se devi puntare a un endpoint di autenticazione diverso.
WithSecurityScopes(scopes ...)	Imposta gli scope di sicurezza da richiedere durante l'autenticazione.	Sostituisce qualsiasi scope precedentemente configurato.
WithAdditionalSecurityScopes(scopes ...)	Aggiunge scope di sicurezza supplementari all'elenco esistente.	Non sovrascrive gli scope già presenti.

Caching del Token (Opzionale)

Per migliorare le prestazioni e la resilienza, l'SDK può memorizzare nella cache il token di accesso su uno store esterno. È fortemente consigliato nelle applicazioni di produzione per evitare di richiedere un nuovo token a ogni avvio.

Setter Opzione	Descrizione	Note
WithRedisTokenRepositoryFromURI(redisURI)	Configura un'istanza Redis come cache persistente per il token di accesso, specificando l'URI completo.	Esclusione reciproca: non può essere usato con le opzioni WithFileTokenRepository.... Il formato URI è redis://<user>:<pass>@<host>:<port>/<db>.
WithRedisTokenRepositoryFromStandardURI()	Configura il caching Redis usando l'URI locale standard (redis://admin:admin@localhost:6379/0).	Scorciatoia per lo sviluppo locale. Non imposta il drift di scadenza; abbinare con WithStandardTokenExpirationDriftSeconds() o usare WithStandardRedisTokenRepository().
WithFileTokenRepositoryFromBaseDir(baseDir)	Configura una directory locale per memorizzare il token di accesso in un file JSON.	Esclusione reciproca: non può essere usato con le opzioni WithRedisTokenRepository.... Il processo SDK deve avere i permessi di lettura/scrittura sulla directory specificata.
WithFileTokenRepositoryFromStandardBaseDir()	Configura il caching su file in /tmp/sdk-go.	Scorciatoia per lo sviluppo locale. Non imposta il drift di scadenza; abbinare con WithStandardTokenExpirationDriftSeconds() o usare WithStandardFileTokenRepository().
WithTokenExpirationDriftSeconds(seconds)	Imposta un buffer di sicurezza (in secondi) per considerare un token scaduto prima che lo sia effettivamente.	Previene race condition in cui l'SDK usa un token che scade appena prima del completamento della richiesta API. Il valore predefinito è 300 secondi (5 minuti). Questa opzione non ha effetto se non è configurato un meccanismo di caching (Redis o File).
WithStandardTokenExpirationDriftSeconds()	Imposta il drift di scadenza a 300 secondi (5 minuti).	Equivalente a WithTokenExpirationDriftSeconds(300).
WithStandardRedisTokenRepository()	Helper che configura il caching Redis su localhost:6379 e imposta il drift di scadenza standard (300s).	Scorciatoia comoda per lo sviluppo locale.
WithStandardFileTokenRepository()	Helper che configura il caching su file in /tmp/sdk-go e imposta il drift di scadenza standard (300s).	Scorciatoia comoda per lo sviluppo locale.

Logging

Il logging è disabilitato per impostazione predefinita.

Setter Opzione	Descrizione	Note
WithDefaultLogger()	Ripristina il logger al valore predefinito dell'SDK (nessun log). Chiamato da DefaultOptions().	Da usare quando si vuole ripristinare esplicitamente il logging dopo aver configurato un logger personalizzato.
WithNoLogs()	Disabilita tutto il logging dell'SDK.	Questo è il comportamento predefinito.
WithNativeLogger()	Abilita il logger integrato dell'SDK, che utilizza il pacchetto standard log.	Utile per il debug di base.
WithLoggerType(loggerType)	Funzione più generale per impostare il tipo di logger.	loggerType può essere LoggerNoLog o LoggerNative.
WithCustomLogger(logger)	Inietta un logger personalizzato che rispetta l'interfaccia ports/logger.Logger.	Consente l'integrazione con il framework di logging dell'applicazione (ad esempio, Logrus, Zap). Impostando questo valore, il tipo di logger viene automaticamente impostato su loggerCustom.

Identità del Client HTTP

L'SDK imposta automaticamente un header User-Agent su ogni richiesta in uscita, in modo che i log di accesso API possano essere attribuiti alla versione dell'SDK. Per impostazione predefinita il valore dell'header è sdk-go@<version> (ad esempio sdk-go@1.0.0), derivato dalla costante aruba.Version definita in pkg/aruba/version.go.

Setter Opzione	Descrizione	Note
WithUserAgent(ua)	Sovrascrive il valore predefinito dell'header User-Agent inviato con ogni richiesta.	Da usare quando si costruisce uno strumento sopra l'SDK e si vuole che i log API mostrino l'identità del proprio strumento invece di (o in aggiunta a) la versione grezza dell'SDK. Esempio: WithUserAgent("acloud-cli@1.0.0").

Avanzato / Dipendenze Personalizzate

Queste opzioni sono destinate a casi d'uso avanzati in cui è necessario iniettare componenti personalizzati nel flusso di lavoro dell'SDK.

Setter Opzione	Descrizione	Note
WithCustomHTTPClient(client)	Inietta un *http.Client pre-configurato.	Utile per impostare timeout personalizzati, transport o altre configurazioni a livello HTTP.
WithCustomMiddleware(middleware)	Inietta un middleware personalizzato che rispetta l'interfaccia ports/interceptor.Interceptor.	Consente di aggiungere logica personalizzata (come logging o tracing di richiesta/risposta) nella catena di chiamate HTTP dell'SDK. Il middleware di autenticazione dell'SDK verrà automaticamente collegato alla fine della catena di middleware personalizzata.