Firebase Uzantısı Yükleme

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

Her kurulum yöntemi için desteklenen işlemlerdeki farklılıkları inceleyin.


Otomatik olarak oluşturulan bir SDK'yı kullanarak 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 otomatik olarak bir Node SDK'sı oluşturmak üzere CLI'yi 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 şunları içerir:

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

Bir uzantı SDK'sı oluşturduktan sonra uzantının tüm yapılandırması kodda gerçekleşir.

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


Uzantı 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ı yüklemek için projenizin Blaze (kullandıkça öde) planında olması gerekir. Uzantıları yüklemek ücretsiz olsa da Firebase hizmetlerini veya Cloud Secret Manager gibi Cloud hizmetlerini ücretsiz katmanlarının ötesinde kullanırsanız 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 geçirin.

  3. Firebase CLI'yi yükleyin veya en son sürümüne güncelleyin.

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

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

1. adım: Bir uzantı hakkında ayrıntılı bilgileri görüntüleme

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

Firebase Extension yüklemeden önce aşağıdakiler de dahil olmak üzere uzantı hakkında ayrıntılı bilgileri incelemenizi öneririz:

  • Uzantının işleyiş şekli, yükleme öncesi görevler 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 (işlevler gibi)
  • Kullanıcı tarafından yapılandırılabilir parametrelerin açıklamaları

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

  1. Ortamınızı oluşturduğunuzdan ve bir uzantı seçtiğinizden emin olun.

  2. Bilgisayarınızdaki herhangi bir yerden extension-info komutunu ç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 yükleme ayrıntıları sayfasında bulunabilir.

2. adım: Bir 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 Cloud Functions for Firebase kullanılmıyorsa init functions komutunu çalıştırın:

cd your-project
firebase init functions

İşlev 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ızdan da hariç tutmak isteyebilirsiniz (.eslintrc.js):

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

Uzatma 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 gereklidir ve extensions.dev adresindeki uzantının ön 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.

Belirtmeniz gereken iki seçenek vardır:

  • --force: Başka bir onay almadan aşağıdakilerin tümünü 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ı. Belirtilmemesi durumunda komut, SDK'yı varsayılan kod tabanına (functions) ekler.

Bu komut, uzantı için otomatik olarak oluşturulan bir SDK içeren bir Node paketi oluşturur ve bu paketi projenizin Cloud Functions kod tabanlarından birine ekler. Varsayılan kod tabanında (functions), SDK aşağıdaki 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 istemi Evet olarak yanıtlayın.

Uzantı örneklerini yapılandırma

Uzantı yapılandırması 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şleve projeye özgü 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 kurucuyu 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ı, şifre gibi gizli değerler gerektiriyorsa Cloud Functions SDK'sındaki defineSecret işlevine de ihtiyacınız vardır:

    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ı, şifre gibi gizli değerler gerektiriyorsa Cloud Functions SDK'sındaki defineSecret işlevine de ihtiyacınız vardır:

    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 bir örneğe yalnızca küçük harf, sayı 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 anahtar değerlerinin 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

    Normal 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ı, Firebase konsolunun Extensions kontrol panelindeki uzantınızın yükleme sonrası ayrıntılar sayfasında bulabilirsiniz (kontrol paneline özel 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

Eklentiyi, mevcut olmayan Firebase kaynaklarını (Cloud Firestorekoleksiyonlar, Realtime Database yollar, Cloud Storage paketler) kullanacak şekilde yapılandırdıysanız eklentiyi kullanmadan önce bunları oluşturun.

Eventarc etkinlik işleyicileri oluşturma

Bazı uzantılar, yürütme sırasında önemli olaylar olduğunda Eventarc'ta yayınlanır. Bir uzantı etkinlik yayınlarsa kendi özel mantığınızla bu etkinliklere tepki veren işlevler yazabilirsiniz. Bu, örneğin uzun süren görevler tamamlandığında kullanıcıları bilgilendirmek veya bir uzantı işlevinin çıktısını son işleme tabi tutmak için yararlı olabilir.

Uzantı tarafından yayınlanan etkinliklerden herhangi biri için işleyiciler tanımlamak istiyorsanız bunu her örneğin tetikleyici yöntemlerini kullanarak 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 değişiklik yaptıktan sonra hem uzantıyı hem de işleyiciyi yeniden dağıtın.

Birden fazla uzantı örneği yükleme

Aynı uzantıyı aynı projeye birden fazla kez yükleyebilirsiniz. Yüklenen her örnek, özelleştirilmiş kendi yapılandırmasına ve kendi uzantı kaynaklarına sahip olabilir. Yüklü her örneği, projenizde benzersiz olan örnek kimliğini kullanarak tanımlar ve referans olarak kullanırsınız.

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

Sonraki adımlar