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

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

• Функция «добавить сообщение», которая предоставляет URL-адрес, принимающий текстовое значение и записывающий его в Cloud Firestore .
• Функция преобразования текста в верхний регистр, которая срабатывает при записи в Cloud Firestore и преобразует текст в верхний регистр.

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

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

Создайте проект Firebase.

Настройте Node.js и Firebase CLI.

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

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

npm install -g firebase-tools

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

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

При инициализации Firebase SDK для 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 . Интерфейс командной строки предложит вам выбрать существующую кодовую базу или инициализировать и назвать новую. На начальном этапе достаточно одной кодовой базы в расположении по умолчанию; позже, по мере расширения вашей реализации, вы можете захотеть организовать функции в кодовые базы .

5. Интерфейс командной строки предоставляет следующие возможности для поддержки языков:

   • 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 admin = require("firebase-admin");
admin.initializeApp();
index.js

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

Интерфейс командной строки Firebase автоматически устанавливает модули Node Firebase и Firebase SDK для 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 admin
    .firestore()
    .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 , либо объект, либо промис . Если ничего не возвращается, функция завершается по истечении времени ожидания, сигнализируя об ошибке, и повторяется. См. раздел «Синхронные, асинхронные функции и промисы» .

Имитируйте выполнение ваших функций.

Пакет 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
    

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

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

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

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

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

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

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

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

В производственной среде может потребоваться оптимизация производительности функций и контроль затрат путем установки минимального и максимального количества запускаемых экземпляров. Дополнительную информацию об этих параметрах во время выполнения см. в разделе «Управление поведением масштабирования» .

Ознакомьтесь с полным примером кода.

Вот готовый файл 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 admin = require("firebase-admin");
admin.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 admin
    .firestore()
    .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.