İşlevleriniz için genellikle üçüncü taraf API anahtarları veya ayarlanabilir ayarlar gibi ek yapılandırmalar gerekir. Cloud Functions için Firebase SDK'sı, projeniz için bu tür verileri depolamayı ve almayı kolaylaştıran yerleşik ortam yapılandırması sunar.
Aşağıdaki seçeneklerden birini belirleyebilirsiniz:
- Parametreli yapılandırma (çoğu senaryo için önerilir). Bu sayede, dağıtım sırasında doğrulanan parametrelerle kesin olarak yazılmış ortam yapılandırması sağlanır. Bu da hataları önler ve hata ayıklamayı kolaylaştırır.
- Ortam değişkenlerinin dosya tabanlı yapılandırması. Bu yaklaşımda, ortam değişkenlerini yüklemek için manuel olarak bir dotenv dosyası oluşturursunuz.
Çoğu kullanım alanında parametreleştirilmiş yapılandırma önerilir. Bu yaklaşım, yapılandırma değerlerini hem çalışma zamanında hem de dağıtım zamanında kullanılabilir hale getirir ve tüm parametreler geçerli bir değere sahip olmadığı sürece dağıtım engellenir. Buna karşılık, ortam değişkenleriyle yapılandırma, dağıtım sırasında kullanılamaz.
Parametreli yapılandırma
Cloud Functions for Firebase, kod tabanınızda yapılandırma parametrelerini bildirimli olarak tanımlamak için bir arayüz sağlar. Bu parametrelerin değeri, hem işlev dağıtımı sırasında (dağıtım ve çalışma zamanı seçenekleri ayarlanırken) hem de yürütme sırasında kullanılabilir. Bu, tüm parametreler geçerli bir değere sahip olmadığı sürece CLI'nın dağıtımı engelleyeceği anlamına gelir.
Kodunuzda parametreleri tanımlamak için şu modeli uygulayın:
const functions = require('firebase-functions/v1');
const { defineInt, defineString } = require('firebase-functions/params');
// Define some parameters
const minInstancesConfig = defineInt('HELLO_WORLD_MININSTANCES');
const welcomeMessage = defineString('WELCOME_MESSAGE');
// To use configured parameters inside the config for a function, provide them
// directly. To use them at runtime, call .value() on them.
export const helloWorld = functions.runWith({ minInstances: minInstancesConfig}).https.onRequest(
(req, res) => {
res.send(`${welcomeMessage.value()}! I am a function.`);
}
);
Parametreli yapılandırma değişkenleri içeren bir işlev dağıtılırken Firebase CLI, öncelikle bu değişkenlerin değerlerini yerel .env dosyalarından yüklemeye çalışır. Bu dosyalarda yoklarsa ve default ayarlanmamışsa CLI, dağıtım sırasında değerleri ister ve ardından değerlerini functions/ dizininizdeki .env.<project_ID> adlı bir .env dosyasına otomatik olarak kaydeder:
$ firebase deploy
i functions: preparing codebase default for deployment
? Enter a string value for ENVIRONMENT: prod
i functions: Writing new parameter values to disk: .env.projectId
…
$ firebase deploy
i functions: Loaded environment variables from .env.projectId
Geliştirme iş akışınıza bağlı olarak, oluşturulan .env.<project_ID> dosyasını sürüm denetimine eklemek faydalı olabilir.
Global kapsamda parametreleri kullanma
Dağıtım sırasında, işlev kodunuz yüklenir ve parametreleriniz gerçek değerlere sahip olmadan önce incelenir. Bu nedenle, global kapsam sırasında parametre değerlerinin alınması dağıtımın başarısız olmasına neden olur. Genel bir değeri başlatmak için parametre kullanmak istediğiniz durumlarda başlatma geri çağırma işlevini onInit() kullanın. Bu geri çağırma, üretimde herhangi bir işlev çalıştırılmadan önce çalışır ancak dağıtım sırasında çağrılmaz. Bu nedenle, bir parametrenin değerine erişmek için güvenli bir yerdir.
const { GoogleGenerativeAI } = require('@google/generative-ai');
const { defineSecret } = require('firebase-functions/params');
const { onInit } = require('firebase-functions/v1');
const apiKey = defineSecret('GOOGLE_API_KEY');
let genAI;
onInit(() => {
genAI = new GoogleGenerativeAI(apiKey.value());
})
CLI davranışını yapılandırma
Parametreler, KSA'nın değerleri nasıl isteyeceğini kontrol eden bir Options nesnesiyle yapılandırılabilir. Aşağıdaki örnekte, telefon numarasının biçimini doğrulamak, basit bir seçim seçeneği sunmak ve Firebase projesinden otomatik olarak bir seçim seçeneği doldurmak için seçenekler ayarlanmaktadır:
const { defineString } = require('firebase-functions/params');
const welcomeMessage = defineString('WELCOME_MESSAGE', {default: 'Hello World',
description: 'The greeting that is returned to the caller of this function'});
const onlyPhoneNumbers = defineString('PHONE_NUMBER', {input: {text:
{validationRegex: /\d{3}-\d{3}-\d{4}/, validationErrorMessage: "Please enter
a phone number in the format XXX-YYY-ZZZZ"}}});
const selectedOption = defineString('PARITY', {input: {select: {options:
[{value: "odd"}, {value: "even"}]}}})
const storageBucket = defineString('BUCKET', {input: {resource: {type:
"storage.googleapis.com/Bucket"}}, description: "This will automatically
populate the selector field with the deploying Cloud Project’s
storage buckets"})
Parametre türleri
Parametreli yapılandırma, parametre değerleri için güçlü yazma sağlar ve Cloud Secret Manager'daki gizli anahtarları da destekler. Desteklenen türler:
- Gizli Anahtar
- Dize
- Boole
- Tam sayı
- Kayan
Parametreleri tanımlama işlevleri hakkında bilgi edinmek için params ad alanı referansına bakın.
Parametre değerleri ve ifadeler
Firebase, parametrelerinizi hem dağıtım sırasında hem de işleviniz yürütülürken değerlendirir. Bu ikili ortamlar nedeniyle, parametre değerlerini karşılaştırırken ve işlevleriniz için çalışma zamanı seçeneklerini ayarlamak üzere bu değerleri kullanırken daha dikkatli olunmalıdır.
İşlevinize çalışma zamanı seçeneği olarak bir parametre iletmek için parametreyi doğrudan iletin:
const functions = require('firebase-functions/v1');
const { defineInt} = require('firebase-functions/params');
const minInstancesConfig = defineInt('HELLO_WORLD_MININSTANCES');
export const helloWorld = functions.runWith({ minInstances: minInstancesConfig}).https.onRequest(
(req, res) => {
//…
Ayrıca, hangi seçeneği belirleyeceğinizi öğrenmek için bir parametreyle karşılaştırma yapmanız gerekiyorsa değeri kontrol etmek yerine yerleşik karşılaştırıcıları kullanmanız gerekir:
const functions = require('firebase-functions/v1');
const { defineBool } = require('firebase-functions/params');
const environment = params.defineString(‘ENVIRONMENT’, {default: ‘dev’});
// use built-in comparators
const minInstancesConfig =environment.equals('PRODUCTION').thenElse(10, 1);
export const helloWorld = functions.runWith({ minInstances: minInstancesConfig}).https.onRequest(
(req, res) => {
//…
Yalnızca çalışma zamanında kullanılan parametrelere ve parametre ifadelerine value işleviyle erişilebilir:
const functions = require('firebase-functions/v1');
const { defineString } = require('firebase-functions/params');
const welcomeMessage = defineString('WELCOME_MESSAGE');
// To use configured parameters inside the config for a function, provide them
// directly. To use them at runtime, call .value() on them.
export const helloWorld = functions.https.onRequest(
(req, res) => {
res.send(`${welcomeMessage.value()}! I am a function.`);
}
);
Yerleşik parametreler
Cloud Functions SDK'sı, firebase-functions/params alt paketinde bulunan önceden tanımlanmış üç parametre sunar:
projectID: İşlevin çalıştığı Cloud projesi.databaseURL: İşlevle ilişkili Realtime Database örneğinin URL'si (Firebase projesinde etkinleştirilmişse).storageBucket: İşlevle ilişkili Cloud Storage paketi (Firebase projesinde etkinleştirilmişse).
Bunlar, her açıdan kullanıcı tanımlı dize parametreleri gibi çalışır. Ancak değerleri Firebase CLI tarafından her zaman bilindiğinden, dağıtım sırasında değerleri hiçbir zaman sorulmaz veya .env dosyalarına kaydedilmez.
Gizli parametreler
defineSecret() kullanılarak tanımlanan Secret türündeki parametreler, Cloud Secret Manager'da depolanan bir değere sahip dize
parametrelerini temsil eder. Gizli parametreler, yerel bir .env dosyasına göre kontrol yapıp eksikse dosyaya yeni bir değer yazmak yerine Cloud Secret Manager'da var olup olmadığını kontrol eder ve dağıtım sırasında yeni bir gizli anahtarın değerini etkileşimli olarak ister.
Bu şekilde tanımlanan gizli parametreler, bunlara erişmesi gereken ayrı işlevlere bağlanmalıdır:
const functions = require('firebase-functions/v1');
const { defineSecret } = require('firebase-functions/params');
const discordApiKey = defineSecret('DISCORD_API_KEY');
export const postToDiscord = functions.runWith({ secrets: [discordApiKey] }).https.onRequest(
(req, res) => {
const apiKey = discordApiKey.value();
//…
Ortam değişkenleri
Cloud Functions for Firebase, .env dosyasında belirtilen ortam değişkenlerini uygulama çalışma zamanınıza yüklemek için dotenv dosya biçimini destekler. Dağıtıldıktan sonra ortam değişkenleri process.env arayüzü üzerinden okunabilir.
Ortamınızı bu şekilde yapılandırmak için projenizde bir .env dosyası oluşturun, istediğiniz değişkenleri ekleyin ve dağıtın:
functions/dizininizde bir.envdosyası oluşturun:# Directory layout: # my-project/ # firebase.json # functions/ # .env # package.json # index.js.envdosyasını düzenlemek için açın ve istediğiniz anahtarları ekleyin. Örneğin:PLANET=Earth AUDIENCE=Humansİşlevleri dağıtın ve ortam değişkenlerinin yüklendiğini doğrulayın:
firebase deploy --only functions # ... # i functions: Loaded environment variables from .env. # ...
Özel ortam değişkenleriniz dağıtıldıktan sonra işlev kodunuz, process.env söz dizimiyle bunlara erişebilir:
// Responds with "Hello Earth and Humans"
exports.hello = functions.https.onRequest((request, response) => {
response.send(`Hello ${process.env.PLANET} and ${process.env.AUDIENCE}`);
});
Birden fazla ortam değişkeni grubu dağıtma
Firebase projeleriniz için alternatif bir ortam değişkeni grubuna (ör. hazırlık ve üretim) ihtiyacınız varsa .env.<project or
alias> dosyası oluşturun ve projeye özgü ortam değişkenlerinizi bu dosyaya yazın. .env ve projeye özel .env dosyalarındaki (varsa) ortam değişkenleri, dağıtılan tüm işlevlere dahil edilir.
Örneğin, bir projede geliştirme ve üretim için biraz farklı değerler içeren şu üç dosya bulunabilir:
.env
|
.env.dev
|
.env.prod
|
| PLANET=Earth
AUDIENCE=Humans |
AUDIENCE=Dev Humans | AUDIENCE=Prod Humans |
Bu ayrı dosyalardaki değerler göz önüne alındığında, işlevlerinizle dağıtılan ortam değişkenleri grubu hedef projenize bağlı olarak değişir:
$ firebase use dev
$ firebase deploy --only functions
i functions: Loaded environment variables from .env, .env.dev.
# Deploys functions with following user-defined environment variables:
# PLANET=Earth
# AUDIENCE=Dev Humans
$ firebase use prod
$ firebase deploy --only functions
i functions: Loaded environment variables from .env, .env.prod.
# Deploys functions with following user-defined environment variables:
# PLANET=Earth
# AUDIENCE=Prod Humans
Ayrılmış ortam değişkenleri
Bazı ortam değişkeni anahtarları dahili kullanım için ayrılmıştır. .env dosyalarınızda bu anahtarlardan hiçbirini kullanmayın:
- X_GOOGLE_ ile başlayan tüm anahtarlar
- EXT_ ile başlayan tüm anahtarlar
- FIREBASE_ ile başlayan tüm anahtarlar
- Aşağıdaki listeden herhangi bir tuş:
- CLOUD_RUNTIME_CONFIG
- ENTRY_POINT
- GCP_PROJECT
- GCLOUD_PROJECT
- GOOGLE_CLOUD_PROJECT
- FUNCTION_TRIGGER_TYPE
- FUNCTION_NAME
- FUNCTION_MEMORY_MB
- FUNCTION_TIMEOUT_SEC
- FUNCTION_IDENTITY
- FUNCTION_REGION
- FUNCTION_TARGET
- FUNCTION_SIGNATURE_TYPE
- K_SERVICE
- K_REVISION
- PORT
- K_CONFIGURATION
Hassas yapılandırma bilgilerini depolama ve bunlara erişme
.env dosyalarında depolanan ortam değişkenleri, işlev yapılandırması için kullanılabilir ancak veritabanı kimlik bilgileri veya API anahtarları gibi hassas bilgileri depolamanın güvenli bir yolu olarak kabul edilmemelidir. Bu durum, özellikle .env dosyalarınızı kaynak denetimine ekliyorsanız önemlidir.
Hassas yapılandırma bilgilerini depolamanıza yardımcı olmak için Cloud Functions for Firebase, Google Cloud Secret Manager ile entegre olur. Bu şifrelenmiş hizmet, yapılandırma değerlerini güvenli bir şekilde saklarken gerektiğinde işlevlerinizden kolayca erişilmesine olanak tanır.
Gizli anahtar oluşturma ve kullanma
Gizli anahtar oluşturmak için Firebase CLI'yı kullanın.
Gizli anahtar oluşturmak ve kullanmak için:
Yerel proje dizininizin kökünden aşağıdaki komutu çalıştırın:
firebase functions:secrets:set SECRET_NAME
SECRET_NAME için bir değer girin.
CLI, bir başarı mesajı gösterir ve değişikliğin geçerli olması için işlevleri dağıtmanız gerektiği konusunda uyarır.
Dağıtımdan önce, işlev kodunuzun
runWithparametresini kullanarak işlevin gizli anahtara erişmesine izin verdiğinden emin olun:exports.processPayment = functions // Make the secret available to this function .runWith({ secrets: ["SECRET_NAME"] }) .onCall((data, context) => { const myBillingService = initializeBillingService( // reference the secret value process.env.SECRET_NAME ); // Process the payment });Cloud Functions dağıtma:
firebase deploy --only functions
Artık diğer ortam değişkenleri gibi buna da erişebilirsiniz.
Buna karşılık, runWith içinde gizli anahtarı belirtmeyen başka bir işlev gizli anahtara erişmeye çalışırsa tanımsız bir değer alır:
exports.anotherEndpoint = functions.https.onRequest((request, response) => {
response.send(`The secret API key is ${process.env.SECRET_NAME}`);
// responds with "The secret API key is undefined" because the `runWith` parameter is missing
});
İşleviniz dağıtıldıktan sonra gizli değere erişebilir. Yalnızca
runWith parametresinde açıkça gizli anahtar içeren işlevler
, bu gizli anahtara ortam değişkeni olarak erişebilir. Bu sayede, gizli değerlerin yalnızca ihtiyaç duyulan yerlerde kullanılmasını sağlayarak gizli bilgilerin yanlışlıkla sızdırılması riskini azaltabilirsiniz.
Gizli anahtarları yönetme
Gizli anahtarlarınızı yönetmek için Firebase CLI'yı kullanın. Gizli anahtarları bu şekilde yönetirken bazı CLI değişikliklerinin, ilişkili işlevleri değiştirmenizi ve/veya yeniden dağıtmanızı gerektirdiğini unutmayın. Özellikle:
- Bir gizli anahtar için yeni bir değer belirlediğinizde, bu gizli anahtara referans veren tüm işlevleri yeniden dağıtmanız gerekir. Böylece işlevler en son değeri alır.
- Bir gizli anahtarı silerseniz dağıtılan işlevlerinizden hiçbirinin bu gizli anahtara referans vermediğinden emin olun. Silinen bir gizli değeri kullanan işlevler sessizce başarısız olur.
Secret Manager için Firebase KSA komutlarının özeti aşağıda verilmiştir:
# Change the value of an existing secret firebase functions:secrets:set SECRET_NAME # View the value of a secret functions:secrets:access SECRET_NAME # Destroy a secret functions:secrets:destroy SECRET_NAME # View all secret versions and their state functions:secrets:get SECRET_NAME # Automatically clean up all secrets that aren't referenced by any of your functions functions:secrets:prune
access ve destroy komutları için belirli bir sürümü yönetmek üzere isteğe bağlı sürüm parametresini sağlayabilirsiniz. Örneğin:
functions:secrets:access SECRET_NAME[@VERSION]
Bu işlemler hakkında daha fazla bilgi edinmek için CLI yardımını görüntüleme komutuyla -h parametresini iletin.
Gizli anahtarlar nasıl faturalandırılır?
Secret Manager, 6 etkin gizli sürümün ücretsiz olarak kullanılmasına olanak tanır. Bu, bir Firebase projesinde ayda 6 gizli anahtarı ücretsiz olarak kullanabileceğiniz anlamına gelir.
Varsayılan olarak Firebase CLI, uygun durumlarda (ör. işlevleri gizli anahtarın yeni bir sürümüyle dağıttığınızda) kullanılmayan gizli anahtar sürümlerini otomatik olarak imha etmeye çalışır. Ayrıca, functions:secrets:destroy ve functions:secrets:prune kullanarak kullanılmayan gizli anahtarları etkin bir şekilde temizleyebilirsiniz.
Secret Manager, bir gizli anahtar üzerinde faturalandırılmayan 10.000 aylık erişim işlemine izin verir. İşlev örnekleri, her soğuk başlatmada yalnızca secrets seçeneğinde belirtilen gizli anahtarları okur. Çok sayıda gizli anahtarı okuyan çok sayıda işlev örneğiniz varsa projeniz bu sınırı aşabilir. Bu durumda, her 10.000 erişim işlemi için 0,03 ABD doları ücret alınır.
Daha fazla bilgi için Secret Manager fiyatlandırması başlıklı makaleyi inceleyin.
Emülatör desteği
dotenv ile ortam yapılandırması, yerel bir Cloud Functions emülatörüyle birlikte çalışacak şekilde tasarlanmıştır.
Yerel bir Cloud Functions emülatörü kullanırken .env.local dosyası oluşturarak projenizin ortam değişkenlerini geçersiz kılabilirsiniz. .env.local dosyasının içeriği, .env ve projeye özel .env dosyasına göre önceliklidir.
Örneğin, bir projede geliştirme ve yerel test için biraz farklı değerler içeren şu üç dosya bulunabilir:
.env
|
.env.dev
|
.env.local
|
|
PLANET=Earth AUDIENCE=Humans |
AUDIENCE=Dev Humans | AUDIENCE=Local Humans |
Local Context'te başlatıldığında emülatör, ortam değişkenlerini aşağıdaki gibi yükler:
$ firebase emulators:start
i emulators: Starting emulators: functions
# Starts emulator with following environment variables:
# PLANET=Earth
# AUDIENCE=Local Humans
Cloud Functions emülatöründeki gizli anahtarlar ve kimlik bilgileri
Cloud Functions emülatörü, hassas yapılandırma bilgilerini depolamak ve bunlara erişmek için gizli anahtarların kullanılmasını destekler. Öykünücü, varsayılan olarak uygulama varsayılan kimlik bilgilerini kullanarak üretim gizli anahtarlarınıza erişmeye çalışır. CI ortamları gibi belirli durumlarda emülatör, izin kısıtlamaları nedeniyle gizli değerlere erişemeyebilir.
Cloud Functions emülatörünün ortam değişkenleri desteğine benzer şekilde, bir .secret.local dosyası oluşturarak gizli anahtar değerlerini geçersiz kılabilirsiniz. Bu sayede, özellikle gizli değere erişiminiz yoksa işlevlerinizi yerel olarak test etmeniz kolaylaşır.
Çalışma zamanı yapılandırmasından taşıma
functions.config API'nin desteği sonlandırıldı ve Mart 2027'de kullanımdan kaldırılacak.
Bu tarihten sonra functions.config ile yapılan dağıtımlar başarısız olur.
Dağıtım hatalarını önlemek için Firebase KSA'yı kullanarak yapılandırmanızı Cloud Secret Manager'a taşıyın. Yapılandırmanızı taşımanın en verimli ve güvenli yolu olduğu için bu yöntem kesinlikle önerilir.
Firebase CLI ile yapılandırmayı dışa aktarma
Mevcut ortam yapılandırmanızı Cloud Secret Manager'da yeni bir gizli anahtara aktarmak için
config exportkomutunu kullanın:$ firebase functions:config:export i This command retrieves your Runtime Config values (accessed via functions.config()) and exports them as a Secret Manager secret. i Fetching your existing functions.config() from your project... ✔ Fetched your existing functions.config(). i Configuration to be exported: ⚠ This may contain sensitive data. Do not share this output. { ... } ✔ What would you like to name the new secret for your configuration? RUNTIME_CONFIG ✔ Created new secret version projects/project/secrets/RUNTIME_CONFIG/versions/1```Gizli anahtarları bağlamak için işlev kodunu güncelleme
Cloud Secret Manager'da yeni gizli anahtarda depolanan yapılandırmayı kullanmak için işlev kaynağınızda
defineJsonSecretAPI'sini kullanın. Ayrıca gizli anahtarların, ihtiyaç duyan tüm işlevlere bağlı olduğundan emin olun.Önce
const functions = require("firebase-functions/v1"); exports.myFunction = functions.https.onRequest((req, res) => { const apiKey = functions.config().someapi.key; // ... });Sonra
const { onRequest } = require("firebase-functions/v2/https"); const { defineJsonSecret } = require("firebase-functions/params"); const config = defineJsonSecret("RUNTIME_CONFIG"); exports.myFunction = onRequest( // Bind secret to your function { secrets: [config] }, (req, res) => { // Access secret values via .value() const apiKey = config.value().someapi.key; // ... });İşlevleri dağıtma
Değişiklikleri uygulamak ve gizli anahtar izinlerini bağlamak için güncellenmiş işlevlerinizi dağıtın.
firebase deploy --only functions:<your-function-name>
Otomatik olarak doldurulan ortam değişkenleri
İşlevlerin çalışma zamanında ve yerel olarak emüle edilen işlevlerde otomatik olarak doldurulan ortam değişkenleri vardır. Bunlar arasında Google Cloud tarafından doldurulanlar ve Firebase'e özgü bir ortam değişkeni yer alır:
process.env.FIREBASE_CONFIG: Aşağıdaki Firebase projesi yapılandırma bilgilerini sağlar:
{
databaseURL: 'https://DATABASE_NAME.firebaseio.com',
storageBucket: 'PROJECT_ID.firebasestorage.app ',
projectId: 'PROJECT_ID'
}
Gerçek Firebase yapılandırmanızdaki değerlerin, projenizde sağladığınız kaynaklara bağlı olarak değişebileceğini unutmayın.
Bu yapılandırma, Firebase Admin SDK'yı bağımsız değişken olmadan başlattığınızda otomatik olarak uygulanır. JavaScript'te işlev yazıyorsanız şu şekilde başlatın:
const admin = require('firebase-admin');
admin.initializeApp();
TypeScript'te işlev yazıyorsanız şu şekilde başlatın:
import * as functions from 'firebase-functions/v1';
import * as admin from 'firebase-admin';
import 'firebase-functions/v1';
admin.initializeApp();
Hizmet hesabı kimlik bilgilerini kullanarak Admin SDK'yı varsayılan proje yapılandırmasıyla ilk kullanıma hazırlamanız gerekiyorsa kimlik bilgilerini bir dosyadan yükleyip şu şekilde FIREBASE_CONFIG'e ekleyebilirsiniz:
serviceAccount = require('./serviceAccount.json');
const adminConfig = JSON.parse(process.env.FIREBASE_CONFIG);
adminConfig.credential = admin.credential.cert(serviceAccount);
admin.initializeApp(adminConfig);