Firebase Uzantısı Yükleme

Resmi Firebase uzantılarından herhangi birini Firebase konsolunu, Firebase CLI'yı (komut satırı arayüzü) veya otomatik olarak oluşturulan bir SDK'yı kullanarak yükleyebilir (ve yönetebilirsiniz).

Her yükleme yöntemi için desteklenen işlemler arasındaki farklılıkları incelediğinizden emin olun.


Otomatik olarak oluşturulan bir SDK kullanılarak yükleme, uzantıları yüklemek ve yönetmek için yeni bir seçenektir. Bu seçenekte, belirli bir uzantı sürümü için Node SDK'sını otomatik olarak oluşturmak üzere CLI'yı kullanırsınız. Bu SDK'yı JavaScript veya TypeScript Cloud Functions'ınızda normal bir bağımlılık olarak içe aktarabilirsiniz.

Bu otomatik olarak oluşturulan SDK'da şunlar bulunur:

  • Uzantının parametrelerini ve çoğu ilkel olmayan parametre türü için tür bildirimlerini temsil eden bir arayüz.
  • Uzantının bir örneğini başlatan bir oluşturucu işlevi
  • Uzantı tarafından yayınlanan tüm etkinlikler için Eventarc tetikleyicilerini içeren bir uzantı sınıfı.

Uzantı SDK'sı oluşturduktan sonra uzantının tüm yapılandırması kodda yapılır.

Bu yükleme seçeneğini kullanmak, özellikle uzantıların dışında tanımlanmış Cloud işlevleri içeren projelerde birden fazla uzantı örneğinin yönetimini büyük ölçüde basitleştirebilir.


Uzantıları yüklemek veya yönetmek için şu rollerden birine atanmış olmanız gerekir: Sahip veya Düzenleyici ya da Firebase Yöneticisi.

Uzantı yüklemek için projenizin Blaze (kullandıkça öde) planı kapsamında olması gerekir. Uzantı yükleme işlemi ücretsiz olsa da kullanımınız hizmetlerin ücretsiz katmanını aşarsa Firebase hizmetleri veya Cloud Secret Manager gibi Cloud hizmetlerinin kullanımı için sizden ücret alınabilir.

Başlamadan önce

  1. Henüz yapmadıysanız Firebase'i projenize ekleyin.

  2. Henüz yapmadıysanız projenizi Blaze (kullandıkça öde) planına yükseltin.

  3. Firebase CLI'nın en son sürümünü yükleyin veya bu sürüme güncelleyin.

  4. Firebase proje kimliğinizi veya daha önce yapılandırılmış proje takma adınızı not edin.

    • Proje Kimliği: Bilgisayarınızın herhangi bir yerinden firebase projects:list komutunu çalıştırın.
    • Proje takma adı: Yerel uygulama dizininizden firebase use komutunu çalıştırın.

1. adım: Bir uzantıyla ilgili ayrıntılı bilgileri görüntüleyin

Bu adım isteğe bağlıdır ancak kesinlikle önerilir.

Firebase Extension yüklemeden önce uzantıyla ilgili ayrıntılı bilgileri incelemenizi öneririz. Bu bilgiler arasında şunlar yer alır:

  • Uzantının işleyiş şekli, önceden yapılması gereken yükleme görevleri ve uzantıyla ilgili ayrıntılar
  • Genel tanımlayıcı bilgiler ve açıklama
  • Uzantının görevleri için faturalandırma hesabı gerekip gerekmediği
  • İşlem için gereken Google hizmetleri (API'ler) ve erişim rolleri
  • Uzantı için oluşturulan kaynaklar (ör. işlevler)
  • Kullanıcı tarafından yapılandırılabilen parametrelerin açıklamaları

Bir uzantının ayrıntılı bilgilerini görüntülemek için:

  1. Ortamınızı ayarladığınızdan ve bir uzantı seçtiğinizden emin olun.

  2. extension-info komutunu bilgisayarınızın herhangi bir yerinden çalıştırın:

    firebase ext:info publisher-id/extension-id

    publisher-id ve extension-id bağımsız değişkenleri zorunludur ve uzantının önceden yükleme ayrıntıları sayfasında bulunabilir.

2. adım: Uzantı yükleyin

Yüklemeden önce uzantının temel özelliklerini (ör. etkinleştirilen API'ler, oluşturulan kaynaklar, verilen erişim vb.) ve faturalandırma şartlarını inceleyin.

Devam etmeden önce ortamınızı ayarladığınızdan ve bir uzantı seçtiğinizden emin olun.

Cloud Functions for Firebase'i başlatma

Yeni bir projeye başlıyorsanız veya projenizde henüz Cloud Functions for Firebase kullanılmıyorsa init functions komutunu çalıştırın:

cd your-project
firebase init functions

İşlevlerinizin dili olarak TypeScript veya JavaScript'i seçin.

Projenizde Cloud Functions zaten başlatılmışsa firebase-functions paketinin 5.1.0 veya daha yeni bir sürümünü kullandığınızdan emin olun:

cd your-project/functions
npm upgrade --save firebase-functions

ESLint kullanıyorsanız oluşturulan SDK'ları yapılandırmanızın dışında tutmak da isteyebilirsiniz (.eslintrc.js):

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

Uzantı SDK'sı oluşturma

Yerel Firebase dizininizden ext:sdk:install komutunu çalıştırın.

firebase ext:sdk:install publisher-id/extension-id@version

Örneğin, firestore-send-email uzantısının 0.1.34 sürümünü yüklemek için:

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

publisher-id ve extension-id gerekli olup extensions.dev adresindeki uzantının önceden yükleme ayrıntıları sayfasında bulunabilir. @version kısmı isteğe bağlıdır. Bu kısmı atlarsanız araç en son sürümü yükler.

Belirtebileceğiniz iki seçenek vardır:

  • --force: Aşağıdakilerin tümünü başka bir onay olmadan yapın:

    • Aynı uzantı ve sürüm için daha önce oluşturulmuş olsa bile SDK'yı otomatik olarak oluşturun.
    • Otomatik olarak oluşturulan SDK paketini Cloud Functions Node projesine yükleyin.

  • --codebase: SDK'nın ekleneceği kod tabanının adı. Belirtilmezse komut, SDK'yı varsayılan kod tabanına (functions) ekler.

Bu komut, uzantı için otomatik olarak oluşturulan bir SDK'yı içeren bir Node paketi oluşturur ve bunu projenizin Cloud Functions kod tabanlarından birine ekler. Varsayılan kod tabanında (functions) SDK şu konuma kaydedilir: 

functions/generated/extensions/publisher-id/extension-id/version

SDK oluşturulduktan sonra komut, SDK'yı Cloud Functions Node projenize de yüklemek isteyip istemediğinizi sorar. Bu isteme Evet yanıtını verin.

Uzantı örneklerini yapılandırma

Uzantıyı yapılandırmak için SDK'yı içe aktarın ve yüklemek istediğiniz her uzantı örneği için oluşturucu işlevini çağırın. Bu işlevi çağırırken, projeye özel bir örnek kimliği ve uzantının gerektirdiği yapılandırma parametrelerini iletin.

  1. Cloud Functions kaynağınızda, ext:sdk:install komutu tarafından yazdırılan ifadeyi kullanarak oluşturucuyu içe aktarın.

    TypeScript

    Örneğin, firestore-send-email uzantısı için bir SDK oluşturduysanız import ifadesi aşağıdaki gibi görünür:

    import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";

    Uzantı için şifre gibi gizli değerler gerekiyorsa Cloud Functions SDK'sındaki defineSecret işlevini de kullanmanız gerekir:

    import { defineSecret } from "firebase-functions/params";

    JavaScript

    Örneğin, firestore-send-email uzantısı için bir SDK oluşturduysanız require ifadesi aşağıdaki gibi görünür:

    const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");

    Uzantı için şifre gibi gizli değerler gerekiyorsa Cloud Functions SDK'sındaki defineSecret işlevini de kullanmanız gerekir:

    const { defineSecret } = require('firebase-functions/params');

  2. Yapılandırmak istediğiniz her örnek için oluşturucu işlevini çağırın ve sonucu dışa aktarın.

    Her örneğe yalnızca küçük harf, rakam ve kısa çizgi içeren benzersiz bir kimlik verin.

    TypeScript

    export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    JavaScript

    exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    Gizli değerlerin defineSecret işlevi kullanılarak belirtilmesi gerektiğini unutmayın.

  3. Ardından, yapılandırdığınız uzantıları dağıtmak için şu komutu çalıştırın: 

    firebase deploy --only functions --project=projectId-or-alias

    Her zamanki Cloud Functions dağıtım seçeneklerinin tümü geçerlidir. Örneğin, belirli bir kod tabanından tek bir uzantı örneği dağıtmak için: 

    firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

3. adım: Yükleme sonrası kurulumu tamamlayın

Bazı uzantıları kullanmadan önce tamamlamanız gereken zorunlu veya isteğe bağlı adımlar vardır. Bu talimatları, Extensions konsolunun Firebase kontrol panelindeki uzantınızın yükleme sonrası ayrıntılar sayfasında bulabilirsiniz (Kontrol paneline giden bağlantı, yükleme işleminden sonra terminalde gösterilir).

Bu talimatları, uzantının kaynak dizininde bulunan POSTINSTALL.md dosyasında da bulabilirsiniz.

Firebase kaynakları oluşturma

Uzantıyı, henüz mevcut olmayan Firebase kaynaklarını (Cloud Firestorekoleksiyonlar, Realtime Database yollar, Cloud Storage paketler) kullanacak şekilde yapılandırdıysanız uzantıyı kullanmadan önce bu kaynakları oluşturun.

Eventarc etkinlik işleyicileri oluşturma

Bazı uzantılar, yürütme sırasında önemli olaylar gerçekleştiğinde Eventarc'a yayın yapar. Bir uzantı etkinlik yayınlıyorsa bu etkinliklere kendi özel mantığınızla tepki veren işlevler yazabilirsiniz. Bu özellik, örneğin uzun süren görevler tamamlandığında kullanıcıları bilgilendirmek veya bir uzantı işlevinin çıkışını sonradan işlemek için yararlı olabilir.

Uzantı tarafından yayınlanan etkinliklerden herhangi biri için işleyiciler tanımlamak istiyorsanız her örneğin tetikleme yöntemlerini kullanarak bunu yapabilirsiniz:

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

Etkinlik işleyiciyi uzantı örneğiyle birlikte dışa aktarmanız gerekir.

Bir etkinlik işleyici tanımladıktan ve birinde her değişiklik yaptığınızda hem uzantıyı hem de işleyiciyi yeniden dağıtın.

Birden fazla uzantı örneği yükleme

Aynı uzantıyı aynı projede birden fazla kez yükleyebilirsiniz. Yüklenen her örneğin kendi özelleştirilmiş yapılandırması ve kendi uzantı kaynakları olabilir. Yüklü her örneği, projenizde benzersiz olan örnek kimliği ile tanımlar ve buna göre referans verirsiniz.

Yüklemek ve yapılandırmak istediğiniz her örnek için otomatik olarak oluşturulan SDK'nın oluşturucu işlevini bir kez çağırın.

Sonraki adımlar