หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

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

ลงทะเบียนฟังก์ชันของคุณเป็นทรัพยากรส่วนขยายด้วย 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: {}
```
ลงทะเบียนฟังก์ชันเป็นตัวแฮนเดิลสําหรับเหตุการณ์ในวงจรอย่างน้อย 1 เหตุการณ์ ดังนี้
```
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 กิจกรรมทั้งหมดเหล่านี้เป็นตัวเลือก

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

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

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

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() วิธี

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 ส่วนขยายทั้งหมดใช้เครื่องจัดการเหตุการณ์อายุการใช้งานเพื่อทดแทนข้อมูล