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

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

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

Вот полный пример кода, содержащий функции:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

// 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 = 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 saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

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

  const uppercase = original.toUpperCase();

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

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()


@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")


@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

Об этом уроке

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

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

Создать проект 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 .

Настройте свою среду и Firebase CLI

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

При инициализации Firebase SDK для Cloud Functions создаётся пустой проект, содержащий зависимости и минимальный пример кода. Если вы используете Node.js, вы можете выбрать 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
   • Машинопись
   • Питон

   Для этого руководства выберите JavaScript или Python . Для написания кода на TypeScript см. раздел «Написание функций на TypeScript» .

6. Интерфейс командной строки (CLI) позволяет устанавливать зависимости. От этой опции можно отказаться, если вы хотите управлять зависимостями другим способом.

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

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

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
      |
      +- main.py      # Main source file for your Cloud Functions code
      |
      +- requirements.txt  #  List of the project's modules and packages 
      |
      +- venv/ # Directory where your dependencies are installed

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

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

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

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

initializeApp();
index.js

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()
main.py

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

Firebase CLI автоматически устанавливает модули Firebase Admin SDK и Firebase SDK for Cloud Functions при инициализации проекта. Подробнее о добавлении сторонних библиотек в проект см. в разделе «Обработка зависимостей» .

Добавить функцию «добавить сообщение»

Для функции «добавить сообщение» добавьте следующие строки в исходный файл:

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = 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

@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")
main.py

Функция «добавить сообщение» — это конечная точка HTTP. Любой запрос к конечной точке приводит к отправке объектов запроса и ответа, которые передаются обработчику запросов вашей платформы ( onRequest() или on_request ).

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

Добавить функцию «сделать заглавными»

Для функции «сделать заглавными» добавьте следующие строки в исходный файл:

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

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

  const uppercase = original.toUpperCase();

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

@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

Функция «make uppercase» выполняется при записи в Cloud Firestore , определяя документ для прослушивания. В целях производительности следует указывать максимально точные данные.

В фигурные скобки, например, {documentId} заключены «параметры» — подстановочные знаки, которые отображают соответствующие им данные в обратном вызове. Cloud Firestore запускает обратный вызов при каждом добавлении новых сообщений.

В Node.js функции, управляемые событиями, такие как события 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-функции. Он будет выглядеть примерно так 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. На вкладке «Журналы» вы должны увидеть новые журналы, указывающие на то, что ваши HTTP-функции были выполнены успешно:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

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

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

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

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

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-адрес, выведенный CLI, добавьте параметр текстового запроса и откройте его в браузере:

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

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

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

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

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

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

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

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