Firestore 트리거(2세대)
Firestore 데이터베이스에서 이벤트에 의해 Cloud Functions가 트리거되도록 구성할 수 있습니다. 함수가 트리거되면 Firestore API 및 클라이언트 라이브러리를 통해 이러한 이벤트에 대한 응답으로 Firestore 데이터베이스를 읽고 업데이트할 수 있습니다.
일반적인 수명 주기에서 Firestore 함수는 다음을 수행합니다.
특정 문서가 변경되기를 기다립니다.
이벤트가 발생하면 트리거되어 작업을 수행합니다.
영향을 받는 문서의 스냅샷이 있는 데이터 객체를 수신합니다.
write
또는update
이벤트의 경우 데이터 객체에는 이벤트 트리거 전후의 문서 상태를 나타내는 스냅샷이 포함됩니다.
이벤트 유형
Firestore는 create
, update
, delete
, write
이벤트를 지원합니다. write
이벤트는 문서에 대한 모든 수정사항을 포함합니다.
이벤트 유형 | 트리거 |
---|---|
google.cloud.firestore.document.v1.created (기본) |
문서를 처음으로 기록할 때 트리거됩니다. |
google.cloud.firestore.document.v1.updated |
이미 존재하는 문서에서 값이 변경되었을 때 트리거됩니다. |
google.cloud.firestore.document.v1.deleted |
데이터가 있는 문서가 삭제되면 트리거됩니다. |
google.cloud.firestore.document.v1.written |
문서가 생성, 업데이트 또는 삭제되면 트리거됩니다. |
와일드 카드는 다음과 같이 중괄호를 사용하여 트리거에 작성됩니다. "projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}"
문서 경로 지정
함수를 트리거하려면 리슨할 문서 경로를 지정합니다. 문서 경로는 함수와 동일한 Google Cloud 프로젝트에 있어야 합니다.
다음은 유효한 문서 경로의 몇 가지 예시입니다.
users/marie
: 유효한 트리거입니다. 단일 문서/users/marie
를 모니터링합니다.users/{username}
: 유효한 트리거입니다. 모든 사용자 문서를 모니터링합니다. 와일드 카드를 사용하면 컬렉션의 모든 문서를 모니터링할 수 있습니다.users/{username}/addresses
: 트리거가 잘못되었습니다. 문서가 아닌 하위 컬렉션addresses
를 나타냅니다.users/{username}/addresses/home
: 유효한 트리거입니다. 모든 사용자에 대한 집 주소 문서를 모니터링합니다.users/{username}/addresses/{addressId}
: 유효한 트리거입니다. 모든 주소 문서를 모니터링합니다.users/{user=**}
: 유효한 트리거입니다. 모든 사용자 문서와/users/userID/address/home
또는/users/userID/phone/work
등 각 사용자 문서에 포함된 하위 컬렉션의 문서를 모니터링합니다.
와일드 카드 및 매개변수
모니터링할 특정 문서를 알 수 없는 경우에는 문서 ID 대신 {wildcard}
를 사용합니다.
users/{username}
은 모든 사용자 문서에 대한 변경을 리슨합니다.
이 예시에서 users
의 문서에서 필드가 변경되면 필드는 {username}
라는 와일드 카드와 일치합니다.
users
의 문서에 하위 컬렉션이 있고, 이 하위 컬렉션 문서 중 하나에서 필드가 변경되면 {username}
와일드 카드가 트리거되지 않습니다. 하위 컬렉션의 이벤트에도 응답하려는 경우 다중 세그먼트 와일드 카드 {username=**}
을 사용합니다.
와일드 카드 일치는 문서 경로에서 추출됩니다. 원하는 만큼 와일드 카드를 정의하여 명시적 컬렉션 또는 문서 ID를 대체할 수 있습니다. {username=**}
과 같이 최대 한 개의 다중 세그먼트 와일드 카드를 사용할 수 있습니다.
이벤트 구조
이 트리거는 다음과 유사한 이벤트로 함수를 호출합니다.
{ "oldValue": { // Update and Delete operations only A Document object containing a pre-operation document snapshot }, "updateMask": { // Update operations only A DocumentMask object that lists changed fields. }, "value": { // A Document object containing a post-operation document snapshot } }
각 Document
객체에는 Value
객체가 하나 이상 포함됩니다. 유형 참조는 Value
문서를 참조하세요. 특히 Go와 같은 입력 언어를 사용하여 함수를 작성하는 경우에 유용합니다.
Firestore 데이터베이스 설정
이 문서의 샘플을 테스트하려면 Firestore 데이터베이스가 필요합니다. 함수를 배포하기 전에 이를 수행해야 합니다. 아직 Firestore 데이터베이스가 없으면 다음과 같이 데이터베이스를 만듭니다.
Firestore 데이터 페이지로 이동합니다.
기본 모드 선택을 클릭합니다.
데이터베이스가 상주할 리전(위치)을 선택합니다. 이 선택은 되돌릴 수 없습니다.
데이터베이스 만들기를 클릭합니다.
Firestore 데이터 모델은 문서가 포함된 컬렉션으로 구성됩니다. 각 문서에는 키-값 쌍이 들어 있습니다.
이 튜토리얼에서 만드는 함수는 지정된 컬렉션의 문서를 변경할 때 트리거됩니다.
예시 1: Hello Firestore 함수
다음 샘플 Cloud 함수는 트리거하는 Firestore 이벤트의 필드를 출력합니다.
Node.js
protobufjs를 사용하여 이벤트 데이터를 디코딩합니다. 소스에 google.events.cloud.firestore.v1
data.proto
를 포함합니다.
Python
Go
Java
C#
Hello Firestore 함수 배포
아직 Firestore 데이터베이스를 설정하지 않았으면 설정합니다.
Firestore 트리거를 사용하여 Hello Firestore 함수를 배포하려면 샘플 코드(또는 자바의 경우
pom.xml
파일)가 포함된 디렉터리에서 다음 명령어를 실행합니다.gcloud functions deploy FUNCTION_NAME \ --gen2 \ --runtime=RUNTIME \ --region=REGION \ --trigger-location=TRIGGER REGION \ --source=. \ --entry-point=ENTRY_POINT \ --trigger-event-filters=type=google.cloud.firestore.document.v1.written \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='users/{username}'
다음을 바꿉니다.
FUNCTION_NAME
: 배포된 함수의 이름입니다.RUNTIME
: 함수에서 사용하는 언어 런타임입니다.REGION
: 함수를 배포할 리전입니다.TRIGGER_REGION
: 트리거의 위치로, Firestore 데이터베이스의 리전과 동일해야 합니다.ENTRY_POINT
: 소스 코드에 있는 함수의 진입점입니다. 이는 함수가 실행될 때 실행되는 코드입니다.
다른 필드는 다음과 같이 사용합니다.
--trigger-event-filters=type=google.cloud.firestore.document.v1.written
은google.cloud.firestore.document.v1.written
이벤트 유형에 따라 문서가 생성, 업데이트 또는 삭제될 때 함수가 트리거되도록 지정합니다.--trigger-event-filters=database='(default)'
는 Firebase 데이터베이스를 지정합니다. 기본 데이터베이스 이름에는(default)
를 사용합니다.--trigger-event-filters-path-pattern=document='users/{username}'
은 관련 변경사항을 모니터링해야 하는 문서의 경로 패턴을 제공합니다. 이 경로 패턴은users
컬렉션의 모든 문서를 모니터링해야 함을 나타냅니다. 자세한 내용은 경로 패턴 이해를 참조하세요.
Hello Firestore 함수 테스트
Hello Firestore 함수를 테스트하려면 Firestore 데이터베이스에서 users
라는 컬렉션을 설정합니다.
Firestore 데이터 페이지에서 컬렉션 시작을 클릭합니다.
컬렉션 ID로
users
를 지정합니다.컬렉션의 첫 번째 문서 추가를 시작하려면 첫 번째 문서 추가에서 자동 생성된 문서 ID를 수락합니다.
문서에 대한 필드를 하나 이상 추가하고 이름과 값을 지정합니다. 이 예시에서 이름은 'username'이고 값은 'rowan:'입니다.
완료했으면 저장을 클릭합니다.
이 작업은 새 문서를 만들어 함수를 트리거합니다.
함수가 트리거되었는지 확인하려면 Google Cloud Console Cloud Functions 개요 페이지에서 함수의 링크된 이름을 클릭하여 함수 세부정보 페이지를 엽니다.
로그 탭을 열고 다음 문자열을 찾습니다.
Function triggered by change to: //firestore.googleapis.com/projects/your-project-id/databases/(default)'
예시 2: 대문자로 변환 함수
이 예시에서는 사용자가 추가한 값을 검색하고 해당 위치의 문자열을 대문자로 변환한 후 해당 값을 대문자 문자열로 바꿉니다.
Node.js
protobufjs를 사용하여 이벤트 데이터를 디코딩합니다. 소스에 google.events.cloud.firestore.v1
data.proto
를 포함합니다.
Python
Go
Java
C#
대문자로 변환 함수 배포
아직 Firestore 데이터베이스를 설정하지 않았으면 설정합니다.
다음 명령어를 사용하여
companies/{CompanyId}
문서의 쓰기 이벤트에 의해 트리거되는 함수를 배포합니다.gcloud functions deploy FUNCTION_NAME \ --gen2 \ --runtime=RUNTIME \ --trigger-location=TRIGGER REGION \ --region=REGION \ --source=. \ --entry-point=ENTRY_POINT \ --trigger-event-filters=type=google.cloud.firestore.document.v1.written \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='messages/{pushId}'
다음을 바꿉니다.
FUNCTION_NAME
: 배포된 함수의 이름입니다.RUNTIME
: 함수에서 사용하는 언어 런타임입니다.REGION
: 함수를 배포할 리전입니다.TRIGGER_REGION
: 트리거의 위치로, Firestore 데이터베이스의 리전과 동일해야 합니다.ENTRY_POINT
: 소스 코드에 있는 함수의 진입점입니다. 이는 함수가 실행될 때 실행되는 코드입니다.
다른 필드는 다음과 같이 사용합니다.
--trigger-event-filters=type=google.cloud.firestore.document.v1.written
은google.cloud.firestore.document.v1.written
이벤트 유형에 따라 문서가 생성, 업데이트 또는 삭제될 때 함수가 트리거되도록 지정합니다.--trigger-event-filters=database='(default)'
는 Firestore 데이터베이스를 지정합니다. 기본 데이터베이스 이름에는(default)
를 사용합니다.--trigger-event-filters-path-pattern=document='messages/{pushId}'
은 관련 변경사항을 모니터링해야 하는 문서의 경로 패턴을 제공합니다. 이 경로 패턴은messages
컬렉션의 모든 문서를 모니터링해야 함을 나타냅니다. 자세한 내용은 경로 패턴 이해를 참조하세요.
대문자로 변환 함수 테스트
방금 배포한 대문자로 변환 함수를 테스트하려면 Firestore 데이터베이스에서 messages
라는 컬렉션을 설정합니다.
Firestore 데이터 페이지로 이동합니다.
컬렉션 시작을 클릭합니다.
컬렉션 ID로
messages
를 지정합니다.컬렉션의 첫 번째 문서 추가를 시작하려면 첫 번째 문서 추가에서 자동 생성된 문서 ID를 수락합니다.
배포된 함수를 트리거하려면 필드 이름이 'original'이고 필드 값이 소문자인 문서를 추가합니다. 예를 들면 다음과 같습니다.
문서를 저장하면 값 필드의 소문자가 대문자로 변환됩니다.
나중에 소문자를 포함하도록 필드 값을 수정하면 함수가 다시 트리거되어 모든 소문자가 대문자로 변환됩니다.
제한사항
Cloud Functions용 Firestore 트리거의 다음 제한사항에 유의하세요.
- Cloud Functions(1세대)는 Firestore 기본 모드의 기존 '(기본값)' 데이터베이스를 기본 요건으로 합니다. 이름이 지정된 Firestore 데이터베이스 또는 Datastore 모드는 지원하지 않습니다. 이러한 경우 Cloud Functions(2세대)를 사용하여 이벤트를 구성하세요.
- 순서는 보장되지 않습니다. 급격하게 변경하면 예기치 않은 순서로 함수 호출이 트리거될 수 있습니다.
- 이벤트는 최소 1회 전송되지만 하나의 이벤트에 함수가 여러 번 호출될 수 있습니다. 정확히 한 번에 처리하는 메커니즘에 의존하지 말고 멱등 함수를 작성하세요.
- Datastore 모드의 Cloud Firestore에는 Cloud Functions(2세대)가 필요합니다. Cloud Functions(1세대)는 Datastore 모드를 지원하지 않습니다.
- 트리거는 단일 데이터베이스와 연결됩니다. 여러 데이터베이스와 일치하는 트리거를 만들 수 없습니다.
- 데이터베이스를 삭제해도 해당 데이터베이스의 트리거가 자동으로 삭제되지 않습니다. 트리거가 이벤트 제공을 중지하지만 트리거를 삭제하기 전까지 계속 존재합니다.
- 일치하는 이벤트가 최대 요청 크기를 초과하면 이벤트가 Cloud Functions(1세대)로 전달되지 않을 수 있습니다.
- 요청 크기로 인해 전달되지 않은 이벤트는 플랫폼 로그에 로깅되고 프로젝트의 로그 사용량에 포함됩니다.
- 이러한 로그는 로그 탐색기에서 '크기가 1세대... 한도를 초과하여 Cloud 함수에 이벤트를 전송할 수 없음'이라는
error
심각도의 메시지와 함께 확인할 수 있습니다.functionName
필드에서 함수 이름을 확인할 수 있습니다.receiveTimestamp
필드가 지금부터 1시간 이내인 경우 타임스탬프 전후의 스냅샷과 함께 해당 문서를 읽어 실제 이벤트 콘텐츠를 추론할 수 있습니다. - 이러한 주기를 피하려면 다음을 수행하면 됩니다.
- Cloud Functions(2세대)로 마이그레이션 및 업그레이드
- 문서 크기 축소
- 해당 Cloud Functions 삭제
- 제외를 사용하여 로깅 자체를 사용 중지할 수 있지만 그래도 문제가 되는 이벤트가 전송되지 않습니다.