확장 프로그램에서 매개변수 설정 및 사용

매개변수는 사용자가 확장 프로그램의 설치된 각 인스턴스를 맞춤설정하는 데 사용하는 메커니즘입니다. 매개변수는 확장 프로그램의 환경 변수와 같습니다. 매개변수 값은 자동 입력 값(설치 후 Firebase에서 제공) 또는 사용자 구성 값(설치 중 사용자가 지정)입니다.

이러한 매개변수는 확장 프로그램의 함수 소스 코드, extension.yaml 파일, POSTINSTALL.md 파일에서 참조할 수 있습니다. 다음은 PARAMETER_NAME이라는 매개변수를 참조하는 방법에 대한 구문입니다.

• 함수 소스 코드 내에서 params 모듈(예: params.defineInt("PARAMETER_NAME")) 또는 process.env.PARAMETER_NAME을 사용합니다.

• extension.yaml 및 POSTINSTALL.md 내에서 ${param:PARAMETER_NAME}을 사용합니다.

  설치 후 Firebase 콘솔은 POSTINSTALL.md 파일의 콘텐츠를 표시하고 설치된 인스턴스의 실제 값으로 매개변수 참조를 채웁니다.

자동 입력 매개변수

확장 프로그램의 설치된 각 인스턴스는 Firebase에서 제공하는 여러 가지 기본 자동 입력 매개변수에 자동으로 액세스할 수 있습니다(아래 표 참조). 이러한 매개변수 값은 Firebase 프로젝트의 기본 값(예: 기본 Storage 버킷)이거나 확장 프로그램 관련 값(예: 확장 프로그램의 인스턴스 ID)입니다.

모든 자동 입력 매개변수 값은 변경할 수 없습니다. 프로젝트를 만들거나 확장 프로그램을 설치할 때 설정됩니다.

팁: Realtime Database와 Cloud Storage는 모두 단일 Firebase 프로젝트에 여러 데이터베이스 인스턴스와 버킷을 각각 허용합니다. 따라서 사용자가 확장 프로그램에서 프로젝트의 기본 인스턴스 또는 버킷을 사용하기를 원한다고 가정하지 않고, 사용자에게 확장 프로그램이 어떤 인스턴스나 버킷을 사용할지 지정하라는 메시지를 표시하도록 사용자 구성 매개변수를 설정하는 것이 좋습니다.

Firebase는 확장 프로그램에 이러한 매개변수 값을 자동으로 입력하지만 Firebase는 설치 중에 사용자를 위해 연결된 제품을 자동 프로비저닝하지 않습니다. 확장 프로그램을 설치하는 사용자는 설치하기 전에 프로젝트에 연결된 관련 제품을 사용 설정해야 합니다. 예를 들어 확장 프로그램이 Cloud Firestore와 관련된 경우 사용자가 프로젝트에 Cloud Firestore를 설정해야 합니다. PREINSTALL.md 파일을 통해 이러한 요구사항을 사용자에게 알리는 것이 좋습니다.

자동 입력 매개변수에 대한 참조	설명	매개변수 값(Firebase가 제공)
Firebase 프로젝트의 기본값이 포함된 매개변수
PROJECT_ID	확장 프로그램이 설치된 Firebase 프로젝트의 고유 식별자	일반적인 형식: project-id 값 예시: project-123
DATABASE_URL	Firebase 프로젝트의 기본 Realtime Database 인스턴스 URL	일반 형식: https://project-id-default-rtdb.firebaseio.com (미국 인스턴스) 또는 https://project-id-default-rtdb.region-code.firebasedatabase.app (미국 이외 인스턴스) 값 예시: https://project-123-default-rtdb.firebaseio.com
DATABASE_INSTANCE	Firebase 프로젝트의 기본 Realtime Database 인스턴스 이름 일반적으로 이 값은 프로젝트 ID와 동일하거나 -default-rtdb로 끝납니다.	일반적인 형식: project-id 값 예시: project-123
STORAGE_BUCKET	Firebase 프로젝트의 기본 Cloud Storage 버킷 이름	일반적인 형식: 값 예시: project-123.firebasestorage.app
확장 프로그램 설치의 기본값이 포함된 매개변수
EXT_INSTANCE_ID	설치된 확장 프로그램 인스턴스의 고유 식별자 이 값은 extension.yaml 파일에 지정된 name 필드를 통해 생성됩니다.	첫 번째로 설치된 인스턴스의 일반적인 형식(Firebase에서 자동으로 할당, 설치 중 사용자가 수정 불가) name-from-extension.yaml 값 예시: my-awesome-extension 두 번째 이후로 설치된 인스턴스의 일반적인 형식(Firebase에서 자동으로 할당, 설치 중 사용자가 수정 가능) name-from-extension.yaml-4-digit-alphanumeric-hash 값 예시: my-awesome-extension-6m31

사용자 구성 매개변수

사용자가 확장 프로그램의 설치된 각 인스턴스를 맞춤설정할 수 있도록 하려면 설치 중에 매개변수 값을 지정하라는 메시지를 사용자에게 표시합니다. 이러한 값을 요청하려면 extension.yaml 파일의 params 섹션에 프롬프트를 설정합니다.

params 섹션의 예시는 다음과 같으며, 그 뒤에 사용 가능한 모든 매개변수 필드를 설명하는 테이블이 이어집니다.

# extension.yaml
...

# Parameters (environment variables) for which the user specifies values during installation
params:
  - param: DB_PATH
    label: Realtime Database path
    description: >-
      What is the Realtime Database path where you will write new text
      for sentiment analysis?
    type: string
    validationRegex: ^\S+$
    validationErrorMessage: Realtime Database path cannot contain spaces.
    example: path/to/posts
    required: true

  - param: TEXT_KEY
    label: Key for text
    description: What is the name of the key that will contain text to be analyzed?
    type: string
    default: textToAnalyze
    required: true

extension.yaml 파일의 params 섹션에 다음 필드를 사용하여 사용자 구성 매개변수를 정의합니다.

필드	유형	설명
param (필수)	문자열	매개변수 이름
label (필수)	문자열	매개변수에 대한 간단한 설명 매개변수 값을 입력하라는 메시지가 사용자에게 표시될 때 함께 표시됩니다.
description (선택사항)	문자열	매개변수에 대한 자세한 설명 매개변수 값을 입력하라는 메시지가 사용자에게 표시될 때 함께 표시됩니다. 마크다운 지원
type (선택사항)	문자열	사용자가 매개변수 값을 설정하는 방법에 대한 입력 메커니즘(예: 텍스트를 직접 입력하거나 드롭다운 목록에서 선택) 유효한 값은 다음과 같습니다. string: 자유 형식 텍스트 입력 허용(validationRegex에 의해 제한됨) select: 사전 정의된 옵션 목록에서 1개 항목을 선택할 수 있습니다. 이 값을 지정하는 경우 options 필드도 정의해야 합니다. multiSelect: 사전 정의된 옵션 목록에서 1개 이상의 항목을 선택할 수 있습니다. 이 값을 지정하는 경우 options 필드도 정의해야 합니다. selectResource: 사용자 프로젝트에서 특정 유형의 Firebase 리소스(예: Cloud Storage 버킷)를 선택할 수 있습니다. 이 유형의 매개변수를 지정하면 설치 UI에서 보다 사용자 친화적인 선택 위젯을 사용할 수 있습니다. 그러므로 가능한 한 selectResource 매개변수를 사용하세요. 이 값을 지정하는 경우 resourceType 필드도 정의해야 합니다. secret: 민감한 문자열을 저장할 수 있습니다(예: 서드 파티 서비스용 API 키). 이러한 값은 Cloud Secret Manager에 저장됩니다. Cloud Secret Manager는 유료 서비스이므로 확장 프로그램을 설치하는 사용자에게 요금이 부과될 수 있습니다. secret 매개변수 유형을 사용하는 경우 확장 프로그램에서 Cloud Secret Manager를 사용한다고 PREINSTALL 파일에 문서화해야 합니다. 이 필드를 생략하면 이 매개변수의 type이 기본적으로 string으로 설정됩니다.
options (type 매개변수가 select 또는 multiSelect일 경우 필수)	list	사용자가 선택할 수 있는 값 목록 options 필드 내에 label 및 value 필드를 포함합니다. label(문자열): 선택 가능한 옵션에 대한 간단한 설명 value(문자열): 선택 가능한 옵션의 실제 값 의도치 않은 유형 변환을 방지하려면 이러한 문자열에 따옴표를 사용해야 합니다. options 필드에는 value 필드가 필요합니다. label을 생략하면 목록 옵션이 기본적으로 value를 표시하도록 설정됩니다. 예시 구문 options: - label: value: - label: value: - label: value:
resourceType (type 매개변수가 selectResource일 경우 필수)	문자열	사용자에게 선택하라는 메시지를 표시하는 Firebase 리소스 유형입니다. 현재 Cloud Storage 버킷만 리소스 선택기를 지원합니다. 리소스 유형 유형 ID 버킷 Cloud Storage개 storage.googleapis.com/Bucket 알 수 없는 resourceType 값은 무시되고 UI는 매개변수를 자유 형식 string 입력란으로 렌더링합니다.
example (선택사항)	문자열	매개변수의 예시 값
validationRegex (선택사항) (type 매개변수가 string일 경우에만 해당)	문자열	매개변수의 사용자 구성 값 확인을 위한 정규식 문자열 정규식은 go 라이브러리(RE2)를 사용하여 컴파일됩니다. 유효성 검사에 대한 자세한 내용은 아래의 유효성 검사 및 오류 메시지를 참조하세요.
validationErrorMessage (선택사항)	문자열	validationRegex가 실패할 경우 표시할 오류 메시지 오류 메시지에 대한 자세한 내용은 아래의 유효성 검사 및 오류 메시지를 참조하세요.
default (선택사항)	문자열	사용자가 매개변수 값을 비워 둘 경우에 적용되는 매개변수 기본값 해당하는 경우 default 값에 자동 입력 매개변수 값을 지정할 수 있습니다(예: Resize Images 확장 프로그램의 IMG_BUCKET 매개변수 참조).
required (선택사항)	부울	사용자가 매개변수 값을 입력하라는 메시지가 표시될 때 빈 문자열을 제출할 수 있는지 여부를 정의합니다. required를 생략하면 이 값이 기본적으로 true(필수 매개변수)로 설정됩니다.
immutable (선택사항)	부울	설치 후 사용자가 매개변수 값을 변경할 수 있는지 여부를 정의합니다(예: 확장 프로그램을 재구성하는 경우). immutable을 생략하면 이 값이 기본적으로 false로 설정됩니다. 참고: 확장 프로그램의 배포된 함수에 'location' 매개변수를 정의하는 경우 이 immutable 필드를 해당 매개변수 객체에 포함해야 합니다.

사용자 구성 값의 유효성 검사 및 오류 메시지

type이 string인 매개변수를 설정할 때는 매개변수의 validationRegex 필드를 통해 적절한 정규식 유효성 검사를 정의해야 합니다.

또한 대다수의 확장 프로그램은 일반적으로 데이터베이스 경로 또는 Cloud Storage 버킷 매개변수 값을 요청합니다. 설치, 재구성 또는 업데이트 중에 Extensions 서비스는 매개변수 값 입력 시점에 다음을 확인하지 않는다는 점에 유의하세요.

• 지정된 데이터베이스 또는 Cloud Storage 버킷이 사용자의 Firebase 프로젝트 내에 설정되었는지 여부
• 지정된 데이터베이스 경로가 사용자의 데이터베이스 내에 있는지 여부

그러나 확장 프로그램이 실제로 리소스를 배포할 때 참조된 데이터베이스 또는 Cloud Storage 버킷이 아직 프로젝트에 설정되지 않은 경우 Firebase 콘솔 또는 Firebase CLI에 오류 메시지가 표시됩니다.

사용자가 확장 프로그램을 설치할 때 확장 프로그램이 성공적으로 설치되고 올바르게 작동할 수 있도록 PREINSTALL 파일을 통해 사용자에게 이 요구사항을 알릴 것을 적극 권장합니다.

시스템 매개변수

시스템 매개변수는 확장 프로그램 리소스의 기본 구성을 제어합니다. 이는 리소스 구성을 제어하기 위한 것이므로 함수 코드 내에서 환경 변수로 액세스할 수 없습니다.

일반적으로 extension.yaml에서는 이러한 매개변수에 관해 어느 것도 선언할 필요가 없습니다. 모든 확장 프로그램 인스턴스에 대해 자동으로 정의되며 사용자는 확장 프로그램을 설치할 때 커스텀 값을 설정할 수 있습니다.

그러나 확장 프로그램에 특별한 리소스 요구사항이 있는 경우 extension.yaml에서 리소스 수준별로 특정 값을 설정할 수 있습니다. 이러한 리소스별 구성 설정은 사용자의 확장 프로그램 인스턴스 전체 설정을 재정의합니다. 예를 들면 다음과 같습니다.

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    availableMemoryMb: 1024
- name: normal_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function has no special memory requirements. It will use the
    default value, or the value of `firebaseextension.v1beta.function/memory`
  properties:
    httpsTrigger: {}
    runtime: nodejs18

사용 가능한 시스템 매개변수는 다음과 같습니다.

이름	라벨(인간 친화적)	properties의 해당 필드	설명
firebaseextensions.v1beta.function/location	위치	location	Cloud Functions는 어느 리전에 배포해야 하나요?
firebaseextensions.v1beta.function/memory	함수 메모리	memory	각 함수에 몇 MB의 메모리를 할당해야 하나요?
firebaseextensions.v1beta.function/timeoutSeconds	함수 제한 시간	timeout	제한 시간 전에 함수를 몇 초 동안 실행해야 하나요?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings	VPC 커넥터 이그레스	vpcConnectorEgressSettings	VPC 커넥터가 구성된 경우 발신 트래픽 제어
firebaseextensions.v1beta.function/vpcConnector	VPC 커넥터	vpcConnector	Cloud Functions를 지정된 VPC 커넥터에 연결
firebaseextensions.v1beta.function/minInstances	최소 함수 인스턴스	minInstances	한 번에 실행할 이 함수의 최소 인스턴스 수
firebaseextensions.v1beta.function/maxInstances	최대 함수 인스턴스	maxInstances	한 번에 실행할 수 있는 이 함수의 최대 인스턴스 수
firebaseextensions.v1beta.function/ingressSettings	인그레스 설정	ingressSettings	수신 트래픽이 수신되는 위치 제어
firebaseextensions.v1beta.function/labels	라벨	labels	확장 프로그램의 모든 리소스에 적용할 라벨