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

Uzantınız, bir uzantı örneği aşağıdaki yaşam döngüsü olaylarından herhangi birinden geçtiğinde tetiklenen Bulut Görevleri işlevlerini içerebilir:

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

Bu özelliğin en önemli kullanım durumlarından biri verilerin doldurulmasıdır . Örneğin, bir Cloud Storage paketine yüklenen görüntülerin küçük resim önizlemelerini oluşturan bir uzantı oluşturduğunuzu varsayalım. Uzantınızın asıl işi, onFinalize Cloud Storage olayı tarafından tetiklenen bir işlevde yapılacaktır. Ancak yalnızca uzantı yüklendikten sonra yüklenen resimler işlenir. Uzantınıza onInstall yaşam döngüsü olayı tarafından tetiklenen bir işlevi dahil ederek, uzantı yüklendiğinde mevcut görüntülerin küçük resim önizlemelerini de oluşturabilirsiniz.

Yaşam döngüsü olayı tetikleyicilerinin diğer bazı kullanım durumları şunları içerir:

  • Kurulum sonrası kurulumu otomatikleştirin (veritabanı kayıtları oluşturma, indeksleme vb.)
  • Geriye dönük olarak uyumsuz değişiklikler yayınlamanız gerekiyorsa, verileri güncelleme sırasında otomatik olarak taşıyın

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

Göreviniz maksimum Bulut İşlevleri süresi (birinci nesil API kullanılarak 9 dakika) içinde tamamen çalıştırılabiliyorsa yaşam döngüsü olay işleyicinizi, görev kuyruğunda onDispatch olayını tetikleyen 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. taskQueueTrigger özellik kümesiyle işlevinizi bir uzantı kaynağı olarak kaydedin. taskQueueTrigger boş haritaya ( {} ) ayarlarsanız, uzantınız varsayılan ayarları kullanarak bir Bulut Görevleri kuyruğu hazırlayacaktır; isteğe bağlı olarak bu ayarları yapabilirsiniz.

    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ü olayı 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 olaylardan herhangi biri için işlevleri kaydedebilirsiniz: onInstall , onUpdate ve onConfigure . Bu etkinliklerin tümü isteğe bağlıdır.

  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ılan bir parametre ekleyin.

    Örneğin aşağıdakine benzer 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
    

    Ve fonksiyonunuzda parametre false olarak ayarlanmışsa erken çıkı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üren görevleri gerçekleştirmek

Göreviniz maksimum Bulut İşlevleri 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 alarak her bir alt görevi sırayla gerçekleştirin.

Örneğin Cloud Firestore verilerini doldurmak istediğinizi varsayalım. Sorgu imleçlerini kullanarak belge koleksiyonunu parçalara bölebilirsiniz. Bir yığını işledikten sonra, başlangıç ​​uzaklığını ilerletin ve aşağıda gösterildiği gibi başka bir işlev çağrısını 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).
  }
});

Önceki bölümde açıklandığı gibi işlevi extension.yaml dosyanıza 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ılı tamamlama ve ölümcül olmayan hatalar

Başarılı tamamlamayı 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:

Ölümcül olmayan durumlar
PROCESSING_COMPLETE

Görevin başarıyla tamamlandığını bildirmek için kullanın. Örnek:

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

Kısmi başarıyı 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 hataları bildirmek için kullanın ancak uzantıyı kullanılamaz durumda bırakmayın. Örnek:

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

Uzantıyı kullanılamaz duruma getiren hataları bildirmek için setFatalError() öğesini çağırın.

NONE

Görevin durumunu temizlemek için kullanın. Durum mesajını konsoldan temizlemek için isteğe bağlı olarak bunu kullanabilirsiniz (örneğin, PROCESSING_COMPLETE ayarının üzerinden belli 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örevinin başarısız olması), ölümcül hatayı setFatalError() ile bildirin:

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

// ...

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

Görev kuyruğunu ayarlama

taskQueueTrigger özelliğini {} olarak ayarlarsanız uzantınız, bir uzantı örneği yüklendiğinde varsayılan ayarlarla bir Bulut Görevleri kuyruğunun temel hazırlığını yapar. Alternatif olarak, belirli değerleri sağlayarak görev kuyruğunun eşzamanlılık sınırlarını ayarlayabilir ve davranışı yeniden deneyebilirsiniz:

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 belgelerindeki Bulut Görevleri sıralarını yapılandırma konusuna bakın.

Görev kuyruğu parametrelerini taskQueue() işlevine ileterek belirtmeye çalışmayın. Bu ayarlar, extension.yaml dosyasındaki yapılandırma ve yapılandırma varsayılanları lehine göz ardı edilir.

Örneğin, bu işe yaramayacak:

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 dosyasındaki 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ü olay işleyicilerini kullanır.