Uzantınız, bir uzantı örneği aşağıdaki yaşam döngüsü etkinliklerinden herhangi birine geçtiğinde tetiklenen Cloud Tasks işlevlerini içerebilir:
- Uzantının bir örneği yüklendi
- 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 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 ana işlemi, 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 tüm mevcut görüntülerin 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 uyumsuz değişiklikler yayınlamanız gerekiyorsa güncelleme yapıldığında verileri otomatik olarak taşıyın
Kısa süreli yaşam döngüsü etkinlik işleyicileri
Göreviniz tamamen maksimum Cloud Functions süresi (birinci nesil API kullanılarak 9 dakika) içinde çalışabiliyorsa yaşam döngüsü etkinlik işleyicinizi, görev sırası 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:
İşlevinizi,
taskQueueTrigger
özellik kümesiyle bir uzantı kaynağı olarak kaydedin.taskQueueTrigger
değerini boş haritaya ({}
) ayarlarsanız uzantınız varsayılan ayarları kullanarak bir Cloud Tasks sırası sağlar. Dilerseniz 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: {}
İş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
Şu etkinlikler için işlevleri kaydedebilirsiniz:
onInstall
,onUpdate
veonConfigure
. Bu etkinliklerin tümü isteğe bağlıdır.Ö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örevleri gerçekleştirme
Göreviniz maksimum Cloud Functions süresi içinde tamamlanamazsa görevi alt görevlere bölün ve işleri Yönetici SDK'sının TaskQueue.enqueue()
yöntemiyle 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çleri kullanarak belge 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
öğenize ekleyin.
Raporlama durumu
Tüm işleme işlevleriniz başarılı bir şekilde veya bir hatayla tamamlandığında Yönetici SDK'sinin 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 ö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ö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. Bununla birlikte, uzantıyı kullanılamaz durumda bırakmayın. Örnek: getExtensions().runtime().setProcessingState( "PROCESSING_FAILED", `Backfill failed. ${errorMsg} ${optionalInstructionsToFixTheProblem}.` ); Uzantıyı kullanılmaz bırakan hataları bildirmek için |
NONE |
Görevin durumunu temizlemek için kullanın. İsterseniz bunu konsoldan durum mesajını temizlemek için kullanabilirsiniz (örneğin, 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
özelliğini {}
olarak ayarlarsanız uzantınız, bir uzantı örneği yüklendiğinde 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ı ayarlayabilir ve yeniden deneme davranışını belirleyebilirsiniz:
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()
işlevine ileterek belirtmeye çalışmayın.
Bu ayarlar yok sayılır. Bunun yerine, extension.yaml
yapılandırması ve varsayılan yapılandırmalar kullanılır.
Örneğin, şu komut 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(
// ...
);
extension.yaml
öğesindeki 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.