Cloud Firestore 使用入门

此快速入门将向您展示如何设置 Cloud Firestore、添加数据以及在 Firebase 控制台中查看您刚刚添加的数据。

创建 Cloud Firestore 项目

1. 打开 Firebase 控制台并创建一个新项目。

2. 在 Database（数据库）部分中，点击试用 Firestore 测试版。

3. 点击启用。

Cloud Firestore 和 App Engine：您不能在一个项目中同时使用 Cloud Firestore 和 Cloud Datastore，否则可能会影响使用 App Engine 的应用。请尝试在其他项目中使用 Cloud Firestore。

您在创建 Cloud Firestore 项目时，也会在 Cloud API Manager 中启用 API。

设置您的开发环境

将所需的依赖项和客户端库添加到您的应用。

网页

1. 按照相关说明将 Firebase 添加到您的网页应用。
2. 将 Firebase 库和 Cloud Firestore 库添加到您的应用中：

   <script src="https://www.gstatic.com/firebasejs/4.12.1/firebase.js"></script>
   <script src="https://www.gstatic.com/firebasejs/4.12.1/firebase-firestore.js"></script>

   Cloud Firestore SDK 也可以作为 npm 软件包提供。

   npm install firebase@4.12.1 --save
   

   您需要手动通过 require() 函数同时引入 Firebase 和 Cloud Firestore。

   const firebase = require("firebase");
   // Required for side-effects
   require("firebase/firestore");
   

iOS

1. 按照相关说明将 Firebase 添加到您的 iOS 应用。
2. 将 Cloud Firestore pod 添加到您的 Podfile

   pod 'Firebase/Core'
   pod 'Firebase/Firestore'

3. 保存该文件并运行 pod install。

Android

1. 按照相关说明将 Firebase 添加到您的 Android 应用。
2. 将 Cloud Firestore Android 库添加到您的 app/build.gradle 文件中：

   compile 'com.google.firebase:firebase-firestore:15.0.0'

Java

1. 将 Firebase Admin SDK 添加到您的应用中：
   • 使用 Gradle：

     compile 'com.google.firebase:firebase-admin:5.10.0'
     

   • 使用 Maven：

     <dependency>
       <groupId>com.google.firebase</groupId>
       <artifactId>firebase-admin</artifactId>
       <version>5.10.0</version>
     </dependency>
          

2. 按照以下说明在您的环境中使用适当的凭据初始化 Cloud Firestore。

Python

1. 将 Firebase Admin SDK 添加到您的 Python 应用中：

   pip install --upgrade firebase-admin

2. 按照以下说明在您的环境中使用适当的凭据初始化 Cloud Firestore。

Node.js

1. 将 Firebase Admin SDK 添加到您的应用中：

   npm install firebase-admin --save

2. 按照以下说明在您的环境中使用适当的凭据初始化 Cloud Firestore。

Go

1. 将 Firebase Admin SDK 添加到您的 Go 应用中：

   go get firebase.google.com/go
   

2. 按照以下说明在您的环境中使用适当的凭据初始化 Cloud Firestore。

PHP

1. Cloud Firestore 服务器客户端库（Java、Node.js、Python 和 Go）使用 Google 应用默认凭据进行身份验证。
   • 要从开发环境中进行身份验证，请将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为指向 JSON 服务帐号密钥文件。您可以在 API 控制台的“凭据”页面上创建一个密钥文件。

     export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/keyfile.json"

   • 在生产环境中，如果您使用 Cloud Firestore 所用的那个项目在 App Engine 或 Compute Engine 上运行应用，则无需进行身份验证。否则，请设置服务帐号。
2. 为 PHP 安装并启用 gRPC 扩展程序（您在使用客户端库时会用到它）。
3. 将 Cloud Firestore PHP 库添加到您的应用中：

   composer require google/cloud-firestore

初始化 Cloud Firestore

初始化 Cloud Firestore 的实例：

网页

firebase.initializeApp({
  apiKey: '### FIREBASE API KEY ###',
  authDomain: '### FIREBASE AUTH DOMAIN ###',
  projectId: '### CLOUD FIRESTORE PROJECT ID ###'
});

// Initialize Cloud Firestore through Firebase
var db = firebase.firestore();

要在设备失去网络连接时保留数据，请参阅启用离线数据这篇文档。

Swift

import Firebase

FirebaseApp.configure()

let db = Firestore.firestore()
AppDelegate.swift

Objective-C

@import Firebase;

// Use Firebase library to configure APIs
[FIRApp configure];

FIRFirestore *defaultFirestore = [FIRFirestore firestore];
AppDelegate.m
  

Android

// Access a Cloud Firestore instance from your Activity

FirebaseFirestore db = FirebaseFirestore.getInstance();
DocSnippets.java

Java

Cloud Firestore SDK 可通过各种不同的方式进行初始化，具体取决于您的环境。以下是最常用的一些方法。如需完整的参考，请参阅初始化 Admin SDK。

在 Google Cloud Platform 上初始化

import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.firestore.Firestore;

import com.google.firebase.FirebaseApp;
import com.google.firebase.FirebaseOptions;

// Use the application default credentials
GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
FirebaseOptions options = new FirebaseOptions.Builder()
    .setCredentials(credentials)
    .setProjectId(projectId)
    .build();
FirebaseApp.initializeApp(options);

Firestore db = FirestoreClient.getFirestore();

在您自己的服务器上初始化

要在您自己的服务器上使用 Firebase Admin SDK，请使用一个服务帐号。

在 Cloud Platform Console 中，转到 IAM 和管理 > 服务帐号。生成一个新的私钥并保存该 JSON 文件。然后使用该文件来初始化 SDK：

import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.firestore.Firestore;

import com.google.firebase.FirebaseApp;
import com.google.firebase.FirebaseOptions;

// Use a service account
InputStream serviceAccount = new FileInputStream("path/to/serviceAccount.json");
GoogleCredentials credentials = GoogleCredentials.fromStream(serviceAccount);
FirebaseOptions options = new FirebaseOptions.Builder()
    .setCredentials(credentials)
    .build();
FirebaseApp.initializeApp(options);

Firestore db = FirestoreClient.getFirestore();

Python

Cloud Firestore SDK 可通过各种不同的方式进行初始化，具体取决于您的环境。以下是最常用的一些方法。如需完整的参考，请参阅初始化 Admin SDK。

在 Google Cloud Platform 上初始化

import firebase_admin
from firebase_admin import credentials
from firebase_admin import firestore

# Use the application default credentials
cred = credentials.ApplicationDefault()
firebase_admin.initialize_app(cred, {
  'projectId': project_id,
})

db = firestore.client()

在您自己的服务器上初始化

要在您自己的服务器上使用 Firebase Admin SDK，请使用一个服务帐号。

在 Cloud Platform Console 中，转到 IAM 和管理 > 服务帐号。生成一个新的私钥并保存该 JSON 文件。然后使用该文件来初始化 SDK：

import firebase_admin
from firebase_admin import credentials
from firebase_admin import firestore

# Use a service account
cred = credentials.Certificate('path/to/serviceAccount.json')
firebase_admin.initialize_app(cred)

db = firestore.client()

Node.js

Cloud Firestore SDK 可通过各种不同的方式进行初始化，具体取决于您的环境。以下是最常用的一些方法。如需完整的参考，请参阅初始化 Admin SDK。

• 在 Cloud Functions 上初始化

  const admin = require('firebase-admin');const functions = require('firebase-functions');
  
  admin.initializeApp(functions.config().firebase);
  
  var db = admin.firestore();
  index.js
  

• 在 Google Cloud Platform 上初始化

  const admin = require('firebase-admin');
  admin.initializeApp({
    credential: admin.credential.applicationDefault()
  });
  
  var db = admin.firestore();
  index.js
  

• 在您自己的服务器上初始化

  要在您自己的服务器上（或其他任何 Node.js 环境中）使用 Firebase Admin SDK，请使用一个服务帐号。 在 Cloud Platform Console 中，转到 IAM 和管理 > 服务帐号。生成一个新的私钥并保存该 JSON 文件。然后使用该文件来初始化 SDK：

  const admin = require('firebase-admin');
  var serviceAccount = require('path/to/serviceAccountKey.json');
  
  admin.initializeApp({
    credential: admin.credential.cert(serviceAccount)
  });
  
  var db = admin.firestore();
  index.js
  

Go

Cloud Firestore SDK 可通过各种不同的方式进行初始化，具体取决于您的环境。以下是最常用的一些方法。如需完整的参考，请参阅初始化 Admin SDK。

在 Google Cloud Platform 上初始化

import (
  "log"

  firebase "firebase.google.com/go"
  "google.golang.org/api/option"
)

// Use the application default credentials
conf := &firebase.Config{ProjectID: projectID}
app, err := firebase.NewApp(ctx, conf)
if err != nil {
  log.Fatalln(err)
}

client, err := app.Firestore(ctx)
if err != nil {
  log.Fatalln(err)
}
defer client.Close()

在您自己的服务器上初始化

要在您自己的服务器上使用 Firebase Admin SDK，请使用一个服务帐号。

在 Cloud Platform Console 中，转到 IAM 和管理 > 服务帐号。生成一个新的私钥并保存该 JSON 文件。然后使用该文件来初始化 SDK：

import (
  "log"

  firebase "firebase.google.com/go"
  "google.golang.org/api/option"
)

// Use a service account
sa := option.WithCredentialsFile("path/to/serviceAccount.json")
app, err := firebase.NewApp(ctx, nil, sa)
if err != nil {
  log.Fatalln(err)
}

client, err := app.Firestore(ctx)
if err != nil {
  log.Fatalln(err)
}
defer client.Close()

PHP

use Google\Cloud\Firestore\FirestoreClient;

/**
 * Initialize Cloud Firestore with default project ID.
 * ```
 * initialize();
 * ```
 */
function initialize()
{
    // Create the Cloud Firestore client
    $db = new FirestoreClient();
    printf('Created Cloud Firestore client with default project ID.' . PHP_EOL);
}
initialize.php

添加数据

Cloud Firestore 将数据存储在文档中，而文档存储在集合中。在您首次向文档添加数据时，Cloud Firestore 就会隐式创建集合和文档。您不需要显式创建集合或文档。

使用以下示例代码创建一个新集合和一个新文档。

网页

db.collection("users").add({
    first: "Ada",
    last: "Lovelace",
    born: 1815
})
.then(function(docRef) {
    console.log("Document written with ID: ", docRef.id);
})
.catch(function(error) {
    console.error("Error adding document: ", error);
});
test.firestore.js

Swift

// Add a new document with a generated ID
var ref: DocumentReference? = nil
ref = db.collection("users").addDocument(data: [
    "first": "Ada",
    "last": "Lovelace",
    "born": 1815
]) { err in
    if let err = err {
        print("Error adding document: \(err)")
    } else {
        print("Document added with ID: \(ref!.documentID)")
    }
}
ViewController.swift

Objective-C

// Add a new document with a generated ID
__block FIRDocumentReference *ref =
    [[self.db collectionWithPath:@"users"] addDocumentWithData:@{
      @"first": @"Ada",
      @"last": @"Lovelace",
      @"born": @1815
    } completion:^(NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error adding document: %@", error);
      } else {
        NSLog(@"Document added with ID: %@", ref.documentID);
      }
    }];
ViewController.m
  

Android

// 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);
            }
        });
DocSnippets.java

Java

DocumentReference docRef = db.collection("users").document("alovelace");
// Add document data  with id "alovelace" using a hashmap
Map<String, Object> data = new HashMap<>();
data.put("first", "Ada");
data.put("last", "Lovelace");
data.put("born", 1815);
//asynchronously write data
ApiFuture<WriteResult> result = docRef.set(data);
// ...
// result.get() blocks on response
System.out.println("Update time : " + result.get().getUpdateTime());
Quickstart.java
  

Python

doc_ref = db.collection(u'users').document(u'alovelace')
doc_ref.set({
    u'first': u'Ada',
    u'last': u'Lovelace',
    u'born': 1815
})
snippets.py
  

Node.js

var docRef = db.collection('users').doc('alovelace');

var setAda = docRef.set({
  first: 'Ada',
  last: 'Lovelace',
  born: 1815
});
index.js
  

Go

_, _, err = client.Collection("users").Add(ctx, map[string]interface{}{
	"first": "Ada",
	"last":  "Lovelace",
	"born":  1815,
})
if err != nil {
	log.Fatalf("Failed adding alovelace: %v", err)
}
main.go
  

PHP

$docRef = $db->collection('users')->document('lovelace');
$docRef->set([
    'first' => 'Ada',
    'last' => 'Lovelace',
    'born' => 1815
]);
printf('Added data to the lovelace document in the users collection.' . PHP_EOL);
add_data.php
  

现在将另一个文档添加到 users 集合。请注意，此文档包含第一个文档中没有的一个键值对（中间名）。集合中的文档可以包含不同的信息集。

网页

// Add a second document with a generated ID.
db.collection("users").add({
    first: "Alan",
    middle: "Mathison",
    last: "Turing",
    born: 1912
})
.then(function(docRef) {
    console.log("Document written with ID: ", docRef.id);
})
.catch(function(error) {
    console.error("Error adding document: ", error);
});
test.firestore.js

Swift

// Add a second document with a generated ID.
ref = db.collection("users").addDocument(data: [
    "first": "Alan",
    "middle": "Mathison",
    "last": "Turing",
    "born": 1912
]) { err in
    if let err = err {
        print("Error adding document: \(err)")
    } else {
        print("Document added with ID: \(ref!.documentID)")
    }
}
ViewController.swift

Objective-C

// Add a second document with a generated ID.
__block FIRDocumentReference *ref =
    [[self.db collectionWithPath:@"users"] addDocumentWithData:@{
      @"first": @"Alan",
      @"middle": @"Mathison",
      @"last": @"Turing",
      @"born": @1912
    } completion:^(NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error adding document: %@", error);
      } else {
        NSLog(@"Document added with ID: %@", ref.documentID);
      }
    }];
ViewController.m
  

Android

// 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);
            }
        });
DocSnippets.java

Java

DocumentReference docRef = db.collection("users").document("aturing");
// Add document data with an additional field ("middle")
Map<String, Object> data = new HashMap<>();
data.put("first", "Alan");
data.put("middle", "Mathison");
data.put("last", "Turing");
data.put("born", 1912);

ApiFuture<WriteResult> result = docRef.set(data);
System.out.println("Update time : " + result.get().getUpdateTime());
Quickstart.java
  

Python

doc_ref = db.collection(u'users').document(u'aturing')
doc_ref.set({
    u'first': u'Alan',
    u'middle': u'Mathison',
    u'last': u'Turing',
    u'born': 1912
})
snippets.py
  

Node.js

var aTuringRef = db.collection('users').doc('aturing');

var setAlan = aTuringRef.set({
  'first': 'Alan',
  'middle': 'Mathison',
  'last': 'Turing',
  'born': 1912
});
index.js
  

Go

_, _, err = client.Collection("users").Add(ctx, map[string]interface{}{
	"first":  "Alan",
	"middle": "Mathison",
	"last":   "Turing",
	"born":   1912,
})
if err != nil {
	log.Fatalf("Failed adding aturing: %v", err)
}
main.go
  

PHP

$docRef = $db->collection('users')->document('aturing');
$docRef->set([
    'first' => 'Alan',
    'middle' => 'Mathison',
    'last' => 'Turing',
    'born' => 1912
]);
printf('Added data to the aturing document in the users collection.' . PHP_EOL);
add_data.php
  

读取数据

要快速验证是否已将数据添加到 Cloud Firestore，请使用 Firebase 控制台中的数据查看器。

您也可以使用“get”方法来检索整个集合。

网页

db.collection("users").get().then((querySnapshot) => {
    querySnapshot.forEach((doc) => {
        console.log(`${doc.id} => ${doc.data()}`);
    });
});
test.firestore.js

Swift

db.collection("users").getDocuments() { (querySnapshot, err) in
    if let err = err {
        print("Error getting documents: \(err)")
    } else {
        for document in querySnapshot!.documents {
            print("\(document.documentID) => \(document.data())")
        }
    }
}
ViewController.swift

Objective-C

[[self.db collectionWithPath:@"users"]
    getDocumentsWithCompletion:^(FIRQuerySnapshot * _Nullable snapshot,
                                 NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error getting documents: %@", error);
      } else {
        for (FIRDocumentSnapshot *document in snapshot.documents) {
          NSLog(@"%@ => %@", document.documentID, document.data);
        }
      }
    }];
ViewController.m
  

Android

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());
                }
            }
        });
DocSnippets.java

Java

// asynchronously retrieve all users
ApiFuture<QuerySnapshot> query = db.collection("users").get();
// ...
// query.get() blocks on response
QuerySnapshot querySnapshot = query.get();
List<QueryDocumentSnapshot> documents = querySnapshot.getDocuments();
for (QueryDocumentSnapshot document : documents) {
  System.out.println("User: " + document.getId());
  System.out.println("First: " + document.getString("first"));
  if (document.contains("middle")) {
    System.out.println("Middle: " + document.getString("middle"));
  }
  System.out.println("Last: " + document.getString("last"));
  System.out.println("Born: " + document.getLong("born"));
}
Quickstart.java
  

Python

users_ref = db.collection(u'users')
docs = users_ref.get()

for doc in docs:
    print(u'{} => {}'.format(doc.id, doc.to_dict()))
snippets.py
  

Node.js

db.collection('users').get()
    .then((snapshot) => {
      snapshot.forEach((doc) => {
        console.log(doc.id, '=>', doc.data());
      });
    })
    .catch((err) => {
      console.log('Error getting documents', err);
    });
index.js
  

Go

iter := client.Collection("users").Documents(ctx)
for {
	doc, err := iter.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("Failed to iterate: %v", err)
	}
	fmt.Println(doc.Data())
}
main.go
  

PHP

$usersRef = $db->collection('users');
$snapshot = $usersRef->documents();
foreach ($snapshot as $user) {
    printf('User: %s' . PHP_EOL, $user->id());
    printf('First: %s' . PHP_EOL, $user['first']);
    if (!empty($user['middle'])) {
        printf('Middle: %s' . PHP_EOL, $user['middle']);
    }
    printf('Last: %s' . PHP_EOL, $user['last']);
    printf('Born: %d' . PHP_EOL, $user['born']);
    printf(PHP_EOL);
}
printf('Retrieved and printed out all documents from the users collection.' . PHP_EOL);
get_all.php
  

保护您的数据

• 如果您使用的是网页版、Android 版或 iOS 版 SDK，请使用 Firebase 身份验证和 Cloud Firestore 安全规则来保护 Cloud Firestore 中的数据。
• 如果您使用的是服务器 SDK 中的一种，请使用 Identity and Access Management (IAM) 来保护 Cloud Firestore 中的数据。

观看视频教程

如需帮助您开始使用 Cloud Firestore 移动和网页客户端库的详细指南，请观看以下视频教程之一：

网页

iOS

Android

您可以在 Firebase YouTube 频道中找到更多视频。

后续步骤

通过以下各主题深入了解相关知识：

• 代码实验室 - 通过针对 Android 版、iOS 版或网页版应用的代码实验室，了解如何在实际应用中使用 Cloud Firestore。
• 数据模型 - 详细了解 Cloud Firestore 中数据的结构组织形式，包括分层数据和子集合。
• 添加数据 - 详细了解如何在 Cloud Firestore 中创建和更新数据。
• 获取数据 - 详细了解如何检索数据。
• 执行简单查询和复合查询 - 了解如何运行简单查询和复合查询。
• 对查询结果进行排序和限定数量 - 了解如何对查询返回的数据进行排序和限定数量。