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

Uzantınız, bir uzantı örneği aşağıdaki yaşam döngüsü etkinliklerinden herhangi birini geçirdiğinde tetiklenen Cloud Tasks işlevler içerebilir:

• Uzantının bir örneği yüklü olmalıdır.
• Uzantının bir örneği yeni sürüme güncellendiğinde
• 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 işlevi, onFinalize Cloud Storage etkinliği tarafından tetiklenen bir işlevde gerçekleştirilir. 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 bazı kullanım alanları şunlardır:

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

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

Göreviniz maksimum Cloud Functions süre (birinci nesil API ile 9 dakika) içinde tamamen çalıştırılabiliyorsa yaşam döngüsü etkinliği 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özellik grubuylataskQueueTrigger uzantı kaynağı olarak kaydedin. taskQueueTrigger değerini boş harita ({}) olarak ayarlarsanız uzantınız, varsayılan ayarları kullanarak bir Cloud Tasks sırası oluşturur. İsteğe bağlı olarak 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ğinin işleyicisi 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
   
   

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

3. Önerilen: İşleme görevinin uzantınızın çalışması için gerekli olmaması durumunda, kullanıcıların etkinleştirip etkinleştirmeyeceklerini seçmelerine olanak tanıyan kullanıcı tarafından yapılandırılan 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
   

   Ayrıca işlevinizde parametre false olarak ayarlanmışsa 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örevleri gerçekleştirme

Görevleriniz maksimum Cloud Functions süre içinde tamamlanamıyorsa görevi alt görevlere ayırın ve her alt görevi sırayla gerçekleştirin. Bunu yapmak için Admin SDK'nın TaskQueue.enqueue() yöntemini kullanarak işleri sıraya alın.

Ö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ıç uzaklığını ilerletin ve aşağıdaki örnekte gösterildiği gibi başka bir işlev çağrısı sıraya alın:

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 ekleyin.

Raporlama durumu

Tüm işleme işlevleriniz başarıyla veya hatayla tamamlandığında, Admin SDK'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.

Başarıyla tamamlanma ve önemli olmayan hatalar

Başarılı tamamlanmayı ve önemli olmayan hataları (uzantıyı işlevsiz duruma getirmeyen hatalar) bildirmek için Admin SDK'nın setProcessingState() uzantı çalışma zamanı yöntemini kullanın:

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

// ...

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

Aşağıdaki durumları ayarlayabilirsiniz:

getExtensions().runtime().setProcessingState(
  "PROCESSING_COMPLETE",
  `Backfill complete. Successfully processed ${numSuccess} documents.`
);

getExtensions().runtime().setProcessingState(
  "PROCESSING_WARNING",
  `Backfill complete. ${numSuccess} documents processed successfully.`
    + ` ${numFailed} documents failed to process. ${listOfErrors}.`
    + ` ${instructionsToFixTheProblem}`
);

getExtensions().runtime().setProcessingState(
  "PROCESSING_FAILED",
  `Backfill failed. ${errorMsg} ${optionalInstructionsToFixTheProblem}.`
);

getExtensions().runtime().setProcessingState("NONE");

Önemli hatalar

Uzantının çalışmasını engelleyen bir hata oluşursa (ör. gerekli bir kurulum görevi başarısız olursa) setFatalError() ile ölümcül hatayı bildirin:

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

// ...

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

Görev sırasını ayarlama

taskQueueTrigger özelliğini {} olarak ayarlarsanız uzantı örneği yüklendiğinde uzantınız varsayılan ayarlarla bir Cloud Tasks sırası sağlar. Alternatif olarak, belirli değerler sağlayarak görev sırasının 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ındaki Cloud Tasks sıralarını yapılandırma bölümüne bakın.

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

Örneğin, bu yöntem çalışmaz:

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(
    // ...
  );

extension.yaml içindeki taskQueueTrigger özelliği, bir uzantının görev sıralarını yapılandırmanın tek yoludur.

Ö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.