개요

Cloud Run Functions는 Firestore, Cloud Spanner, Cloud SQL, Cloud Bigtable과 같은 Google Cloud 데이터베이스 및 Google Cloud의 인메모리 데이터 스토어 캐시 서비스인 Memorystore와 통합하여 애플리케이션과 서비스를 확장할 수 있습니다.

이 실습에서는 Google Cloud의 서버리스 NoSQL 문서 데이터베이스인 Firestore와 통합되는 Cloud Run Functions를 만듭니다. Cloud Run Functions 프레임워크와 Node.js용 Firestore 클라이언트 라이브러리를 사용하여 함수를 만들고, 데이터베이스에서 이벤트가 발생할 때 함수를 실행하도록 트리거를 설정합니다.

Firestore 함수의 수명 주기에는 일반적으로 다음 단계가 포함됩니다.

• Firestore 데이터베이스의 특정 문서가 변경되기를 기다립니다.
• 이벤트가 발생하면 트리거됩니다.
• 영향을 받는 문서의 스냅샷과 함께 수신된 데이터 객체를 사용하여 작업을 수행합니다.

목표

이 실습에서 학습할 내용은 다음과 같습니다.

• Firestore 데이터베이스 설정
• Firestore에서 문서가 생성될 때 정보를 기록하는 이벤트 기반 함수 개발 및 배포
• 문서 콘텐츠를 업데이트하기 위한 이벤트 기반 함수 개발 및 배포
• Cloud Run Functions에서 보안 비밀 액세스 및 사용
• Google Cloud 콘솔을 사용하여 함수에서 생성된 로그 확인

설정하기

실습 시작 버튼을 클릭하기 전에

참고: 다음 안내를 확인하세요.

실습에는 시간제한이 있으며 일시중지할 수 없습니다. 실습 시작을 클릭하면 타이머가 시작됩니다. 이 타이머는 Google Cloud 리소스를 사용할 수 있는 시간이 얼마나 남았는지를 표시합니다.

Google Skills 실무형 실습을 통해 시뮬레이션이나 데모 환경이 아닌 실제 클라우드 환경에서 직접 실습 활동을 진행할 수 있습니다. 실습 시간 동안 Google Cloud에 로그인하고 액세스하는 데 사용할 수 있는 새로운 임시 사용자 인증 정보가 제공됩니다.

필요한 사항

이 실습을 완료하려면 다음이 필요합니다.

• 표준 인터넷 브라우저(Chrome 브라우저 권장)
• 실습을 끝까지 진행할 수 있는 충분한 시간

참고: 이미 개인용 Google Cloud 계정이나 프로젝트가 있어도 이 실습에서는 사용하지 마세요. 참고: Pixelbook을 사용하는 경우 시크릿 창을 열어 이 실습을 실행하세요.

Google Cloud Shell 활성화하기

Google Cloud Shell은 다양한 개발 도구가 탑재된 가상 머신으로, 5GB의 영구 홈 디렉터리를 제공하며 Google Cloud에서 실행됩니다.

Google Cloud Shell을 사용하면 명령줄을 통해 Google Cloud 리소스에 액세스할 수 있습니다.

1. Cloud 콘솔의 오른쪽 상단 툴바에서 'Cloud Shell 열기' 버튼을 클릭합니다.

   

2. 계속을 클릭합니다.

환경을 프로비저닝하고 연결하는 데 몇 분 정도 소요됩니다. 연결되면 사용자가 미리 인증되어 프로젝트가 PROJECT_ID로 설정됩니다. 예:

gcloud는 Google Cloud의 명령줄 도구입니다. Cloud Shell에 사전 설치되어 있으며 명령줄 자동 완성을 지원합니다.

• 다음 명령어를 사용하여 사용 중인 계정 이름을 나열할 수 있습니다.

gcloud auth list

출력:

Credentialed accounts: - @.com (active)

출력 예시:

Credentialed accounts: - google1623327_student@qwiklabs.net

• 다음 명령어를 사용하여 프로젝트 ID를 나열할 수 있습니다.

gcloud config list project

출력:

[core] project =

출력 예시:

[core] project = qwiklabs-gcp-44776a13dea667a6 참고: gcloud 전체 문서는 gcloud CLI 개요 가이드를 참조하세요.

작업 1. 환경 설정하기

이 작업에서는 환경 변수를 설정하고 이 실습을 수행하는 데 필요한 관련 서비스 API를 사용 설정합니다.

환경 변수 설정하기

Cloud Run Functions를 만들기 전에 몇 가지 환경 변수를 설정합니다.

1. 실습 사용자 인증 정보로 Google Cloud 콘솔에 로그인하고 Cloud Shell 터미널 창을 엽니다.

2. Cloud Shell에서 다음 명령어를 실행하여 프로젝트 ID 및 리전 환경 변수를 설정합니다.

   PROJECT_ID=$(gcloud config get-value project) REGION={{{project_0.default_region|set at lab start}}}

3. 프로젝트 번호 환경 변수를 설정합니다.

   PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" \ --format="value(projectNumber)")

4. Cloud Run Functions의 기본 리전을 설정합니다.

   gcloud config set functions/region {{{project_0.default_region|set at lab start}}}

API 사용 설정하기

1. 이 실습에 필요한 서비스 API를 사용 설정하려면 다음 명령어를 실행합니다.

   gcloud services enable \ artifactregistry.googleapis.com \ cloudfunctions.googleapis.com \ cloudbuild.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ logging.googleapis.com \ storage.googleapis.com \ pubsub.googleapis.com

작업 2. Firestore 설정하기

이 실습의 작업을 수행하려면 Firestore 데이터베이스를 설정해야 합니다. Firestore는 데이터를 문서와 컬렉션의 형태로 저장합니다. Firestore와 함께 Cloud Run Functions를 사용하려면 함수를 배포하기 전에 먼저 Firestore를 설정해야 합니다.

1. Google Cloud 콘솔의 상단 탐색 메뉴에서 검색창을 클릭하고 Firestore를 입력합니다. 검색 결과에서 Firestore를 선택합니다.

2. Firestore 데이터베이스 만들기를 클릭합니다.

3. Standard 버전을 선택합니다.

4. 구성 옵션에서 기본 모드의 Firestore를 선택합니다.

5. 보안 규칙에는 열기를 선택합니다.

6. 위치 유형에서 리전을 클릭한 다음 목록에서 실습을 시작할 때 설정한 실습 리전을 선택합니다.

   참고: 리전 목록이 채워지지 않는다면 브라우저를 새로고침하거나 Cloud 콘솔 메뉴에서 마법사를 다시 실행해 보세요.

7. 다른 설정은 기본값으로 두고 데이터베이스 만들기를 클릭합니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. Firestore 설정

작업 3. 새 Firestore 문서용 이벤트 기반 함수 개발하기

Firestore 데이터베이스를 만든 후 함수 코드를 개발할 수 있습니다. 이 작업에서는 데이터베이스에 새 문서가 생성될 때 응답하는 함수의 소스 코드를 작성합니다. 함수는 함수 호출에서 수신된 데이터에 대한 정보를 기록합니다.

작업 디렉터리 설정하기

Firestore 함수는 protobuf.js npm 모듈을 사용하여 프로토콜 버퍼로 디코딩할 수 있는 cloudevents 데이터 구조로 호출됩니다. 자세한 내용은 실습 마지막에 제공된 링크를 참조하세요.

1. 필요한 .proto 파일과 종속 항목 파일을 Cloud Storage에서 복사하고 보관 파일에서 콘텐츠를 추출하려면 다음 명령어를 실행합니다.

   gcloud storage cp gs://cloud-training/CBL493/firestore_functions.zip . && unzip firestore_functions && rm firestore_functions.zip

2. firestore_functions 디렉터리로 변경합니다.

   cd firestore_functions

   firestore_functions 디렉터리에는 다음 하위 작업에서 업데이트할 빈 node.js 및 package.json 파일도 포함되어 있습니다.

함수 코드 작성하기

1. Cloud Shell 툴바에서 편집기 열기를 클릭합니다.

   Cloud Shell과 코드 편집기 간에 전환하려면 편집기 열기 또는 터미널 열기를 클릭하거나, 새 창에서 열기를 클릭해 편집기를 별도의 탭에 열어 둡니다.

2. 편집기에서 다음 코드를 firestore_functions/index.js 파일에 추가합니다.

   /** * Cloud Event Function triggered by a change to a Firestore document. */ const functions = require('@google-cloud/functions-framework'); const protobuf = require('protobufjs'); functions.cloudEvent('newCustomer', async cloudEvent => { console.log(`Function triggered by event on: ${cloudEvent.source}`); console.log(`Event type: ${cloudEvent.type}`); console.log('Loading protos...'); const root = await protobuf.load('data.proto'); const DocumentEventData = root.lookupType('google.events.cloud.firestore.v1.DocumentEventData'); console.log('Decoding data...'); const firestoreReceived = DocumentEventData.decode(cloudEvent.data); console.log('\nNew document:'); console.log(JSON.stringify(firestoreReceived.value, null, 2)); const documentData = firestoreReceived.value.fields; console.log('Document data:', documentData); }); 이 코드는 Cloud Run Functions 프레임워크 Node.js 라이브러리를 사용하여 cloudEvent 사양을 통해 제공된 데이터를 처리하는 함수를 만듭니다.

3. 편집기에서 firestore_functions/package.json 파일에 다음을 추가합니다.

   { "name": "firestore_functions", "version": "0.0.1", "main": "index.js", "dependencies": { "@google-cloud/functions-framework": "^3.1.3", "protobufjs": "^7.2.2", "@google-cloud/firestore": "^6.0.0" } }

서비스 계정 권한 업데이트하기

함수를 배포하기 전에 Cloud Run Functions 서비스 에이전트에 특정 권한을 부여합니다. Cloud Shell에서 다음 명령어를 실행합니다.

1. 터미널 열기를 클릭합니다.

2. Cloud Run Functions 서비스 에이전트의 서비스 계정에 대한 환경 변수를 설정합니다.

   SERVICE_ACCOUNT=service-$PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com

3. Artifact Registry에서 아티팩트를 보고 가져오려면 Cloud Run Functions 서비스 계정에 artifactregistry.reader 역할을 부여합니다.

   gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:$SERVICE_ACCOUNT --role roles/artifactregistry.reader 참고: 이전 단계에서 서비스 계정이 존재하지 않거나 요청에 잘못된 사용자 인증 정보가 포함되어 있다는 오류 메시지가 표시되면 다음 단계를 수행합니다.

4. Cloud Functions API를 사용 중지합니다.

   gcloud services disable cloudfunctions.googleapis.com

5. Cloud Functions API를 다시 사용 설정합니다.

   gcloud services enable cloudfunctions.googleapis.com

6. 몇 초 정도 기다린 후 명령어를 다시 실행하여 Cloud Run Functions 서비스 계정에 artifactregistry.reader 역할을 부여합니다.

   gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:$SERVICE_ACCOUNT --role roles/artifactregistry.reader

함수 배포하기

• 함수를 배포하려면 Cloud Shell에서 다음 명령어를 실행합니다.

  gcloud functions deploy newCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=newCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.created \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}' Firestore는 배포 명령어에 trigger-event-filter 옵션으로 지정하는 created, updated, deleted, written 이벤트를 지원합니다. 이 경로 패턴은 customers 컬렉션의 모든 문서를 모니터링해야 함을 나타냅니다.

  명령어가 성공적으로 실행되면 이 샘플 부분 명령어 출력에 표시된 것처럼 함수 엔드포인트의 URL이 생성됩니다.

  ... state: ACTIVE updateTime: '2024-03-19T21:38:04.917134057Z' url: https://{{{project_0.default_region|set at lab start}}}-{{{project_0.default_region}}}.cloudfunctions.net/newCustomer 함수를 배포할 때 오류가 발생하면 몇 분 정도 기다린 후 배포 명령어를 다시 시도하세요. Eventarc에 대한 서비스 계정 권한이 반영되는 데 시간이 걸릴 수 있습니다.

함수 테스트하기

1. Cloud 콘솔에서 Firestore Studio로 이동합니다.

2. 새 문서 컬렉션을 만들려면 컬렉션 시작을 클릭합니다.

3. 컬렉션 ID에 customers를 입력합니다.

4. 이 컬렉션의 문서에 대한 ID를 생성하려면 문서 ID를 클릭합니다.

5. 이 문서에 다음 값을 가진 필드를 추가합니다.

   필드 이름	필드 유형	필드 값
   firstname	문자열	루카스

6. 저장을 클릭합니다.

7. Cloud Run Functions가 호출되었는지 확인하려면 탐색 메뉴()에서 Cloud Run을 클릭합니다.

8. 함수 이름 newCustomer를 클릭합니다.

9. 로그를 클릭합니다.

10. 함수 코드에서 생성된 로그 항목이 있고 생성한 데이터베이스 문서의 데이터가 표시되는지 확인합니다.

    최신 로그 항목을 보려면 새로고침을 클릭해야 할 수 있습니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. 새 Firestore 문서용 이벤트 기반 함수 개발

작업 4. Firestore용 이벤트 기반 함수를 개발하여 문서 업데이트하기

이 작업에서는 Firestore 데이터베이스에서 문서가 업데이트될 때 트리거되는 함수를 개발합니다. 함수는 다른 문서의 필드 값에서 파생된 값을 사용하여 문서에 새 필드를 추가합니다.

함수 코드 작성하기

1. 편집기에서 firestore_functions/index.js 파일에 다음 코드를 추가합니다.

   const Firestore = require('@google-cloud/firestore'); const firestore = new Firestore({ projectId: process.env.GOOGLE_CLOUD_PROJECT, }); functions.cloudEvent('updateCustomer', async cloudEvent => { console.log('Loading protos...'); const root = await protobuf.load('data.proto'); const DocumentEventData = root.lookupType( 'google.events.cloud.firestore.v1.DocumentEventData' ); console.log('Decoding data...'); const firestoreReceived = DocumentEventData.decode(cloudEvent.data); const resource = firestoreReceived.value.name; const affectedDoc = firestore.doc(resource.split('/documents/')[1]); // Fullname already exists, so don't update again to avoid infinite loop. if (firestoreReceived.value.fields.hasOwnProperty('fullname')) { console.log('Fullname is already present in document.'); return; } if (firestoreReceived.value.fields.hasOwnProperty('lastname')) { const lname = firestoreReceived.value.fields.lastname.stringValue; const fname = firestoreReceived.value.fields.firstname.stringValue; const fullname = `${fname} ${lname}` console.log(`Adding fullname --> ${fullname}`); await affectedDoc.update({ fullname: fullname }); } }); 동일한 프로젝트의 main 파일에서 자체 진입점을 가진 여러 함수를 정의하고 이를 Cloud Run Functions에 개별적으로 배포할 수 있습니다.

   이 접근방식을 사용하면 일부 함수에 해당 종속 항목이 필요하지 않더라도 모든 함수가 동일한 종속 항목 집합을 공유할 수 있습니다.

   특정 함수에 필요한 종속 항목 수를 최소화하고 메모리 요구사항을 줄이려면 각 함수의 소스 코드를 자체 프로젝트 구성 파일과 함께 자체 최상위 디렉터리에 보관하는 것이 좋습니다.

함수 배포하기

1. 새 함수를 배포하려면 Cloud Shell에서 다음 명령어를 실행합니다.

   gcloud functions deploy updateCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=updateCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.updated \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}'

2. 함수가 배포되었고 상태가 Active임을 나타내는 명령어 출력을 확인합니다.

함수 테스트하기

1. Cloud 콘솔의 Firestore Studio에서 customers 컬렉션에 있는 기존 문서 중 firstname 필드 값이 루카스인 문서를 선택합니다.

2. 이 문서에 대해 필드 추가를 클릭합니다.

3. 다음 값을 사용하여 필드를 추가합니다.

   필드 이름	필드 유형	필드 값
   lastname	문자열	셔먼

4. 저장을 클릭합니다.

5. 몇 초 정도 기다린 후 문서에 새 필드 fullname이 추가되었는지 확인합니다.

   이는 문서가 업데이트될 때 updateCustomer 함수가 호출되었음을 나타냅니다.

6. Cloud Run Functions가 호출되었는지 확인하려면 탐색 메뉴()에서 Cloud Run을 클릭합니다.

7. 함수 이름 updateCustomer를 클릭합니다.

8. 로그를 클릭합니다.

9. 함수 코드에서 fullname 필드가 문서에 추가되었음을 나타내는 로그 항목이 생성되었는지 확인합니다.

   최신 로그 항목을 보려면 새로고침을 클릭해야 할 수 있습니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. Firestore용 이벤트 기반 함수를 개발하여 문서 업데이트

작업 5. Cloud Run Functions에서 보안 비밀 사용하기

Secret Manager는 API 키, 비밀번호, 인증서, 사용자 인증 정보, 기타 민감한 정보와 같은 데이터를 안전하게 저장하는 Google Cloud 서비스입니다. 이러한 데이터를 저장한 다음 Cloud Run Functions 또는 다른 서비스에서 이러한 보안 비밀에 액세스하여 함수 로직 또는 서비스 구현에 사용할 수 있습니다.

이 작업에서는 Secret Manager에서 사용자 인증 정보를 만들고 보안 비밀로 저장합니다. 함수 로직의 키에 액세스하는 함수를 개발합니다.

보안 비밀 만들기

1. 보안 비밀을 만들고 사용하려면 Cloud Shell에서 다음 명령어를 실행하여 Secret Manager API를 사용 설정합니다.

   gcloud services enable secretmanager.googleapis.com

2. Secret Manager에서 값이 secret_api_key인 api-cred라는 이름의 보안 비밀을 만들고 저장합니다.

   echo -n "secret_api_key" | gcloud secrets create api-cred --replication-policy="automatic" --data-file=- replication-policy는 보안 비밀과 그 버전을 저장하는 데 사용되는 리전을 결정하는 데 사용됩니다. 보안 비밀을 복제할 수 있는 리전을 하나 이상 지정하려면 replication-policy를 user-managed로 설정하면 됩니다.

액세스 권한 부여하기

보안 비밀에 액세스하려면 함수의 런타임 서비스 계정에 보안 비밀에 대한 액세스 권한을 부여해야 합니다.

• 기본적으로 Cloud Run Functions는 Compute Engine 기본 서비스 계정을 함수의 런타임 서비스 계정으로 사용합니다.

  Secret Manager에 인증하려면 Compute Engine 기본 서비스 계정에 Secret Manager Secret Accessor 역할을 부여합니다.

  gcloud secrets add-iam-policy-binding api-cred --member=serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com --project=$PROJECT_ID --role='roles/secretmanager.secretAccessor' 참고: 프로덕션에서 사용하는 경우 함수의 작업을 수행하는 데 필요한 최소한의 역할 집합이 할당된 자체 사용자 관리 서비스 계정으로 인증하도록 함수를 구성해야 합니다.

함수에서 보안 비밀에 액세스하기

이 하위 작업에서는 앞서 개발한 newCustomer 함수를 수정하여 보안 비밀에 액세스합니다.

• 편집기에서 index.js 파일의 newCustomer 함수에 다음 코드를 추가합니다. 함수 본문의 마지막 console.log 문 이후 함수의 끝에 코드를 추가합니다.

  // BEGIN access a secret const fs = require('fs/promises'); try { const secret = await fs.readFile('/etc/secrets/api_cred/latest', { encoding: 'utf8' }); // use the secret. 실습 테스트를 위해 보안 비밀을 기록합니다. console.log('secret: ', secret); } catch (err) { console.log(err); } // End access a secret 함수 코드는 함수에서 액세스할 수 있는 볼륨에 마운트된 파일에서 보안 비밀 값을 읽습니다. 다음 단계에서 함수를 배포할 때 이 보안 비밀 액세스 방법을 구성합니다.

함수 재배포하기

1. Cloud Shell에서 보안 비밀을 포함하여 newCustomer 함수를 다시 배포합니다.

   gcloud functions deploy newCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=newCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.created \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}' \ --set-secrets '/etc/secrets/api_cred/latest=api-cred:latest' set-secrets 배포 명령어 옵션은 마운트 경로(/etc/secrets/api_cred)와 보안 비밀 경로(/latest)를 지정합니다.

   함수는 보안 비밀을 볼륨으로 참조함으로써 디스크에서 파일을 읽을 때마다 Secret Manager의 최신 보안 비밀 값에 액세스합니다.

   함수는 보안 비밀 값의 특정 버전을 환경 변수로 액세스할 수도 있습니다. 자세한 내용은 Cloud Run Functions에서 보안 비밀 사용에 관한 문서를 참조하세요.

2. 함수가 배포된 후 보안 비밀에 액세스할 수 있는지 확인합니다.

   gcloud functions describe newCustomer

   describe 명령어의 출력에는 보안 비밀에 대한 정보가 포함됩니다. 다음은 명령어의 출력 일부입니다.

   ... secretVolumes: - mountPath: /etc/secrets/api_cred projectId: '{{{project_0.project_id|Project_ID}}}' secret: api-cred versions: - path: /latest version: latest ...

함수 테스트하기

1. 함수를 테스트하려면 이전 작업의 테스트를 반복하여 Cloud 콘솔의 Firestore Studio에서 새 고객 문서를 추가합니다.

2. Cloud 콘솔에서 함수의 로그를 보려면 탐색 메뉴()에서 Cloud Run을 클릭합니다.

3. newCustomer 함수 이름을 클릭합니다.

4. 함수의 로그를 보려면 로그를 클릭합니다.

   보안 비밀 키의 값을 기록하는 항목이 있는지 확인합니다.

   secret: secret_api_key 참고: 보안 비밀의 값을 기록하는 것은 일반적인 관행이 아니지만, 이 단계는 함수가 보안 비밀 값에 액세스할 수 있으며 코드에서 보안 비밀을 사용할 수 있는지 확인하는 데 사용됩니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. Cloud Run Functions에서 보안 비밀 사용

수고하셨습니다

이 실습에서는 Firestore 데이터베이스를 설정하고 데이터베이스에 새 문서가 생성될 때 트리거되는 이벤트 기반 Cloud 함수를 개발했습니다. 문서가 업데이트될 때 문서에 새 필드를 추가하는 함수도 개발했습니다. 또한 Cloud Run Functions에서 보안 비밀을 만들고 액세스했으며 로그를 사용하여 보안 비밀 값을 확인했습니다.

다음 단계/자세히 알아보기

Firestore용 Cloud Run Functions 및 기타 주제에 대해 자세히 알아보려면 다음 문서를 참조하세요.

• Firestore 트리거
• 프로토콜 버퍼
• Firebase용 Cloud Functions

Copyright 2026 Google LLC All rights reserved. Google 및 Google 로고는 Google LLC의 상표입니다. 기타 모든 회사명 및 제품명은 해당 업체의 상표일 수 있습니다.