В этом кратком руководстве рассказывается, как настроить Firestore Enterprise, добавить данные, а затем использовать основные операции или операции конвейера, чтобы запросить данные, которые вы только что добавили в консоли Firebase.
Cloud Firestore поддерживает SDK для мобильных устройств и веб-сайтов, а также клиентские библиотеки для серверов:
Cloud Firestore поддерживает SDK для Android, iOS, веб-сайтов и других платформ. В сочетании с Cloud Firestore Security Rules и Firebase Authentication SDK для мобильных устройств и веб-приложений поддерживают бессерверные архитектуры приложений, в которых клиенты подключаются непосредственно к вашей базе данных Cloud Firestore.
Cloud Firestore поддерживает серверные клиентские библиотеки для Java, Node.js и Python. Используйте эти клиентские библиотеки, чтобы настроить привилегированные серверные среды с полным доступом к базе данных. Подробнее об этих библиотеках рассказывается в кратком руководстве по клиентским библиотекам для серверов.
Запрос к ИИ для получения помощи от ИИ
Чтобы получить помощь от ИИ, скопируйте запрос ниже и вставьте его в свой ИИ-агент для программирования (например, Gemini в Android Studio, Antigravity, Claude Code, Codex или Cursor). Вы можете настроить запрос и повторить его с агентом. Подробные инструкции по установке вы найдете в статье Навыки агента Firebase.
Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me set up and use Firebase for the backend of my app. Set up Firestore database in **Enterprise edition**. Help me to choose the best location for my database instance.
Как создать базу данных Firestore Enterprise
Если у вас ещё нет проекта Firebase, создайте его. Для этого в консоли Firebase нажмите Добавить проект и следуйте инструкциям на экране. Вы также можете добавить сервисы Firebase в существующий проект Google Cloud.
На панели слева выберите Databases & Storage (Базы данных и хранилище) > Firestore.
Нажмите Create database (Создать базу данных).
В качестве режима базы данных выберите Enterprise.
В качестве режима работы выберите Firestore в стандартном режиме, который поддерживает операции Core и Pipeline.
Выберите местоположение для базы данных.
Выберите режим запуска для устройства "Cloud Firestore Security Rules":
- Режим тестирования
Подходит для начала работы с клиентскими библиотеками для мобильных устройств и веб-клиентов, но позволяет любому пользователю читать и перезаписывать ваши данные. После тестирования обязательно ознакомьтесь с разделом Защита данных.
Чтобы начать работу с SDK для веб-сайтов, платформ Apple или Android, выберите тестовый режим.
- Производственный режим
Запрещает все операции чтения и записи для мобильных и веб-клиентов. Ваши серверы приложений, прошедшие аутентификацию (Python), по-прежнему могут обращаться к базе данных.
Начальный набор Cloud Firestore Security Rules будет применен к базе данных Cloud Firestore по умолчанию. Если вы создадите несколько баз данных для проекта, то сможете развернуть Cloud Firestore Security Rules для каждой из них.
Нажмите Создать.
При включении Firestore Enterprise также включается API в Cloud API Manager.
Как настроить среду разработки
Добавьте в приложение необходимые зависимости и клиентские библиотеки.
Web
- Следуйте инструкциям, чтобы добавить Firebase в веб-приложение.
-
SDK Cloud Firestore доступен в виде пакета npm.
Вам нужно импортировать Firebase и Cloud Firestore.npm install firebase@13.0.0 --save
import { initializeApp } from "firebase/app"; import { getFirestore } from "firebase/firestore";
iOS+
Следуйте инструкциям, чтобы добавить Firebase в приложение Apple.
Для установки зависимостей Firebase и управления ими используйте Swift Package Manager.
- Откройте проект приложения в Xcode и перейдите в меню File (Файл) > Swift Packages (Пакеты Swift) > Add Package Dependency (Добавить зависимость пакетов).
- Когда появится запрос, добавьте хранилище Firebase SDK для платформ Apple:
- Выберите библиотеку Firestore.
- После этого Xcode автоматически начнет распознавать и скачивать зависимости в фоновом режиме.
https://github.com/firebase/firebase-ios-sdk
Android
- Следуйте инструкциям, чтобы добавить Firebase в приложение для Android.
- Используя Firebase Android BoM, укажите зависимость для библиотеки Cloud Firestore для Android в модульном файле Gradle на уровне приложения (обычно
app/build.gradle.ktsилиapp/build.gradle).dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:35.0.1")) // Declare the dependency for the Cloud Firestore library // When using the BoM, you don't specify versions in Firebase library dependencies implementation("com.google.firebase:firebase-firestore") }
Благодаря Firebase Android BoM в вашем приложении всегда будут использоваться совместимые версии библиотек Firebase Android.
(Альтернативный вариант) Объявите зависимости библиотеки Firebase, не используя BoM.
Если вы не хотите использовать Firebase BoM, вам нужно будет указать версию каждой библиотеки Firebase в строке зависимости.
Если вы используете в приложении несколько библиотек Firebase, настоятельно рекомендуем управлять их версиями с помощью BoM. Это позволит обеспечить совместимость всех версий.
dependencies { // Declare the dependency for the Cloud Firestore library // When NOT using the BoM, you must specify versions in Firebase library dependencies implementation("com.google.firebase:firebase-firestore:27.0.0") }
Ищете модуль библиотеки для Kotlin? Начиная с октябрьского выпуска 2023 года, разработчики, использующие Kotlin и Java, могут зависеть от основного модуля библиотеки. Подробную информацию вы найдете в разделе часто задаваемых вопросов об этой инициативе.
Инициализация Cloud Firestore
Инициализируйте экземпляр Cloud Firestore:
Web
import { initializeApp } from "firebase/app"; import { getFirestore } from "firebase/firestore"; // TODO: Replace the following with your app's Firebase project configuration // See: https://support.google.com/firebase/answer/7015592 const firebaseConfig = { FIREBASE_CONFIGURATION }; // Initialize Firebase const app = initializeApp(firebaseConfig); // When initializing Firestore, remember to use the name of the database you created earlier: const db = initializeFirestore(app, {}, 'your-new-enterprise-database');
Замените FIREBASE_CONFIGURATION на firebaseConfig вашего веб-приложения.
Чтобы сохранить данные, когда устройство теряет подключение, ознакомьтесь с документацией Включить офлайн-данные.
Swift
import FirebaseCore import FirebaseFirestore FirebaseApp.configure() // When initializing Firestore, remember to use the name of the database you created earlier: let db = Firestore.firestore(database: "your-new-enterprise-database")
Kotlin
// Access a Cloud Firestore instance from your Activity // When initializing Firestore, remember to use the name of the database you created earlier: val firestore = FirebaseFirestore.getInstance("your-new-enterprise-database")
Java
// Access a Cloud Firestore instance from your Activity // When initializing Firestore, remember to use the name of the database you created earlier: FirebaseFirestore firestore = FirebaseFirestore.getInstance("your-new-enterprise-database");
Как добавить данные с помощью основных операций
Чтобы изучить основные операции и операции конвейера для запроса данных, добавьте данные в базу данных с помощью основных операций.
Cloud Firestore хранит данные в документах, которые хранятся в коллекциях. Cloud Firestore создает коллекции и документы неявно при первом добавлении данных в документ. Вам не нужно явно создавать коллекции или документы.
Создайте новую коллекцию и документ, используя следующий пример кода.
Web
import { collection, addDoc } from "firebase/firestore"; try { const docRef = await addDoc(collection(db, "users"), { first: "Ada", last: "Lovelace", born: 1815 }); console.log("Document written with ID: ", docRef.id); } catch (e) { console.error("Error adding document: ", e); }
Web
db.collection("users").add({ first: "Ada", last: "Lovelace", born: 1815 }) .then((docRef) => { console.log("Document written with ID: ", docRef.id); }) .catch((error) => { console.error("Error adding document: ", error); });
Swift
// Add a new document with a generated ID do { let ref = try await db.collection("users").addDocument(data: [ "first": "Ada", "last": "Lovelace", "born": 1815 ]) print("Document added with ID: \(ref.documentID)") } catch { print("Error adding document: \(error)") }
Kotlin
// Create a new user with a first and last name val user = hashMapOf( "first" to "Ada", "last" to "Lovelace", "born" to 1815, ) // Add a new document with a generated ID db.collection("users") .add(user) .addOnSuccessListener { documentReference -> Log.d(TAG, "DocumentSnapshot added with ID: ${documentReference.id}") } .addOnFailureListener { e -> Log.w(TAG, "Error adding document", e) }
Java
// Create a new user with a first and last name Map<String, Object> user = new HashMap<>(); user.put("first", "Ada"); user.put("last", "Lovelace"); user.put("born", 1815); // Add a new document with a generated ID db.collection("users") .add(user) .addOnSuccessListener(new OnSuccessListener<DocumentReference>() { @Override public void onSuccess(DocumentReference documentReference) { Log.d(TAG, "DocumentSnapshot added with ID: " + documentReference.getId()); } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { Log.w(TAG, "Error adding document", e); } });
Теперь добавьте ещё один документ в коллекцию users. Обратите внимание, что в этом документе есть пара "ключ-значение" (отчество), которой нет в первом документе. Документы в коллекции могут содержать разные наборы информации.
Web
// Add a second document with a generated ID. import { addDoc, collection } from "firebase/firestore"; try { const docRef = await addDoc(collection(db, "users"), { first: "Alan", middle: "Mathison", last: "Turing", born: 1912 }); console.log("Document written with ID: ", docRef.id); } catch (e) { console.error("Error adding document: ", e); }
Web
// Add a second document with a generated ID. db.collection("users").add({ first: "Alan", middle: "Mathison", last: "Turing", born: 1912 }) .then((docRef) => { console.log("Document written with ID: ", docRef.id); }) .catch((error) => { console.error("Error adding document: ", error); });
Swift
// Add a second document with a generated ID. do { let ref = try await db.collection("users").addDocument(data: [ "first": "Alan", "middle": "Mathison", "last": "Turing", "born": 1912 ]) print("Document added with ID: \(ref.documentID)") } catch { print("Error adding document: \(error)") }
Kotlin
// Create a new user with a first, middle, and last name val user = hashMapOf( "first" to "Alan", "middle" to "Mathison", "last" to "Turing", "born" to 1912, ) // Add a new document with a generated ID db.collection("users") .add(user) .addOnSuccessListener { documentReference -> Log.d(TAG, "DocumentSnapshot added with ID: ${documentReference.id}") } .addOnFailureListener { e -> Log.w(TAG, "Error adding document", e) }
Java
// Create a new user with a first, middle, and last name Map<String, Object> user = new HashMap<>(); user.put("first", "Alan"); user.put("middle", "Mathison"); user.put("last", "Turing"); user.put("born", 1912); // Add a new document with a generated ID db.collection("users") .add(user) .addOnSuccessListener(new OnSuccessListener<DocumentReference>() { @Override public void onSuccess(DocumentReference documentReference) { Log.d(TAG, "DocumentSnapshot added with ID: " + documentReference.getId()); } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { Log.w(TAG, "Error adding document", e); } });
Чтение данных с помощью основных операций
Используйте средство просмотра данных в консоли Firebase, чтобы быстро проверить, добавили ли вы данные в Cloud Firestore.
Вы также можете использовать метод get, чтобы получить всю коллекцию.
Web
import { collection, getDocs } from "firebase/firestore"; const querySnapshot = await getDocs(collection(db, "users")); querySnapshot.forEach((doc) => { console.log(doc.id, "=>", doc.data()); });
Web
db.collection("users").get().then((querySnapshot) => { querySnapshot.forEach((doc) => { console.log(doc.id, "=>", doc.data()); }); });
Swift
do { let snapshot = try await db.collection("users").getDocuments() for document in snapshot.documents { print("\(document.documentID) => \(document.data())") } } catch { print("Error getting documents: \(error)") }
Kotlin
db.collection("users") .get() .addOnSuccessListener { result -> for (document in result) { Log.d(TAG, "${document.id} => ${document.data}") } } .addOnFailureListener { exception -> Log.w(TAG, "Error getting documents.", exception) }
Java
db.collection("users") .get() .addOnCompleteListener(new OnCompleteListener<QuerySnapshot>() { @Override public void onComplete(@NonNull Task<QuerySnapshot> task) { if (task.isSuccessful()) { for (QueryDocumentSnapshot document : task.getResult()) { Log.d(TAG, document.getId() + " => " + document.getData()); } } else { Log.w(TAG, "Error getting documents.", task.getException()); } } });
Чтение данных с помощью операций конвейера
Теперь вы можете сравнить работу с запросами в Pipeline и Core.
Web
// The import/require of "firebase/firestore/pipelines" has a side-effect // of extending the Firestore class with the `.pipeline()` method. // Without this import/require, you will not be able to create a Pipeline. // import { execute } from "firebase/firestore/pipelines"; const readDataPipeline = db.pipeline() .collection("users"); // Execute the pipeline and handle the result try { const querySnapshot = await execute(readDataPipeline); querySnapshot.results.forEach((result) => { console.log(`${result.id} => ${result.data()}`); }); } catch (error) { console.error("Error getting documents: ", error); }
Swift
do { // Initialize a Firestore Pipeline instance and specify the "users" collection as the // input stage. let snapshot = try await db.pipeline() .collection("users") .execute() // Execute the pipeline to retrieve documents. // Iterate through the documents in the pipeline results, similar to a regular query // snapshot. for result in snapshot.results { print("\(result.id ?? "no ID") => \(result.data)") } } catch { print("Error getting documents with pipeline: \(error)") }
Kotlin
val readDataPipeline = db.pipeline() .collection("users") // Execute the pipeline and handle the result readDataPipeline.execute() .addOnSuccessListener { result -> for (document in result) { println("${document.getId()} => ${document.getData()}") } } .addOnFailureListener { exception -> println("Error getting documents: $exception") }
Java
Pipeline readDataPipeline = db.pipeline() .collection("users"); readDataPipeline.execute() .addOnSuccessListener(new OnSuccessListener<Pipeline.Snapshot>() { @Override public void onSuccess(Pipeline.Snapshot snapshot) { for (PipelineResult result : snapshot.getResults()) { System.out.println(result.getId() + " => " + result.getData()); } } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { System.out.println("Error getting documents: " + e); } });
Как защитить данные для мобильных и веб-SDK
Если вы используете SDK для веб-платформ, Android или Apple, используйте Firebase Authentication и Cloud Firestore Security Rules, чтобы защитить данные в Cloud Firestore.
Ниже приведены примеры наборов правил, которые можно использовать в качестве основы. Вы можете изменить правила безопасности в консоли Firebase на вкладке Databases & Storage (Базы данных и хранилище) > Firestore > Rules (Правила).
Требуется аутентификация
// Allow read/write access to a document keyed by the user's UID
service cloud.firestore {
match /databases/{database}/documents {
match /users/{uid} {
allow read, write: if request.auth != null && request.auth.uid == uid;
}
}
}
Производственный режим
// Deny read/write access to all users under any conditions
service cloud.firestore {
match /databases/{database}/documents {
match /{document=**} {
allow read, write: if false;
}
}
}
Прежде чем развертывать веб-приложение или приложение для Android или iOS в рабочей среде, убедитесь, что доступ к данным Cloud Firestore есть только у клиентов вашего приложения. Ознакомьтесь с документацией по проверке приложений.
Если вы используете один из серверных SDK, то для защиты данных в Cloud Firestore используйте Identity and Access Management (IAM).
Дальнейшие действия
Углубите свои знания об основных операциях и операциях с конвейером, изучив следующие темы:
- Подробнее о запросах с основными операциями…
- Подробнее об операциях конвейера…
- Узнайте, как улучшить инструменты разработки на основе ИИ, чтобы эффективнее выполнять задачи, и как использовать рекомендации по работе с Cloud Firestore (например, написание Cloud Firestore Security Rules) с помощью навыков агента Firebase.