extension.yaml에 대한 참조

확장 프로그램의 사양 파일(extension.yaml)은 확장 프로그램의 메타데이터를 포함하고, 확장 프로그램에서 생성한 리소스와 확장 프로그램에 필요한 API 및 액세스를 선언하고, 확장 프로그램에서 제공하는 사용자 구성 매개변수를 정의합니다.

이 페이지의 표에서는 extension.yaml 파일에 사용할 수 있는 필드를 설명합니다.

기본 및 식별 정보

name: your-extension-name
version: 1.0.0         # Semantic versioning (semver)
specVersion: v1beta    # Always "v1beta"
license: Apache-2.0    # Always "Apache-2.0" (required to publish on extensions.dev)
billingRequired: true  # Always "true"

displayName: Your extension name
description: >-
  Description of the extension. (One or two
  sentences.)
icon: icon.png
tags: [tag, anothertag]

sourceUrl: https://github.com/your-org/your-repo   # GitHub repo URL
releaseNotesUrl: https://github.com/your-org/your-repo/blob/main/CHANGELOG.md

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
기본 필드
name
문자열
(필수)

확장 프로그램의 식별자.

소문자, 숫자 및 대시만 포함할 수 있습니다(글자 수 제한 40자).

참고: 이 값은 확장 프로그램의 인스턴스 ID를 생성하는 데 사용되며, 이후 인스턴스 ID는 확장 프로그램의 서비스 계정 이름 및 확장 프로그램 관련 리소스를 생성하는 데 사용됩니다.

version
문자열
(필수)

확장 프로그램의 버전.

semver 버전 관리 방식(예: 1.2.0)을 따라야 합니다.

specVersion
문자열
(필수)

Firebase Extensions 사양의 버전.

현재 값: v1beta

license
문자열
(선택사항)

확장 프로그램의 라이선스.

Apache-2.0을 사용하여 확장 프로그램에 라이선스를 부여해야 합니다.

billingRequired
불리언
(선택사항)

확장 프로그램에서 사용하는 서비스에 유료 등급의 Firebase 결제 계정이 필요한지 여부.

항상 true로 설정합니다.

displayName
문자열
(선택사항)

확장 프로그램의 친숙한 표시 이름(3~5개 단어).

글자 수가 40자(영문 기준)로 제한됩니다.

description
문자열
(선택사항)
확장 프로그램이 수행하는 태스크에 대한 간략한 설명(약 1개 문장).
icon
문자열
(선택사항)

extensions.devFirebase 콘솔에서 확장 프로그램 아이콘으로 사용할 파일.

512x512~1,024x1,024픽셀 크기의 정사각형 PNG 파일이어야 합니다. 파일을 extension.yaml과 동일한 디렉터리에 넣습니다. 하위 디렉터리를 지정할 수 없습니다.

확장 프로그램 아이콘을 디자인할 때는 다음 가이드라인에 유의하세요.

  • 브랜드에 적합한 배경 및 아트워크 색상을 선택합니다.
  • 2가지 색상만 사용하여 아이콘 색상을 단순하게 유지합니다. 여러 색상을 사용하면 아이콘이 시각적으로 부담스러울 수 있습니다.
  • 마찬가지 이유로 아이콘에 그라데이션을 사용하지 마세요. 그라데이션은 크기가 작을 때 구별하기 어렵고 아이콘을 시각적으로 복잡하게 만듭니다.
  • 확장 프로그램의 기능을 전달하는 간단하고 고유한 이미지를 사용합니다.
  • 회사에서 여러 확장 프로그램을 빌드하는 경우 회사 로고를 아이콘으로 사용하지 마세요. 사용자가 확장 프로그램을 구별하기 어려워집니다.
  • 아트워크를 그래픽으로 굵게 표시합니다. 섬세하거나 정교한 아트를 사용하지 마세요. 크기가 작을 때 잘 렌더링되지 않습니다.
  • 확장 프로그램의 기능을 설명하는 단어를 포함하지 마세요. 크기가 작을 때 텍스트를 읽을 수 없는 경우가 많습니다.
tags
문자열 목록
(선택사항)
사용자가 확장 프로그램을 검색하는 데 도움이 되는 태그. 다음 태그는 Extensions Hub의 카테고리에 매핑됩니다. marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
문자열
(선택사항)
확장 프로그램 디렉터리에 액세스할 수 있는 공개 URL.
releaseNotesUrl
문자열
(선택사항)
확장 프로그램의 출시 노트에 액세스할 수 있는 공개 URL.
author
작성자 객체 1개
(선택사항)

확장 프로그램의 기본 작성자 및 담당자.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
작성자 필드
authorName
문자열
(필수)

작성자 이름.

사람, 회사, 조직 등이 될 수 있습니다.

email
문자열
(선택사항)
작성자의 이메일 주소.
url
문자열
(선택사항)
작성자에 대한 정보에 액세스할 수 있는 공개 URL.
contributors
작성자 객체 목록
(선택사항)

확장 프로그램에 기여한 추가 작성자.

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
작성자 필드
authorName
문자열
(필수)

작성자 이름.

사람, 회사, 조직 등이 될 수 있습니다.

email
문자열
(선택사항)
작성자의 이메일 주소.
url
문자열
(선택사항)
작성자에 대한 정보에 액세스할 수 있는 공개 URL.

Firebase API 및 Google Cloud API

이 필드는 확장 프로그램에서 사용하는 Firebase API 및 Google API를 지정합니다. 사용자는 확장 프로그램을 설치할 때 프로젝트에서 이러한 API를 자동으로 사용 설정하도록 선택할 수 있습니다.

apis:
  - apiName: apiname.googleapis.com
    reason: Explanation of why the extension uses this API
  - apiName: anotherapiname.googleapis.com
    reason: Explanation of why the extension uses this API
API 필드
apiName
문자열
(필수)

Google API의 이름

Google Cloud API 라이브러리의 각 API 개요 페이지(예시)에 나열된 서비스 이름 필드와 일치해야 합니다.

reason
문자열
(필수)
확장 프로그램이 이 API를 사용해야 하는 이유에 대한 간략한 설명

IAM 역할

이 필드는 확장 프로그램에 필요한 Cloud IAM 역할을 지정합니다. 확장 프로그램에 프로비저닝된 서비스 계정에는 이러한 역할이 부여됩니다.

지원되는 역할 중 하나만 지정할 수 있습니다.

roles:
  - role: product.role
    reason: Explanation of why the extension needs this level of access
  - role: anotherproduct.role
    resource: projects/${project_id}/resource_type/*
    reason: Explanation of why the extension needs this level of access
역할 필드
role
문자열
(필수)

확장 프로그램이 작동하는 데 필요한 IAM 역할의 이름.

지원되는 역할 중 하나여야 합니다.

reason
문자열
(필수)
확장 프로그램에 이 역할이 부여하는 액세스 권한이 필요한 이유에 대한 간략한 설명
resource
문자열
(선택사항)

역할 범위를 이 리소스로 제한합니다.

생략할 경우 기본값은 projects/${project_id}입니다. 역할 범위 줄이기를 참조하세요.

외부 서비스

이 필드는 확장 프로그램에서 사용하는 Firebase 이외의 서비스와 Google 이외의 서비스(일반적으로 REST API)를 지정합니다. Firebase Extensions 플랫폼은 이러한 서비스를 자동으로 사용 설정하거나 승인할 수 있는 방법을 제공하지 않습니다.

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing
외부 서비스 필드
name
문자열
(필수)
확장 프로그램이 작동하는 데 필요한 외부 서비스의 이름
pricingUri
문자열
(필수)
서비스의 가격 책정 정보 URI

사용자가 구성할 수 있는 매개변수

이 필드는 확장 프로그램에서 사용자가 구성할 수 있는 매개변수를 정의합니다.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What do you want to set PARAM_ID to?
      This is a longer description of the parameter, often phrased as a prompt
      to the user.
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >
      What do you want to set ANOTHER_PARAM_ID to?
      This is a longer description of the parameter.
    example: example-input
    validationRegex: "^[a-zA-Z][a-zA-Z-]*[a-zA-Z]?$"
    validationErrorMessage:
      Must be a hyphen-delimited string of alphabetic characters
    default: default-value
    required: false
    immutable: true
매개변수 필드
param
문자열
(필수)
매개변수의 이름. 이 이름을 사용하여 코드의 매개변수 값을 참조합니다.
label
문자열
(필수)
매개변수에 대한 간단한 설명. 매개변수 값을 입력하라는 메시지가 사용자에게 표시될 때 함께 표시됩니다.
description
문자열
(선택사항)

매개변수에 대한 자세한 설명. 매개변수 값을 입력하라는 메시지가 사용자에게 표시될 때 함께 표시됩니다.

마크다운을 지원합니다.

example
문자열
(선택사항)
매개변수의 예시 값.
default
문자열
(선택사항)
사용자가 매개변수 값을 비워 둘 경우에 적용되는 매개변수 기본값.
validationRegex
문자열
(선택사항)
매개변수의 사용자 구성 값 유효성 검사를 위한 정규 표현식. Google RE2 구문.
validationErrorMessage
문자열
(선택사항)
정규식 유효성 검사에 실패할 경우 표시할 오류 메시지.
required
불리언
(선택사항)
사용자가 매개변수 값을 입력하라는 메시지가 표시될 때 빈 문자열을 제출할 수 있는지 여부를 정의합니다. 기본값은 true입니다.
immutable
불리언
(선택사항)

설치 후 사용자가 매개변수 값을 변경할 수 있는지 여부를 정의합니다(예: 확장 프로그램을 재구성하는 경우). 기본값은 false입니다.

참고: 확장 프로그램의 배포된 함수에 '위치' 매개변수를 정의하는 경우 이 필드를 true로 설정합니다.

type
문자열
(선택사항)
매개변수 유형. 특수 매개변수 유형에는 추가 요구사항 또는 다른 UI 프레젠테이션이 있을 수 있습니다. 다음 섹션을 참조하세요.

선택 가능한 매개변수 및 다중 선택 가능한 매개변수

선택 가능한 매개변수 및 다중 선택 가능한 매개변수는 사용자에게 사전 정의된 옵션 목록에서 선택하라는 메시지를 표시합니다.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Do you want to enable the option?
    type: select
    options:
      - label: Yes
        value: true
      - label: No
        value: false
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >-
      Which options do you want to enable?
    type: multiselect
    options:
      - value: red
      - value: green
      - value: blue
다중 선택 매개변수 필드
type
문자열

select 또는 multiselect

매개변수가 하나의 값(select)인지 아니면 사전 정의된 항목에서 선택된 여러 값(multiselect)인지 지정합니다.

options
옵션 목록
(필수)

사용자가 선택할 수 있는 옵션

옵션 필드
value
문자열
(필수)
사용자가 선택할 수 있는 값 중 하나. 이는 코드에서 매개변수 값을 읽을 때 얻게 되는 값입니다.
label
문자열
(선택사항)
선택 가능한 옵션에 대한 간단한 설명. 생략할 경우 기본값은 value입니다.

선택 가능한 리소스 매개변수

선택 가능한 리소스 매개변수는 사용자에게 프로젝트에서 리소스(데이터베이스 인스턴스, 스토리지 버킷 등)를 선택하라는 메시지를 표시합니다.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Which resource do you want to use?
    type: selectresource
    resourceType: product.googleapis.com/ResourceType
리소스 매개변수 필드
type
문자열

selectresource

매개변수가 프로젝트 리소스를 나타내도록 지정합니다.

resourceType
문자열
(필수)

사용자에게 선택하라는 메시지를 표시하는 리소스 유형.

유효한 값:

  • storage.googleapis.com/Bucket
  • firestore.googleapis.com/Database
  • firebasedatabase.googleapis.com/DatabaseInstance

그러나 현재 Cloud Storage 버킷에만 선택 UI가 있습니다(다른 리소스 유형은 자유 형식 텍스트 입력란으로 표시됨).

보안 비밀 매개변수

사용자가 제공한 보안 비밀 값(예: API 키)은 다르게 처리됩니다.

  • 보안 비밀 값은 Cloud Secret Manager를 사용하여 저장됩니다. 승인된 클라이언트(예: 확장 프로그램의 설치된 인스턴스)만 이러한 값에 액세스할 수 있습니다.
  • 사용자에게 이러한 값을 입력하라는 메시지가 표시될 때 입력 내용은 표시되지 않습니다.
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
보안 비밀 매개변수 필드
type
문자열

secret

매개변수가 보안 비밀 값임을 지정합니다.

Cloud 함수 리소스

이러한 필드는 확장 프로그램에 포함된 Cloud Functions를 선언합니다. 리소스 선언 구문은 확장 프로그램에서 공존할 수 있는 1세대 함수와 2세대 함수 간에 약간 다르게 보입니다.

1세대 Cloud Functions

resources:
  - name: functionName
    type: firebaseextensions.v1beta.function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      runtime: runtime-version
      eventTrigger:
        eventType: google.product.event
        resource: projects/_/resource/specifier
리소스 필드
name
문자열
(필수)

내보낸 함수의 사용자 친화적 이름.

entryPoint 속성(아래 참조)을 지정하지 않는 경우 이 값은 함수 소스 코드의 함수 이름과 일치해야 합니다.

배포된 함수의 최종 이름은 ext-extension-instance-id-name 형식입니다.

type
문자열
(필수)
1세대 함수 리소스의 경우: firebaseextensions.v1beta.function
description
문자열
(필수)

함수가 확장 프로그램에서 수행하는 태스크에 대한 간략한 설명.

properties
(필수)

1세대 Cloud Functions 속성. 가장 중요한 속성은 아래에 나열되어 있지만 Cloud Functions 참조에서 전체 목록을 확인할 수 있습니다.

속성
location
(선택사항)

함수를 배포할 위치. 기본값은 us-central1입니다.

entryPoint
(선택사항)
확장 프로그램에서 찾아야 하는 함수 소스 코드 내에서 내보낸 함수의 이름. 기본값은 위의 name 값입니다.
sourceDirectory
(선택사항)

루트에 package.json이 포함된 디렉터리. 함수 소스 코드의 파일은 이 디렉터리에 있어야 합니다. 기본값은 functions입니다.

참고: package.jsonmain 필드는 함수 소스 코드의 파일을 지정합니다(예: index.js).

timeout
(선택사항)

함수의 최대 실행 시간.

  • 기본값: 60s
  • 최댓값: 540s
availableMemoryMb
(선택사항)

함수에 사용할 수 있는 메모리 양(MB).

  • 기본값: 256
  • 유효한 값: 128, 256, 512, 1024, 2048
runtime
(권장)

함수의 런타임 환경.

httpsTrigger
또는
eventTrigger
또는
scheduleTrigger
또는
taskQueueTrigger
(이러한 함수 트리거 유형 중 하나 필수)
각 트리거 유형에 대한 자세한 내용은 확장 프로그램용 Cloud Functions 작성을 참조하세요.

2세대 Cloud Functions

resources:
  - name: functionName
    type: firebaseextensions.v1beta.v2function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      buildConfig:
        runtime: nodejs16
      serviceConfig:
        availableMemory: 512M
      eventTrigger:
        eventType: google.firebase.firebasealerts.alerts.v1.published
        triggerRegion: global
        eventFilters:
          - attribute: alerttype
            value: crashlytics.newFatalIssue

리소스 필드
name
문자열
(필수)

내보낸 함수의 사용자 친화적 이름.

entryPoint 속성(아래 참조)을 지정하지 않는 경우 이 값은 함수 소스 코드의 함수 이름과 일치해야 합니다.

배포된 함수의 최종 이름은 ext-extension-instance-id-name 형식입니다.

type
문자열
(필수)
2세대 함수 리소스의 경우: firebaseextensions.v1beta.v2function
description
문자열
(필수)

함수가 확장 프로그램에서 수행하는 태스크에 대한 간략한 설명.

properties
(필수)

2세대 Cloud Functions 속성. 가장 중요한 속성은 아래에 나열되어 있지만 Cloud Functions 참조에서 전체 목록을 확인할 수 있습니다.

속성
location
(선택사항)

함수를 배포할 위치. 기본값은 us-central1입니다.

sourceDirectory
(선택사항)

루트에 package.json이 포함된 디렉터리. 함수 소스 코드의 파일은 이 디렉터리에 있어야 합니다. 기본값은 functions입니다.

참고: package.jsonmain 필드는 함수 소스 코드의 파일을 지정합니다(예: index.js).

또한 자체 속성이 있는 3가지 객체 유형 필드도 있습니다.

buildConfig 속성
buildConfig.runtime
(권장)

함수의 런타임 환경.

buildConfig.entryPoint
(선택사항)
확장 프로그램에서 찾아야 하는 함수 소스 코드 내에서 내보낸 함수의 이름. 기본값은 위의 name 값입니다.
serviceConfig 속성
serviceConfig.timeoutSeconds
(선택사항)

함수의 최대 실행 시간.

  • 기본값: 60
  • 최댓값: 540
serviceConfig.availableMemory
(선택사항)
함수에 사용할 수 있는 메모리 양. 기본값은 256M입니다. 지원되는 단위는 k, M, G, Mi, Gi입니다. 단위가 제공되지 않으면 값이 바이트로 해석됩니다.
eventTrigger 속성
eventTrigger.eventType
(필수)
리슨할 이벤트의 유형. 각 제품에서 사용할 수 있는 이벤트 유형은 확장 프로그램의 Cloud Functions 작성을 참조하세요.
eventTrigger.eventFilters
(선택사항)
리슨할 이벤트를 추가로 제한하는 필터. 예를 들어 특정 리소스 패턴과 일치하는 이벤트만 리슨할 수 있습니다. 각 이벤트 유형을 필터링하는 방법은 확장 프로그램용 Cloud Functions 작성을 참조하세요.
eventTrigger.channel
(선택사항)
트리거와 연결된 채널의 이름(projects/{project}/locations/{location}/channels/{channel} 형식). 이 속성을 생략하면 함수가 프로젝트의 기본 채널에서 이벤트를 리슨합니다.
eventTrigger.triggerRegion
(선택사항)
트리거는 이 리전에서 발생하는 이벤트만 수신합니다. 함수와 동일한 리전, 다른 리전, 멀티 리전 또는 전역 리전일 수 있습니다. 값을 제공하지 않으면 기본값은 함수와 동일한 리전입니다.

수명 주기 이벤트

수명 주기 이벤트를 사용하면 사용자가 확장 프로그램의 인스턴스를 설치, 업데이트, 구성할 때 실행할 함수를 지정할 수 있습니다. 확장 프로그램의 수명 주기 이벤트 처리를 참조하세요.

lifecycleEvents:
  onInstall:
    function: myTaskFunction
    processingMessage: Describes the task being completed
  onUpdate:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
  onConfigure:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
수명 주기 이벤트 필드
onInstall
(선택사항)

사용자가 확장 프로그램을 설치할 때 실행되는 함수를 지정합니다.

함수 사양
function
문자열
(필수)

이벤트를 처리할 태스크 큐 트리거 함수의 이름.

이 함수는 resources 섹션에서 선언되어야 하고 taskQueue가 정의되어 있어야 합니다.

processingMessage
문자열
(필수)
태스크가 진행되는 동안 Firebase Console에 표시할 메시지.
onUpdate
(선택사항)

사용자가 확장 프로그램을 업데이트할 때 실행되는 함수를 지정합니다.

함수 사양
function
문자열
(필수)

이벤트를 처리할 태스크 큐 트리거 함수의 이름.

이 함수는 resources 섹션에서 선언되어야 하고 taskQueue가 정의되어 있어야 합니다.

processingMessage
문자열
(필수)
태스크가 진행되는 동안 Firebase Console에 표시할 메시지.
onConfigure
(선택사항)

사용자가 확장 프로그램을 다시 구성할 때 실행되는 함수를 지정합니다.

함수 사양
function
문자열
(필수)

이벤트를 처리할 태스크 큐 트리거 함수의 이름.

이 함수는 resources 섹션에서 선언되어야 하고 taskQueue가 정의되어 있어야 합니다.

processingMessage
문자열
(필수)
태스크가 진행되는 동안 Firebase Console에 표시할 메시지.

커스텀 이벤트(Eventarc)

커스텀 이벤트는 사용자가 확장 프로그램에 자체 로직을 삽입할 수 있도록 확장 프로그램에서 내보내는 이벤트입니다. 확장 프로그램에 사용자 후크 추가에서 Eventarc 섹션을 참조하세요.

events:
  - type: publisher-id.extension-name.version.event-name
    description: Description of the event
  - type: publisher-id.extension-name.version.another-event-name
    description: Description of the other event
커스텀 이벤트 필드
type
문자열
(필수)
이벤트 유형 식별자. 점으로 구분된 3~4개의 필드로 식별자를 구성합니다. 게시자 ID, 확장 프로그램 이름, 이벤트 이름 필드는 필수 필드이고 버전 필드는 권장 필드입니다. 게시하는 이벤트 유형마다 고유하고 구체적인 이벤트 이름을 선택합니다.
description
문자열
(필수)
이벤트 설명.