Catch up on highlights from Firebase at Google I/O 2023. Learn more

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


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

  • Функция «добавить сообщение», которая предоставляет 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:

    Либо выберите существующую учетную запись Google Analytics , либо создайте новую учетную запись.

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

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

Firebase автоматически выделяет ресурсы для вашего проекта Firebase. Когда процесс завершится, вы попадете на страницу обзора вашего проекта Firebase в консоли Firebase.

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

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

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

npm install -g firebase-tools

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

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

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

    Для этого руководства выберите 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");

// 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, аутентификации и базы данных Firebase Realtime, она обеспечивает мощный способ интеграции Firebase с использованием облачных функций.

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

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

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

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

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

  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:

    1. На вкладке «Журналы» вы должны увидеть новые журналы, указывающие на выполнение функций addMessage() и makeUppercase() :

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

    2. На вкладке Firestore вы должны увидеть документ, содержащий ваше исходное сообщение, а также версию вашего сообщения в верхнем регистре (если оно изначально было «верхним регистром», вы увидите «ВЕРХНИЙ РЕГИСТР»).

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

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

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

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

     firebase deploy --only functions

    После запуска этой команды интерфейс командной строки Firebase выводит 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 Console . Если вам нужно удалить функции в разработке или производстве, используйте интерфейс командной строки 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");

// 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

Следующие шаги

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

Чтобы узнать больше об облачных функциях, вы также можете сделать следующее: