Başlayın: İlk işlevlerinizi yazın, test edin ve dağıtın


Cloud Functions'ı kullanmaya başlamak için bu eğitime göz atın. Eğitimde, gerekli kurulum görevleriyle başlayıp iki ilgili işlevin oluşturulması, test edilmesi ve dağıtılması anlatılıyor:

  • Bir metin değerini kabul eden ve bunu Cloud Firestore öğesine yazan bir URL'yi kullanıma sunan "mesaj ekle" işlevi.
  • Cloud Firestore yazma işleminde tetiklenen ve metni büyük harfe dönüştüren bir "büyük harf yap" işlevi.

Bu örnekte Cloud Firestore ve HTTP tetikli JavaScript işlevlerini seçmemizin nedenlerinden biri, bu arka plan tetikleyicilerinin Firebase Local Emulator Suite aracılığıyla kapsamlı bir şekilde test edilebilmesidir. Bu araç seti Realtime Database, PubSub, Auth ve HTTP ile çağrılabilen tetikleyicileri de destekler. Remote Config, TestLab ve Analytics tetikleyicileri gibi diğer arka plan tetikleyici türlerinin tümü, bu sayfada açıklanmayan araç setleri kullanılarak etkileşimli olarak test edilebilir.

Bu eğitimin aşağıdaki bölümlerinde, örneği oluşturmak, test etmek ve dağıtmak için gereken adımlar ayrıntılı olarak açıklanmaktadır. Kodu çalıştırmayı ve incelemeyi tercih ediyorsanız Tam örnek kodu inceleme bölümüne gidin.

Firebase projesi oluşturma

  1. Firebase konsolunda Proje ekle'yi tıklayın.

    • Firebase kaynaklarını mevcut bir Google Cloud projeye eklemek için projenin adını girin veya açılır menüden projeyi seçin.

    • Yeni bir proje oluşturmak için proje adı girin. İsterseniz proje adının altında gösterilen proje kimliğini de düzenleyebilirsiniz.

  2. İstenirse Firebase şartlarını inceleyip kabul edin.

  3. Devam'ı tıklayın.

  4. (İsteğe bağlı) Projeniz için Google Analytics'ı ayarlayın. Bu, aşağıdaki Firebase ürünlerini kullanarak optimum bir deneyim sağlar: Firebase A/B Testing, Cloud Messaging, Crashlytics, In-App Messaging ve Remote Config (kişiselleştirme dahil).

    Mevcut bir Google Analytics hesabı seçin veya yeni bir hesap oluşturun. Yeni bir hesap oluşturursanız Analytics raporlama konumunuzu seçin, ardından projeniz için veri paylaşım ayarlarını ve Google Analytics şartlarını kabul edin.

  5. Proje oluştur'u (veya Firebase'i mevcut bir Google Cloud projesine ekliyorsanız Firebase ekle'yi) tıklayın.

Firebase, Firebase projeniz için kaynakları otomatik olarak sağlar. İşlem tamamlandığında Firebase konsolunda Firebase projenizin genel bakış sayfasına yönlendirilirsiniz.

Node.js ve Firebase CLI'yı ayarlama

İşlev yazmak için Node.js ortamına, işlevleri Cloud Functions çalışma zamanına dağıtmak için ise Firebase CLI'ya ihtiyacınız vardır. Node.js ve npm'yi yüklemek için Node Version Manager önerilir.

Node.js ve npm'yi yükledikten sonra, tercih ettiğiniz yöntemi kullanarak Firebase CLI'yı yükleyin. CLI'yı npm aracılığıyla yüklemek için şunu kullanın:

npm install -g firebase-tools

Bu komut, tüm dünyada kullanılabilen firebase komutunu yükler. Komut başarısız olursa npm izinlerini değiştirmeniz gerekebilir. firebase-tools uygulamasının en son sürümüne güncellemek için aynı komutu tekrar çalıştırın.

Projenizi ilk kullanıma hazırlayın

Firebase SDK'sını başlattığınızda Cloud Functions, bağımlılıkları ve bazı minimum örnek kodları içeren boş bir proje oluşturur ve işlevleri oluşturmak için TypeScript veya JavaScript'i seçersiniz. Bu eğitimin amaçları doğrultusunda Cloud Firestore öğesini de başlatmanız gerekir.

Projenizi başlatmak için:

  1. Tarayıcı üzerinden giriş yapmak ve Firebase CLI'nın kimliğini doğrulamak için firebase login komutunu çalıştırın.

  2. Firebase proje dizininize gidin.

  3. Koşu firebase init firestore. Bu eğitimde, Firestore kuralları ve dizin dosyaları istendiğinde varsayılan değerleri kabul edebilirsiniz. Bu projede henüz Cloud Firestore kullanmadıysanız Cloud Firestore ile çalışmaya başlama başlıklı makalede açıklandığı gibi Firestore için bir başlangıç modu ve konumu da seçmeniz gerekir.

  4. Koşu firebase init functions. CLI, mevcut bir kod tabanı seçmenizi veya yeni bir kod tabanı başlatıp adlandırmanızı ister. Başlangıç aşamasında varsayılan konumdaki tek bir kod tabanı yeterlidir. Daha sonra, uygulamanız genişledikçe kod tabanlarındaki işlevleri düzenlemek isteyebilirsiniz.

  5. CLI, dil desteği için aşağıdaki seçenekleri sunar:

    Bu eğitim için JavaScript'i seçin.

  6. CLI, npm ile bağımlılıkları yükleme seçeneği sunar. Bağımlılıkları başka bir şekilde yönetmek istiyorsanız reddetmeniz güvenlidir. Ancak reddederseniz işlevlerinizi taklit etmeden veya dağıtmadan önce npm install komutunu çalıştırmanız gerekir.

Bu komutlar başarıyla tamamlandıktan sonra proje yapınız şu şekilde görünür:

myproject
 +- .firebaserc    # Hidden file that helps you quickly switch between
 |                 # projects with `firebase use`
 |
 +- firebase.json  # Describes properties for your project
 |
 +- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # main source file for your Cloud Functions code
      |
      +- node_modules/ # directory where your dependencies (declared in
                       # package.json) are installed

İlk kullanıma hazırlama sırasında oluşturulan package.json dosyası önemli bir anahtar içerir: "engines": {"node": "16"}. Bu, işlevleri yazmak ve dağıtmak için Node.js sürümünüzü belirtir. Desteklenen diğer sürümleri seçebilirsiniz.

Gerekli modülleri içe aktarın ve bir uygulamayı başlatın

Kurulum görevlerini tamamladıktan sonra kaynak dizini açabilir ve aşağıdaki bölümlerde açıklandığı gibi kod eklemeye başlayabilirsiniz. Bu örnek için projenizin Cloud Functions ve Admin SDK modüllerini Node require ifadelerini kullanarak içe aktarması gerekir. index.js dosyanıza aşağıdakine benzer satırlar ekleyin:

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();
index.js

Bu satırlar firebase-functions ve firebase-admin modüllerini yükler ve Cloud Firestore değişikliklerinin yapılabileceği bir admin uygulama örneğini başlatır. Admin SDK desteğinin sunulduğu her yerde (FCM, Authentication ve Firebase Realtime Database için olduğu gibi) Cloud Functions kullanarak Firebase'i entegre etmenin güçlü bir yolunu sunar.

Firebase CLI, projenizi başlattığınızda Firebase ve Firebase SDK'sını Cloud Functions Node modülleri için otomatik olarak yükler. Projenize üçüncü taraf kitaplıkları eklemek için package.json dosyasını değiştirebilir ve npm install komutunu çalıştırabilirsiniz. Daha fazla bilgi için Bağımlılıkları İşleme başlıklı makaleyi inceleyin.

addMessage() işlevini ekleyin

addMessage() işlevi için index.js dosyasına şu satırları ekleyin:

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin
    .firestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});
index.js

addMessage() işlevi bir HTTP uç noktasıdır. Uç noktaya yapılan tüm istekler, ExpressJS tarzı Request ve Response nesnelerinin onRequest() geri çağırma işlevine iletilmesiyle sonuçlanır.

HTTP işlevleri eşzamanlıdır (çağrılabilir işlevlere benzer). Bu nedenle, yanıtı mümkün olduğunca hızlı bir şekilde göndermeli ve Cloud Firestore kullanarak çalışmayı ertelemelisiniz. addMessage() HTTP işlevi, bir metin değerini HTTP uç noktasına iletir ve /messages/:documentId/original yolu altındaki veritabanına ekler.

makeUppercase() işlevini ekleyin

makeUppercase() işlevi için index.js dosyasına şu satırları ekleyin:

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });
index.js

makeUppercase() işlevi, Cloud Firestore yazıldığında yürütülür. ref.set işlevi, dinlenecek belgeyi tanımlar. Performans nedeniyle mümkün olduğunca ayrıntılı bilgi vermeniz gerekir.

Ayraçlar (ör. {documentId}), geri çağırmada eşleşen verilerini gösteren joker karakterler olan "parametreleri" çevreler.

Cloud Firestore, yeni mesajlar eklendiğinde onCreate() geri çağırma işlevini tetikler.

Cloud Firestore etkinlikleri gibi olaya dayalı işlevler asenkron çalışır. Geri çağırma işlevi null, bir Nesne veya Promise döndürmelidir. Herhangi bir değer döndürmezseniz işlevin zaman aşımı gerçekleşir, hata sinyali verilir ve işlev yeniden denenir. Sync, Async, and Promises (Senkron, Eşzamansız ve Sözler) başlıklı makaleyi inceleyin.

İşlevlerinizin yürütülmesini taklit etme

Firebase Local Emulator Suite, uygulamaları bir Firebase projesine dağıtmak yerine yerel makinenizde oluşturup test etmenize olanak tanır. Geliştirme sırasında yerel test yapılması, kısmen üretim ortamında maliyete neden olabilecek kodlama hatalarından kaynaklanan riski azaltması nedeniyle önemle tavsiye edilir (ör. sonsuz döngü).

İşlevlerinizi taklit etmek için:

  1. firebase emulators:start komutunu çalıştırın ve Emulator Suite UI URL'sinin çıkışını kontrol edin. Varsayılan olarak localhost:4000'dir ancak makinenizde farklı bir bağlantı noktasında barındırılabilir. Emulator Suite UI platformunu açmak için bu URL'yi tarayıcınıza girin.

  2. HTTP işlevinin URL'si için firebase emulators:start komutunun çıkışını kontrol edin addMessage(). Bu, http://localhost:5001/MY_PROJECT/us-central1/addMessage gibi görünür ancak:

    1. MY_PROJECT yerine proje kimliğiniz yazılır.
    2. Bağlantı noktası, yerel makinenizde farklı olabilir.

  3. Sorgu dizesi ?text=uppercaseme işlevin URL'sinin sonuna ekleyin. Bu, şuna benzer bir şekilde görünmelidir: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. İsteğe bağlı olarak, "uppercaseme" mesajını özel bir mesajla değiştirebilirsiniz.

  4. URL'yi tarayıcınızda yeni bir sekmede açarak yeni bir mesaj oluşturun.

  5. İşlevlerin Emulator Suite UI üzerindeki etkilerini görüntüleyin:

    1. Günlükler sekmesinde, addMessage() ve makeUppercase() işlevlerinin çalıştığını belirten yeni günlükler görmelisiniz:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

    2. Firestore sekmesinde, orijinal mesajınızı ve mesajınızın büyük harfli sürümünü içeren bir doküman görürsünüz (örneğin, orijinal mesajınız "uppercaseme" ise "UPPERCASEME" olarak görünür).

İşlevleri bir üretim ortamına dağıtma

İşlevleriniz emülatörde istediğiniz gibi çalıştıktan sonra bunları üretim ortamında dağıtma, test etme ve çalıştırma işlemlerine geçebilirsiniz. Node.js 14 çalışma zamanı ortamına dağıtım yapmak için projenizin Blaze fiyatlandırma planı kapsamında olması gerektiğini unutmayın. Cloud Functions Fiyatlandırma bölümüne bakın.

Eğitimi tamamlamak için işlevlerinizi dağıtın ve ardından addMessage() komutunu çalıştırarak makeUppercase() tetikleyin.

  1. İşlevlerinizi dağıtmak için şu komutu çalıştırın:

     firebase deploy --only functions

    Bu komutu çalıştırdıktan sonra Firebase KSA, tüm HTTP işlevi uç noktalarının URL'sini verir. Terminalinizde aşağıdaki gibi bir satır görmeniz gerekir:

    Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage

    URL, proje kimliğinizin yanı sıra HTTP işlevi için bir bölge içerir. Şu anda bu konuda endişelenmenize gerek olmasa da bazı üretim HTTP işlevleri, ağ gecikmesini en aza indirmek için bir konum belirtmelidir.

    "Projeye erişim yetkilendirilemiyor" gibi erişim hatalarıyla karşılaşırsanız proje takma adınızı kontrol etmeyi deneyin.

  2. CLI tarafından oluşturulan addMessage() URL'sini kullanarak bir metin sorgusu parametresi ekleyin ve bunu tarayıcıda açın:

    https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo

    İşlev yürütülür ve tarayıcı, metin dizesinin depolandığı veritabanı konumundaki Firebase konsoluna yönlendirilir. Bu yazma etkinliği, dizenin büyük harfli sürümünü yazan makeUppercase() işlevini tetikler.

İşlevleri dağıtıp yürüttükten sonra günlükleri Google Cloud konsolunda görüntüleyebilirsiniz. Geliştirme veya üretim aşamasındaki işlevleri silmeniz gerekiyorsa Firebase CLI'yı kullanın.

Üretimde, çalıştırılacak minimum ve maksimum örnek sayısını ayarlayarak işlev performansını optimize edebilir ve maliyetleri kontrol edebilirsiniz. Bu çalışma zamanı seçenekleri hakkında daha fazla bilgi için Ölçeklendirme davranışını kontrol etme başlıklı makaleyi inceleyin.

Tam örnek kodu inceleme

functions/index.js işlevlerini içeren tamamlanmış addMessage() ve makeUppercase() işlevleri aşağıda verilmiştir. Bu işlevler, Cloud Firestore değerini yazan ve ardından dizedeki tüm karakterleri büyük harfe çevirerek dönüştüren bir HTTP uç noktasına parametre iletmenize olanak tanır.

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin
    .firestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });
index.js

Sonraki adımlar

Bu dokümanda, Cloud Functions için işlevleri yönetme ve Cloud Functions tarafından desteklenen tüm etkinlik türlerini işleme hakkında daha fazla bilgi edinebilirsiniz.

Cloud Functions hakkında daha fazla bilgi edinmek için şunları da yapabilirsiniz: