Google is committed to advancing racial equity for Black communities. See how.
Эта страница была переведа с помощью Cloud Translation API.
Switch to English

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

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

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

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

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

Создать проект Firebase

  1. В консоли Firebase нажмите Добавить проект , затем выберите или введите имя проекта .

    Если у вас есть существующий проект Google Cloud Platform (GCP), вы можете выбрать проект из раскрывающегося меню, чтобы добавить ресурсы Firebase в этот проект.

  2. (Необязательно) Если вы создаете новый проект, вы можете изменить идентификатор проекта .

    Firebase автоматически присваивает уникальный идентификатор вашему проекту Firebase. Посетите Understand Firebase Projects, чтобы узнать, как Firebase использует идентификатор проекта.

  3. Щелкните Продолжить .

  4. (Необязательно) Настройте Google Analytics для своего проекта, что позволит вам оптимально использовать любой из следующих продуктов Firebase:

    При появлении запроса выберите использование существующей учетной записи Google Analytics или создание новой учетной записи.
    Если вы решили создать новую учетную запись, выберите место для создания отчетов Analytics , затем примите настройки совместного использования данных и условия Google Analytics для своего проекта.

  5. Нажмите « Создать проект» (или « Добавить Firebase» , если вы используете существующий проект GCP).

Firebase автоматически выделяет ресурсы для вашего проекта Firebase. Когда процесс завершится, вы попадете на страницу обзора вашего проекта Firebase в консоли Firebase.

Настройте Node.js и Firebase CLI

Вам понадобится среда Node.js для написания функций, и вам понадобится интерфейс командной строки 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 для облачных функций, вы создаете пустой проект, содержащий зависимости и некоторый минимальный образец кода, и выбираете TypeScript или JavaScript для создания функций. Для целей этого руководства вам также потребуется инициализировать Cloud Firestore.

Чтобы инициализировать ваш проект:

  1. Запустите firebase login чтобы войти через браузер и аутентифицировать инструмент firebase.
  2. Перейдите в каталог проекта Firebase.
  3. Запустите firebase init firestore . В этом руководстве вы можете принять значения по умолчанию при запросе правил Firestore и индексных файлов. Если вы еще не использовали Cloud Firestore в этом проекте, вам также необходимо выбрать начальный режим и местоположение для Firestore, как описано в разделе «Начало работы с Cloud Firestore» .
  4. Запустите firebase init functions . Инструмент дает вам возможность установить зависимости с помощью npm. Можно безопасно отказаться, если вы хотите управлять зависимостями другим способом, хотя, если вы откажетесь, вам нужно будет запустить npm install перед эмуляцией или развертыванием ваших функций.
  5. Инструмент предлагает два варианта языковой поддержки:

    В этом руководстве выберите JavaScript .

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

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": "10"} . Это указывает вашу версию Node.js для написания и развертывания функций. Вы можете выбрать другие поддерживаемые версии .

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

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

// The Cloud Functions for Firebase SDK to create Cloud Functions and setup triggers.
const functions = require('firebase-functions');

// The Firebase Admin SDK to access Cloud Firestore.
const admin = require('firebase-admin');
admin.initializeApp();

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

Интерфейс командной строки Firebase автоматически устанавливает Firebase и Firebase SDK для модулей узла облачных функций при инициализации проекта. Чтобы добавить сторонние библиотеки в свой проект, вы можете изменить package.json и запустить npm install . Дополнительные сведения см. В разделе « Обработка зависимостей» .

Добавьте addMessage()

Для функции addMessage() добавьте эти строки в index.js :

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Cloud 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 Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've succesfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

Функция addMessage() - это конечная точка HTTP. Любой запрос к конечной точке приводит к тому, что объекты запроса и ответа в стиле ExpressJS передаются в onRequest() обратного вызова onRequest() .

Функции HTTP являются синхронными (аналогично вызываемым функциям ), поэтому вам следует отправить ответ как можно быстрее и отложить работу с помощью Cloud Firestore. addMessage() 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 Cloud 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 Cloud Firestore.
      // Setting an 'uppercase' field in Cloud Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

Функция makeUppercase() выполняется при записи в Cloud Firestore. Функция ref.set определяет документ для прослушивания. По соображениям производительности вы должны быть как можно более конкретными.

Фигурные скобки, например {documentId} заключают в себе «параметры», подстановочные знаки, которые раскрывают соответствующие данные в обратном вызове.

Cloud Firestore запускает onWrite() вызов onWrite() всякий раз, когда данные записываются или обновляются в данном документе.

Управляемые событиями функции, такие как события Cloud Firestore, являются асинхронными. Функция обратного вызова должна возвращать либо значение null , либо объект, либо обещание . Если вы ничего не вернете, функция истечет по тайм-ауту, сигнализируя об ошибке, и будет повторена попытка. См. Раздел « Синхронизация», «Асинхронизация» и «Обещания» .

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

Пакет локального эмулятора Firebase позволяет создавать и тестировать приложения на локальном компьютере вместо развертывания в проекте Firebase. Настоятельно рекомендуется локальное тестирование во время разработки, отчасти потому, что оно снижает риск ошибок кодирования, которые потенциально могут повлечь за собой затраты в производственной среде (например, бесконечный цикл).

Чтобы подражать вашим функциям:

  1. Запустите firebase emulators:start и проверьте вывод URL-адреса пользовательского интерфейса Emulator Suite. По умолчанию это localhost: 4000 , но может быть размещен на другом порту вашей машины. Введите этот URL-адрес в своем браузере, чтобы открыть пользовательский интерфейс Emulator Suite.

  2. Проверьте вывод команды firebase emulators:start для URL-адреса HTTP-функции addMessage() . Он будет похож на 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 . При желании вы можете изменить сообщение «верхний регистр» на собственное сообщение.

  4. Создайте новое сообщение, открыв URL-адрес в новой вкладке в браузере.

  5. Просмотрите эффекты функций в пользовательском интерфейсе Emulator Suite:

    1. На вкладке Журналы вы должны увидеть новые журналы, указывающие, что функции addMessage() и makeUppercase() выполнялись:

      Функции i: начало выполнения "addMessage"

      i функции: начало выполнения makeUppercase

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

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

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

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

  1. Запустите эту команду, чтобы развернуть свои функции:

    $ firebase deploy --only functions
    

    После запуска этой команды интерфейс командной строки Firebase выводит URL-адреса для любых конечных точек функции HTTP. В вашем терминале вы должны увидеть такую ​​строку:

    Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
    

    URL-адрес содержит идентификатор вашего проекта, а также регион для функции HTTP. Хотя сейчас вам не нужно об этом беспокоиться, некоторые производственные HTTP-функции должны указывать местоположение, чтобы минимизировать задержку в сети.

    Если вы столкнулись с ошибками доступа, такими как «Не удалось авторизовать доступ к проекту», попробуйте проверить псевдоним вашего проекта .

  2. Используя addMessage() URL addMessage() из интерфейса командной строки, добавьте параметр текстового запроса и откройте его в браузере:

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

    Функция выполняет и перенаправляет браузер на консоль Firebase в том месте базы данных, где хранится текстовая строка. Это событие записи запускает makeUppercase() , который записывает версию строки в верхнем регистре.

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

Просмотрите полный пример кода

Вот завершенные functions/index.js содержащие функции addMessage() и makeUppercase() . Эти функции позволяют передавать параметр конечной точке HTTP, которая записывает значение в Cloud Firestore, а затем преобразует его, переводя все символы в строку в верхний регистр.

// The Cloud Functions for Firebase SDK to create Cloud Functions and setup triggers.
const functions = require('firebase-functions');

// The Firebase Admin SDK to access Cloud Firestore.
const admin = require('firebase-admin');
admin.initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Cloud 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 Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've succesfully 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 Cloud 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 Cloud Firestore.
      // Setting an 'uppercase' field in Cloud Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

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

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

Чтобы узнать больше об облачных функциях, вы также можете сделать следующее:

Видеоурок

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