Uzantınızda parametreleri ayarlayın ve kullanın

Parametreler, kullanıcının bir uzantının yüklenen her örneğini özelleştirdiği mekanizmadır. Parametreler, uzantıların ortam değişkenleri gibidir. Parametrelerin değerleri otomatik olarak doldurulabilir (yüklemeden sonra Firebase tarafından sağlanır) veya kullanıcı tarafından yapılandırılabilir (yükleme sırasında kullanıcı tarafından belirtilir).

Bu parametreleri, uzantınızın işlevler kaynak kodunda, extension.yaml dosyanızda ve POSTINSTALL.md dosyanızda referans olarak kullanabilirsiniz. PARAMETER_NAME adlı bir parametreye nasıl referans verileceğinin söz dizimi aşağıda verilmiştir:

  • İşlevlerinizin kaynak kodunda params modülünü (örneğin, params.defineInt("PARAMETER_NAME")) veya process.env.PARAMETER_NAME kullanın.

  • extension.yaml ve POSTINSTALL.md içinde ${param:PARAMETER_NAME} özelliğini kullanın.

    Kurulumdan sonra Firebase konsolu, POSTINSTALL.md dosyasının içeriğini gösterir ve tüm parametre referanslarını, yüklenen örnek için gerçek değerlerle doldurur.

Otomatik olarak doldurulan parametreler

Bir uzantının yüklenen her örneği, Firebase tarafından sağlanan otomatik olarak doldurulmuş birkaç varsayılan parametreye otomatik olarak erişebilir (aşağıdaki tabloya bakın). Bu parametre değerleri, Firebase projesinin varsayılan değerleri (ör. varsayılan Storage paketi) veya uzantıya özel değerlerdir (ör. uzantının örnek kimliği).

Otomatik olarak doldurulan tüm parametre değerleri değiştirilemez. Bu ayarlar, proje oluşturulurken veya uzantı yüklenirken belirlenir.

Firebase, bu parametre değerlerini uzantı için otomatik olarak doldursa da Firebase, yükleme sırasında kullanıcı için ilişkili ürünleri otomatik olarak sağlamaz. Uzantıyı yükleyen kullanıcının, yüklemeden önce projesinde ilişkili ve geçerli ürünleri etkinleştirmesi gerekir. Örneğin, uzantınız Cloud Firestore içeriyorsa kullanıcının projesinde Cloud Firestore kurulumunu yapması gerekir. Kullanıcılarınızı bu şartlar hakkında PREINSTALL.md dosyasında bilgilendirmenizi öneririz.

Otomatik olarak doldurulan parametre referansı Açıklama Parametre değeri (Firebase tarafından sağlanır)
Firebase projesinden varsayılan değerlere sahip parametreler
PROJECT_ID Uzantının yüklü olduğu Firebase projesinin benzersiz tanımlayıcısı

Genelleştirilmiş biçim:
project-id

Örnek değer:
project-123

DATABASE_URL Firebase projesinin varsayılan Realtime Database örneğinin URL'si

Genelleştirilmiş biçim:
https://project-id-default-rtdb.firebaseio.com
(ABD örnekleri)
veya
https://project-id-default-rtdb.region-code.firebasedatabase.app
(ABD dışındaki örnekler)

Örnek değer:
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

Firebase projesinin varsayılan Realtime Database örnek adı

Bu değer genellikle proje kimliğiyle aynıdır veya -default-rtdb ile biter.

Genelleştirilmiş biçim:
project-id

Örnek değer:
project-123

STORAGE_BUCKET Firebase projesinin varsayılan Cloud Storage paketi adı

Genelleştirilmiş biçim:
PROJECT_ID.firebasestorage.app

Örnek değer:
project-123.firebasestorage.app

Uzantı yüklemesinden varsayılan değere sahip parametre
EXT_INSTANCE_ID

Yüklü uzantı örneğinin benzersiz tanımlayıcısı

Bu değer, extension.yaml dosyasında belirtilen name alanından oluşturulur.

İlk yüklenen örnek için genelleştirilmiş biçim (Firebase tarafından otomatik olarak atanır; yükleme sırasında kullanıcı tarafından değiştirilemez):
name-from-extension.yaml

Örnek değer:
my-awesome-extension


2. yüklenen örnek ve sonraki örnekler için genelleştirilmiş biçim (Firebase tarafından otomatik olarak atanır; yükleme sırasında kullanıcı tarafından değiştirilebilir):
name-from-extension.yaml-4-digit-alphanumeric-hash

Örnek değer:
my-awesome-extension-6m31

Kullanıcı tarafından yapılandırılan parametreler

Bir kullanıcının uzantının yüklenen her örneğini özelleştirmesini sağlamak için kullanıcıdan yükleme sırasında parametre değerlerini belirtmesini isteyebilirsiniz. Bu değerleri istemek için params dosyanızın extension.yaml bölümünde istemleri ayarlarsınız.

Burada bir örnek params bölümü ve ardından kullanılabilen tüm parametre alanlarını açıklayan bir tablo yer almaktadır.

# extension.yaml
...

# Parameters (environment variables) for which the user specifies values during installation
params:
  - param: DB_PATH
    label: Realtime Database path
    description: >-
      What is the Realtime Database path where you will write new text
      for sentiment analysis?
    type: string
    validationRegex: ^\S+$
    validationErrorMessage: Realtime Database path cannot contain spaces.
    example: path/to/posts
    required: true

  - param: TEXT_KEY
    label: Key for text
    description: What is the name of the key that will contain text to be analyzed?
    type: string
    default: textToAnalyze
    required: true

params dosyanızın extension.yaml bölümünde, kullanıcı tarafından yapılandırılmış bir parametreyi tanımlamak için aşağıdaki alanları kullanın:

Alan Tür Açıklama
param
(zorunlu) 		dize Parametrenin adı
label
(zorunlu) 		dize

Parametre için kısa açıklama

Parametre değeri istendiğinde kullanıcıya gösterilir.

description
(isteğe bağlı) 		dize

Parametre için ayrıntılı açıklama

Parametre değeri istendiğinde kullanıcıya gösterilir.

Markdown desteği

type
(isteğe bağlı) 		dize

Kullanıcının parametrenin değerini nasıl ayarladığına ilişkin giriş mekanizması (örneğin, metni doğrudan girme veya açılır listeden seçme)

Geçerli değerler şunlardır:

  • string: Serbest biçimli metin girişine izin verir (validationRegex ile sınırlı olduğu için)
  • select: Önceden tanımlanmış seçenekler listesinden bir girişin seçilmesine olanak tanır. Bu değeri belirtirseniz options alanını da tanımlamanız gerekir.
  • multiSelect: Önceden tanımlanmış seçenekler listesinden bir veya daha fazla girişin seçilmesine olanak tanır. Bu değeri belirtirseniz options alanını da tanımlamanız gerekir.
  • selectResource: Kullanıcının projesinden belirli bir Firebase kaynağı türünün (ör. Cloud Storage grubu) seçilmesine olanak tanır.

    Bu tür bir parametre belirttiğinizde, kullanıcılar yükleme kullanıcı arayüzünde daha kullanıcı dostu bir seçim widget'ı görür. Bu nedenle, mümkün olduğunda selectResource parametrelerini kullanın.

    Bu değeri belirtirseniz resourceType alanını da tanımlamanız gerekir.

  • secret: Üçüncü taraf hizmetleri için API anahtarları gibi hassas dizelerin depolanmasına izin verir. Bu değerler Cloud Secret Manager'da depolanır.

    Cloud Secret Manager, ücretli bir hizmettir ve bu hizmetin kullanımı, uzantınızı yükleyen kullanıcılardan ücret alınmasına neden olabilir. secret parametre türünü kullanıyorsanız uzantınızın Cloud Secret Manager'ı kullandığını PREINSTALL dosyanızda belgelediğinizden emin olun.

Bu alan çıkarılırsa parametre varsayılan olarak type string olur.

options
(type parametresi select veya multiSelect ise zorunludur) 		list

Kullanıcının seçim yapabileceği değerlerin listesi

label ve value alanlarını options alanına ekleyin:

  • label (string): Seçilebilir seçeneğin kısa açıklaması
  • value (string): Seçilebilir seçeneğin gerçek değeri

value alanı, options alanı için zorunludur.
label atlanırsa liste seçeneği varsayılan olarak value görüntülenir.
resourceType
(type parametresi selectResource ise zorunludur) 		dize

Kullanıcıdan seçmesini istemek için kullanılacak Firebase kaynağının türü. Şu anda yalnızca Cloud Storage grupları kaynak seçicileri desteklemektedir:

Kaynak türü Tür Kimliği
Cloud Storage paket storage.googleapis.com/Bucket

Bilinmeyen resourceType değerleri yoksayılır ve kullanıcı arayüzü, parametreyi serbest biçimli bir string giriş alanı olarak oluşturur.
example
(isteğe bağlı) 		dize

Parametre için örnek değer
validationRegex
(isteğe bağlı)
(yalnızca type parametresi string olduğunda geçerlidir) 		dize

Parametrenin kullanıcı tarafından yapılandırılan değerinin doğrulanması için normal ifade dizesi

Normal ifade, go kitaplığı kullanılarak derlenir: RE2

Doğrulama ile ilgili ayrıntılar için aşağıdaki Doğrulama ve hata mesajları bölümüne bakın.

validationErrorMessage
(isteğe bağlı) 		dize

validationRegex başarısız olursa gösterilecek hata mesajı

Hata mesajları hakkında ayrıntılı bilgi için aşağıdaki Doğrulama ve hata mesajları bölümüne bakın.

default
(isteğe bağlı) 		dize

Kullanıcı parametrenin değerini boş bırakırsa parametrenin varsayılan değeri

Gerekirse default değeri için bir otomatik olarak doldurulan parametre değeri belirtebilirsiniz (örnek için Resize Images uzantısının IMG_BUCKET parametresine bakın).

required
(isteğe bağlı) 		boolean

Kullanıcının, parametre değeri istendiğinde boş bir dize gönderip gönderemeyeceğini tanımlar.

required atlanırsa bu değer varsayılan olarak true (yani zorunlu bir parametre) olur.

immutable
(isteğe bağlı) 		boolean

Kullanıcının, yüklemeden sonra parametrenin değerini değiştirip değiştiremeyeceğini tanımlar (örneğin, uzantıyı yeniden yapılandırırsa)

immutable atlanırsa bu değer varsayılan olarak false olur.

Not: Uzantınızın dağıtılan işlevleri için bir"location" parametresi tanımlarsanız, bu immutable alanını parametre nesnesine eklemeniz gerekir.

Kullanıcı tarafından yapılandırılan değerler için doğrulama ve hata mesajları

type değeri string olan bir parametre ayarladığınızda, parametrenin validationRegex alanı aracılığıyla uygun normal ifade doğrulamasını tanımlamanız gerekir.

Ayrıca, birçok uzantı için yaygın olarak istenen parametre değeri bir veritabanı yolu veya Cloud Storage paketi olur. Yükleme, yeniden yapılandırma veya güncelleme sırasında Extensions hizmetinin, parametre değeri girilirken aşağıdaki değerleri doğrulamadığını unutmayın:

  • Belirtilen veritabanının veya Cloud Storage paketin kullanıcının Firebase projesinde ayarlanıp ayarlanmadığı
  • Belirtilen veritabanı yolunun kullanıcının veritabanında bulunup bulunmadığı

Ancak uzantı kaynaklarını dağıtırken referans verilen veritabanı veya Cloud Storage paketi projede henüz ayarlanmamışsa Firebase konsolunda veya Firebase KSA'da bir hata mesajı gösterilir.

Uzantınızı yüklediklerinde başarılı bir şekilde yüklenip beklendiği gibi çalışması için PREINSTALL dosyasındaki kullanıcıları bu şartlar hakkında bilgilendirmenizi önemle tavsiye ederiz.

Sistem parametreleri

Sistem parametreleri, uzantı kaynaklarının temel yapılandırmasını kontrol eder. Kaynak yapılandırmasını kontrol etmek için tasarlandıklarından işlev kodunuzdan ortam değişkenleri olarak erişilemezler.

Normalde bu parametreler için extension.yaml içinde herhangi bir şey bildirmeniz gerekmez. Her uzantı örneği için otomatik olarak tanımlanır ve kullanıcılar uzantınızı yüklerken özel değerler ayarlayabilir.

Ancak uzantınızın özel kaynak gereksinimleri varsa extension.yaml içinde kaynak düzeyinde belirli değerler ayarlayabilirsiniz. Kaynak başına yapılandırma ayarları, kullanıcının uzantı örneği genelindeki ayarlarını geçersiz kılar. Örneğin:

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    availableMemoryMb: 1024
- name: normal_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function has no special memory requirements. It will use the
    default value, or the value of `firebaseextension.v1beta.function/memory`
  properties:
    httpsTrigger: {}
    runtime: nodejs18

Kullanılabilir sistem parametreleri şunlardır:

Ad Etiket (insan tarafından okunabilir) properties içindeki ilgili alan Açıklama
firebaseextensions.v1beta.function/location Konum location Cloud Functions hangi bölgeye dağıtılmalıdır?
firebaseextensions.v1beta.function/memory İşlev belleği memory Her işlev için kaç megabayt bellek ayrılmalıdır?
firebaseextensions.v1beta.function/timeoutSeconds İşlev zaman aşımı timeout Fonksiyonlar zaman aşımına uğramadan önce kaç saniye çalışmalıdır?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings VPC bağlayıcısı çıkışı vpcConnectorEgressSettings VPC bağlayıcısı yapılandırıldığında giden trafiği kontrol eder.
firebaseextensions.v1beta.function/vpcConnector VPC Bağlayıcısı vpcConnector Cloud Functions'ı belirtilen VPC bağlayıcısına bağlar.
firebaseextensions.v1beta.function/minInstances Minimum işlev örneği sayısı minInstances Bu işlevin aynı anda çalıştırılacak minimum örnek sayısı
firebaseextensions.v1beta.function/maxInstances Maksimum işlev örneği sayısı maxInstances Bu işlevin aynı anda çalıştırılacak maksimum örnek sayısı
firebaseextensions.v1beta.function/ingressSettings Giriş ayarları ingressSettings Gelen trafiğin nereden kabul edileceğini kontrol eder.
firebaseextensions.v1beta.function/labels Etiketler labels Uzantıdaki tüm kaynaklara uygulanacak etiketler