Начало работы: напишите, протестируйте и разверните свои первые функции (1-го поколения)

Чтобы начать работу с Cloud Functions, попробуйте выполнить инструкции из этого руководства. В нем описаны необходимые задачи по настройке, а также создание, тестирование и развертывание двух связанных функций:

• Функция add message, которая предоставляет URL, принимающий текстовое значение и записывающий его в Cloud Firestore.
• Функция "make uppercase", которая активируется при записи в Cloud Firestore и преобразует текст в верхний регистр.

Мы выбрали Cloud Firestore и функции JavaScript, активируемые по HTTP, в том числе потому, что эти фоновые триггеры можно тщательно протестировать с помощью Firebase Local Emulator Suite. Этот набор инструментов также поддерживает Realtime Database, PubSub, Auth и триггеры, вызываемые по HTTP. Другие типы фоновых триггеров, например Remote Config, TestLab и триггеры Аналитики, можно протестировать в интерактивном режиме с помощью наборов инструментов, не описанных на этой странице.

В следующих разделах этого руководства подробно описаны шаги, необходимые для создания, тестирования и развертывания примера. Если вы хотите просто запустить код и проверить его, перейдите к разделу Полный образец кода.

Как создать проект Firebase

Настройте Node.js и интерфейс командной строки Firebase

Для написания функций вам понадобится среда Node.js, а для их развертывания в среде выполнения Cloud Functions – интерфейс командной строки Firebase. Для установки Node.js и npm рекомендуется использовать Node Version Manager.

После установки Node.js и npm установите CLI Firebase удобным для вас способом. Чтобы установить CLI через npm, используйте:

npm install -g firebase-tools

Будет установлена глобально доступная команда firebase. Если команда не выполняется, возможно, вам нужно изменить разрешения npm. Чтобы обновить firebase-tools до последней версии, выполните ту же команду.

Инициализируйте проект

При инициализации SDK Firebase для Cloud Functions вы создаете пустой проект, содержащий зависимости и минимальный образец кода, и выбираете TypeScript или JavaScript для составления функций. Для целей этого руководства вам также потребуется инициализировать Cloud Firestore.

Чтобы инициализировать проект, выполните следующие действия:

1. Выполните команду firebase login, чтобы войти через браузер и аутентифицировать Firebase CLI.

2. Перейдите в каталог проекта Firebase.

3. Выполните команду firebase init firestore. В этом руководстве вы можете принять значения по умолчанию, когда вам будет предложено указать правила Firestore и файлы индексов. Если вы ещё не использовали Cloud Firestore в этом проекте, вам также нужно будет выбрать начальный режим и местоположение для Firestore, как описано в статье Начало работы с Cloud Firestore.

4. Выполните команду firebase init functions. CLI предложит вам выбрать существующую базу кода или инициализировать и назвать новую. На начальном этапе достаточно одной базы кода в местоположении по умолчанию. Позже, когда реализация расширится, вы можете организовать функции в базах кода.

5. CLI поддерживает следующие языки:

   • JavaScript
   • Python
   • TypeScript. Дополнительную информацию можно найти в статье Как писать функции на TypeScript.

   Изучая это руководство, выберите вариант JavaScript.

6. Интерфейс командной строки позволяет устанавливать зависимости с помощью npm. Если вы хотите управлять зависимостями другим способом, вы можете отказаться. В этом случае перед эмуляцией или развертыванием функций вам нужно будет выполнить команду npm install.

После успешного выполнения этих команд структура проекта будет выглядеть следующим образом:

myproject
 +- .firebaserc    # Hidden file that helps you quickly switch between
 |                 # projects with `firebase use`
 |
 +- firebase.json  # Describes properties for your project
 |
 +- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # main source file for your Cloud Functions code
      |
      +- node_modules/ # directory where your dependencies (declared in
                       # package.json) are installed

Файл package.json, созданный во время инициализации, содержит важный ключ "engines": {"node": "16"}. Здесь указывается версия Node.js для написания и развертывания функций. Вы можете выбрать другую поддерживаемую версию.

Импортируйте нужные модули и инициализируйте приложение

После выполнения данных инструкций вы сможете открыть каталог с исходными файлами и начать добавлять код, как описано в следующих разделах. Для этого примера в проект нужно импортировать модули Cloud Functions и Admin SDK с помощью инструкций require Node. Добавьте в файл index.js следующие строки:

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const { initializeApp } = require("firebase-admin/app");
const { getFirestore } = require("firebase-admin/firestore");
initializeApp();
index.js

Эти строки загружают модули firebase-functions и firebase-admin, а также инициализируют экземпляр приложения admin, из которого можно вносить изменения в Cloud Firestore. Admin SDK поддерживается в FCM, Authentication и Firebase Realtime Database и позволяет интегрировать Firebase с помощью Cloud Functions.

При инициализации проекта CLI Firebase автоматически устанавливает Firebase и SDK Firebase для модулей Node Cloud Functions. Чтобы добавить в проект сторонние библиотеки, измените файл package.json и выполните команду npm install. Подробную информацию можно найти в разделе Обработка зависимостей.

Добавьте функцию addMessage()

Для функции addMessage() добавьте в index.js следующие строки:

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await getFirestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});
index.js

Функция addMessage() – это конечная точка HTTP. Любой запрос к конечной точке приводит к тому, что объекты Request и Response в стиле ExpressJS передаются обратному вызову onRequest().

HTTP-функции синхронны (как и вызываемые функции), поэтому вам нужно как можно быстрее отправить ответ и отложить работу с помощью Cloud Firestore. Функция HTTP addMessage() передает текстовое значение конечной точке HTTP и вставляет его в базу данных по пути /messages/:documentId/original.

Добавьте функцию makeUppercase()

Для функции makeUppercase() добавьте в index.js следующие строки:

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });
index.js

Функция makeUppercase() выполняется при записи в Cloud Firestore. Функция ref.set определяет документ, который нужно прослушивать. Для повышения производительности следует указывать как можно более точные значения.

Фигурные скобки, например {documentId}, окружают параметры – подстановочные знаки, которые передают в обратный вызов соответствующие им данные.

Cloud Firestore активирует обратный вызов onCreate() при добавлении новых сообщений.

Функции, управляемые событиями, например события Cloud Firestore, являются асинхронными. Функция обратного вызова должна возвращать null, объект или Promise. Если вы ничего не возвращаете, время ожидания функции истекает, сигнализируя об ошибке, и выполняется повторная попытка. Подробнее о синхронных и асинхронных функциях и промисах…

Эмулируйте выполнение своих функций

Firebase Local Emulator Suite позволяет создавать и тестировать приложения на локальном компьютере, не развертывая их в проекте Firebase. Настоятельно рекомендуем проводить локальное тестирование во время разработки, в частности потому, что это снижает риск ошибок в коде, которые могут привести к дополнительным расходам в рабочей среде (например, бесконечный цикл).

Чтобы эмулировать функции:

1. Выполните команду firebase emulators:start и найдите в выходных данных URL Emulator Suite UI. По умолчанию используется localhost:4000, но на вашем компьютере может быть выбран другой порт. Введите этот URL в браузере, чтобы открыть Emulator Suite UI.

2. Проверьте выходные данные команды firebase emulators:start для URL HTTP-функции addMessage(). Он будет похож на http://localhost:5001/MY_PROJECT/us-central1/addMessage, но с некоторыми отличиями:

   1. Вместо MY_PROJECT будет указан идентификатор вашего проекта.
   2. На вашем локальном компьютере порт может быть другим.

3. Добавьте строку запроса ?text=uppercaseme в конец URL функции. Это будет выглядеть примерно так: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. При желании вы можете изменить сообщение uppercaseme на собственное.

4. Чтобы создать сообщение, откройте URL в новой вкладке браузера.

5. Посмотрите, как работают функции в Emulator Suite UI:

   1. На вкладке Журналы вы увидите новые записи, указывающие на то, что функции addMessage() и makeUppercase() были выполнены:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

   2. На вкладке Firestore вы увидите документ, содержащий исходное сообщение и его версию, написанную заглавными буквами (если исходное сообщение было "uppercaseme", вы увидите "UPPERCASEME").

Развертывание функций в рабочей среде

Когда функции будут работать в эмуляторе так, как нужно, вы сможете развернуть, протестировать и запустить их в рабочей среде. Помните, что для развертывания в среде выполнения Node.js 14 ваш проект должен использовать тарифный план Blaze. Подробнее о ценах на Cloud Functions…

Чтобы завершить обучение, разверните функции и выполните addMessage(), чтобы запустить makeUppercase().

1. Выполните эту команду, чтобы развернуть функции:

    firebase deploy --only functions
    

   После выполнения этой команды CLI Firebase выведет URL для всех конечных точек HTTP-функций. В терминале должна появиться строка, похожая на следующую:

   Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
   

   URL содержит идентификатор проекта и регион для функции HTTP. Вам не нужно беспокоиться об этом сейчас, но для некоторых рабочих HTTP-функций следует указать местоположение, чтобы минимизировать задержку в сети.

   Если вы столкнулись с ошибками доступа, например "Не удалось авторизовать доступ к проекту", проверьте псевдонимы проекта.

2. Используя URL addMessage(), выведенный CLI, добавьте параметр текстового запроса и откройте его в браузере:

   https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
   

   Функция выполняется и перенаправляет браузер в консоль Firebase в местоположении базы данных, где хранится текстовая строка. Это событие записи активирует makeUppercase(), который записывает версию строки в верхнем регистре.

После развертывания и выполнения функций вы можете просматривать журналы в консоли Google Cloud. Если вам нужно удалить функции в среде разработки или рабочей среде, используйте интерфейс командной строки Firebase.

В рабочей среде вы можете оптимизировать производительность функций и контролировать затраты, задав минимальное и максимальное количество экземпляров для запуска. Подробнее о том, как управлять масштабированием…

Полный образец кода

Вот готовый functions/index.js, содержащий функции addMessage() и makeUppercase(). Эти функции позволяют передать параметр конечной точке HTTP, которая записывает значение в Cloud Firestore, а затем преобразует его, переводя все символы в строке в верхний регистр.

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const { initializeApp } = require("firebase-admin/app");
const { getFirestore } = require("firebase-admin/firestore");
initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await getFirestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });
index.js

Дальнейшие действия

В этой документации вы можете узнать больше о том, как управлять функциями для Cloud Functions, а также как обрабатывать все типы событий, поддерживаемые Cloud Functions.

Чтобы узнать больше о Cloud Functions, вы также можете сделать следующее:

• Подробнее о примерах использования Cloud Functions…
• Попробуйте практическую работу по Cloud Functions.
• Изучите и запустите примеры кода на GitHub.