Firebase 확장 프로그램 설치

Firebase Console, Firebase CLI(명령줄 인터페이스) 또는 자동 생성된 SDK를 사용하여 공식 Firebase 확장 프로그램을 설치하고 관리할 수 있습니다.

각 설치 방법에서 지원되는 작업의 차이점을 검토하세요.

Firebase Console Firebase CLI 자동 생성 SDK

자동 생성된 SDK를 사용한 설치는 확장 프로그램을 설치하고 관리하는 새로운 옵션입니다. 이 옵션을 사용하면 CLI를 사용하여 특정 확장 프로그램 버전의 Node SDK를 자동으로 생성할 수 있으며, 이 SDK는 JavaScript 또는 TypeScript Cloud Functions에서 일반 종속 항목으로 가져올 수 있습니다.

이 자동 생성 SDK에는 다음이 포함됩니다.

• 확장 프로그램의 파라미터를 나타내는 인터페이스와 대부분의 기본이 아닌 파라미터 유형에 관한 유형 선언
• 확장 프로그램의 인스턴스를 초기화하는 생성자 함수
• 확장 프로그램에서 내보낸 모든 이벤트의 Eventarc 트리거가 포함된 확장 프로그램 클래스

확장 프로그램 SDK를 생성하면 확장 프로그램의 모든 구성이 코드에서 이루어집니다.

이 설치 옵션을 사용하면 특히 확장 프로그램 외부에 정의된 Cloud Functions가 포함된 프로젝트에서 여러 확장 프로그램 인스턴스의 관리를 크게 간소화할 수 있습니다.

Firebase Extension을 처음 사용할 때는 테스트 또는 개발 프로젝트에 확장 프로그램을 설치하는 것이 좋습니다.

확장 프로그램을 설치하거나 관리하려면 소유자 또는 편집자나 Firebase 관리자 역할 중 하나를 할당받아야 합니다.

확장 프로그램을 설치하려면 프로젝트에서 사용한 만큼만 지불하는 Blaze 요금제를 이용해야 합니다. 확장 프로그램 설치에는 요금이 청구되지 않지만 사용량이 서비스 무료 등급을 초과하면 Cloud Secret Manager과 같은 Firebase 서비스나 Cloud 서비스 사용에 대한 요금이 청구될 수 있습니다.

시작하기 전에

1. 아직 추가하지 않은 경우 프로젝트에 Firebase를 추가합니다.

2. 사용한 만큼만 지불하는 Blaze 요금제로 프로젝트를 아직 업그레이드하지 않은 경우 업그레이드합니다.

3. 최신 버전의 Firebase CLI를 설치하거나 업데이트합니다.

4. Firebase 프로젝트 ID 또는 이전에 구성된 프로젝트 별칭을 기록해 둡니다.

   • 프로젝트 ID — 컴퓨터의 어느 위치에서든 firebase projects:list를 실행합니다.
   • 프로젝트 별칭 — 로컬 앱 디렉터리에서 firebase use를 실행합니다.
   참고: CLI 명령어를 사용하여 확장 프로그램을 설치하고 관리하려면 로컬 앱 디렉터리와 연결된 Firebase 프로젝트가 있어야 합니다. 아직 로컬 Firebase 디렉터리를 설정하지 않은 경우 firebase init를 실행하여 설정합니다.

1단계: 확장 프로그램에 대한 자세한 정보 보기

이 단계는 선택사항이지만 적극 권장됩니다.

Firebase Extension을 설치하기 전에 다음을 포함한 확장 프로그램에 대한 자세한 정보를 검토하는 것이 좋습니다.

• 확장 프로그램의 작동 방식, 설치 전 작업, 확장 프로그램에 관한 세부정보
• 일반 식별 정보 및 설명
• 확장 프로그램의 작업을 수행하는 데 결제 계정이 필요한지 여부
• 작업에 필요한 Google 서비스(API) 및 액세스 역할
• 확장 프로그램용으로 생성된 리소스(예: 함수)
• 사용자가 구성할 수 있는 매개변수에 대한 설명

확장 프로그램의 세부정보를 보는 방법은 다음과 같습니다.

1. 환경을 설정하고 확장 프로그램을 선택했는지 확인합니다.

2. 컴퓨터의 어느 위치에서든 다음 확장 프로그램 정보 명령어를 실행합니다.

   firebase ext:info publisher-id/extension-id

   publisher-id 및 extension-id 인수는 필수 항목이며 확장 프로그램의 사전 설치 세부정보 페이지에서 확인할 수 있습니다.

참고: 확장 프로그램 디렉터리에 포함된 README에서도 이 세부정보를 볼 수 있습니다.

2단계: 확장 프로그램 설치

설치하기 전에 확장 프로그램의 기본 사양(예: 사용 설정된 API, 생성된 리소스, 부여된 액세스 권한 등) 및 결제 요구사항을 검토하세요.

계속하기 전에 환경을 설정하고 확장 프로그램을 선택했는지 확인합니다.

Firebase용 Cloud Functions 초기화

새 프로젝트를 시작하거나 프로젝트에서 아직 Firebase용 Cloud Functions를 사용하지 않는 경우 init functions를 실행합니다.

cd your-project
firebase init functions

함수 언어로 TypeScript 또는 JavaScript를 선택합니다.

프로젝트에 이미 Cloud Functions가 초기화된 경우 firebase-functions 패키지의 버전 5.1.0 이상을 사용하고 있는지 확인합니다.

cd your-project/functions
npm upgrade --save firebase-functions

ESLint를 사용하는 경우 생성된 SDK를 구성(.eslintrc.js)에서 제외하는 것이 좋습니다.

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

확장 프로그램 SDK 생성

로컬 Firebase 디렉터리에서 ext:sdk:install 명령어를 실행합니다.

firebase ext:sdk:install publisher-id/extension-id@version

예를 들어 firestore-send-email 확장 프로그램의 버전 0.1.34를 설치하려면 다음을 실행합니다.

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

publisher-id 및 extension-id는 필수 항목이며 extensions.dev의 확장 프로그램 사전 설치 세부정보 페이지에서 확인할 수 있습니다. @version 부분은 선택사항입니다. 생략하면 도구에서 최신 버전을 설치합니다.

지정할 수 있는 옵션에는 두 가지가 있습니다.

• --force: 추가 확인 없이 다음 작업을 모두 실행합니다.

  • 동일한 확장 프로그램 및 버전에 대해 이미 SDK가 생성된 경우에도 SDK를 자동 생성합니다.
  • Cloud Functions 노드 프로젝트에 자동 생성된 SDK 패키지를 설치합니다.

• --codebase: SDK를 추가할 코드베이스의 이름입니다. 지정하지 않으면 이 명령어는 SDK를 기본 코드베이스인 functions에 추가합니다.

이 명령어는 확장 프로그램용으로 자동 생성된 SDK가 포함된 노드 패키지를 만들고 프로젝트의 Cloud Functions 코드베이스 중 하나에 추가합니다. 기본 코드베이스(functions)에서 SDK는 다음 위치에 저장됩니다.

functions/generated/extensions/publisher-id/extension-id/version

SDK를 생성하면 Cloud Functions 노드 프로젝트에도 SDK를 설치할지 묻는 메시지가 표시됩니다. 이 메시지에 예라고 답합니다.

확장 프로그램 인스턴스 구성

확장 프로그램을 구성하려면 SDK를 가져오고 설치하려는 각 확장 프로그램 인스턴스에 대해 생성자 함수를 호출하여 프로젝트 고유 인스턴스 ID와 확장 프로그램에 필요한 구성 파라미터를 전달합니다.

1. Cloud Functions 소스에서 ext:sdk:install 명령어로 출력된 문을 사용하여 생성자를 가져옵니다.

   TypeScript

   예를 들어 firestore-send-email 확장 프로그램용 SDK를 생성한 경우 import 문은 다음과 같이 표시됩니다.

   import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";
   

   확장 프로그램에 비밀번호와 같은 보안 비밀 값이 필요한 경우 Cloud Functions SDK의 defineSecret 함수도 필요합니다.

   import { defineSecret } from "firebase-functions/params";
   

   JavaScript

   예를 들어 firestore-send-email 확장 프로그램용 SDK를 생성한 경우 require 문은 다음과 같이 표시됩니다.

   const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");
   

   확장 프로그램에 비밀번호와 같은 보안 비밀 값이 필요한 경우 Cloud Functions SDK의 defineSecret 함수도 필요합니다.

   const { defineSecret } = require('firebase-functions/params');
   

2. 구성하려는 각 인스턴스에 대해 생성자 함수를 호출하고 결과를 내보냅니다.

   각 인스턴스에 소문자, 숫자, 하이픈만 포함된 고유 ID를 지정합니다.

   TypeScript

   export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
       SMTP_CONNECTION_URI: "smtps://[e-mail]@smtp.example.com:465",
       SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
       MAIL_COLLECTION: "mail",
       DEFAULT_FROM: "ExampleCo <[e-mail]>",
       TTL_EXPIRE_VALUE: "1",
       TTL_EXPIRE_TYPE: "day",
   });
   

   JavaScript

   exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
       SMTP_CONNECTION_URI: "smtps://[e-mail]@smtp.example.com:465",
       SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
       MAIL_COLLECTION: "mail",
       DEFAULT_FROM: "ExampleCo <[e-mail]>",
       TTL_EXPIRE_VALUE: "1",
       TTL_EXPIRE_TYPE: "day",
   });
   

   보안 비밀 값은 defineSecret 함수를 사용하여 지정해야 합니다.

3. 그런 다음 구성한 확장 프로그램을 배포하려면 다음을 실행합니다.

   firebase deploy --only functions --project=projectId-or-alias

   일반적인 모든 Cloud Functions 배포 옵션이 적용됩니다. 예를 들어 특정 코드베이스에서 단일 확장 프로그램 인스턴스를 배포하려면 다음 단계를 따르세요.

   firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

   참고: 시스템에서 확장 프로그램을 설치하고 프로비저닝하는 데 3~5분 정도 걸릴 수 있습니다.

3단계: 설치 후 설정 완료

일부 확장 프로그램의 경우 확장 프로그램을 사용하기 전에 완료해야 하는 단계(필수 또는 선택사항)가 있습니다. Firebase 콘솔의 Extensions 대시보드에 있는 확장 프로그램의 설치 후 세부정보 페이지에서 이러한 안내를 확인합니다. 대시보드와 연결된 특정 링크는 설치 후 터미널에 표시됩니다.

확장 프로그램의 소스 디렉터리에 포함된 POSTINSTALL.md 파일에서도 이러한 안내를 확인할 수 있습니다.

Firebase 리소스 만들기

아직 존재하지 않는 Firebase 리소스(Cloud Firestore 컬렉션, Realtime Database 경로, Cloud Storage 버킷)를 사용하도록 확장 프로그램을 구성한 경우 확장 프로그램을 사용하기 전에 먼저 만듭니다.

Eventarc 이벤트 핸들러 만들기

일부 확장 프로그램은 실행 중에 중요한 이벤트가 발생하면 Eventarc에 게시됩니다. 확장 프로그램에서 이벤트를 게시하는 경우 이러한 이벤트에 반응하는 함수를 자체 커스텀 로직으로 작성할 수 있습니다. 이 방식은 예를 들어 장기 실행 작업이 완료될 때 사용자에게 알리거나 확장 함수의 출력을 후처리하는 데 유용할 수 있습니다.

확장 프로그램에서 내보낸 이벤트의 핸들러를 정의하려면 각 인스턴스의 트리거 메서드를 사용하면 됩니다.

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

확장 프로그램 인스턴스와 함께 이벤트 핸들러를 내보내야 합니다.

이벤트 핸들러를 정의한 후, 그리고 이벤트 핸들러를 변경할 때마다 확장 프로그램과 핸들러를 모두 재배포합니다.

중요: 이벤트를 사용 설정하면 무료 할당량을 초과할 경우 요금이 부과될 수 있습니다. Eventarc 가격 책정을 참조하세요.

여러 확장 프로그램 인스턴스 설치

동일한 프로젝트에 동일한 확장 프로그램을 두 번 이상 설치할 수 있습니다. 설치된 각 인스턴스에는 고유한 커스텀 구성과 자체 확장 리소스가 있을 수 있습니다. 설치된 각 인스턴스는 프로젝트 내에서 고유한 인스턴스 ID를 사용하여 식별하고 참조할 수 있습니다.

설치하고 구성하려는 인스턴스마다 생성된 SDK의 생성자 함수를 한 번씩 호출합니다.

다음 단계

• Firebase 콘솔에서 설치된 확장 프로그램의 세부정보 및 구성을 확인합니다.

• 설치된 확장 프로그램의 상태, 사용량, 로그를 확인하는 등 활동을 모니터링합니다.

• Firebase 콘솔을 사용하여 설치된 확장 프로그램을 관리합니다. 공식 Firebase 확장 프로그램의 경우 확장 프로그램을 다시 구성하거나 제거하고 최신 버전으로 업데이트할 수 있습니다.

• 모든 프로젝트에 대한 권장사항은 Firebase 콘솔에서 프로젝트의 예산 알림을 설정하고 사용량 및 결제 대시보드를 모니터링하는 것입니다.