Saltar al contenido principal

Usar variables de entorno

Objetivo​

Declarar un ajuste una sola vez en su solución (una dirección de API, un buzón, un interruptor de funcionalidad) y dejar que Desarrollo, Prueba y Producción le den cada uno su propio valor, sin editar la solución después de cada importación.

Por qué existe​

Una solución que se promueve de Desarrollo a Prueba y a Producción debe ser la misma solución. Y, sin embargo, parte de lo que hace tiene que variar según el entorno: el servicio al que llama, la dirección desde la que envía, si una funcionalidad está activada.

Sin variables de entorno solo hay dos maneras de expresarlo, y las dos son malas. Puede editar componentes después de cada importación, con lo que sus entornos divergen sin que se note, y la divergencia queda oculta. O puede fijar en el código el valor de Desarrollo y acordarse de cambiarlo, lo que funciona justo hasta el día en que nadie se acuerda.

Una variable de entorno divide el ajuste en dos:

  • La declaración: su nombre, tipo, descripción y valor predeterminado. Pertenece a la solución y viaja con ella.
  • El valor: la respuesta de este entorno. Pertenece al entorno y nunca sale de él. Exportar la solución no lo lleva, e importar la solución no lo sobrescribe.

Requisitos previos​

  • Ha iniciado sesión como creador, con una solución y un entorno seleccionados.

Pasos​

Declarar una variable (normalmente en Desarrollo)​

  1. Abra su solución y elija Variables de entorno en la navegación de la izquierda.
  2. Seleccione Nuevo.
  3. Escriba un nombre para mostrar (por ejemplo, Invoice API URL). El nombre lógico se rellena debajo con el prefijo de su editor aplicado: invoice_api_url pasa a ser par_invoice_api_url.
  4. Elija un tipo: Texto, Número, Booleano (true/false) o JSON. Cualquier valor que se establezca para la variable se comprueba con él, en el entorno en el que se escriba.
  5. Escriba una descripción. Aquí merece más esfuerzo que en la mayoría de las cosas que construye: quien establece el valor en Producción muchas veces no es usted, y un nombre a secas rara vez dice qué aspecto tiene un valor correcto.
  6. Si lo desea, escriba un valor predeterminado: el que se usa en cualquier entorno que no haya establecido ninguno. Déjelo vacío para algo que no tenga un valor predeterminado razonable (un secreto, una dirección propia de cada cliente), de modo que una variable sin establecer se vea claramente sin establecer en lugar de estar mal sin que se note.
  7. Seleccione Guardar.

Establecer el valor de este entorno (en cada entorno)​

  1. Abra Variables de entorno y seleccione la fila de la variable (o selecciónela y elija Establecer valor).
  2. Escriba el valor que debe usar este entorno y seleccione Guardar.
  3. Para volver al valor predeterminado declarado, vacíe el cuadro y guarde. Es una decisión, y es la única manera de volver atrás una vez establecido un valor.

La columna Valor efectivo le indica en cuál de tres estados está cada variable:

MuestraSignifica
un valoreste entorno lo estableció
un valor y después (se usa el predeterminado)aquí no se estableció nada; se aplica el valor predeterminado de la solución
Sin establecerninguna de las dos cosas: nada responde a esta variable aquí, y lo que la lea no encontrará nada

Sin establecer es el estado que hay que resolver antes de la puesta en producción.

Leer una variable desde un paso de complemento​

En un paso de complemento de BS Lang, getEnvironmentVariable("par_invoice_api_url") devuelve el valor efectivo del entorno en el que se produce la escritura. Eso es lo que permite que un mismo script sea correcto en todas partes: nombra el ajuste en lugar de la dirección.

Una variable sin establecer se lee como una cadena vacía, así que un script que necesite una debe decirlo en lugar de seguir adelante:

if (getEnvironmentVariable("par_invoice_api_url") == "") {
    throwValidationError("The invoice API URL is not configured in this environment.");
}

Un ajuste que falta es un error de configuración, no un valor: fallar de forma visible aquí es mucho más amable que fallar de forma confusa más adelante.

Qué ocurre entre bastidores​

La declaración es un componente de solución, como una tabla o un conjunto de opciones: se valida contra un esquema publicado, pertenece al espacio de nombres de su editor y viaja en el paquete de la solución. El valor se guarda asociado al entorno y nunca se escribe en un paquete.

Al importar en otro entorno:

  • una variable que llega por primera vez se crea con su valor predeterminado declarado y sin valor;
  • en una variable que ya existe se actualiza su declaración (una etiqueta con otro nombre, un valor predeterminado cambiado, una descripción corregida) y su valor se deja exactamente como lo estableció ese entorno.

Esa segunda regla es la razón de ser de toda la funcionalidad. Promover una solución a Producción nunca debe hacer que Producción apunte sin avisar al punto de conexión de Desarrollo.

Desinstalar la solución quita sus variables, valores incluidos: en ese momento ya no queda nada que configurar.

Solución de problemas​

  • «'…' no es un valor de tipo Número válido». (o Booleano/JSON) El valor no coincide con el tipo declarado. Se comprueba donde lo escribe, a propósito, y no donde se lea más tarde: un script que lo descubriera fallaría lejos del error, y probablemente en Producción.
  • Cambié el tipo y mi valor desapareció. El valor ya no encajaba en el tipo nuevo, así que se borró en lugar de conservarse como algo que nada puede leer. La variable vuelve a su valor predeterminado y se muestra sin establecer, lo cual se ve. Vuelva a establecerlo.
  • Importé la solución y Producción sigue mostrando el valor anterior. Es el comportamiento previsto: una importación nunca sobrescribe el valor propio de un entorno. Cámbielo en el panel lateral Establecer valor de Producción.
  • Mi valor predeterminado llegó a Producción, pero mi valor de Desarrollo no. También es lo previsto. El valor predeterminado forma parte de la declaración y viaja; el valor es del entorno y no viaja.
  • Un script lee una cadena vacía. La variable está declarada pero sin establecer en este entorno, o el nombre está mal escrito. Compruebe la columna Valor efectivo: Sin establecer distingue el primer caso de una errata, que no aparecerá en la lista.
  • «Ya existe una variable de entorno llamada … en este entorno». Los nombres lógicos son únicos dentro de un entorno. Elija otro o edite la existente.

Escenarios relacionados​