Configure variáveis de ambiente (1.ª geração)

Pode implementar pares de chave/valor arbitrários juntamente com uma função do Cloud Run. Estes pares são disponibilizados à sua função como variáveis de ambiente literais, acessíveis pelo seu código no tempo de execução, ou como informações de configuração para os buildpacks do Google Cloud.

As variáveis de ambiente estão associadas a uma única função e não estão visíveis para outras funções no seu projeto. Google Cloud Cada variável é armazenada no back-end das funções do Cloud Run e existe no mesmo ciclo de vida que a função à qual estão associadas.

Pode adicionar ou remover variáveis de ambiente de tempo de execução através da CLI gcloud ou da Google Cloud consola.

Definir variáveis de ambiente de tempo de execução

Use estes métodos para estabelecer novas variáveis ou substituir completamente as variáveis existentes. Para fazer alterações aditivas, use o processo de atualização descrito na secção seguinte.

gcloud

Para definir uma variável de ambiente de tempo de execução através da Google Cloud CLI, use a flag --set-env-vars no momento da implementação:

gcloud functions deploy --no-gen2 FUNCTION_NAME --set-env-vars FOO=bar FLAGS ...

Também pode definir várias variáveis de ambiente de tempo de execução através de uma lista separada por vírgulas:

gcloud functions deploy --no-gen2 FUNCTION_NAME --set-env-vars FOO=bar,BAZ=boo FLAGS...

Se quiser armazenar a sua configuração num ficheiro (por exemplo, sob controlo de origem), pode usar um ficheiro YAML juntamente com a flag --env-vars-file:

gcloud functions deploy --no-gen2 FUNCTION_NAME --env-vars-file .env.yaml FLAGS...

Onde se encontra o conteúdo do ficheiro .env.yaml:

 FOO: bar
 BAZ: boo

Nos exemplos acima, FLAGS... refere-se a outras opções que transmite durante a implementação da sua função. Para uma referência completa do comando deploy, consulte gcloud functions deploy.

Google Cloud IU da consola

Pode definir variáveis de ambiente de tempo de execução durante a criação da função na Google Cloud consola:

  1. Abra a página Vista geral das funções na Google Cloud consola:

    Aceda à página Vista geral das funções do Cloud Run.

  2. Clique em Criar função.

  3. Preencha os campos obrigatórios para a sua função.

  4. Abra a secção Definições de tempo de execução, compilação e ligações.

  5. Selecione o separador Tempo de execução.

  6. Na secção Variáveis de ambiente de tempo de execução, clique em Adicionar variável e adicione o nome e o valor.

    Para ver instruções sobre como adicionar variáveis de ambiente a uma função existente, consulte o artigo Atualizar variáveis de ambiente de tempo de execução.

Atualizar variáveis de ambiente de tempo de execução

Também pode atualizar as variáveis de ambiente de tempo de execução para funções existentes. Esta é uma abordagem não destrutiva que altera ou adiciona variáveis do ambiente de tempo de execução, mas não elimina.

gcloud

Para atualizar uma variável através da Google Cloud CLI, use a flag --update-env-vars no momento da implementação:

gcloud functions deploy FUNCTION_NAME --no-gen2 --update-env-vars FOO=bar

Também pode atualizar várias variáveis de ambiente de tempo de execução através de uma lista separada por vírgulas:

gcloud functions deploy FUNCTION_NAME --no-gen2 --update-env-vars FOO=bar,BAZ=boo

Google Cloud IU da consola

Para atualizar as variáveis de ambiente de tempo de execução através da Google Cloud consola:

  1. Abra a página Vista geral das funções na Google Cloud consola:

    Aceda à página Vista geral das funções do Cloud Run.

  2. Clique numa função existente para aceder à respetiva página de detalhes.

  3. Clique em Edit.

  4. Abra a secção Definições de tempo de execução, compilação e ligações.

  5. Selecione o separador Tempo de execução.

  6. Faça as edições na secção Variáveis de ambiente de tempo de execução.

Eliminar variáveis de ambiente de tempo de execução

gcloud

Se quiser remover seletivamente variáveis de ambiente de tempo de execução, pode usar a flag --remove-env-vars no momento da implementação:

gcloud functions deploy FUNCTION_NAME --no-gen2 --remove-env-vars FOO,BAZ

Em alternativa, pode limpar todas as variáveis do ambiente de tempo de execução definidas anteriormente com a flag --clear-env-vars:

gcloud functions deploy FUNCTION_NAME --no-gen2 --clear-env-vars

Google Cloud IU da consola

Para eliminar variáveis de ambiente de tempo de execução através da Google Cloud consola:

  1. Abra a página Vista geral das funções na Google Cloud consola:

    Aceda à página Vista geral das funções do Cloud Run.

  2. Clique numa função existente para aceder à respetiva página de detalhes.

  3. Clique em Edit.

  4. Abra a secção Definições de tempo de execução, compilação e ligações.

  5. Selecione o separador Tempo de execução.

  6. Na secção Variáveis do ambiente de tempo de execução, clique no ícone de lixo junto ao par chave/valor para o eliminar.

Variáveis de ambiente do tempo de execução definidas automaticamente

Esta secção apresenta as variáveis de ambiente de tempo de execução que são definidas automaticamente.

Chave Descrição
FUNCTION_TARGET Reservado: a função a executar.
FUNCTION_SIGNATURE_TYPE Reservado: o tipo da função: http para funções HTTP e event para funções orientadas por eventos.
K_SERVICE Reservado: o nome do recurso de função.
K_REVISION Reservado: o identificador da versão da função.
PORT Reservado: a porta através da qual a função é invocada. 
gcloud functions deploy envVarMemory \
--no-gen2 \
--runtime nodejs10 \
--set-env-vars FUNCTION_MEMORY_MB=2Gi \
--memory 2Gi \
--trigger-http

Definir e obter variáveis de ambiente de tempo de execução: um exemplo

Defina a variável de ambiente de tempo de execução:

Node.js 

gcloud functions deploy envVar \
--runtime nodejs20 \
--set-env-vars FOO=bar \
--trigger-http

Use a flag --runtime para especificar o ID de tempo de execução de uma versão suportada do Node.js para executar a sua função.

Python 

gcloud functions deploy env_vars \
--runtime python312 \
--set-env-vars FOO=bar \
--trigger-http

Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Python suportada para executar a sua função.

Go 

gcloud functions deploy EnvVar \
--runtime go121 \
--set-env-vars FOO=bar \
--trigger-http

Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Go suportada para executar a sua função.

Java 

gcloud functions deploy java-envVar-function \
--entry-point functions.EnvVars \
--runtime java17 \
--memory 512MB \
--set-env-vars FOO=bar \
--trigger-http

Use a flag --runtime para especificar o ID de tempo de execução de uma versão Java suportada para executar a sua função.

C# 

gcloud functions deploy csharp-envVar-function \
--entry-point EnvironmentVariables.Function \
--runtime dotnet6 \
--set-env-vars FOO=bar \
--trigger-http

Use a flag --runtime para especificar o ID de tempo de execução de uma versão .NET suportada para executar a sua função.

Ruby 

gcloud functions deploy env_vars --runtime ruby33 \
--set-env-vars FOO=bar \
--trigger-http

Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Ruby suportada para executar a sua função.

PHP 

 gcloud functions deploy envVar --runtime php82 \
--set-env-vars FOO=bar \
--trigger-http

Use a flag --runtime para especificar o ID de tempo de execução de uma versão do PHP suportada para executar a sua função.

Em tempo de execução, aceda às variáveis de forma programática:

Node.js

No Node.js, use a propriedade process.env para aceder às variáveis do ambiente de tempo de execução:

exports.envVar = (req, res) => {
  // Sends 'bar' as response
  res.send(process.env.FOO);
};

Python

Em Python, use os.environ para aceder às variáveis de ambiente de tempo de execução:

import os


def env_vars(request):
    return os.environ.get("FOO", "Specified environment variable is not set.")

Go

Em Go, use os.Getenv() para aceder às variáveis de ambiente do tempo de execução:


// Package tips contains tips for writing Cloud Functions in Go.
package tips

import (
	"fmt"
	"net/http"
	"os"
)

// EnvVar is an example of getting an environment variable in a Go function.
func EnvVar(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "FOO: %q", os.Getenv("FOO"))
}

Java

Em Java, use System.getenv para aceder às variáveis do ambiente de tempo de execução:


import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.BufferedWriter;
import java.io.IOException;

public class EnvVars implements HttpFunction {

  // Returns the environment variable "foo" set during function deployment.
  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    BufferedWriter writer = response.getWriter();
    String foo = System.getenv("FOO");
    if (foo == null) {
      foo = "Specified environment variable is not set.";
    }
    writer.write(foo);
  }
}

C#

Em tempo de execução, as variáveis de ambiente são acessíveis através de Environment.GetEnvironmentVariable em C#:

using Google.Cloud.Functions.Framework;
using Microsoft.AspNetCore.Http;
using System;
using System.Threading.Tasks;

namespace EnvironmentVariables;

public class Function : IHttpFunction
{
    public async Task HandleAsync(HttpContext context)
    {
        string foo = Environment.GetEnvironmentVariable("FOO")
            ?? "Specified environment variable is not set.";
        await context.Response.WriteAsync(foo, context.RequestAborted);
    }
}

Ruby

Em tempo de execução, as variáveis de ambiente são acessíveis através de ENV no Ruby:

require "functions_framework"

FunctionsFramework.http "env_vars" do |_request|
  ENV["FOO"] || "Specified environment variable is not set."
end

PHP

Em tempo de execução, as variáveis de ambiente são acessíveis através da função getenv do PHP:

use Psr\Http\Message\ServerRequestInterface;

function envVar(ServerRequestInterface $request): string
{
    return getenv('FOO') . PHP_EOL;
}

Usar variáveis de ambiente de compilação

Também pode definir variáveis de ambiente de compilação para tempos de execução que suportam buildpacks.

As variáveis de ambiente de compilação são pares de chave/valor implementados juntamente com uma função que lhe permitem transmitir informações de configuração para os buildpacks. Por exemplo, pode querer personalizar as opções do compilador. Pode adicionar ou remover estas variáveis de ambiente de compilação através da CLI Google Cloud ou da IU da consola Google Cloud .

Definir variáveis do ambiente de compilação

Use estes métodos para estabelecer novas variáveis ou substituir completamente as variáveis existentes. Para fazer alterações aditivas, use o processo de atualização (a flag --update-build-env-vars em gcloud) descrito na secção seguinte.

gcloud

Para definir uma variável através da Google Cloud CLI, use a flag --set-build-env-vars no momento da implementação:

gcloud beta functions deploy FUNCTION_NAME --no-gen2 --set-build-env-vars FOO=bar FLAGS...

Também pode definir várias variáveis do ambiente de compilação através de uma lista separada por vírgulas:

gcloud functions deploy FUNCTION_NAME --no-gen2 --set-build-env-vars FOO=bar,BAZ=boo FLAGS...

Se quiser armazenar a sua configuração num ficheiro (por exemplo, sob controlo de origem), pode usar um ficheiro YAML juntamente com a flag --build-env-vars-file:

gcloud functions deploy FUNCTION_NAME --no-gen2 --build-env-vars-file FILE_NAME.yaml FLAGS...

Onde se encontra o conteúdo do ficheiro *.yaml:

 FOO: bar
 BAZ: boo

Nos exemplos acima, FLAGS... refere-se a outras opções que transmite durante a implementação da sua função. Para uma referência completa do comando deploy, consulte gcloud beta functions deploy.

Google Cloud IU da consola

Também pode definir variáveis de ambiente de compilação durante a criação da função na Google Cloud consola:

  1. Abra a página Vista geral das funções na Google Cloud consola:

    Aceda à página Vista geral das funções do Cloud Run.

  2. Clique em Criar função.

  3. Preencha os campos obrigatórios para a sua função.

  4. Abra a secção Definições de tempo de execução, compilação e ligações.

  5. Selecione o separador Criar.

  6. Na secção Crie variáveis de ambiente, clique em Adicionar variável e adicione o nome e o valor.

Atualizar variáveis de ambiente de compilação

Também pode atualizar as variáveis do ambiente de compilação para funções existentes. Esta é uma abordagem não destrutiva que altera ou adiciona variáveis do ambiente de compilação, mas não elimina.

gcloud

Para definir uma variável através da Google Cloud CLI, use a flag --update-build-env-vars no momento da implementação:

gcloud functions deploy FUNCTION_NAME --no-gen2 --update-build-env-vars FOO=bar

Também pode atualizar várias variáveis do ambiente de compilação através de uma lista separada por vírgulas:

gcloud functions deploy FUNCTION_NAME --no-gen2 --update-build-env-vars FOO=bar,BAZ=boo

Google Cloud IU da consola

Para atualizar as variáveis do ambiente de compilação através da Google Cloud consola:

  1. Abra a página Vista geral das funções na Google Cloud consola:

    Aceda à página Vista geral das funções do Cloud Run.

  2. Clique numa função existente para aceder à respetiva página de detalhes.

  3. Clique em Edit.

  4. Abra a secção Definições de tempo de execução, compilação e ligações.

  5. Selecione o separador Criar.

  6. Faça as edições na secção Criar variáveis de ambiente.

Eliminar variáveis de ambiente de compilação

gcloud

Se quiser remover seletivamente variáveis do ambiente de compilação, pode usar a flag --remove-build-env-vars no momento da implementação:

gcloud functions deploy FUNCTION_NAME --no-gen2 --remove-build-env-vars FOO,BAZ

Em alternativa, pode limpar todas as variáveis de ambiente de compilação definidas anteriormente com a flag --clear-build-env-vars:

gcloud functions deploy FUNCTION_NAME --no-gen2 --clear-build-env-vars

Google Cloud IU da consola

Para eliminar variáveis do ambiente de compilação através da Google Cloud consola:

  1. Abra a página Vista geral das funções na Google Cloud consola:

    Aceda à página Vista geral das funções do Cloud Run.

  2. Clique numa função existente para aceder à respetiva página de detalhes.

  3. Clique em Edit.

  4. Abra a secção Definições de tempo de execução, compilação e ligações.

  5. Selecione o separador Criar.

  6. Na secção Criar variáveis de ambiente, clique no ícone do lixo junto ao par chave/valor para o eliminar.

Ciclo de vida das variáveis

Todas as variáveis de ambiente estão associadas a uma implementação de uma função do Cloud Run e só podem ser definidas ou alteradas com uma implementação. Se uma implementação falhar por qualquer motivo, não são aplicadas alterações às variáveis de ambiente. As alterações às variáveis de ambiente requerem uma implementação bem-sucedida.

Práticas recomendadas e variáveis de ambiente reservadas

Algumas variáveis de ambiente adicionais são definidas automaticamente consoante o tempo de execução usado pela sua função. Estes baseiam-se no sistema operativo do tempo de execução (por exemplo, DEBIAN_FRONTEND, SHLVL ou PATH) e no tempo de execução da linguagem (por exemplo, NODE_ENV, VIRTUAL_ENV ou GOPATH).

As variáveis de ambiente fornecidas pelo ambiente (exceto as indicadas em Variáveis de ambiente definidas automaticamente) podem mudar em versões de tempo de execução futuras. Como prática recomendada, sugerimos que não dependa nem modifique variáveis de ambiente que não tenha definido explicitamente.

A modificação de variáveis de ambiente fornecidas pelo ambiente pode levar a resultados imprevisíveis. As tentativas de modificar essas variáveis de ambiente podem ser bloqueadas ou, pior, levar a consequências não intencionais, como funções que não podem ser iniciadas. Como prática recomendada, considere prefixar quaisquer variáveis de ambiente com uma chave única para evitar conflitos.

Por último, não pode usar as seguintes variáveis de ambiente:

Chave Descrição
Vazio ('') As chaves não podem ser uma string vazia.
= As chaves não podem conter o caráter "=".
X_GOOGLE_ As chaves não podem conter o prefixo X_GOOGLE_.

Limites de tamanho

O número total de bytes usados pelos nomes e valores das variáveis do ambiente de tempo de execução para uma função individual está limitado a 32 KiB. Não existem limites específicos para chaves ou valores individuais dentro desta capacidade geral.

Para variáveis de ambiente de compilação, podem ser definidas até 100 variáveis, com a string de definição foo=bar limitada a 64 KiB.

Gerir segredos

As variáveis de ambiente podem ser usadas para a configuração de funções, mas não são recomendadas como forma de armazenar segredos, como credenciais de bases de dados ou chaves de API. Estes valores mais confidenciais devem ser armazenados fora do código fonte e das variáveis de ambiente. Alguns ambientes de execução ou a utilização de alguns frameworks podem resultar no envio do conteúdo das variáveis de ambiente para registos. Além disso, não é recomendado armazenar credenciais confidenciais em ficheiros YAML, scripts de implementação ou sob controlo de origem.

Para armazenar segredos, recomendamos que use o Secret Manager. Para configurar funções do Cloud Run para aceder a segredos armazenados no Secret Manager, consulte o artigo Configure segredos. Tenha em atenção que não existe uma integração específica das funções do Cloud Run com o Cloud KMS.

Portabilidade

É possível que as variáveis de ambiente que funcionam atualmente com a sua função do Cloud Run não funcionem com um ambiente de tempo de execução diferente, como num idioma diferente ou com determinadas ferramentas ou bibliotecas. Também é possível que não sejam aceites por uma plataforma diferente.

Pode evitar estes problemas seguindo a norma POSIX para variáveis de ambiente. Se usar a Google Cloud consola para editar variáveis, Google Cloud a consola avisa sempre que define uma variável que possa ter problemas de portabilidade (mas não impede a implementação). Como regra geral, recomendamos que as chaves das variáveis de ambiente sejam compostas apenas por letras maiúsculas, dígitos e <underscore> (_), conforme definido no conjunto de carateres portátil, e que não comecem por um dígito.