확장 프로그램에 사용자 후크 추가

확장 프로그램을 설치한 사용자에게 자체 커스텀 로직을 확장 프로그램 실행에 삽입할 수 있는 기능을 제공할 수 있습니다. 여기에는 두 가지 방법이 있습니다.

  • Eventarc 이벤트: 사용자에게 이벤트에 비동기식으로 반응하는 방법을 제공하려면 Eventarc에 게시하면 됩니다. 예를 들어 장기 실행 태스크가 완료된 후 알림을 전송하는 이벤트 핸들러 함수를 배포하거나 자체 후처리 함수를 정의할 수 있습니다.

  • 동기식 후크: 확장 프로그램에 차단 로직을 추가하는 방법을 사용자에게 제공하려면 확장 프로그램 작업의 사전 정의된 지점에 동기식 후크를 추가하면 됩니다. 이 지점에서 사용자 제공업체 함수를 실행하고 완료 후에만 계속합니다. 전처리 태스크가 종종 이 카테고리에 속합니다.

확장 프로그램에서는 두 가지 방법 중 하나 또는 둘 다 사용할 수 있습니다.

Eventarc 이벤트

확장 프로그램에서 이벤트를 게시하는 방법은 다음과 같습니다.

  1. extension.yaml 파일에 게시할 이벤트 유형을 선언합니다.

    events:
  - type: publisher-id.extension-name.version.event-name
    description: event-description
  - type: publisher-id.extension-name.version.another-event-name
    description: another-event-description

    type 식별자는 점으로 구분된 여러 필드로 구성됩니다. 게시자 ID, 확장 프로그램 이름, 이벤트 이름 필드는 필수 필드입니다. 버전 필드는 권장 필드입니다. 게시하는 이벤트 유형마다 고유하고 구체적인 이벤트 이름을 선택합니다.

    예를 들어 storage-resize-images 확장 프로그램은 단일 이벤트 유형을 선언합니다.

    events:
  - type: firebase.extensions.storage-resize-images.v1.complete
    description: |
      Occurs when image resizing completes. The event will contain further
      details about specific formats and sizes.

    사용자는 확장 프로그램을 설치할 때 구독할 이벤트를 선택할 수 있습니다.

  2. 확장 프로그램 함수의 Admin SDK에서 Eventarc API를 가져오고 사용자의 설치 설정을 사용하여 이벤트 채널을 초기화합니다. 이러한 설정은 다음 환경 변수를 사용하여 표시됩니다.

    • EVENTARC_CHANNEL: 사용자가 이벤트를 게시하기로 선택한 Eventarc 채널의 정규화된 이름입니다.
    • EXT_SELECTED_EVENTS: 사용자가 게시하기 위해 선택한 이벤트 유형을 쉼표로 구분한 목록입니다. 이 값으로 채널을 초기화하면 Admin SDK는 사용자가 선택하지 않은 이벤트를 자동으로 필터링합니다.
    • EVENTARC_CLOUD_EVENT_SOURCE: Cloud 이벤트 소스 식별자입니다. Admin SDK는 게시된 이벤트의 source 필드에 이 값을 자동으로 전달합니다. 일반적으로 이 변수는 명시적으로 사용하지 않아도 됩니다.

    설치 시 이벤트가 사용 설정되지 않은 경우 이러한 변수가 정의되지 않습니다. 이벤트가 사용 설정된 경우에만 이 사실을 사용하여 이벤트 채널을 초기화할 수 있습니다.

    import * as admin from "firebase-admin";
import {getEventarc} from 'firebase-admin/eventarc';

admin.initializeApp();

// Set eventChannel to a newly-initialized channel, or `undefined` if events
// aren't enabled.
const eventChannel =
  process.env.EVENTARC_CHANNEL &&
  getEventarc().channel(process.env.EVENTARC_CHANNEL, {
    allowedEventTypes: process.env.EXT_SELECTED_EVENTS,
  });

  3. 사용자에게 표시할 확장 프로그램의 지점에서 채널에 이벤트를 게시합니다. 예를 들면 다음과 같습니다.

    // If events are enabled, publish a `complete` event to the configured
// channel.
eventChannel && eventChannel.publish({
    type: 'firebase.extensions.storage-resize-images.v1.complete',
    subject: filename,  // the name of the original file
    data: {
      // ...
    }
});

  4. 게시하는 이벤트를 PREINSTALL 또는 POSTINSTALL 파일에 문서화합니다.

    각 이벤트에 대해 다음 사항을 문서화합니다.

    • 사용 목적
    • 확장 프로그램 로직에서 실행되는 지점
    • 포함된 출력 데이터
    • 실행 조건

    또한 동일한 확장 프로그램을 트리거하여 무한 루프가 발생할 수 있는 작업을 이벤트 핸들러에서 수행하지 않도록 사용자에게 경고합니다.

확장 프로그램에서 이벤트를 게시하면 사용자가 이벤트 핸들러를 배포하여 커스텀 로직으로 응답할 수 있습니다.

예를 들어 다음 예시에서는 이미지 크기를 조절한 후 원본 이미지를 삭제합니다. 이 예시 핸들러는 이벤트의 subject 속성(이 경우 이미지의 원래 파일 이름)을 사용합니다.

exports.onimageresized = onCustomEventPublished(
    "firebase.extensions.storage-resize-images.v1.complete",
    (event) => {
      logger.info("Received image resize completed event", event);
      // For example, delete the original.
      return admin.storage()
          .bucket("my-project.appspot.com")
          .file(event.subject)
          .delete();
    });

자세한 내용은 커스텀 이벤트 트리거를 참조하세요.

예

공식 이미지 크기 조절 확장 프로그램은 이미지 크기를 조절한 후 Eventarc에 게시하여 비동기식 후크를 제공합니다.

동기식 후크

확장 프로그램 함수 중 하나가 제대로 작동하도록 하는 후크를 사용자에게 제공하려면 동기식 후크를 사용합니다.

동기식 후크는 사용자 정의 HTTPS 호출 가능 Cloud 함수를 호출하고 완료될 때까지(반환된 값이 있을 수 있음) 대기합니다. 사용자 제공 함수에 오류가 발생하면 확장 프로그램 함수에서 오류가 발생합니다.

동기식 후크를 노출하는 방법은 다음과 같습니다.

  1. 사용자가 커스텀 Cloud 함수 URL로 확장 프로그램을 구성할 수 있도록 확장 프로그램에 매개변수를 추가합니다. 예를 들면 다음과 같습니다.

    - param: PREPROCESSING_FUNCTION
  label: Pre-processing function URL
  description: >
    An HTTPS callable function that will be called to transform the input data
    before it is processed by this function.
  type: string
  example: https://us-west1-my-project-id.cloudfunctions.net/preprocessData
  required: false

  2. 확장 프로그램에서 후크를 노출하려는 지점에 URL을 사용하여 함수를 호출합니다. 예를 들면 다음과 같습니다.

    const functions = require('firebase-functions');
const fetch = require('node-fetch');

const preprocessFunctionURL = process.env.PREPROCESSING_FUNCTION;

exports.yourFunctionName = functions.firestore.document("collection/{doc_id}")
    .onWrite((change, context) => {
      // PREPROCESSING_FUNCTION hook begins here.
      // If a preprocessing function is defined, call it before continuing.
      if (preprocessFunctionURL) {
        try {
          await fetch(preprocessFunctionURL); // Could also be a POST request if you want to send data.
        } catch (e) {
          // Preprocessing failure causes the function to fail.
          functions.logger.error("Preprocessor error:", e);
          return;
        }
      }
      // End of PREPROCESSING_FUNCTION hook.

      // Main function logic follows.
      // ...
    });

  3. PREINSTALL 또는 POSTINSTALL 파일에서 사용 가능한 후크를 문서화합니다.

    각 후크에 대해 다음을 문서화합니다.

    • 사용 목적
    • 확장 프로그램 로직에서 실행되는 지점
    • 예상되는 입력 및 출력
    • 실행 조건(또는 옵션)

    또한 동일한 확장 프로그램을 트리거하여 무한 루프가 발생할 수 있는 작업을 후크 함수에서 수행하지 않도록 사용자에게 경고합니다.

예

Algolia 검색 확장 프로그램은 Algolia에 작성하기 전에 사용자 제공 변환 함수를 호출하기 위한 동기식 후크를 제공합니다.