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

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

• Функция add message, которая предоставляет URL, принимающий текстовое значение и записывающий его в Cloud Firestore.
• Функция "make uppercase", которая активируется при записи в Cloud Firestore и преобразует текст в верхний регистр.

Ниже приведен полный образец кода, содержащий функции.

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/https");
const {onDocumentCreated} = require("firebase-functions/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

Настройте среду и интерфейс командной строки Firebase

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

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

5. CLI поддерживает следующие языки:

   • JavaScript
   • TypeScript
   • Python

   Изучая это руководство, выберите 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/https");
const {onDocumentCreated} = require("firebase-functions/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.

При инициализации проекта CLI Firebase автоматически устанавливает Firebase Admin SDK и SDK Firebase для модулей Cloud Functions. Подробнее о том, как добавлять сторонние библиотеки в проект…

Добавьте функцию add message

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

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

Функция add message – это конечная точка HTTP. Любой запрос к конечной точке приводит к передаче объектов запроса и ответа обработчику запросов для вашей платформы (onRequest() или on_request).

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

Добавьте функцию "make uppercase" (сделать заглавными).

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

// 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, объект или 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. На вкладке Logs (Журналы) должны появиться новые записи, указывающие на то, что 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
    

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

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

Дальнейшие действия

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

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

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