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

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

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

   • JavaScript
   • Машинопись
   • Python

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

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

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

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

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

Пакет 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 по адресу базы данных, где хранится текстовая строка. Это событие записи запускает функцию "преобразовать в верхний регистр", которая записывает версию строки в верхнем регистре.

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

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

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

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

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

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