Variabili di ambiente

Le variabili di ambiente consentono di aggiungere variabili a un processo di applicazione in esecuzione in un ambiente senza dover modificare il codice. Le variabili di ambiente vengono archiviate in maniera sicura e il loro utilizzo è ideale nei seguenti casi:

• Chiavi API per integrazioni di terze parti
• Flag di funzionalità per logica di applicazione
• Configurazione che differisce da un ambiente all'altro o che potrebbe non essere segreta

Seguire questi tutorial per impostare le variabili di ambiente, quindi implementare il codice nel sito PWA Kit per usare le variabili in questione. È possibile personalizzare il codice in base alle proprie esigenze specifiche. I tutorial illustrano quanto segue:

• Accesso alle risorse protette con le variabili di ambiente
• Uso delle variabili di ambiente in React.js

È consigliabile testare i passaggi nel computer locale, quindi in un ambiente non di produzione prima di distribuire le modifiche nell'ambiente Production. Per ulteriori indicazioni, vedere Best practive, Risoluzione dei problemi relativi alle variabili di ambiente e Debug locale.

Variabili di ambiente:

• Possono essere gestite utilizzando Managed Runtime API o Runtime Admin
• È possibile accedervi in Node.js utilizzando process.env

Quando si introduce una nuova variabile di ambiente, impostarla prima tramite API o Runtime Admin. Attendere il completamento della ridistribuzione, quindi distribuire un nuovo bundle che la utilizza.

Per impostare le variabili di ambiente, aggiornarle o annullarne l'impostazione

Utilizzare projects_target_env_var_partial_update:

Per annullare l'impostazione di una variabile di ambiente esistente, impostarne il valore su null.

La modifica delle variabili di ambiente comporta la ridistribuzione dell'ambiente. I valori aggiornati sono disponibili al termine della distribuzione.

Per ottenere tutte le variabili d'ambiente

Utilizzare projects_target_env_var_list:

Per creare, aggiornare, rimuovere o visualizzare le variabili di ambiente:

1. Accedere a Runtime Admin. Per ottenere l'accesso a Runtime Admin, vedere Amministrazione in Managed Runtime.
2. Passare alla pagina Overview (Panoramica) di un progetto.
3. Fare clic sul nome dell'ambiente per il quale si desidera gestire le variabili di ambiente.
4. Fare clic su Environment Variables (Variabili di ambiente) nel riquadro di navigazione a sinistra.

• Scegliere i nomi delle variabili di ambiente più appropriati per la propria app. Usare nomi descrittivi: Scegliere nomi chiari e concisi per le variabili di ambiente per renderle facilmente comprensibili per il proprio team.
• Evitare l'hardcoding nel codice di informazioni sensibili come le chiavi API. Utilizzare le variabili di ambiente per mantenerle al sicuro.
• Non passare le variabili di ambiente ai dati che verranno serializzati sulla pagina. Considerare la possibilità di aggiungere un test per assicurarsi di non perdere i dati delle variabili di ambiente.
• Non restituire variabili di ambiente da getProps o hook react-query.
• Utilizzare le variabili di ambiente solo sul lato server. Per impostazione predefinita, le variabili di ambiente non sono esposte al lato client. È possibile scegliere di esporle al lato client (ad esempio, nel file di configurazione), ma assicurarsi che l'esposizione dei valori sia conforme alle proprie procedure di sicurezza.
• Testare le variabili di ambiente sul computer locale, quindi in un ambiente non di produzione prima di distribuirle nell'ambiente Production. In questo modo è possibile risolvere rapidamente i problemi in locale, quindi simulare il comportamento del sito, convalidare la funzionalità ed eseguire eventuali test di accettazione dell'utente prima della distribuzione in Production.
• Includere nel codice la gestione degli errori che utilizza variabili di ambiente per evitare errori dovuti a variabili di ambiente non definite.
• Controllare l'accesso alle variabili di ambiente per impedire modifiche non autorizzate.
• Documentare lo scopo e la configurazione di ogni variabile di ambiente. Questo aiuta a eseguire l'onboarding di nuovi sviluppatori e a risolvere i problemi.

L'utilizzo delle variabili di ambiente è soggetto ai seguenti vincoli:

• I valori delle variabili di ambiente devono essere stringhe. Per memorizzare valori complessi, codificare JSON in una stringa.
• Ogni ambiente ha un limite di 100 variabili.
• La dimensione massima dei valori delle variabili di ambiente impostate per un ambiente è 32 KB.
• I nomi delle variabili di ambiente devono contenere al massimo 512 caratteri e non possono iniziare con prefissi riservati: AWS, MRT, X_MRT, MOBIFY, X_MOBIFY, SSR_PROXY, NODE.
• Le variabili di ambiente non possono utilizzare nomi riservati: BUNDLE_ID, DEPLOY_ID, DEPLOY_TARGET, EXTERNAL_DOMAIN_NAME, HANDLER, LAMBDA_RUNTIME_DIR, LAMBDA_TASK_ROOT, NODE_ENV, REDIRECT_BUCKET, REDIRECT_KEY, REDIRECT_UPDATE, REMOTE, X_AMZN_TRACE_ID.

In questa sezione vengono suggerite soluzioni per gli errori comuni che potrebbero verificarsi con l'utilizzo delle variabili di ambiente.

Il codice genera un Error che indica la mancanza di una variabile.

Causa: La variabile di ambiente richiamata dal codice non è impostata.

Soluzione suggerita: Richiamare l'endpoint API projects_target_env_var_partial_update per impostare la variabile di ambiente applicabile.

Il codice registra un messaggio di errore che indica che la variabile di ambiente non è stata trovata.

Causa: Il codice non è riuscito a trovare la variabile di ambiente perché si è verificato un errore di battitura nel codice o è stato utilizzato un nome di variabile di ambiente errato.

Soluzione suggerita: Verificare di aver digitato correttamente il nome della variabile di ambiente nel codice e di aver utilizzato il nome della variabile di ambiente desiderato. Controllare il nome della variabile di ambiente richiamando l'endpoint API projects_target_env_var_list per visualizzare l'elenco completo delle variabili impostate.

La chiamata API per impostare una variabile di ambiente ha esito negativo.

Causa: Il nome della variabile di ambiente potrebbe non soddisfare i vincoli. Ad esempio, la dimensione del valore di una variabile di ambiente è superiore a 32 KB.

Soluzione suggerita: Verificare che la variabile di ambiente sia conforme ai vincoli.

Gli errori di autenticazione si verificano quando si esegue un codice che prevede l'utilizzo di una chiave API.

Causa: La chiave API utilizzata per impostare la variabile di ambiente non è nel formato previsto o è mancante.

Soluzione suggerita: Verificare che la chiave API memorizzata da una variabile di ambiente sia corretta. Se necessario, chiamare l'endpoint API projects_target_env_var_partial_update per correggere la chiave API.

Una richiesta fetch ha esito negativo e viene visualizzato un errore di rete.

Causa: Un URL di endpoint API richiamato nel codice potrebbe non essere stato definito correttamente o non è valido. Ad esempio, l'URL di un endpoint del sistema di gestione del contenuto (CMS) non è corretto.

Soluzione suggerita: Verificare che tutti gli URL di endpoint API nel codice siano corretti.