Uso de variáveis de ambiente

É possível definir pares de chave-valor arbitrários para o Cloud Functions no momento da implantação. Esses pares são exibidos como variáveis de ambiente literais, acessíveis pelo seu código no ambiente de execução ou como informações de configuração do sistema buildpack. Eles são armazenados no back-end do Cloud Functions, estão vinculados a uma única função e existem dentro do mesmo ciclo de vida da função a que estão vinculados.

Como usar variáveis de ambiente de execução

As variáveis de ambiente de execução são pares de chave-valor implantados com uma função. Essas variáveis são definidas para o escopo da função, e não são visíveis para outras funções no projeto. É possível adicionar ou remover variáveis de ambiente de execução usando a ferramenta de linha de comando gcloud ou a IU do Console do Cloud.

Como definir variáveis de ambiente de execução

Use esses 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 sinalização --update-env-vars em gcloud) descrito na próxima seção.

gcloud

Para definir uma variável de ambiente de execução usando a ferramenta de linha de comando gcloud, use a sinalização --set-env-vars no momento da implantação:

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

Também é possível definir várias variáveis de ambiente de execução usando uma lista separada por vírgulas:

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

Para armazenar sua configuração em um arquivo (por exemplo, no controle de origem), use um arquivo YAML com a sinalização --env-vars-file:

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

em que o conteúdo do arquivo .env.yaml é:

 FOO: bar
 BAZ: boo

Nos exemplos acima, FLAGS... se refere a outras opções passadas durante a implantação da função. Para uma referência completa para o comando deploy, consulte gcloud functions deploy.

IU do Console do Cloud

É possível definir variáveis de ambiente de execução durante a criação da função no Console do Cloud:

  1. Abra a página Visão geral das funções no Console do Cloud:

    Acessar a página Visão geral do Cloud Functions.

  2. Clique em Criar função.

  3. Preencha os campos obrigatórios da função.

  4. Abra a seção Configurações de ambiente de execução, criação e conexões.

  5. Selecione a guia Ambiente de execução.

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

    Para instruções sobre como adicionar variáveis de ambiente a uma função existente, consulte Como atualizar variáveis de ambiente de execução.

Como atualizar variáveis de ambiente de execução

Também é possível atualizar as variáveis de ambiente de execução para as funções atuais. Essa é uma abordagem não destrutiva que altera ou adiciona variáveis de ambiente de execução, mas não as exclui.

gcloud

Para atualizar uma variável usando a ferramenta de linha de comando gcloud, use a sinalização --update-env-vars no momento da implantação:

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

Também é possível atualizar várias variáveis de ambiente de execução usando uma lista separada por vírgulas:

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

IU do Console do Cloud

Para atualizar variáveis de ambiente de execução usando o Console do Cloud:

  1. Abra a página Visão geral das funções no Console do Cloud:

    Acessar a página Visão geral do Cloud Functions.

  2. Clique em uma função existente para acessar a página de detalhes.

  3. Clique em Editar.

  4. Abra a seção Configurações de ambiente de execução, criação e conexões.

  5. Selecione a guia Ambiente de execução.

  6. Faça suas edições na seção Variáveis de ambiente de execução.

Como excluir variáveis de ambiente de execução

gcloud

Se você quiser remover seletivamente as variáveis de ambiente de execução, use a sinalização --remove-env-vars no momento da implantação:

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

Também é possível apagar todas as variáveis de ambiente de execução já definidas com a sinalização --clear-env-vars:

gcloud functions deploy FUNCTION_NAME --clear-env-vars

IU do Console do Cloud

Para excluir variáveis de ambiente de execução usando o Console do Cloud, siga estas etapas:

  1. Abra a página Visão geral das funções no Console do Cloud:

    Acessar a página Visão geral do Cloud Functions.

  2. Clique em uma função existente para acessar a página de detalhes.

  3. Clique em Editar.

  4. Abra a seção Configurações de ambiente de execução, criação e conexões.

  5. Selecione a guia Ambiente de execução.

  6. Na seção Variáveis de ambiente de execução, clique no ícone de lixeira ao lado do par de chave-valor para excluí-lo.

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

Esta seção lista as variáveis de ambiente de execução que são definidas automaticamente.

Node.js 8, Python 3.7 e Go 1.11

As seguintes variáveis do ambiente de execução são definidas automaticamente para os ambientes de execução Node.js 8, Python 3.7 e Go 1.11. Todos os outros ambientes de execução do Cloud Functions usam um conjunto mais limitado de variáveis de ambiente, conforme descrito na seção sobre ambientes de execução mais recentes.

Chave Descrição
ENTRY_POINT Reservado: a função a ser executada.
GCP_PROJECT Reservado: o ID do projeto atual no GCP.
GCLOUD_PROJECT Reservado: o ID do projeto atual no GCP (obsoleto).
GOOGLE_CLOUD_PROJECT Reservado: não definido, mas reservado para uso interno.
FUNCTION_TRIGGER_TYPE Reservado: o tipo de gatilho da função.
FUNCTION_NAME Reservado: o nome do recurso da função.
FUNCTION_MEMORY_MB Reservado: a memória máxima da função.
FUNCTION_TIMEOUT_SEC Reservado: o tempo limite de execução em segundos.
FUNCTION_IDENTITY Reservado: a identidade atual (conta de serviço) da função.
FUNCTION_REGION Reservado: a região da função (exemplo: us-central1).

Ambientes de execução mais recentes

Os ambientes de execução mais recentes definem automaticamente menos variáveis de ambiente do que as mais antigas. Todas as linguagens e ambientes de execução não mencionados na seção anterior usam esse conjunto mais limitado de variáveis de ambiente predefinidas.

Chave Descrição
FUNCTION_TARGET Reservado: a função a ser executada.
FUNCTION_SIGNATURE_TYPE Reservado: o tipo da função - http para funções HTTP e event para funções orientadas a eventos.
K_SERVICE Reservado: o nome do recurso da função.
K_REVISION Reservado: o identificador da versão da função.
PORT Reservado: a porta pela qual a função é invocada.
gcloud functions deploy envVarMemory \
--runtime nodejs10 \
--set-env-vars FUNCTION_MEMORY_MB=2Gi \
--memory 2Gi \
--trigger-http
gcloud functions deploy envVarMemory \
--runtime nodejs14 \
--set-env-vars NODE_OPTIONS="--max_old_space_size=8192" \
--memory 8Gi \
--trigger-http

Como configurar e recuperar variáveis de ambiente de execução: um exemplo

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

Node.js

gcloud functions deploy envVar \
--runtime nodejs14 \
--set-env-vars FOO=bar \
--trigger-http
É possível usar os seguintes valores para a sinalização --runtime para especificar sua versão preferida do Node.js:
  • nodejs16 (visualização)
  • nodejs14 (recomendado)
  • nodejs12
  • nodejs10

Python

gcloud functions deploy env_vars \
--runtime python39 \
--set-env-vars FOO=bar \
--trigger-http
É possível usar os seguintes valores da sinalização --runtime para especificar a versão preferencial do Python:
  • python39 (recomendado)
  • python38
  • python37

Go

gcloud functions deploy EnvVar \
--runtime go113 \
--set-env-vars FOO=bar \
--trigger-http
É possível usar os seguintes valores para a sinalização --runtime para especificar sua versão Go preferencial:
  • go116 (visualização)
  • go113 (recomendado)
  • go111

Java

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

C#

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

Ruby

gcloud functions deploy env_vars --runtime ruby27 \
--set-env-vars FOO=bar \
--trigger-http
Use os seguintes valores da sinalização --runtime para especificar a versão do Ruby que você quer usar:
  • ruby27 (recomendado)
  • ruby26

PHP

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

Acesse as variáveis de maneira programática no momento da execução:

Node.js

Em Node.js, use a propriedade process.env para acessar variáveis de ambiente de execução:

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

Python

No Python, use os.environ para acessar as variáveis de ambiente 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 acessar as variáveis de ambiente 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 acessar variáveis de ambiente 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#

No ambiente de execução, as variáveis de ambiente são acessíveis por meio da propriedade 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);
        }
    }
}

Ruby

No ambiente de execução, as variáveis de ambiente são acessíveis usando ENV em Ruby:

require "functions_framework"

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

PHP

No ambiente de execução, as variáveis de ambiente são acessíveis usando a função getenv do PHP:


use Psr\Http\Message\ServerRequestInterface;

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

Como usar variáveis de ambiente de build

Também é possível definir variáveis de ambiente de criação para ambientes de execução compatíveis com pacotes de criação.

Variáveis de ambiente de build são pares de chave-valor implantados com uma função que permite passar informações de configuração para pacotes de criação. Por exemplo, convém personalizar as opções do compilador. É possível adicionar ou remover essas variáveis de ambiente de build usando a ferramenta de linha de comando gcloud ou a IU do Console do Cloud.

Como definir variáveis de ambiente de build

Use esses 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 sinalização --update-build-env-vars em gcloud) descrito na próxima seção.

gcloud

Para definir uma variável usando a ferramenta de linha de comando gcloud, use a sinalização --set-build-env-vars no momento da implantação:

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

Também é possível definir várias variáveis de ambiente de build usando uma lista separada por vírgulas:

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

Para armazenar sua configuração em um arquivo (por exemplo, no controle de origem), use um arquivo YAML com a sinalização --build-env-vars-file:

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

em que o conteúdo do arquivo *.yaml é:

 FOO: bar
 BAZ: boo

Nos exemplos acima, FLAGS... se refere a outras opções passadas durante a implantação da função. Para uma referência completa para o comando deploy, consulte gcloud beta functions deploy.

IU do Console do Cloud

Também é possível definir variáveis de ambiente de build durante a criação da função no Console do Cloud:

  1. Abra a página Visão geral das funções no Console do Cloud:

    Acessar a página Visão geral do Cloud Functions.

  2. Clique em Criar função.

  3. Preencha os campos obrigatórios da função.

  4. Abra a seção Configurações de ambiente de execução, criação e conexões.

  5. Selecione a guia Criar.

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

Como atualizar variáveis de ambiente de build

Também é possível atualizar variáveis de ambiente de build para funções atuais. Essa é uma abordagem não destrutiva que altera ou adiciona variáveis de ambiente de build, mas não as exclui.

gcloud

Para definir uma variável usando a ferramenta de linha de comando gcloud, use a sinalização --update-build-env-vars no momento da implantação:

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

Também é possível atualizar várias variáveis de ambiente de build usando uma lista separada por vírgulas:

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

IU do Console do Cloud

Para atualizar variáveis de ambiente de build usando o Console do Cloud:

  1. Abra a página Visão geral das funções no Console do Cloud:

    Acessar a página Visão geral do Cloud Functions.

  2. Clique em uma função existente para acessar a página de detalhes.

  3. Clique em Editar.

  4. Abra a seção Configurações de ambiente de execução, criação e conexões.

  5. Selecione a guia Criar.

  6. Faça suas edições na seção Variáveis de ambiente de build.

Como excluir variáveis de ambiente de build

gcloud

Se você quiser remover seletivamente variáveis de ambiente de build, use a sinalização --remove-build-env-vars no momento da implantação:

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

Também é possível apagar todas as variáveis de ambiente de build definidas anteriormente com a sinalização --clear-build-env-vars:

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

IU do Console do Cloud

Para excluir variáveis de ambiente de build usando o Console do Cloud:

  1. Abra a página Visão geral das funções no Console do Cloud:

    Acessar a página Visão geral do Cloud Functions.

  2. Clique em uma função existente para acessar a página de detalhes.

  3. Clique em Editar.

  4. Abra a seção Configurações de ambiente de execução, criação e conexões.

  5. Selecione a guia Criar.

  6. Na seção Variáveis de ambiente de build, clique no ícone de lixeira ao lado do par de chave-valor para excluí-lo.

Ciclo de vida variável

Todas as variáveis de ambiente estão vinculadas a uma implementação de uma das Cloud Functions e só podem ser definidas ou alteradas com uma implantação. Se uma implantação falhar por algum motivo, todas as alterações feitas nas variáveis de ambiente não serão aplicadas. As mudanças na variável de ambiente precisam de uma implantação bem-sucedida.

Práticas recomendadas e variáveis de ambiente reservadas

Algumas outras variáveis de ambiente são definidas automaticamente, dependendo do ambiente de execução usado pela função. Eles são baseados no sistema operacional do ambiente de execução (por exemplo, DEBIAN_FRONTEND, SHLVL ou PATH) e no ambiente de execução da linguagem (por exemplo, NODE_ENV, VIRTUAL_ENV ou GOPATH).

Variáveis de ambiente fornecidas pelo ambiente (além das listadas em Variáveis de ambiente definidas automaticamente) podem ser alteradas em futuras versões do ambiente de execução. Como prática recomendada, recomendamos não depender de ou modificar variáveis de ambiente que você não tenha definido explicitamente.

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

Por fim, não é possível usar estas variáveis de ambiente:

Chave Descrição
Vazia ('') As chaves não podem ser uma string vazia.
= As chaves não podem conter o caractere "=".
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 de ambiente para uma função individual é limitado a 32 KiB. Porém, não há limites específicos sobre chaves ou valores individuais nessa capacidade geral.

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

Como gerenciar secrets

As variáveis de ambiente podem ser usadas na configuração da função, mas não são recomendadas como uma maneira de armazenar segredos, como credenciais de banco de dados ou chaves de API. Esses valores mais confidenciais precisam ser armazenados fora do código-fonte e das variáveis de ambiente externas. Alguns ambientes de execução ou o uso de alguns frameworks podem fazer com que o conteúdo de variáveis de ambiente seja enviado para registros, e armazenar credenciais confidenciais em arquivos YAML, scripts de implantação ou controle de origem não é recomendado.

Para armazenar segredos, recomendamos consultar as práticas recomendadas para gerenciamento de segredos. Não há integração específica do Cloud Functions com o Cloud KMS.

Portabilidade

É possível que as variáveis de ambiente que atualmente funcionam com o Cloud Function não funcionem com um ambiente de execução diferente, como em uma linguagem diferente ou com determinadas ferramentas ou bibliotecas. Também é possível que elas não sejam aceitos por uma plataforma diferente.

Evite esses problemas seguindo o padrão POSIX para variáveis de ambiente. Se você usar o Console do Cloud para editar variáveis, o Console do Cloud avisará sempre que você definir uma variável que possa ter problemas de portabilidade, mas não impedirá a implantação. Como regra geral, recomendamos que as chaves de variáveis de ambiente consistam somente em letras maiúsculas, dígitos e <underscore> (_), como definido no Conjunto de caracteres portáteis, e que elas não iniciem com um dígito.