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


Cloud Functions'ı kullanmaya başlamak için gerekli kurulum görevleriyle başlayan ve ilgili iki işlevi oluşturma, test etme ve dağıtma adımlarıyla çalışan bu eğiticiyle çalışmayı deneyin:

  • Metin değeri kabul eden bir URL'yi gösteren ve bunu Cloud Firestore'a yazan bir "mesaj ekle" işlevi.
  • Cloud Firestore yazmalarında tetiklenen ve metni büyük harfe dönüştüren "büyük harf yap" işlevi.

Bu arka plan tetikleyicilerinin Firebase Local Emulator Suite üzerinden kapsamlı bir şekilde test edilebildiğinden bu örnek için Cloud Firestore ve HTTP tetiklenen JavaScript işlevlerini seçtik. Bu araç seti; Realtime Database, PubSub, Auth ve HTTP çağrılabilir tetikleyicilerini de destekler. Remote Config, TestLab ve Analytics tetikleyicileri gibi diğer arka plan tetikleyici türlerinin tümü, bu sayfada açıklanmayan araç kümeleri kullanılarak etkileşimli olarak test edilebilir.

Bu eğiticinin 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ırıp incelemek isterseniz Örnek kodu eksiksiz inceleyin bölümüne geçin.

Firebase Projesi oluşturma

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

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

    • Yeni proje oluşturmak için istediğiniz proje adını girin. İsteğe bağlı olarak, 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'i kurun. Bu sayede, aşağıdaki Firebase ürünlerinden herhangi birini kullanırken optimum deneyim elde edebilirsiniz:

    Mevcut bir Google Analytics hesabını seçin veya yeni bir hesap oluşturun.

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

  5. Proje oluştur'u (veya mevcut bir Google Cloud projesini kullanıyorsanı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'yi ve Firebase CLI'ı ayarlama

İşlevler yazmak için Node.js ortamına, işlevleri Cloud Functions çalışma zamanına dağıtmak için Firebase CLI'ya ihtiyacınız vardır. Node.js ve npm'yi yüklemek için Düğüm Sürüm Yöneticisi önerilir.

Node.js ve npm'yi yükledikten sonra tercih ettiğiniz yöntemle Firebase CLI'ı yükleyin. CLI'yı npm üzerinden yüklemek için şunu kullanın:

npm install -g firebase-tools

Bu işlem, dünya genelinde 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 yeniden çalıştırın.

Projenizi ilk kullanıma hazırlayın

Cloud Functions için Firebase SDK'sını başlattığınızda bağımlılıklar ve minimum düzeyde örnek kod içeren boş bir proje oluşturur ve işlev oluşturmak için TypeScript veya JavaScript'i seçersiniz. Bu eğiticinin amaçları için Cloud Firestore'u ilk kullanıma hazırlamanız da gerekir.

Projenizi ilk kullanıma hazırlamak için:

  1. Tarayıcı üzerinden giriş yapmak ve Firebase CLI'ın kimliğini doğrulamak için firebase login komutunu çalıştırın.
  2. Firebase proje dizininize gidin.
  3. firebase init firestore çalıştır. Bu eğitimde, Firestore kuralları ve dizin dosyaları istendiğinde varsayılan değerleri kabul edebilirsiniz. Bu projede henüz Cloud Firestore'u kullanmadıysanız Cloud Firestore'u kullanmaya başlama bölümünde açıklandığı gibi Firestore için başlangıç modu ve konum seçmeniz gerekir.
  4. firebase init functions çalıştır. CLI, mevcut bir kod tabanı seçmenizi veya yeni bir kod tabanı oluşturup adlandırmanızı ister. Yeni başlayan aşamasında, varsayılan konumda tek bir kod tabanı yeterli olacaktır. Daha sonra uygulamanız genişledikçe işlevleri kod tabanlarında düzenlemek isteyebilirsiniz.

  5. CLI, dil desteği için iki seçenek 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 reddetmeyi tercih edebilirsiniz. Ancak reddederseniz işlevlerinizi öykünmeden veya dağıtmadan önce npm install öğesini ç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

Başlatma sırasında oluşturulan package.json dosyası önemli bir anahtar içeriyor: "engines": {"node": "16"}. Bu, işlevleri yazmak ve dağıtmak için kullanılan Node.js sürümünü 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ığı şekilde kod eklemeye başlayabilirsiniz. Bu örnek için projeniz, Node require ifadelerini kullanarak Cloud Functions ve Yönetici SDK'sı modüllerini içe aktarmalıdır. 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 mevcut olduğu her yerde (FCM, Authentication ve Firebase Realtime Database'de olduğu gibi) Cloud Functions'ı kullanarak Firebase'i entegre etmek için etkili bir yol sunar.

Projenizi ilk kullanıma hazırladığınızda Firebase CLI, Cloud Functions Düğümü için Firebase ve Firebase SDK'sı modüllerini otomatik olarak yükler. Projenize üçüncü taraf kitaplıkları eklemek için package.json öğesini değiştirip npm install çalıştırabilirsiniz. Daha fazla bilgi için Bağımlılıkları Yönetme bölümüne bakın.

addMessage() işlevini ekleyin

addMessage() işlevi için şu satırları index.js işlevine 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, onRequest() geri çağırmasına iletilen ExpressJS stili Request ve Response nesneleriyle sonuçlanır.

HTTP işlevleri eşzamanlıdır (çağrılanabilir işlevlere benzer). Bu nedenle, mümkün olduğunca hızlı bir şekilde yanıt göndermeniz ve Cloud Firestore'u kullanarak işi ertelemeniz gerekir. addMessage() HTTP işlevi, HTTP uç noktasına bir metin değeri iletir ve bunu /messages/:documentId/original yolunun altına veritabanına ekler.

makeUppercase() işlevini ekleyin

makeUppercase() işlevi için şu satırları index.js işlevine 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'a yazıldığında yürütülür. ref.set işlevi, dinlenecek dokümanı tanımlar. Performansı artırmak için mümkün olduğunca ayrıntı vermeye dikkat edin.

Ayraçlar (ör. {documentId}), geri çağırmada kendi eşleşen verilerinin gösterildiği "parametreler" ve joker karakterlerle çevrilidir.

Cloud Firestore, yeni mesaj eklendiğinde onCreate() geri çağırmasını tetikler.

Cloud Firestore etkinlikleri gibi etkinliğe dayalı işlevler eşzamansızdır. Geri çağırma işlevi bir null, nesne veya Promise döndürmelidir. Hiçbir şey döndürmezseniz işlev zaman aşımına uğrayarak hata sinyali verir ve işlem yeniden denenir. Senkronizasyon, Eşzamansız ve Vaatler başlıklı bölüme bakın.

İşlevlerinizin yürütülmesini emüle etme

Firebase Local Emulator Suite sayesinde uygulamaları Firebase projesine dağıtmak yerine yerel makinenizde derleyip test edebilirsiniz. Geliştirme sırasında yerel test yapılması önemle tavsiye edilir. Bunun nedenlerinden biri, üretim ortamında (örneğin, sonsuz döngü) potansiyel olarak maliyet doğurabilecek kodlama hatalarının riskini azaltmasıdır.

İşlevlerinizi emüle etmek için:

  1. firebase emulators:start komutunu çalıştırın ve Emulator Suite kullanıcı arayüzünün URL'sinin çıkışını kontrol edin. Varsayılan olarak localhost:4000 değerine ayarlanır ancak makinenizdeki farklı bir bağlantı noktasında barındırılıyor olabilir. Emulator Suite kullanıcı arayüzünü açmak için tarayıcınıza bu URL'yi girin.

  2. addMessage() HTTP işlevinin URL'si için firebase emulators:start komutunun çıkışını kontrol edin. http://localhost:5001/MY_PROJECT/us-central1/addMessage ile benzerdir ancak şu noktaları fark etmez:

    1. MY_PROJECT, proje kimliğinizle değiştirilecek.
    2. Bağlantı noktası, yerel makinenizde farklı olabilir.

  3. ?text=uppercaseme sorgu dizesini, işlevin URL'sinin sonuna ekleyin. Şuna benzer bir görünümde olacaktır: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. İsteğe bağlı olarak, "büyük harf" mesajını özel bir mesajla değiştirebilirsiniz.

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

  5. Emulator Suite kullanıcı arayüzündeki işlevlerin etkilerini görüntüleyin:

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

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

    2. Firestore sekmesinde, orijinal mesajınızın yanı sıra iletinizin büyük harfli versiyonunu da içeren bir doküman görürsünüz (aslında "büyük harf" ise "BÜYÜK HARF" gösterilir).

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

İşlevleriniz emülatörde istediğiniz gibi çalıştığında bunları dağıtma, test etme ve üretim ortamında çalıştırmaya geçebilirsiniz. Önerilen Node.js 14 çalışma zamanı ortamına dağıtım yapmak için projenizin Blaze fiyatlandırma planında olması gerektiğini unutmayın. Cloud Functions fiyatlandırmasını inceleyin.

Eğiticiyi tamamlamak için işlevlerinizi dağıtın ve ardından makeUppercase() tetiklemek için addMessage() yürütün.

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

     firebase deploy --only functions

    Bu komutu çalıştırdıktan sonra Firebase CLI, tüm HTTP işlevi uç noktaları için URL'yi oluşturur. Terminalinizde şuna benzer bir satır görürsünüz:

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

    URL, HTTP işlevinin bölgesinin yanı sıra proje kimliğinizi de içerir. 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. KSA'nın addMessage() URL çıkışını kullanarak bir metin sorgusu parametresi ekleyin ve bunu tarayıcıda açın:

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

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

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

Üretimde, çalıştırılacak minimum ve maksimum örnek sayılarını belirleyerek işlev performansını optimize etmek ve maliyetleri kontrol etmek isteyebilirsiniz. Bu çalışma zamanı seçenekleri hakkında daha fazla bilgi için Ölçeklendirme davranışını kontrol etme bölümüne bakın.

Örnek kodun tamamını inceleyin

addMessage() ve makeUppercase() işlevlerini içeren tamamlanmış functions/index.js aşağıda verilmiştir. Bu işlevler, Cloud Firestore'a değer yazan ve ardından dizedeki tüm karakterleri büyük harfle yazarak bu parametreyi dönüştüren bir HTTP uç noktasına parametre iletmenizi sağlar.

// 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 belgede, Cloud Functions için işlevleri yönetme ve Cloud Functions tarafından desteklenen tüm etkinlik türlerini yönetme hakkında daha fazla bilgi edinebilirsiniz.

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