Начало работы: напишите, протестируйте и разверните свои первые функции.


Чтобы приступить к работе с 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

  1. В консоли Firebase нажмите Добавить проект .

    • Чтобы добавить ресурсы Firebase в существующий проект Google Cloud , введите имя проекта или выберите его из раскрывающегося меню.

    • Чтобы создать новый проект, введите его название. Вы также можете изменить идентификатор проекта, отображаемый под его названием.

  2. При необходимости ознакомьтесь и примите условия Firebase .

  3. Нажмите «Продолжить» .

  4. (Необязательно) Настройте Google Analytics для своего проекта, что обеспечит оптимальную работу с использованием следующих продуктов Firebase: Firebase A/B Testing , Cloud Messaging , Crashlytics , In-App Messaging и Remote Config (включая Personalization ).

    Выберите существующий аккаунт Google Analytics или создайте новый. При создании нового аккаунта выберите местоположение для отчётов Google Analytics , а затем примите настройки доступа к данным и условия использования Google Analytics для вашего проекта.

  5. Нажмите «Создать проект» (или «Добавить Firebase» , если вы добавляете Firebase в существующий проект Google Cloud ).

Firebase автоматически выделяет ресурсы для вашего проекта Firebase. После завершения процесса вы будете перенаправлены на страницу обзора вашего проекта Firebase в консоли 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. CLI предоставляет вам следующие возможности языковой поддержки:

    Для этого руководства выберите JavaScript .

  6. Интерфейс командной строки (CLI) позволяет устанавливать зависимости с помощью 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 с помощью операторов Node require . Добавьте в файл 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 CLI автоматически устанавливает модули Firebase и Firebase SDK for Cloud Functions Node при инициализации проекта. Чтобы добавить сторонние библиотеки в проект, отредактируйте 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 , либо Object , либо Promise . Если функция не возвращает ничего, она завершается по тайм-ауту, сигнализируя об ошибке, и выполняется повторно. См. разделы Синхронизация, Асинхронность и 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

    После выполнения этой команды Firebase CLI выведет 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 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 , вы также можете сделать следующее: