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 и преобразует текст в верхний регистр.

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

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

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

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

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

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

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

  3. Нажмите Продолжить .

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

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

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

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

Настройте Node.js и интерфейс командной строки Firebase

Вам понадобится среда Node.js для написания функций, и вам потребуется CLI Firebase для развертывания функций во время выполнения Cloud Functions. Для установки Node.js и npm рекомендуется Node Version Manager .

После того, как вы установили Node.js и npm, установите Firebase CLI с помощью предпочтительного метода. Чтобы установить CLI через npm, используйте:

 npm install -g firebase-tools
 

Это установит глобально доступную команду firebase. Если команда не выполняется, вам может потребоваться изменить разрешения npm . Чтобы обновить до последней версии firebase-tools , повторите команду.

Инициализируйте Firebase SDK для облачных функций

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

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

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

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

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

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

Firebase CLI автоматически устанавливает модули 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() .

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 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 Local Emulator Suite позволяет создавать и тестировать приложения на локальном компьютере вместо развертывания в проекте 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 . При желании вы можете изменить сообщение «uppercaseme» на пользовательское сообщение.

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

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

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

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

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

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

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

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

Чтобы завершить учебник, разверните свои функции и затем выполните 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. Используя URL-адрес addMessage() выведенный CLI, добавьте параметр текстового запроса и откройте его в браузере:

     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 и настройку CLI.