Начните работу с Cloud Firestore

В этом кратком руководстве показано, как настроить Cloud Firestore , добавить данные, а затем использовать либо основные операции, либо операции Pipeline для запроса данных, которые вы только что добавили в консоль Firebase .

Создайте базу данных Cloud Firestore

  1. Если вы еще этого не сделали, создайте проект Firebase: в консоли Firebase нажмите «Добавить проект» , а затем следуйте инструкциям на экране, чтобы создать проект Firebase или добавить сервисы Firebase в существующий проект Google Cloud .
  1. Откройте свой проект в консоли Firebase . В левой панели разверните раздел «Сборка» , а затем выберите базу данных Firestore .

  2. Нажмите «Создать базу данных» .

  3. Выберите режим базы данных «Предприятие» .

  4. Выберите режим работы Firestore in Native Mode , который поддерживает операции Core и Pipeline.

  5. Выберите местоположение для вашей базы данных.

  6. Выберите режим запуска Cloud Firestore Security Rules :

    Тестовый режим

    Подходит для начала работы с библиотеками мобильного и веб-клиента, но позволяет любому читать и перезаписывать ваши данные. После тестирования обязательно ознакомьтесь с разделом «Защита данных» .

    Для начала работы с веб-версией, платформами Apple или Android SDK выберите тестовый режим.

    Режим производства

    Запрещает все операции чтения и записи с мобильных и веб-клиентов. Ваши аутентифицированные серверы приложений (Python) по-прежнему смогут получать доступ к вашей базе данных.

    Первоначальный набор Cloud Firestore Security Rules будет применяться к вашей базе данных Cloud Firestore по умолчанию. Если вы создадите несколько баз данных для своего проекта, вы можете развернуть Cloud Firestore Security Rules для каждой из них.

  7. Нажмите «Создать» .

При включении Cloud Firestore также активируется API в Cloud API Manager .

Настройте среду разработки.

Добавьте необходимые зависимости и клиентские библиотеки в ваше приложение.

Web

  1. Следуйте инструкциям, чтобы добавить Firebase в ваше веб-приложение .
  2. SDK Cloud Firestore для закрытого предварительного просмотра доступен в виде пакета npm.

    Для установки SDK Firestore в ваш npm-проект используйте следующую команду.

    npm install --save firebase@eap-firestore-pipelines
iOS+
  1. Следуйте инструкциям, чтобы добавить Firebase в ваше iOS-приложение .
  2. Клонируйте Firebase SDK с GitHub и переключитесь на ветку pipelines. Запишите путь, куда вы клонировали репозиторий, так как он понадобится вам на следующем шаге:
    git clone https://github.com/firebase/firebase-ios-sdk.git
    # or git clone git@github.com:firebase/firebase-ios-sdk.git
    cd firebase-ios-sdk
    
    # check out pipeline feature branch
    git fetch origin feat/pipeline/private-preview
    git checkout feat/pipeline/private-preview
  3. Затем добавьте каталог (firebase-ios-sdk) в качестве локальной зависимости в ваш проект Xcode:
    1. В меню «Файл» выберите «Добавить зависимости пакета» .
    2. Нажмите кнопку «Добавить локальный…» , затем найдите каталог firebase-ios-sdk с веткой разработки, которую вы переключили.
Android
  1. Следуйте инструкциям, чтобы добавить Firebase в ваше Android-приложение .
  2. Клонируйте SDK Firebase из GitHub, переключитесь на ветку pipelines и опубликуйте его в локальном Maven:
    # Prerequisites before you start:
    # Install Java 17
    # Setup Android Development environments (having proper ANDROID_HOME, etc)
    
    git clone https://github.com/firebase/firebase-android-sdk.git
    # or git clone git@github.com:firebase/firebase-android-sdk.git
    cd firebase-android-sdk
    
    # check out pipeline feature branch
    git fetch origin feat/pipeline/private-preview
    git checkout feat/pipeline/private-preview
    
    # publish firebase SDK (without crashlytics) to maven local
    ./gradlew publishToMavenLocal -x :firebase-crashlytics:publishToMavenLocal -x :firebase-crashlytics-ndk:publishToMavenLocal
    
    # Optionally, if you want crashlytics built and published to mavel local
    # Make sure you have Android NDK 21 installed
    git submodule update --init --recursive
    ./gradlew publishToMavenLocal
  3. Добавьте mavenLocal в файл settings.gradle.kts на уровне проекта:
    dependencyResolutionManagement {
      repositories {
        mavenLocal() // Add this line
        ..
      }
    }
  4. Затем добавьте локальную версию SDK:
    ...
    // Firestore 99.0.0-pipeline.preview.1 has pipelines
    implementation("com.google.firebase:firebase-firestore:99.0.0-pipeline.preview.1")
    
    // Firebase Authentication
    implementation("com.google.firebase:firebase-auth")
    ...
Python
  1. Клонируйте Firestore Python SDK и переключитесь на ветку предварительного просмотра конвейера:
    git clone https://github.com/googleapis/python-firestore.git
    # or git clone git@github.com:googleapis/python-firestore.git
    cd python-firestore
    
    # check out pipeline preview branch
    git fetch origin pipeline-preview
    git checkout pipeline-preview
  2. Установите локальный SDK сервера python-firestore:
    python -m pip install -e .
  3. Установите Firebase Python Admin SDK как обычно:
    pip install --user firebase-admin

Инициализация 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 вашего веб-приложения.

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

Быстрый
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");
Python

Аутентификация в корпоративной базе данных осуществляется с помощью Admin SDK:

import firebase_admin
from firebase_admin import firestore

def main():
  default_app = firebase_admin.initialize_app()
  client = firestore.client(default_app, "your-new-enterprise-database")
  query = client.pipeline().database().limit(5)
  for result in query.execute():
    print(result.data())

if __name__ == "__main__":
    main()

Добавление данных с использованием основных операций.

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

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);
});
Быстрый
Примечание: Этот продукт недоступен для watchOS и приложений App Clip.
// 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);
            }
        });
Python
doc_ref = db.collection("users").document("alovelace")
doc_ref.set({"first": "Ada", "last": "Lovelace", "born": 1815})

Теперь добавьте еще один документ в коллекцию 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);
});
Быстрый
Примечание: Этот продукт недоступен для watchOS и приложений App Clip.
// 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);
            }
        });
Python
doc_ref = db.collection("users").document("aturing")
doc_ref.set({"first": "Alan", "middle": "Mathison", "last": "Turing", "born": 1912})

Чтение данных с использованием основных операций.

Воспользуйтесь средством просмотра данных в консоли 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()}`);
    });
});
Быстрый
Примечание: Этот продукт недоступен для watchOS и приложений App Clip.
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());
                }
            }
        });
Python
users_ref = db.collection("users")
docs = users_ref.stream()

for doc in docs:
    print(f"{doc.id} => {doc.to_dict()}")

Чтение данных с использованием операций конвейера.

Теперь вы можете сравнить удобство выполнения запросов в Pipeline с удобством выполнения запросов в Core.

Web

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);
}
Быстрый
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);
    }
});
Python
pipeline = client.pipeline().collection("users")
for result in pipeline.execute():
    print(f"{result.id} => {result.data()}")

Защитите свои данные

Если вы используете SDK для веб-платформ, Android или Apple, используйте Firebase Authentication и Cloud Firestore Security Rules для защиты ваших данных в Cloud Firestore .

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

Требуется авторизация

// 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, воспользуйтесь системой управления идентификацией и доступом (IAM) для защиты ваших данных в Cloud Firestore .

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

Углубите свои знания в области основных и трубопроводных операций, изучив следующие темы: