확장 프로그램의 사양 파일(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 사양의 버전. 현재 값: |
||||||||
license문자열 (선택사항) |
확장 프로그램의 라이선스.
|
||||||||
billingRequired불리언 (선택사항) |
확장 프로그램에서 사용하는 서비스에 유료 등급의 Firebase 결제 계정이 필요한지 여부. 항상 |
||||||||
displayName문자열 (선택사항) |
확장 프로그램의 친숙한 표시 이름(3~5개 단어). 글자 수가 40자(영문 기준)로 제한됩니다. |
||||||||
description문자열 (선택사항) |
확장 프로그램이 수행하는 태스크에 대한 간략한 설명(약 1개 문장). | ||||||||
icon문자열 (선택사항) |
512x512~1,024x1,024픽셀 크기의 정사각형 PNG 파일이어야 합니다.
파일을 확장 프로그램 아이콘을 디자인할 때는 다음 가이드라인에 유의하세요.
|
||||||||
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/
|
||||||||
contributors작성자 객체 목록 (선택사항) |
확장 프로그램에 기여한 추가 작성자.
contributors:
- authorName: Your Name
- authorName: Another Contributor
email: colleague@example.net
url: https://github.com/their-org/
|
||||||||
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문자열 (선택사항) |
역할 범위를 이 리소스로 제한합니다. 생략할 경우 기본값은 |
외부 서비스
이 필드는 확장 프로그램에서 사용하는 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불리언 (선택사항) |
설치 후 사용자가 매개변수 값을 변경할 수 있는지 여부를 정의합니다(예: 확장 프로그램을 재구성하는 경우). 기본값은 참고: 확장 프로그램의 배포된 함수에 '위치' 매개변수를 정의하는 경우 이 필드를 |
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문자열 |
매개변수가 하나의 값( |
||||||
options옵션 목록 (필수) |
사용자가 선택할 수 있는 옵션
|
||||||
선택 가능한 리소스 매개변수
선택 가능한 리소스 매개변수는 사용자에게 프로젝트에서 리소스(데이터베이스 인스턴스, 스토리지 버킷 등)를 선택하라는 메시지를 표시합니다.
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문자열 |
매개변수가 프로젝트 리소스를 나타내도록 지정합니다. |
resourceType문자열 (필수) |
사용자에게 선택하라는 메시지를 표시하는 리소스 유형. 유효한 값:
그러나 현재 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문자열 |
매개변수가 보안 비밀 값임을 지정합니다. |
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문자열 (필수) |
내보낸 함수의 사용자 친화적 이름.
배포된 함수의 최종 이름은 |
||||||||||||||||
type문자열 (필수) |
1세대 함수 리소스의 경우: firebaseextensions.v1beta.function
|
||||||||||||||||
description문자열 (필수) |
함수가 확장 프로그램에서 수행하는 태스크에 대한 간략한 설명. |
||||||||||||||||
properties(필수) |
1세대 Cloud Functions 속성. 가장 중요한 속성은 아래에 나열되어 있지만 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문자열 (필수) |
내보낸 함수의 사용자 친화적 이름.
배포된 함수의 최종 이름은 |
||||||||||||||||||||||||||||
type문자열 (필수) |
2세대 함수 리소스의 경우: firebaseextensions.v1beta.v2function
|
||||||||||||||||||||||||||||
description문자열 (필수) |
함수가 확장 프로그램에서 수행하는 태스크에 대한 간략한 설명. |
||||||||||||||||||||||||||||
properties(필수) |
2세대 Cloud Functions 속성. 가장 중요한 속성은 아래에 나열되어 있지만 Cloud Functions 참조에서 전체 목록을 확인할 수 있습니다.
또한 자체 속성이 있는 3가지 객체 유형 필드도 있습니다.
|
||||||||||||||||||||||||||||
수명 주기 이벤트
수명 주기 이벤트를 사용하면 사용자가 확장 프로그램의 인스턴스를 설치, 업데이트, 구성할 때 실행할 함수를 지정할 수 있습니다. 확장 프로그램의 수명 주기 이벤트 처리를 참조하세요.
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(선택사항) |
사용자가 확장 프로그램을 설치할 때 실행되는 함수를 지정합니다.
|
||||||
onUpdate(선택사항) |
사용자가 확장 프로그램을 업데이트할 때 실행되는 함수를 지정합니다.
|
||||||
onConfigure(선택사항) |
사용자가 확장 프로그램을 다시 구성할 때 실행되는 함수를 지정합니다.
|
||||||
커스텀 이벤트(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문자열 (필수) |
이벤트 설명. |