콘솔로 이동

Cloud 함수로 Cloud Firestore 확장

클라우드 함수를 사용하면 Node.js 코드를 배포하여 Cloud Firestore 데이터베이스의 변경을 통해 트리거되는 이벤트를 처리할 수 있습니다. 덕분에 자체 서버를 실행하지 않고도 앱에 서버 측 기능을 쉽게 추가할 수 있습니다.

사용 사례는 클라우드 함수로 무엇을 할 수 있나요? 또는 함수 샘플 GitHub 저장소를 참조하세요.

Cloud Firestore 함수 트리거

Firebase용 Cloud 함수 SDK는 특정 이벤트에 연결된 핸들러를 만들 수 있는 functions.firestore 개체를 내보냅니다.

Cloud Firestore는 create, update, delete, write 이벤트를 지원합니다.

이벤트 유형 트리거
onCreate 문서를 처음으로 기록할 때 트리거됩니다.
onUpdate 이미 존재하는 문서에서 값이 변경되었을 때 트리거됩니다.
onDelete 데이터가 있는 문서가 삭제될 때 트리거됩니다.
onWrite onCreate, onUpdate 또는 onDelete가 트리거될 때 트리거됩니다.

Firebase용 Cloud 함수가 사용 설정된 프로젝트가 없으면 시작하기: 첫 번째 함수 작성 및 배포를 읽고 Firebase 프로젝트에 Cloud 함수를 구성 및 설정하세요.

특정 문서가 변경될 때 함수 트리거

다음 함수를 사용하면 특정 문서의 모든 변경에 이벤트를 트리거할 수 있습니다.

Node.js

// Listen for any change on document `marie` in collection `users`
exports.myFunctionName = functions.firestore
    .document('users/marie').onWrite((change, context) => {
      // ... Your code here
    });

새 문서가 생성될 때 함수 트리거

와일드 카드와 함께 onCreate() 핸들러를 사용하면 컬렉션에 새 문서가 생성될 때마다 함수를 트리거하여 실행할 수 있습니다. 다음은 새 사용자 프로필이 추가될 때마다 createUser를 호출하는 함수의 예입니다.

Node.js

exports.createUser = functions.firestore
    .document('users/{userId}')
    .onCreate((snap, context) => {
      // Get an object representing the document
      // e.g. {'name': 'Marie', 'age': 66}
      const newValue = snap.data();

      // access a particular field as you would any JS property
      const name = newValue.name;

      // perform desired operations ...
    });

문서가 업데이트될 때 함수 트리거

또한 와일드 카드와 함께 onUpdate() 함수를 사용하면 문서가 업데이트될 때 함수를 트리거하여 실행할 수 있습니다. 다음은 사용자가 프로필을 변경하면 updateUser를 호출하는 함수의 예입니다.

Node.js

exports.updateUser = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Get an object representing the document
      // e.g. {'name': 'Marie', 'age': 66}
      const newValue = change.after.data();

      // ...or the previous value before this update
      const previousValue = change.before.data();

      // access a particular field as you would any JS property
      const name = newValue.name;

      // perform desired operations ...
    });

문서가 삭제될 때 함수 트리거

와일드 카드와 함께 onDelete() 함수를 사용하여 문서가 삭제될 때 함수를 트리거할 수 있습니다. 다음은 사용자가 자신의 사용자 프로필을 삭제하면 deleteUser를 호출하는 함수의 예입니다.

Node.js

exports.deleteUser = functions.firestore
    .document('users/{userID}')
    .onDelete((snap, context) => {
      // Get an object representing the document prior to deletion
      // e.g. {'name': 'Marie', 'age': 66}
      const deletedValue = snap.data();

      // perform desired operations ...
    });

문서 변경 시 함수 트리거

발생하는 이벤트 유형에 관계없이 Cloud Firestore 문서의 모든 변경을 수신 대기하려면 와일드 카드와 함께 onWrite() 함수를 사용합니다. 다음은 사용자가 생성, 업데이트 또는 삭제될 때 modifyUser를 호출하는 함수의 예입니다.

Node.js

exports.modifyUser = functions.firestore
    .document('users/{userID}')
    .onWrite((change, context) => {
      // Get an object with the current document value.
      // If the document does not exist, it has been deleted.
      const document = change.after.exists ? change.after.data() : null;

      // Get an object with the previous document value (for update or delete)
      const oldDocument = change.before.data();

      // perform desired operations ...
    });

이벤트 데이터 처리

데이터 읽기

함수가 트리거될 때 업데이트된 문서의 데이터 또는 업데이트되기 전의 데이터를 가져와야 할 수 있습니다. 이전 데이터를 가져오려면 업데이트 전의 문서 스냅샷을 포함하는 change.before.data()를 사용합니다. 마찬가지로 change.after.data()는 업데이트 후의 문서 스냅샷 상태를 포함합니다.

Node.js

exports.updateUser = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Get an object representing the current document
      const newValue = change.after.data();

      // ...or the previous value before this update
      const previousValue = change.before.data();
    });

다른 개체와 마찬가지로 속성에 액세스할 수 있습니다. 또는 get 함수를 사용하여 특정 필드에 액세스할 수 있습니다.

Node.js

// Fetch data using standard accessors
const age = snap.data().age;
const name = snap.data()['name'];

// Fetch data using built in accessor
const experience = snap.get('experience');

데이터 쓰기

각 함수 호출은 Cloud Firestore 데이터베이스의 특정 문서와 연관됩니다. 함수로 반환되는 스냅샷의 ref 속성에 있는 DocumentReference로 이 문서에 액세스할 수 있습니다.

Cloud Firebase Node.js SDK에서 제공하는 DocumentReference에는 update(), set(), remove() 등의 메소드가 포함되어 있으므로 함수를 트리거한 문서를 쉽게 수정할 수 있습니다.

Node.js

// Listen for updates to any `user` document.
exports.countNameChanges = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Retrieve the current and previous value
      const data = change.after.data();
      const previousData = change.before.data();

      // We'll only update if the name has changed.
      // This is crucial to prevent infinite loops.
      if (data.name == previousData.name) return;

      // Retrieve the current count of name changes
      let count = data.name_change_count;
      if (!count) {
        count = 0;
      }

      // Then return a promise of a set operation to update the count
      return change.after.ref.set({
        name_change_count: count + 1
      }, {merge: true});
    });

와일드 카드 및 매개변수 사용

이벤트 트리거를 연결할 문서를 특정할 수 없는 경우 문서 ID 대신 {wildcard}를 사용할 수 있습니다.

Node.js

// Listen for changes in all documents and all sub-collections
exports.useWildcard = functions.firestore
    .document('users/{userId}')
    .onWrite((change, context) => {
      // If we set `/users/marie` to {name: "marie"} then
      // context.params.userId == "marie"
      // ... and ...
      // change.after.data() == {name: "Marie"}
    });

이 예에서 users의 문서에서 필드가 하나라도 변경되면 userId라는 와일드 카드와 일치시킵니다.

users의 문서에 있는 하위 컬렉션의 문서 중 하나에 속한 필드가 변경되면 userId 와일드 카드가 트리거되지 않습니다.

와일드 카드 일치는 문서 경로에서 추출되어 event.params에 저장됩니다. 개수 제한 없이 원하는 만큼 와일드 카드를 정의하여 구체적인 컬렉션 또는 문서 ID를 대체할 수 있습니다.

Node.js

// Listen for changes in all documents and all subcollections
exports.useMultipleWildcards = functions.firestore
    .document('users/{userId}/{messageCollectionId}/{messageId}')
    .onWrite((change, context) => {
      // If we set `/users/marie/incoming_messages/134` to {body: "Hello"} then
      // context.params.userId == "marie";
      // context.params.messageCollectionId == "incoming_messages";
      // context.params.messageId == "134";
      // ... and ...
      // change.after.data() == {body: "Hello"}
    });

제한 및 보증

Cloud Firestore와 Firebase용 클라우드 함수는 베타 버전이므로 애플리케이션 개발 중에 예기치 않은 동작이 발생할 수 있다는 점에 유의하시기 바랍니다.

다음을 비롯하여 몇 가지 제한사항이 알려져 있습니다.

  • Cloud Firestore 데이터가 변경된 후 함수가 트리거되기까지 5초 이상 걸릴 수 있습니다.
  • 함수 호출이 현재 확실하게 보장되지 않습니다. 앞으로는 Cloud Firestore와 Cloud 함수의 통합이 개선됨에 따라 '최소 1회' 호출을 보장할 예정입니다. 그러나 베타 기간에는 확실한 보장이 불가능합니다. 또한 단일 이벤트에 호출이 여러 번 이루어질 수 있으므로 함수의 품질을 높이려면 함수가 멱등성을 갖도록 작성하세요.
  • 순서가 보장되지 않습니다. 변경이 빈번하게 발생할 경우 예기치 않은 순서로 함수가 호출될 수 있습니다.