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


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

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

Мы выбрали Cloud Firestore и HTTP-триггерные функции JavaScript для этого примера отчасти потому, что эти фоновые триггеры можно тщательно протестировать с помощью 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 , либо создайте новую учетную запись. Если вы создаете новую учетную запись, выберите местоположение отчетов Analytics , затем примите настройки совместного использования данных и условия Google Analytics для вашего проекта.

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

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

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

Вам понадобится среда Node.js для написания функций, а также Firebase CLI для развертывания функций в среде выполнения Cloud Functions . Для установки 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 . CLI предложит вам выбрать существующую кодовую базу или инициализировать и назвать новую. Когда вы только начинаете, достаточно одной кодовой базы в расположении по умолчанию; позже, по мере расширения вашей реализации, вам может потребоваться организовать функции в кодовые базы .

  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 для Cloud Functions Node при инициализации проекта. Чтобы добавить сторонние библиотеки в проект, можно изменить package.json и запустить npm install . Для получения дополнительной информации см. Handle Dependencies .

Добавьте функцию 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 . Если вы ничего не возвращаете, функция истекает по времени, сигнализируя об ошибке, и выполняется повторно. См. Sync, Async и Promises .

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

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 , вы также можете сделать следующее: