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

Чтобы начать работу с 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/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.
2. Перейдите в каталог проекта Firebase.
3. Выполните команду firebase init firestore. В этом руководстве можно принять значения по умолчанию, когда вам будет предложено задать правила Firestore и индексные файлы. Если вы ещё не использовали Cloud Firestore в этом проекте, вам также нужно будет выбрать начальный режим и местоположение для Firestore, как описано в статье Начало работы с Cloud Firestore.
4. Выполните команду firebase init functions. Интерфейс командной строки предложит вам выбрать существующую базу кода или инициализировать и назвать новую. На начальном этапе достаточно одного набора кода в местоположении по умолчанию. Позже, когда вы расширите реализацию, вам может понадобиться организовать функции в наборы кода.

5. В интерфейсе командной строки доступны следующие варианты поддержки языков:

   • 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.

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

Как эмулировать выполнение функций

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 выводит 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.

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

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

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

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

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