확장 프로그램의 수명 주기 이벤트 처리

확장 프로그램에는 확장 프로그램 인스턴스가 다음 수명 주기 이벤트를 거칠 때 트리거되는 Cloud Tasks 함수가 포함될 수 있습니다.

• 확장 프로그램의 인스턴스가 설치되었습니다.
• 확장 프로그램의 인스턴스가 새 버전으로 업데이트됨
• 확장 인스턴스의 구성이 변경됨

이 기능의 가장 중요한 사용 사례 중 하나는 데이터 백필 입니다. 예를 들어 Cloud Storage 버킷에 업로드된 이미지의 썸네일 미리보기를 생성하는 확장 프로그램을 구축한다고 가정해 보겠습니다. 확장 기능의 주요 작업은 onFinalize Cloud Storage 이벤트에 의해 트리거되는 함수에서 수행됩니다. 그러나 확장 프로그램이 설치된 후에 업로드된 이미지만 처리됩니다. 확장 프로그램에 onInstall 수명 주기 이벤트에 의해 트리거되는 기능을 포함하면 확장 프로그램이 설치될 때 기존 이미지의 축소판 미리보기를 생성할 수도 있습니다.

수명 주기 이벤트 트리거의 다른 사용 사례는 다음과 같습니다.

• 설치 후 설정 자동화(데이터베이스 레코드 생성, 인덱싱 등)
• 이전 버전과 호환되지 않는 변경 사항을 게시해야 하는 경우 업데이트 시 자동으로 데이터 마이그레이션

단기 실행 수명 주기 이벤트 핸들러

작업이 최대 Cloud Functions 기간 (1세대 API 사용 시 9분) 내에서 완전히 실행될 수 있는 경우 수명 주기 이벤트 핸들러를 작업 대기열 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 기간 내에 작업을 완료할 수 없는 경우 Admin SDK의 TaskQueue.enqueue() 메서드로 작업을 대기열에 추가하여 작업을 하위 작업으로 나누고 각 하위 작업을 순서대로 수행합니다.

예를 들어 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 콘솔의 확장 프로그램 세부정보 페이지에서 이 상태를 확인할 수 있습니다.

성공적인 완료 및 치명적이지 않은 오류

성공적인 완료 및 치명적이지 않은 오류(확장 프로그램이 작동하지 않는 상태가 되지 않는 오류)를 보고하려면 Admin SDK의 setProcessingState() 확장 프로그램 런타임 메서드를 사용하세요.

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

// ...

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

다음 상태를 설정할 수 있습니다.

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");

치명적인 오류

확장 기능이 작동하지 않는 오류가 발생하는 경우(예: 필수 설정 작업 실패) 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

이러한 매개변수에 대한 자세한 내용은 Google Cloud 문서에서 Cloud Tasks 대기열 구성을 참조하세요.

예

공식 storage-resize-images , firestore-bigquery-export 및 firestore-translate-text 확장 프로그램은 모두 수명 주기 이벤트 핸들러를 사용하여 데이터를 백필합니다.