Uzantınızın yaşam döngüsü etkinliklerini yönetin

Uzantı örneği aşağıdaki yaşam döngüsü etkinliklerinden herhangi birini gerçekleştirdiğinde tetiklenen Cloud Tasks işlevleri içerebilir:

• Uzantı örneği yüklüyse
• Uzantının bir örneği yeni bir sürüme güncellendi
• Bir uzantı örneğinin yapılandırması değiştirildiğinde

Bu özelliğin en önemli kullanım alanlarından biri verileri doldurmaktır. Örneğin, Cloud Storage paketine yüklenen resimlerin küçük resim önizlemelerini oluşturan bir uzantı oluşturduğunuzu varsayalım. Uzantınızın ana çalışması, onFinalize Cloud Storage etkinliği tarafından tetiklenen bir işlevde yapılır. Ancak yalnızca uzantı yüklendikten sonra yüklenen resimler işlenir. Uzantınıza onInstall yaşam döngüsü etkinliği tarafından tetiklenen bir işlev ekleyerek uzantı yüklendiğinde mevcut resimlerin küçük resim önizlemelerini de oluşturabilirsiniz.

Yaşam döngüsü etkinliği tetikleyicilerinin diğer kullanım alanlarından bazıları şunlardır:

• Yükleme sonrası kurulumu otomatikleştirme (veritabanı kayıtları oluşturma, dizine ekleme vb.)
• Geriye dönük uyumlu olmayan değişiklikler yayınlamanız gerekiyorsa güncelleme sırasında verileri otomatik olarak taşıma

Kısa süreli yaşam döngüsü etkinlik işleyicileri

Göreviniz maksimum Cloud Functions süresi (birinci nesil API'yi kullanarak 9 dakika) içinde tamamen çalışabiliyorsa yaşam döngüsü etkinlik işleyicinizi, görev kuyruğu onDispatch etkinliğinde tetiklenen tek bir işlev olarak yazabilirsiniz:

export const myTaskFunction = functions.tasks.taskQueue()
  .onDispatch(async () => {
    // Complete your lifecycle event handling task.
    // ...

    // When processing is complete, report status to the user (see below).
  });

Ardından, uzantınızın extension.yaml dosyasında aşağıdakileri yapın:

1. İşlevinizi taskQueueTrigger mülk kümesiyle uzantı kaynağı olarak kaydedin. taskQueueTrigger değerini boş haritaya ({}) ayarlarsanız uzantınız varsayılan ayarları kullanarak bir Cloud Tasks kuyruğu oluşturur. İsterseniz bu ayarları düzenleyebilirsiniz.

   resources:
     - name: myTaskFunction
       type: firebaseextensions.v1beta.function
       description: >-
         Describe the task performed when the function is triggered by a lifecycle
         event
       properties:
         location: ${LOCATION}
         taskQueueTrigger: {}
   

2. İşlevinizi bir veya daha fazla yaşam döngüsü etkinliği için işleyici olarak kaydedin:

   resources:
     - ...
   lifecycleEvents:
     onInstall:
       function: myTaskFunction
       processingMessage: Resizing your existing images
     onUpdate:
       function: myOtherTaskFunction
       processingMessage: Setting up your extension
     onConfigure:
       function: myOtherTaskFunction
       processingMessage: Setting up your extension
   
   

   Aşağıdaki etkinliklerden herhangi biri için işlev kaydedebilirsiniz: onInstall, onUpdate ve onConfigure. Bu etkinliklerin tümü isteğe bağlıdır.

   Not: Burada belirttiğiniz mesaj, işleviniz tetiklendiğinde Firebase konsolunda otomatik olarak uzantınızın işleme durumu şeklinde ayarlanır. İşleviniz çalışmasını tamamladığında işlem durumunu güncellemek veya temizlemek için Raporlama durumu bölümünde açıklandığı gibi setProcessingState() işlevini çağırın.

3. Önerilen: Uzantınızın çalışması için işleme görevi gerekli değilse kullanıcıların bunu etkinleştirip etkinleştirmeyeceğini seçmesine olanak tanıyan kullanıcı tarafından yapılandırılmış bir parametre ekleyin.

   Örneğin, aşağıdaki gibi bir parametre ekleyin:

   params:
     - param: DO_BACKFILL
       label: Backfill existing images
       description: >
         Should existing, unresized images in the Storage bucket be resized as well?
       type: select
       options:
         - label: Yes
           value: true
         - label: No
           value: false
   

   İşlevinizde, parametre false değerine ayarlanırsa erken çıkış yapın:

   export const myTaskFunction = functions.tasks.taskQueue()
     .onDispatch(async () => {
       if (!process.env.DO_BACKFILL) {
         await runtime.setProcessingState(
           "PROCESSING_COMPLETE",
           "Existing images were not resized."
         );
         return;
       }
       // Complete your lifecycle event handling task.
       // ...
     });
   

Uzun süreli görevler gerçekleştirme

Göreviniz maksimum Cloud Functions süresi içinde tamamlanamıyorsa görevi alt görevlere bölün ve Admin SDK'nın TaskQueue.enqueue() yöntemiyle işleri sıraya ekleyerek her alt görevi sırayla gerçekleştirin.

Not: Alt görevlerinizin tamamını aynı anda sıraya ekleyip paralel olarak işlemeye çalışmayın. Yetkilendirme, sıraya ekleme sırasında gerçekleştiği için, sıranın sonundaki görevlerin başlama zamanına kadar yetkilendirmenin süresi dolarsa bu görevler başarısız olur. Bunun yerine, bu bölümde açıklandığı gibi alt görevlerinizi seri olarak gerçekleştirin.

Örneğin, Cloud Firestore verilerini doldurmak istediğinizi varsayalım. Sorgu imleçlerini kullanarak doküman koleksiyonunu parçalara ayırabilirsiniz. Bir parçayı işledikten sonra başlangıç ofsetini ilerletin ve aşağıda gösterildiği gibi başka bir işlev çağrısını sıraya koyun:

import { getFirestore } from "firebase-admin/firestore";
import { getFunctions } from "firebase-admin/functions";

exports.backfilldata = functions.tasks.taskQueue().onDispatch(async (data) => {
  // When a lifecycle event triggers this function, it doesn't pass any data,
  // so an undefined offset indicates we're on our first invocation and should
  // start at offset 0. On subsequent invocations, we'll pass an explicit
  // offset.
  const offset = data["offset"] ?? 0;

  // Get a batch of documents, beginning at the offset.
  const snapshot = await getFirestore()
    .collection(process.env.COLLECTION_PATH)
    .startAt(offset)
    .limit(DOCS_PER_BACKFILL)
    .get();
  // Process each document in the batch.
  const processed = await Promise.allSettled(
    snapshot.docs.map(async (documentSnapshot) => {
      // Perform the processing.
    })
  );

  // If we processed a full batch, there are probably more documents to
  // process, so enqueue another invocation of this function, specifying
  // the offset to start with.
  //
  // If we processed less than a full batch, we're done.
  if (processed.length == DOCS_PER_BACKFILL) {
    const queue = getFunctions().taskQueue(
      "backfilldata",
      process.env.EXT_INSTANCE_ID
    );
    await queue.enqueue({
      offset: offset + DOCS_PER_BACKFILL,
    });
  } else {
      // Processing is complete. Report status to the user (see below).
  }
});

İşlevi, önceki bölümde açıklandığı şekilde extension.yaml'ünüze ekleyin.

Raporlama durumu

Tüm işleme işlevleriniz başarılı bir şekilde veya bir hatayla tamamlandığında Yönetici SDK'sının uzantı çalışma zamanı yöntemlerini kullanarak görevin durumunu bildirin. Kullanıcılar bu durumu Firebase konsolundaki uzantı ayrıntıları sayfasında görebilir.

Not: Durumu yalnızca yaşam döngüsü etkinliği tetikleyicisini her işlediğinizde bir kez raporlayın. Özellikle, işleme görevinizi birden fazla işlev çağrısına bölerseniz her çağrıda durumu bildirmeyin.

Başarılı tamamlama ve önemli olmayan hatalar

Başarılı tamamlama hatalarını ve önemli olmayan hataları (uzantıyı işlevsel olmayan bir duruma getirmeyen hatalar) bildirmek için Yönetici SDK'sının setProcessingState() uzantısı çalışma zamanı yöntemini kullanın:

import { getExtensions } from "firebase-admin/extensions";

// ...

getExtensions().runtime().setProcessingState(processingState, message);

Aşağıdaki durumları ayarlayabilirsiniz:

Önemli olmayan durumlar
PROCESSING_COMPLETE	Görevlerin başarıyla tamamlandığını bildirmek için kullanılır. Örnek: getExtensions().runtime().setProcessingState( "PROCESSING_COMPLETE", `Backfill complete. Successfully processed ${numSuccess} documents.` );
PROCESSING_WARNING	Kısmi başarı bildirmek için kullanın. Örnek: getExtensions().runtime().setProcessingState( "PROCESSING_WARNING", `Backfill complete. ${numSuccess} documents processed successfully.` + ` ${numFailed} documents failed to process. ${listOfErrors}.` + ` ${instructionsToFixTheProblem}` );
PROCESSING_FAILED	Görevin tamamlanmasını engelleyen ancak uzantının kullanılamaz hale gelmesine yol açmayan hataları bildirmek için kullanın. Örnek: getExtensions().runtime().setProcessingState( "PROCESSING_FAILED", `Backfill failed. ${errorMsg} ${optionalInstructionsToFixTheProblem}.` ); Uzantıyı kullanılamaz hale getiren hataları bildirmek için setFatalError() numaralı telefonu arayın.
NONE	Görevin durumunu temizlemek için kullanın. İsteğe bağlı olarak, durum mesajını konsoldan temizlemek için bu seçeneği kullanabilirsiniz (örneğin, PROCESSING_COMPLETE ayarlandıktan sonra belirli bir süre geçtikten sonra). Örnek: getExtensions().runtime().setProcessingState("NONE");

Önemli hatalar

Uzantının çalışmasını engelleyen bir hata oluşursa (örneğin, gerekli bir kurulum görevi başarısız olursa) önemli hatayı setFatalError() ile bildirin:

import { getExtensions } from "firebase-admin/extensions";

// ...

getExtensions().runtime().setFatalError(`Post-installation setup failed. ${errorMessage}`);

Görev sırasını ayarlama

taskQueueTrigger mülkünü {} olarak ayarlarsanız uzantınız, bir uzantı örneği yüklendiğinde varsayılan ayarlarla bir Cloud Görevler sırası oluşturur. Alternatif olarak, belirli değerler sağlayarak görev kuyruğunun eşzamanlılık sınırlarını ve yeniden deneme davranışını ayarlayabilirsiniz:

resources:
  - name: myTaskFunction
    type: firebaseextensions.v1beta.function
    description: >-
      Perform a task when triggered by a lifecycle event
    properties:
      location: ${LOCATION}
      taskQueueTrigger:
        rateLimits:
          maxConcurrentDispatches: 1000
          maxDispatchesPerSecond: 500
        retryConfig:
          maxAttempts: 100  # Warning: setting this too low can prevent the function from running
          minBackoffSeconds: 0.1
          maxBackoffSeconds: 3600
          maxDoublings: 16
lifecycleEvents:
  onInstall: 
    function: myTaskFunction
    processingMessage: Resizing your existing images
  onUpdate:
    function: myTaskFunction
    processingMessage: Setting up your extension
  onConfigure:
    function: myOtherTaskFunction
    processingMessage: Setting up your extension

Bu parametrelerle ilgili ayrıntılar için Google Cloud dokümanlarında Cloud Tasks sıralarını yapılandırma bölümüne göz atın.

Görev sırası parametrelerini taskQueue() parametresine ileterek belirtmeye çalışmayın. Bu ayarlar, extension.yaml'teki yapılandırma ve yapılandırma varsayılanları için yoksayılır.

Örneğin, aşağıdakiler işe yaramaz:

export const myBrokenTaskFunction = functions.tasks
  // DON'T DO THIS IN AN EXTENSION! THESE SETTINGS ARE IGNORED.
  .taskQueue({
    retryConfig: {
      maxAttempts: 5,
      minBackoffSeconds: 60,
    },
    rateLimits: {
      maxConcurrentDispatches: 1000,
      maxDispatchesPerSecond: 10,
    },
  })
  .onDispatch(
    // ...
  );

Uzantının görev sıralarını yapılandırmanın tek yolu, extension.yaml içindeki taskQueueTrigger mülküdür.

Örnekler

Resmi storage-resize-images, firestore-bigquery-export ve firestore-translate-text uzantılarının tümü, verileri doldurmak için yaşam döngüsü etkinlik işleyicilerini kullanır.