จัดการเหตุการณ์วงจรชีวิตของส่วนขยายของคุณ

ส่วนขยายของคุณสามารถรวม ฟังก์ชัน Cloud Tasks ที่ทริกเกอร์เมื่ออินสแตนซ์ส่วนขยายผ่านเหตุการณ์วงจรชีวิตใดๆ ต่อไปนี้:

  • มีการติดตั้งอินสแตนซ์ของส่วนขยาย
  • อินสแตนซ์ของส่วนขยายได้รับการอัปเดตเป็นเวอร์ชันใหม่
  • การกำหนดค่าของอินสแตนซ์ส่วนขยายมีการเปลี่ยนแปลง

กรณีการใช้งานที่สำคัญที่สุดประการหนึ่งของคุณลักษณะนี้คือ การทดแทนข้อมูล ตัวอย่างเช่น สมมติว่าคุณกำลังสร้างส่วนขยายที่สร้างภาพตัวอย่างขนาดย่อของรูปภาพที่อัปโหลดไปยังที่เก็บข้อมูล Cloud Storage งานหลักของส่วนขยายของคุณจะดำเนินการในฟังก์ชันที่ทริกเกอร์โดยเหตุการณ์ onFinalize Cloud Storage อย่างไรก็ตาม เฉพาะภาพที่อัปโหลด หลังจาก ติดตั้งส่วนขยายแล้วเท่านั้นที่จะได้รับการประมวลผล ด้วยการรวมฟังก์ชันที่ทริกเกอร์โดยเหตุการณ์วงจรการใช้งาน onInstall ไว้ในส่วนขยายของคุณ คุณสามารถสร้างภาพตัวอย่างขนาดย่อของรูปภาพ ที่มีอยู่ได้ เมื่อติดตั้งส่วนขยายแล้ว

กรณีการใช้งานอื่นๆ ของทริกเกอร์เหตุการณ์วงจรการใช้งานได้แก่:

  • ตั้งค่าหลังการติดตั้งโดยอัตโนมัติ (การสร้างบันทึกฐานข้อมูล การทำดัชนี ฯลฯ)
  • หากคุณต้องเผยแพร่การเปลี่ยนแปลงที่เข้ากันไม่ได้แบบย้อนหลัง ให้ย้ายข้อมูลโดยอัตโนมัติเมื่ออัปเดต

ตัวจัดการเหตุการณ์วงจรการใช้งานระยะสั้น

หากงานของคุณสามารถรันได้อย่างสมบูรณ์ภายใน ระยะเวลาสูงสุดของ Cloud Functions (9 นาทีโดยใช้ API รุ่นแรก) คุณสามารถเขียนตัวจัดการเหตุการณ์วงจรการใช้งานของคุณเป็นฟังก์ชันเดียวที่ทริกเกอร์ในคิวงานในเหตุการณ์ onDispatch :

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).
  });

จากนั้น ในไฟล์ extension.yaml ของส่วนขยาย ให้ดำเนินการดังต่อไปนี้:

  1. ลงทะเบียนฟังก์ชันของคุณเป็นทรัพยากรส่วนขยายด้วยชุดคุณสมบัติ taskQueueTrigger หากคุณตั้ง taskQueueTrigger เป็นแมปว่าง ( {} ) ส่วนขยายของคุณจะจัดเตรียมคิว Cloud Tasks โดยใช้การตั้งค่าเริ่มต้น คุณสามารถเลือก ปรับแต่งการตั้งค่าเหล่านี้ ได้

    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. ลงทะเบียนฟังก์ชันของคุณเป็นตัวจัดการสำหรับเหตุการณ์วงจรชีวิตตั้งแต่หนึ่งเหตุการณ์ขึ้นไป:

    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
    
    

    คุณสามารถลงทะเบียนฟังก์ชันสำหรับเหตุการณ์ใดๆ ต่อไปนี้: onInstall , onUpdate และ onConfigure กิจกรรมทั้งหมดเหล่านี้เป็นทางเลือก

  3. แนะนำ : หากไม่จำเป็นต้องมีงานประมวลผลเพื่อให้ส่วนขยายของคุณทำงานได้ ให้เพิ่ม พารามิเตอร์ที่ผู้ใช้กำหนดค่า ซึ่งให้ผู้ใช้เลือกได้ว่าจะเปิดใช้งานหรือไม่

    ตัวอย่างเช่น เพิ่มพารามิเตอร์ดังต่อไปนี้:

    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
    

    และในฟังก์ชันของคุณ หากตั้งค่าพารามิเตอร์เป็น false ให้ออกก่อน:

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

ปฏิบัติงานที่ใช้เวลานาน

หากงานของคุณไม่เสร็จสมบูรณ์ภายในระยะเวลาสูงสุดของ Cloud Functions ให้แบ่งงานออกเป็นงานย่อยและดำเนินการแต่ละงานย่อยตามลำดับโดยจัดคิวงานด้วยเมธอด TaskQueue.enqueue() ของ Admin SDK

ตัวอย่างเช่น สมมติว่าคุณต้องการทดแทนข้อมูล Cloud Firestore คุณสามารถแบ่งคอลเลกชันเอกสารออกเป็นส่วนๆ ได้โดยใช้ เคอร์เซอร์แบบสอบถาม หลังจากประมวลผลก้อนข้อมูลแล้ว ให้เลื่อนออฟเซ็ตเริ่มต้นและเข้าคิวการเรียกใช้ฟังก์ชันอื่นดังที่แสดงด้านล่าง:

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).
  }
});

เพิ่มฟังก์ชันลงใน extension.yaml ของคุณตามที่อธิบายไว้ใน ส่วนก่อนหน้า

สถานะการรายงาน

เมื่อฟังก์ชันการประมวลผลทั้งหมดของคุณเสร็จสิ้น ไม่ว่าจะสำเร็จหรือมีข้อผิดพลาด ให้รายงานสถานะของงานโดยใช้วิธีรันไทม์ส่วนขยายของ Admin SDK ผู้ใช้สามารถดูสถานะนี้ได้ในหน้ารายละเอียดส่วนขยายในคอนโซล Firebase

ดำเนินการสำเร็จและข้อผิดพลาดที่ไม่ร้ายแรง

หากต้องการรายงานการดำเนินการที่สำเร็จและข้อผิดพลาดที่ไม่ร้ายแรง (ข้อผิดพลาดที่ไม่ทำให้ส่วนขยายอยู่ในสถานะไม่ทำงาน) ให้ใช้วิธีการรันไทม์ส่วนขยาย setProcessingState() ของ Admin SDK:

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

// ...

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

คุณสามารถตั้งค่าสถานะต่อไปนี้:

รัฐที่ไม่เป็นอันตรายถึงชีวิต
PROCESSING_COMPLETE

ใช้เพื่อรายงานความสำเร็จของงาน ตัวอย่าง:

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

ใช้เพื่อรายงานความสำเร็จบางส่วน ตัวอย่าง:

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

ใช้เพื่อรายงานข้อผิดพลาดที่ทำให้งานไม่สำเร็จ แต่อย่าปล่อยให้ส่วนขยายใช้งานไม่ได้ ตัวอย่าง:

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

หากต้องการรายงานข้อผิดพลาดที่ ทำให้ ส่วนขยายใช้งานไม่ได้ ให้โทร setFatalError()

NONE

ใช้เพื่อล้างสถานะของงาน คุณสามารถเลือกใช้เพื่อล้างข้อความสถานะจากคอนโซลได้ (เช่น หลังจากผ่านไประยะหนึ่งนับตั้งแต่ตั้งค่า PROCESSING_COMPLETE ) ตัวอย่าง:

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

ข้อผิดพลาดร้ายแรง

หากมีข้อผิดพลาดเกิดขึ้นซึ่งทำให้ส่วนขยายไม่สามารถทำงานได้ เช่น งานการตั้งค่าที่จำเป็นล้มเหลว ให้รายงานข้อผิดพลาดร้ายแรงด้วย setFatalError() :

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

// ...

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

การปรับแต่งคิวงาน

หากคุณตั้งค่าคุณสมบัติ taskQueueTrigger เป็น {} ส่วนขยายของคุณจะจัดเตรียมคิว Cloud Tasks ด้วยการตั้งค่าเริ่มต้นเมื่อมีการติดตั้งอินสแตนซ์ส่วนขยาย หรือคุณสามารถปรับแต่งขีดจำกัดการทำงานพร้อมกันของคิวงานและลองลักษณะการทำงานอีกครั้งโดยระบุค่าเฉพาะ:

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

ดู กำหนดค่าคิว Cloud Tasks ในเอกสาร Google Cloud สำหรับรายละเอียดเกี่ยวกับพารามิเตอร์เหล่านี้

อย่าพยายามระบุพารามิเตอร์คิวงานโดยส่งต่อไปที่ taskQueue() การตั้งค่าเหล่านี้จะถูกละเว้นเนื่องจากการกำหนดค่าใน extension.yaml และค่าเริ่มต้นของการกำหนดค่า

ตัวอย่างเช่น สิ่งนี้จะไม่ทำงาน:

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

คุณสมบัติ taskQueueTrigger ใน extension.yaml เป็นวิธีเดียวในการกำหนดค่าคิวงานของส่วนขยาย

ตัวอย่าง

storage-resize-images อย่างเป็นทางการ, firestore-bigquery-export และส่วนขยาย firestore-translate-text ล้วนใช้ตัวจัดการเหตุการณ์วงจรชีวิตเพื่อทดแทนข้อมูล