Чтобы начать работу с Cloud Functions , попробуйте изучить это руководство, которое начинается с необходимых задач по настройке и завершается созданием, тестированием и развертыванием двух связанных функций:
- Функция «добавить сообщение», которая предоставляет URL-адрес, принимающий текстовое значение, и записывает его в Cloud Firestore .
- Функция «сделать верхний регистр», которая срабатывает при записи Cloud Firestore и преобразует текст в верхний регистр.
Для этого примера мы выбрали Cloud Firestore и функции JavaScript, запускаемые по HTTP, отчасти потому, что эти фоновые триггеры можно тщательно протестировать с помощью Firebase Local Emulator Suite . Этот набор инструментов также поддерживает вызываемые триггеры Realtime Database , PubSub, Auth и HTTP. Другие типы фоновых триггеров, такие как триггеры Remote Config , TestLab и Analytics, можно тестировать в интерактивном режиме с использованием наборов инструментов, не описанных на этой странице.
В следующих разделах этого руководства подробно описаны шаги, необходимые для сборки, тестирования и развертывания примера. Если вы предпочитаете просто запустить код и проверить его, перейдите к разделу «Просмотр полного примера кода» .
Создать проект Firebase
В консоли Firebase нажмите «Добавить проект» .
Чтобы добавить ресурсы Firebase в существующий проект Google Cloud , введите название его проекта или выберите его из раскрывающегося меню.
Чтобы создать новый проект, введите желаемое имя проекта. Вы также можете при желании изменить идентификатор проекта, отображаемый под названием проекта.
При появлении запроса прочтите и примите условия Firebase .
Нажмите Продолжить .
(Необязательно) Настройте Google Analytics для своего проекта, что позволит вам оптимально использовать любой из следующих продуктов Firebase:
Либо выберите существующую учетную запись Google Analytics , либо создайте новую учетную запись.
Если вы создаете новую учетную запись, выберите местоположение для отчетов Analytics , затем примите настройки совместного использования данных и условия Google Analytics для вашего проекта.
Нажмите «Создать проект» (или «Добавить Firebase» , если вы используете существующий проект Google Cloud ).
Firebase автоматически выделяет ресурсы для вашего проекта Firebase. Когда процесс завершится, вы перейдете на страницу обзора вашего проекта Firebase в консоли Firebase .
Настройте Node.js и интерфейс командной строки Firebase.
Для написания функций вам понадобится среда Node.js , а для развертывания функций в среде выполнения Cloud Functions вам понадобится интерфейс командной строки Firebase . Для установки 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 .
Чтобы инициализировать проект:
- Запустите
firebase login
, чтобы войти в систему через браузер и аутентифицировать интерфейс командной строки Firebase . - Перейдите в каталог проекта Firebase.
- Запустите
firebase init firestore
. В этом руководстве вы можете принять значения по умолчанию при появлении запроса на правила Firestore и индексные файлы. Если вы еще не использовали Cloud Firestore в этом проекте, вам также необходимо выбрать режим запуска и местоположение для Firestore, как описано в разделе «Начало работы с Cloud Firestore . - Запустите
firebase init functions
. Интерфейс командной строки предложит вам выбрать существующую кодовую базу или инициализировать и назвать новую. Когда вы только начинаете, достаточно одной базы кода в расположении по умолчанию; позже, по мере расширения вашей реализации, вы можете захотеть организовать функции в базах кода . CLI предоставляет вам два варианта языковой поддержки:
- JavaScript
- TypeScript Дополнительные сведения см. в разделе «Функции записи с помощью TypeScript» .
Для этого урока выберите JavaScript .
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();
Эти строки загружают модули firebase-functions
и firebase-admin
и инициализируют экземпляр приложения admin
, из которого можно вносить изменения Cloud Firestore . Везде, где доступна поддержка Admin SDK , например, для FCM , Authentication и Firebase Realtime Database , она обеспечивает мощный способ интеграции Firebase с использованием Cloud Functions .
Интерфейс командной строки Firebase автоматически устанавливает модули Firebase и Firebase SDK для узла Cloud Functions при инициализации проекта. Чтобы добавить сторонние библиотеки в свой проект, вы можете изменить package.json
и запустить npm install
. Дополнительные сведения см. в разделе Обработка зависимостей .
Добавьте функцию 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.` }); });
Функция 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 }); });
Функция makeUppercase()
выполняется при записи в Cloud Firestore . Функция ref.set
определяет документ для прослушивания. Из соображений производительности вы должны быть как можно более конкретными.
Фигурные скобки, например {documentId}
заключают в себе «параметры», подстановочные знаки, которые предоставляют соответствующие данные в обратном вызове.
Cloud Firestore запускает обратный вызов onCreate()
всякий раз, когда добавляются новые сообщения.
Функции, управляемые событиями, такие как события Cloud Firestore являются асинхронными. Функция обратного вызова должна возвращать либо null
, либо Object, либо Promise . Если вы ничего не возвращаете, время ожидания функции истекает, сигнализируя об ошибке, и она повторяется. См . раздел «Синхронизация, асинхронность и обещания» .
Эмулируйте выполнение ваших функций
Firebase Local Emulator Suite позволяет создавать и тестировать приложения на локальном компьютере вместо развертывания в проекте Firebase. Настоятельно рекомендуется локальное тестирование во время разработки, отчасти потому, что оно снижает риск ошибок кодирования, которые потенциально могут повлечь за собой затраты в производственной среде (например, бесконечный цикл).
Чтобы эмулировать ваши функции:
Запустите
firebase emulators:start
и проверьте выходные данные на наличие URL-адреса Emulator Suite UI . По умолчанию используется localhost:4000 , но он может быть размещен на другом порту вашего компьютера. Введите этот URL-адрес в браузере, чтобы открыть Emulator Suite UI .Проверьте выходные данные
firebase emulators:start
на наличие URL-адреса HTTP-функцииaddMessage()
. Он будет выглядеть примерно такhttp://localhost:5001/MY_PROJECT/us-central1/addMessage
, за исключением того:-
MY_PROJECT
будет заменен идентификатором вашего проекта. - Порт может быть другим на вашем локальном компьютере.
-
Добавьте строку запроса
?text=uppercaseme
в конец URL-адреса функции. Это должно выглядеть примерно так:http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme
. При желании вы можете изменить сообщение «заглавная буква» на собственное сообщение.Создайте новое сообщение, открыв URL-адрес в новой вкладке браузера.
Просмотрите эффекты функций в Emulator Suite UI :
На вкладке «Журналы» вы должны увидеть новые журналы, указывающие на выполнение функций
addMessage()
иmakeUppercase()
:i functions: Beginning execution of "addMessage"
i functions: Beginning execution of "makeUppercase"
На вкладке Firestore вы должны увидеть документ, содержащий ваше исходное сообщение, а также версию вашего сообщения, написанную заглавными буквами (если изначально оно было «ПРОПИСНЫМИ», вы увидите «ПРОПИСНУЮ»).
Развертывание функций в производственной среде
Как только ваши функции в эмуляторе заработают должным образом, вы можете приступить к их развертыванию, тестированию и запуску в производственной среде. Имейте в виду, что для развертывания в рекомендуемой среде выполнения Node.js 14 ваш проект должен находиться в тарифном плане Blaze . См. цены на Cloud Functions .
Чтобы завершить руководство, разверните свои функции, а затем выполните addMessage()
чтобы вызвать makeUppercase()
.
Запустите эту команду, чтобы развернуть ваши функции:
firebase deploy --only functions
После запуска этой команды интерфейс командной строки Firebase выводит URL-адрес для всех конечных точек функции HTTP. В вашем терминале вы должны увидеть строку, подобную следующей:
Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
URL-адрес содержит идентификатор вашего проекта, а также регион для функции HTTP. Хотя сейчас вам не нужно об этом беспокоиться, некоторые рабочие HTTP-функции должны указывать местоположение , чтобы минимизировать задержку в сети.
Если вы столкнулись с ошибками доступа, такими как «Невозможно авторизовать доступ к проекту», попробуйте проверить псевдоним проекта .
Используя URL-адрес
addMessage()
выводимый CLI, добавьте текстовый параметр запроса и откройте его в браузере:https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
Функция выполняет и перенаправляет браузер на консоль Firebase в том месте базы данных, где хранится текстовая строка. Это событие записи запускает
makeUppercase()
, который записывает версию строки в верхнем регистре.
После развертывания и выполнения функций вы можете просмотреть логи в консоли Google Cloud . Если вам нужно удалить функции в разработке или производстве, используйте интерфейс командной строки Firebase .
В производственной среде вы можете оптимизировать производительность функций и контролировать затраты, устанавливая минимальное и максимальное количество запускаемых экземпляров. Дополнительные сведения об этих параметрах среды выполнения см. в разделе Поведение управления масштабированием .
Просмотрите полный пример кода
Вот завершенный 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 }); });
Следующие шаги
В этой документации вы можете узнать больше о том, как управлять функциями Cloud Functions , а также как обрабатывать все типы событий, поддерживаемые Cloud Functions .
Чтобы узнать больше об Cloud Functions , вы также можете сделать следующее:
- Прочтите о вариантах использования Cloud Functions .
- Попробуйте кодовую лабораторию Cloud Functions .
- Просмотрите и запустите примеры кода на GitHub.
Чтобы начать работу с Cloud Functions , попробуйте изучить это руководство, которое начинается с необходимых задач по настройке и завершается созданием, тестированием и развертыванием двух связанных функций:
- Функция «добавить сообщение», которая предоставляет URL-адрес, принимающий текстовое значение, и записывает его в Cloud Firestore .
- Функция «сделать верхний регистр», которая срабатывает при записи Cloud Firestore и преобразует текст в верхний регистр.
Мы выбрали Cloud Firestore и HTTP-функции JavaScript для этого образца частично, потому что эти фоновые триггеры могут быть тщательно протестированы через Firebase Local Emulator Suite . Этот набор инструментов также поддерживает Realtime Database , PubSub, Auth и HTTP Callable Triggers. Другие типы фоновых триггеров, таких как Remote Config , тестовые и аналитические триггеры, могут быть протестированы интерактивно с использованием наборов инструментов, не описанных на этой странице.
В следующих разделах этого учебного пособия подробно описываются шаги, необходимые для создания, тестирования и развертывания образца. Если вы предпочитаете просто запустить код и проверить его, перейдите, чтобы просмотреть полный пример кода .
Создать проект Firebase
В консоли Firebase нажмите «Добавить проект» .
Чтобы добавить ресурсы Firebase в существующий проект Google Cloud , введите название его проекта или выберите его из раскрывающегося меню.
Чтобы создать новый проект, введите желаемое имя проекта. Вы также можете при желании изменить идентификатор проекта, отображаемый под названием проекта.
При появлении запроса прочтите и примите условия Firebase .
Нажмите Продолжить .
(Необязательно) Настройте Google Analytics для своего проекта, что позволит вам оптимально использовать любой из следующих продуктов Firebase:
Либо выберите существующую учетную запись Google Analytics , либо создайте новую учетную запись.
Если вы создаете новую учетную запись, выберите местоположение для отчетов Analytics , затем примите настройки совместного использования данных и условия Google Analytics для вашего проекта.
Нажмите «Создать проект» (или «Добавить Firebase» , если вы используете существующий проект Google Cloud ).
Firebase автоматически выделяет ресурсы для вашего проекта Firebase. Когда процесс завершится, вы перейдете на страницу обзора вашего проекта Firebase в консоли Firebase .
Настройка node.js и CLI Firebase
Вам понадобится среда Node.js для написания функций, и вам понадобится CLI Firebase для развертывания функций в среду выполнения Cloud Functions . Для установки Node.js и NPM рекомендуется диспетчер версий Node .
После установки Node.js и NPM установите CLI Firebase с помощью вашего предпочтительного метода. Чтобы установить CLI через NPM, используйте:
npm install -g firebase-tools
Это устанавливает глобально доступную команду Firebase. Если команда не удается, вам может потребоваться изменить разрешения NPM . Чтобы обновиться до последней версии firebase-tools
, повторно затроните ту же команду.
Инициализируйте свой проект
Когда вы инициализации SDK Firebase SDK для Cloud Functions вы создаете пустой проект, содержащий зависимости и некоторый минимальный код выборки, и вы выбираете либо TypeScript, либо JavaScript для сочинения функций. Для целей этого урока вам также необходимо инициализировать Cloud Firestore .
Для инициализации вашего проекта:
- Запустите
firebase login
, чтобы войти через браузер и аутентифицировать CLI Firebase . - Перейдите в свой каталог проектов Firebase.
- Запустить
firebase init firestore
. Для этого урока вы можете принять значения по умолчанию, когда будут предложены для правил Firestore и файлов индекса. Если вы еще не использовали Cloud Firestore в этом проекте, вам также нужно выбрать начальный режим и местоположение Firestore, как описано в начале работы с Cloud Firestore . - Запустить
firebase init functions
. CLI побуждает вас выбрать существующую кодовую базу или инициализировать и называть новую. Когда вы только начинаете работу, одна кодовая база в месте по умолчанию является адекватной; Позже, когда ваша реализация расширяется, вы можете организовать функции в кодовых базах . CLI дает вам два варианта поддержки языка:
- JavaScript
- TypeScript См. Функции записи с TypeScript для получения дополнительной информации.
Для этого урока выберите JavaScript .
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 и модули SDK Admin, используя require
Node. Добавьте строки, такие как следующие в вашем файле 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();
Эти линии загружают firebase-functions
и модули firebase-admin
и инициализируют экземпляр приложения admin
, из которого могут быть внесены изменения Cloud Firestore . Везде доступна поддержка Admin SDK , как и для FCM , Authentication и Firebase Realtime Database , она обеспечивает мощный способ интеграции Firebase с использованием Cloud Functions .
CLI Firebase автоматически устанавливает SDK Firebase и Firebase для модулей узлов Cloud Functions при инициализации своего проекта. Чтобы добавить сторонние библиотеки в ваш проект, вы можете изменить package.json
и запустить npm install
. Для получения дополнительной информации см. Обработка зависимостей .
Добавить функцию 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.` }); });
Функция addMessage()
является конечной точкой HTTP. Любой запрос к конечной точке приводит к тому, что объекты запроса в стиле ExpressJS и ответа передаются в обратный вызов onRequest()
.
Функции HTTP являются синхронными (аналогичны образным функциям ), поэтому вы должны как можно быстрее отправить ответ и отложить работу с использованием Cloud Firestore . Функция addMessage()
http передает текстовое значение в конечную точку HTTP и вводит ее в базу данных в Path /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 }); });
Функция makeUppercase()
выполняется, когда записан Cloud Firestore . Функция ref.set
определяет документ для прослушивания. По причинам производительности вы должны быть максимально конкретными.
Брекеты - например, {documentId}
–Surround "параметры", подстановочные знаки, которые разоблачают их соответствующие данные в обратном вызове.
Cloud Firestore запускает обратный вызов onCreate()
всякий раз, когда добавляются новые сообщения.
Функции, основанные на событиях, такие как события Cloud Firestore являются асинхронными. Функция обратного вызова должна вернуть либо null
, объект или обещание . Если вы ничего не возвращаете, функция выходит на работу, сигнализирует об ошибке и повторно обречена. Смотрите синхронизацию, асинхрон и обещания .
Эмулировать выполнение ваших функций
Firebase Local Emulator Suite позволяет создавать и тестировать приложения на вашей локальной машине, а не развертываться в проекте Firebase. Локальное тестирование во время разработки настоятельно рекомендуется, отчасти потому, что оно снижает риск из -за ошибок кодирования, которые могут потенциально понести затраты в производственной среде (например, бесконечный цикл).
Чтобы эмулировать ваши функции:
Запустите
firebase emulators:start
и проверьте вывод для URL -адреса Emulator Suite UI . По умолчанию по умолчанию в Localhost: 4000 , но может быть размещен на другом порту на вашей машине. Введите этот URL в своем браузере, чтобы открыть Emulator Suite UI .Проверьте вывод
firebase emulators:start
для URL -адреса функции HTTPaddMessage()
. Это будет похоже наhttp://localhost:5001/MY_PROJECT/us-central1/addMessage
, за исключением того:-
MY_PROJECT
будет заменен на идентификатор вашего проекта. - Порт может отличаться на вашей локальной машине.
-
Добавьте строку запроса
?text=uppercaseme
в конце URL -адреса функции. Это должно выглядеть как-то вроде:http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme
. При желании вы можете изменить сообщение «Appercaseme» на пользовательское сообщение.Создайте новое сообщение, открыв URL -адрес в новой вкладке в вашем браузере.
Просмотреть эффекты функций в Emulator Suite UI :
На вкладке журналов вы должны увидеть новые журналы, указывающие, что функции
addMessage()
иmakeUppercase()
ran:i functions: Beginning execution of "addMessage"
i functions: Beginning execution of "makeUppercase"
На вкладке Firestore вы должны увидеть документ, содержащий ваше исходное сообщение, а также верхнюю версию вашего сообщения (если это было изначально «Aurpcaseme», вы увидите «Appercaseme»).
Развернуть функции в производственную среду
После того, как ваши функции работают так же желать в эмуляторе, вы можете приступить к развертыванию, тестированию и запуску их в производственной среде. Имейте в виду, что для развертывания в рекомендуемой среде выполнения Node.js 14 ваш проект должен быть в плане ценообразования . См. Цены на Cloud Functions .
Чтобы завершить учебник, разверните свои функции, а затем выполните addMessage()
чтобы запустить makeUppercase()
.
Запустите эту команду, чтобы развернуть ваши функции:
firebase deploy --only functions
После запуска этой команды CLI Firebase выводит URL для любых конечных точек функции HTTP. В вашем терминале вы должны увидеть такую линию, подобную следующей:
Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
URL содержит ваш идентификатор проекта, а также область для функции HTTP. Хотя вам не нужно беспокоиться об этом сейчас, некоторые производственные функции HTTP должны указать место для минимизации задержки сети.
Если вы сталкиваетесь с ошибками доступа, такими как «Невозможно разрешить доступ к проекту», попробуйте проверить псевдоним проекта .
Используя выход URL -адреса
addMessage()
с помощью CLI, добавьте параметр текстового запроса и откройте его в браузере:https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
Функция выполняет и перенаправляет браузер на консоли Firebase в месте базы данных, где хранится текстовая строка. Это событие записи запускает
makeUppercase()
, который пишет версию строки в верхней передаче.
После развертывания и выполнения функций вы можете просмотреть журналы в Google Cloud . Если вам нужно удалить функции в разработке или производстве, используйте CLI Firebase .
В производстве вы можете оптимизировать производительность функций и затраты на управление, установив минимальное и максимальное количество экземпляров для запуска. Дополнительные сведения об этих параметрах среды выполнения см. в разделе Поведение управления масштабированием .
Просмотрите полный пример кода
Вот завершенные 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 }); });
Следующие шаги
В этой документации вы можете узнать больше о том, как управлять функциями для Cloud Functions , а также о том, как обрабатывать все типы событий, поддерживаемые Cloud Functions .
Чтобы узнать больше о Cloud Functions , вы также можете сделать следующее:
- Прочитайте о вариантах использования для Cloud Functions .
- Попробуйте Cloud Functions CodeLab .
- Просмотрите и запустите образцы кода на GitHub
Чтобы начать с Cloud Functions , попробуйте проработать этот урок, который начинается с необходимых задач настроек и работает посредством создания, тестирования и развертывания двух связанных функций:
- Функция «Добавить сообщение», которая раскрывает URL, который принимает текстовое значение и записывает его в Cloud Firestore .
- Функция «сделать верхний», которая запускается на Cloud Firestore , и преобразует текст в верхний регистр.
Мы выбрали Cloud Firestore и HTTP-функции JavaScript для этого образца частично, потому что эти фоновые триггеры могут быть тщательно протестированы через Firebase Local Emulator Suite . Этот набор инструментов также поддерживает Realtime Database , PubSub, Auth и HTTP Callable Triggers. Другие типы фоновых триггеров, таких как Remote Config , тестовые и аналитические триггеры, могут быть протестированы интерактивно с использованием наборов инструментов, не описанных на этой странице.
В следующих разделах этого учебного пособия подробно описываются шаги, необходимые для создания, тестирования и развертывания образца. Если вы предпочитаете просто запустить код и проверить его, перейдите, чтобы просмотреть полный пример кода .
Создать проект Firebase
В консоли Firebase нажмите «Добавить проект» .
Чтобы добавить ресурсы Firebase в существующий проект Google Cloud , введите название его проекта или выберите его из раскрывающегося меню.
Чтобы создать новый проект, введите желаемое имя проекта. Вы также можете при желании изменить идентификатор проекта, отображаемый под названием проекта.
При появлении запроса прочтите и примите условия Firebase .
Нажмите Продолжить .
(Необязательно) Настройте Google Analytics для своего проекта, что позволит вам оптимально использовать любой из следующих продуктов Firebase:
Либо выберите существующую учетную запись Google Analytics , либо создайте новую учетную запись.
Если вы создаете новую учетную запись, выберите местоположение для отчетов Analytics , затем примите настройки совместного использования данных и условия Google Analytics для вашего проекта.
Нажмите «Создать проект» (или «Добавить Firebase» , если вы используете существующий проект Google Cloud ).
Firebase автоматически выделяет ресурсы для вашего проекта Firebase. Когда процесс завершится, вы перейдете на страницу обзора вашего проекта Firebase в консоли Firebase .
Настройка node.js и CLI Firebase
Вам понадобится среда Node.js для написания функций, и вам понадобится CLI Firebase для развертывания функций в среду выполнения Cloud Functions . Для установки Node.js и NPM рекомендуется диспетчер версий Node .
После установки Node.js и NPM установите CLI Firebase с помощью вашего предпочтительного метода. Чтобы установить CLI через NPM, используйте:
npm install -g firebase-tools
Это устанавливает глобально доступную команду Firebase. Если команда не удается, вам может потребоваться изменить разрешения NPM . Чтобы обновиться до последней версии firebase-tools
, повторно затроните ту же команду.
Инициализируйте свой проект
Когда вы инициализации SDK Firebase SDK для Cloud Functions вы создаете пустой проект, содержащий зависимости и некоторый минимальный код выборки, и вы выбираете либо TypeScript, либо JavaScript для сочинения функций. Для целей этого урока вам также необходимо инициализировать Cloud Firestore .
Для инициализации вашего проекта:
- Запустите
firebase login
, чтобы войти через браузер и аутентифицировать CLI Firebase . - Перейдите в свой каталог проектов Firebase.
- Запустить
firebase init firestore
. Для этого урока вы можете принять значения по умолчанию, когда будут предложены для правил Firestore и файлов индекса. Если вы еще не использовали Cloud Firestore в этом проекте, вам также нужно выбрать начальный режим и местоположение Firestore, как описано в начале работы с Cloud Firestore . - Запустить
firebase init functions
. CLI побуждает вас выбрать существующую кодовую базу или инициализировать и называть новую. Когда вы только начинаете работу, одна кодовая база в месте по умолчанию является адекватной; Позже, когда ваша реализация расширяется, вы можете организовать функции в кодовых базах . CLI дает вам два варианта поддержки языка:
- JavaScript
- TypeScript См. Функции записи с TypeScript для получения дополнительной информации.
Для этого урока выберите JavaScript .
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 и модули SDK Admin, используя require
Node. Добавьте строки, такие как следующие в вашем файле 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();
Эти линии загружают firebase-functions
и модули firebase-admin
и инициализируют экземпляр приложения admin
, из которого могут быть внесены изменения Cloud Firestore . Везде доступна поддержка Admin SDK , как и для FCM , Authentication и Firebase Realtime Database , она обеспечивает мощный способ интеграции Firebase с использованием Cloud Functions .
CLI Firebase автоматически устанавливает SDK Firebase и Firebase для модулей узлов Cloud Functions при инициализации своего проекта. Чтобы добавить сторонние библиотеки в ваш проект, вы можете изменить package.json
и запустить npm install
. Для получения дополнительной информации см. Обработка зависимостей .
Добавить функцию 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.` }); });
Функция addMessage()
является конечной точкой HTTP. Любой запрос к конечной точке приводит к тому, что объекты запроса в стиле ExpressJS и ответа передаются в обратный вызов onRequest()
.
Функции HTTP являются синхронными (аналогичны образным функциям ), поэтому вы должны как можно быстрее отправить ответ и отложить работу с использованием Cloud Firestore . Функция addMessage()
http передает текстовое значение в конечную точку HTTP и вводит ее в базу данных в Path /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 }); });
Функция makeUppercase()
выполняется, когда записан Cloud Firestore . Функция ref.set
определяет документ для прослушивания. По причинам производительности вы должны быть максимально конкретными.
Брекеты - например, {documentId}
–Surround "параметры", подстановочные знаки, которые разоблачают их соответствующие данные в обратном вызове.
Cloud Firestore запускает обратный вызов onCreate()
всякий раз, когда добавляются новые сообщения.
Функции, основанные на событиях, такие как события Cloud Firestore являются асинхронными. Функция обратного вызова должна вернуть либо null
, объект или обещание . Если вы ничего не возвращаете, функция выходит на работу, сигнализирует об ошибке и повторно обречена. Смотрите синхронизацию, асинхрон и обещания .
Эмулировать выполнение ваших функций
Firebase Local Emulator Suite позволяет создавать и тестировать приложения на вашей локальной машине, а не развертываться в проекте Firebase. Локальное тестирование во время разработки настоятельно рекомендуется, отчасти потому, что оно снижает риск из -за ошибок кодирования, которые могут потенциально понести затраты в производственной среде (например, бесконечный цикл).
Чтобы эмулировать ваши функции:
Запустите
firebase emulators:start
и проверьте вывод для URL -адреса Emulator Suite UI . По умолчанию по умолчанию в Localhost: 4000 , но может быть размещен на другом порту на вашей машине. Введите этот URL в своем браузере, чтобы открыть Emulator Suite UI .Проверьте вывод
firebase emulators:start
для URL -адреса функции HTTPaddMessage()
. Это будет похоже наhttp://localhost:5001/MY_PROJECT/us-central1/addMessage
, за исключением того:-
MY_PROJECT
будет заменен на идентификатор вашего проекта. - Порт может отличаться на вашей локальной машине.
-
Добавьте строку запроса
?text=uppercaseme
в конце URL -адреса функции. Это должно выглядеть как-то вроде:http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme
. При желании вы можете изменить сообщение «Appercaseme» на пользовательское сообщение.Создайте новое сообщение, открыв URL -адрес в новой вкладке в вашем браузере.
Просмотреть эффекты функций в Emulator Suite UI :
На вкладке журналов вы должны увидеть новые журналы, указывающие, что функции
addMessage()
иmakeUppercase()
ran:i functions: Beginning execution of "addMessage"
i functions: Beginning execution of "makeUppercase"
На вкладке Firestore вы должны увидеть документ, содержащий ваше исходное сообщение, а также верхнюю версию вашего сообщения (если это было изначально «Aurpcaseme», вы увидите «Appercaseme»).
Развернуть функции в производственную среду
После того, как ваши функции работают так же желать в эмуляторе, вы можете приступить к развертыванию, тестированию и запуску их в производственной среде. Имейте в виду, что для развертывания в рекомендуемой среде выполнения Node.js 14 ваш проект должен быть в плане ценообразования . См. Цены на Cloud Functions .
Чтобы завершить учебник, разверните свои функции, а затем выполните addMessage()
чтобы запустить makeUppercase()
.
Запустите эту команду, чтобы развернуть ваши функции:
firebase deploy --only functions
После запуска этой команды CLI Firebase выводит URL для любых конечных точек функции HTTP. В вашем терминале вы должны увидеть такую линию, подобную следующей:
Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
URL содержит ваш идентификатор проекта, а также область для функции HTTP. Хотя вам не нужно беспокоиться об этом сейчас, некоторые производственные функции HTTP должны указать место для минимизации задержки сети.
Если вы сталкиваетесь с ошибками доступа, такими как «Невозможно разрешить доступ к проекту», попробуйте проверить псевдоним проекта .
Используя выход URL -адреса
addMessage()
с помощью CLI, добавьте параметр текстового запроса и откройте его в браузере:https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
Функция выполняет и перенаправляет браузер на консоли Firebase в месте базы данных, где хранится текстовая строка. Это событие записи запускает
makeUppercase()
, который пишет версию строки в верхней передаче.
After deploying and executing functions, you can view logs in the Google Cloud console . If you need to delete functions in development or production, use the Firebase CLI.
In production, you may want to optimize function performance and control costs by setting minimum and maximum numbers of instances to run. Дополнительные сведения об этих параметрах среды выполнения см. в разделе Поведение управления масштабированием .
Review complete sample code
Here's the completed functions/index.js
containing the functions addMessage()
and makeUppercase()
. These functions allow you to pass a parameter to an HTTP endpoint that writes a value to Cloud Firestore , and then transforms it by uppercasing all characters in the string.
// 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 }); });
Следующие шаги
In this documentation, you can learn more about how to manage functions for Cloud Functions as well as how to to handle all event types supported by Cloud Functions .
To learn more about Cloud Functions , you could also do the following:
- Read about use cases for Cloud Functions .
- Try the Cloud Functions codelab .
- Review and run code samples on GitHub
To get started with Cloud Functions , try working through this tutorial, which starts with the required setup tasks and works through creating, testing, and deploying two related functions:
- An "add message" function that exposes a URL that accepts a text value and writes it to Cloud Firestore .
- A "make uppercase" function that triggers on a Cloud Firestore write and transforms the text to uppercase.
We've chosen Cloud Firestore and HTTP-triggered JavaScript functions for this sample in part because these background triggers can be thoroughly tested through the Firebase Local Emulator Suite . This toolset also supports Realtime Database , PubSub, Auth, and HTTP callable triggers. Other types of background triggers such as Remote Config , TestLab, and Analytics triggers can all be tested interactively using toolsets not described in this page.
The following sections of this tutorial detail the steps required to build, test, and deploy the sample. If you'd rather just run the code and inspect it, jump to Review complete sample code .
Create a Firebase Project
В консоли Firebase нажмите «Добавить проект» .
Чтобы добавить ресурсы Firebase в существующий проект Google Cloud , введите название его проекта или выберите его из раскрывающегося меню.
Чтобы создать новый проект, введите желаемое имя проекта. Вы также можете при желании изменить идентификатор проекта, отображаемый под названием проекта.
При появлении запроса прочтите и примите условия Firebase .
Нажмите Продолжить .
(Необязательно) Настройте Google Analytics для своего проекта, что позволит вам оптимально использовать любой из следующих продуктов Firebase:
Либо выберите существующую учетную запись Google Analytics , либо создайте новую учетную запись.
Если вы создаете новую учетную запись, выберите местоположение для отчетов Analytics , затем примите настройки совместного использования данных и условия Google Analytics для вашего проекта.
Нажмите «Создать проект» (или «Добавить Firebase» , если вы используете существующий проект Google Cloud ).
Firebase автоматически выделяет ресурсы для вашего проекта Firebase. Когда процесс завершится, вы перейдете на страницу обзора вашего проекта Firebase в консоли Firebase .
Set up Node.js and the Firebase CLI
You'll need a Node.js environment to write functions, and you'll need the Firebase CLI to deploy functions to the Cloud Functions runtime. For installing Node.js and npm , Node Version Manager is recommended.
Once you have Node.js and npm installed, install the Firebase CLI via your preferred method. To install the CLI via npm, use:
npm install -g firebase-tools
This installs the globally available firebase command. If the command fails, you may need to change npm permissions . To update to the latest version of firebase-tools
, rerun the same command.
Initialize your project
When you initialize Firebase SDK for Cloud Functions , you create an empty project containing dependencies and some minimal sample code, and you choose either TypeScript or JavaScript for composing functions. For the purposes of this tutorial, you'll also need to initialize Cloud Firestore .
To initialize your project:
- Run
firebase login
to log in via the browser and authenticate the Firebase CLI. - Go to your Firebase project directory.
- Run
firebase init firestore
. For this tutorial, you can accept the default values when prompted for Firestore rules and index files. If you haven't used Cloud Firestore in this project yet, you'll also need to select a starting mode and location for Firestore as described in Get started with Cloud Firestore . - Run
firebase init functions
. The CLI prompts you to choose an existing codebase or initialize and name a new one. When you're just getting started, a single codebase in the default location is adequate; later, as your implementation expands, you might want to organize functions in codebases . The CLI gives you two options for language support:
- JavaScript
- TypeScript See Write Functions with TypeScript for more information.
For this tutorial, select JavaScript .
The CLI gives you an option to install dependencies with npm. It is safe to decline if you want to manage dependencies in another way, though if you do decline you'll need to run
npm install
before emulating or deploying your functions.
After these commands complete successfully, your project structure looks like this:
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
The package.json
file created during initialization contains an important key: "engines": {"node": "16"}
. This specifies your Node.js version for writing and deploying functions. You can select other supported versions .
Import the required modules and initialize an app
After you have completed the setup tasks, you can open the source directory and start adding code as described in the following sections. For this sample, your project must import the Cloud Functions and Admin SDK modules using Node require
statements. Add lines like the following to your index.js
file:
// 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();
These lines load the firebase-functions
and firebase-admin
modules, and initialize an admin
app instance from which Cloud Firestore changes can be made. Wherever Admin SDK support is available, as it is for FCM , Authentication , and Firebase Realtime Database , it provides a powerful way to integrate Firebase using Cloud Functions .
The Firebase CLI automatically installs the Firebase and Firebase SDK for Cloud Functions Node modules when you initialize your project. To add 3rd party libraries to your project, you can modify package.json
and run npm install
. For more information, see Handle Dependencies .
Add the addMessage()
function
For the addMessage()
function, add these lines to 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.` }); });
The addMessage()
function is an HTTP endpoint. Any request to the endpoint results in ExpressJS-style Request and Response objects passed to the onRequest()
callback.
HTTP functions are synchronous (similar to callable functions ), so you should send a response as quickly as possible and defer work using Cloud Firestore . The addMessage()
HTTP function passes a text value to the HTTP endpoint and inserts it into the database under the path /messages/:documentId/original
.
Add the makeUppercase()
function
For the makeUppercase()
function, add these lines to 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 }); });
The makeUppercase()
function executes when Cloud Firestore is written to. The ref.set
function defines the document to listen on. For performance reasons, you should be as specific as possible.
Braces—for example, {documentId}
—surround "parameters," wildcards that expose their matched data in the callback.
Cloud Firestore triggers the onCreate()
callback whenever new messages are added.
Event-driven functions such as Cloud Firestore events are asynchronous. The callback function should return either a null
, an Object, or a Promise . If you do not return anything, the function times out, signaling an error, and is retried. See Sync, Async, and Promises .
Emulate execution of your functions
The Firebase Local Emulator Suite allows you to build and test apps on your local machine instead of deploying to a Firebase project. Local testing during development is strongly recommended, in part because it lowers the risk from coding errors that could potentially incur cost in a production environment (for example, an infinite loop).
To emulate your functions:
Run
firebase emulators:start
and check the output for the URL of the Emulator Suite UI . It defaults to localhost:4000 , but may be hosted on a different port on your machine. Enter that URL in your browser to open the Emulator Suite UI .Check the output of the
firebase emulators:start
command for the URL of the HTTP functionaddMessage()
. It will look similar tohttp://localhost:5001/MY_PROJECT/us-central1/addMessage
, except that:-
MY_PROJECT
will be replaced with your project ID. - The port may be different on your local machine.
-
Add the query string
?text=uppercaseme
to the end of the function's URL. This should look something like:http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme
. Optionally, you can change the message "uppercaseme" to a custom message.Create a new message by opening the URL in a new tab in your browser.
View the effects of the functions in the Emulator Suite UI :
In the Logs tab, you should see new logs indicating that the functions
addMessage()
andmakeUppercase()
ran:i functions: Beginning execution of "addMessage"
i functions: Beginning execution of "makeUppercase"
In the Firestore tab, you should see a document containing your original message as well as the uppercased version of your message (if it was originally "uppercaseme", you'll see "UPPERCASEME").
Deploy functions to a production environment
Once your functions are working as desired in the emulator, you can proceed to deploying, testing, and running them in the production environment. Keep in mind that to deploy to the recommended Node.js 14 runtime environment, your project must be on the Blaze pricing plan . See Cloud Functions pricing .
To complete the tutorial, deploy your functions and then execute addMessage()
to trigger makeUppercase()
.
Run this command to deploy your functions:
firebase deploy --only functions
After you run this command, the Firebase CLI outputs the URL for any HTTP function endpoints. In your terminal, you should see a line like the following:
Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
The URL contains your project ID as well as a region for the HTTP function. Though you don't need to worry about it now, some production HTTP functions should specify a location to minimize network latency.
If you encounter access errors such as "Unable to authorize access to project," try checking your project aliasing .
Using the
addMessage()
URL output by the CLI, add a text query parameter, and open it in a browser:https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
The function executes and redirects the browser to the Firebase console at the database location where the text string is stored. This write event triggers
makeUppercase()
, which writes an uppercase version of the string.
After deploying and executing functions, you can view logs in the Google Cloud console . If you need to delete functions in development or production, use the Firebase CLI.
In production, you may want to optimize function performance and control costs by setting minimum and maximum numbers of instances to run. Дополнительные сведения об этих параметрах среды выполнения см. в разделе Поведение управления масштабированием .
Review complete sample code
Here's the completed functions/index.js
containing the functions addMessage()
and makeUppercase()
. These functions allow you to pass a parameter to an HTTP endpoint that writes a value to Cloud Firestore , and then transforms it by uppercasing all characters in the string.
// 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 }); });
Следующие шаги
In this documentation, you can learn more about how to manage functions for Cloud Functions as well as how to to handle all event types supported by Cloud Functions .
To learn more about Cloud Functions , you could also do the following:
- Read about use cases for Cloud Functions .
- Try the Cloud Functions codelab .
- Review and run code samples on GitHub