開始使用 Cloud Firestore

本快速入門向您展示如何設置 Cloud Firestore、添加數據，然後在 Firebase 控制台中查看剛剛添加的數據。

創建 Cloud Firestore 數據庫

1. 如果您尚未創建 Firebase 項目，請在Firebase 控制台中點擊添加項目，然後按照屏幕上的說明創建 Firebase 項目或將 Firebase 服務添加到現有 GCP 項目。

2. 導航到Firebase 控制台的Cloud Firestore部分。系統會提示您選擇現有的 Firebase 項目。遵循數據庫創建工作流程。

3. 選擇 Cloud Firestore 安全規則的啟動模式：

   測試模式

   適合開始使用移動和 Web 客戶端庫，但允許任何人讀取和覆蓋您的數據。測試後，請務必查看“保護您的數據”部分。

   要開始使用 Web、Apple 平台或 Android SDK，請選擇測試模式。

   鎖定模式

   拒絕來自移動和 Web 客戶端的所有讀取和寫入。經過身份驗證的應用程序服務器（C#、Go、Java、Node.js、PHP、Python 或 Ruby）仍然可以訪問您的數據庫。

   要開始使用 C#、Go、Java、Node.js、PHP、Python 或 Ruby 服務器客戶端庫，請選擇鎖定模式。

   您的初始 Cloud Firestore 安全規則集將應用於您的默認 Cloud Firestore 數據庫。如果您為項目創建多個數據庫，則可以為每個數據庫部署 Cloud Firestore 安全規則。

4. 選擇數據庫的位置。

   • 此位置設置是您項目的默認 Google Cloud Platform (GCP) 資源位置。請注意，此位置將用於項目中需要位置設置的 GCP 服務，特別是您的默認Cloud Storage存儲桶和App Engine應用（如果您使用 Cloud Scheduler，則需要）。

   • 如果您無法選擇位置，則您的項目已有默認 GCP 資源位置。它是在項目創建期間或設置另一個需要位置設置的服務時設置的。

   警告：設置項目的默認 GCP 資源位置後，您將無法更改它。

5. 單擊“完成” 。

Cloud Firestore 和 App Engine：您不能在同一項目中同時使用 Cloud Firestore 和 Cloud Datastore，這可能會影響使用 App Engine 的應用。嘗試將 Cloud Firestore 與其他項目結合使用。

啟用 Cloud Firestore 時，還會啟用Cloud API Manager中的 API。

設置您的開發環境

將所需的依賴項和客戶端庫添加到您的應用程序。

Web namespaced API

1. 按照說明將Firebase 添加到您的 Web 應用程序。
2. 將 Firebase 和 Cloud Firestore 庫添加到您的應用中：

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

   Cloud Firestore SDK 也可以作為 npm 包提供。

   npm install firebase@10.4.0 --save
   

   您需要手動要求 Firebase 和 Cloud Firestore。

   import firebase from "firebase/compat/app";
   // Required for side-effects
   import "firebase/firestore";
   

Web modular API

1. 按照說明將Firebase 添加到您的 Web 應用程序。
2. Cloud Firestore SDK 以 npm 包的形式提供。

   npm install firebase@10.4.0 --save
   

   您需要導入 Firebase 和 Cloud Firestore。

   import { initializeApp } from "firebase/app";
   import { getFirestore } from "firebase/firestore";
   

正在尋找緊湊的 Firestore 庫，並且只需要簡單的 REST/CRUD 功能？嘗試Firestore Lite SDK ，僅可通過 npm 獲取。

iOS+

按照說明將Firebase 添加到您的 Apple 應用程序。

使用 Swift Package Manager 安裝和管理 Firebase 依賴項。

請訪問我們的安裝指南，了解將 Firebase SDK 添加到 Apple 項目的不同方法，包括直接導入框架和使用 CocoaPods。

1. 在 Xcode 中，打開應用程序項目，導航至File > Swift Packages > Add Package Dependency 。
2. 出現提示時，添加 Firebase Apple 平台 SDK 存儲庫：

  https://github.com/firebase/firebase-ios-sdk
  

注意：新項目應使用默認（最新）SDK 版本，但如果需要，您可以選擇舊版本。
3. 選擇 Firestore 庫。
4. 完成後，Xcode 將自動開始在後台解析並下載您的依賴項。

Kotlin+KTX

1. 按照說明將Firebase 添加到您的 Android 應用。
2. 使用Firebase Android BoM ，在模塊（應用級）Gradle 文件（通常app/build.gradle.kts或app/build.gradle ）中聲明 Cloud Firestore Android 庫的依賴項。

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:32.3.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-ktx")
   }
   

   通過使用Firebase Android BoM ，您的應用將始終使用 Firebase Android 庫的兼容版本。

   （替代方法）在不使用 BoM 的情況下聲明 Firebase 庫依賴項

   如果您選擇不使用 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-ktx:24.8.1")
   }
   

Java

1. 按照說明將Firebase 添加到您的 Android 應用。
2. 使用Firebase Android BoM ，在模塊（應用級）Gradle 文件（通常app/build.gradle.kts或app/build.gradle ）中聲明 Cloud Firestore Android 庫的依賴項。

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:32.3.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 庫的兼容版本。

   （替代方法）在不使用 BoM 的情況下聲明 Firebase 庫依賴項

   如果您選擇不使用 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:24.8.1")
   }
   

Dart

1. 如果您還沒有準備好，請在 Flutter 應用中配置並初始化 Firebase 。
2. 從 Flutter 項目的根目錄運行以下命令來安裝插件：

   flutter pub add cloud_firestore

3. 完成後，重建您的 Flutter 應用程序：

   flutter run

4. 可選：通過包含預編譯框架來縮短 iOS 和 macOS 的構建時間。

   目前，適用於 iOS 的 Firestore SDK 依賴於在 Xcode 中構建可能需要 5 分鐘以上的代碼。要顯著縮短構建時間，您可以通過將此行添加到 Podfile 中的target 'Runner' do塊來使用預編譯版本：

   target 'Runner' do
     pod 'FirebaseFirestore', :git => 'https://github.com/invertase/firestore-ios-sdk-frameworks.git', :tag => '8.15.0'
     # ...
   end

   此外，請確保您已將 CocoaPods 升級到 1.9.1 或更高版本：

   gem install cocoapods

   有關更多信息，請參閱GitHub 上的問題。

爪哇

1. 將 Firebase Admin SDK 添加到您的應用：
   • 使用 Gradle：

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

   • 使用 Maven：

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

2. 按照以下說明，使用您環境中的正確憑據初始化 Cloud Firestore。

Python

1. 將 Firebase Admin SDK 添加到您的 Python 應用：

   pip install --upgrade firebase-admin

2. 按照以下說明，使用您環境中的正確憑據初始化 Cloud Firestore。

C++

1. 按照說明將Firebase 添加到您的 C++ 項目。
2. Android 的 C++ 接口。
• 漸變依賴項。將以下內容添加到您的模塊（應用程序級）Gradle 文件（通常app/build.gradle ）：

          android.defaultConfig.externalNativeBuild.cmake {
            arguments "-DFIREBASE_CPP_SDK_DIR=$gradle.firebase_cpp_sdk_dir"
          }
  
          apply from: "$gradle.firebase_cpp_sdk_dir/Android/firebase_dependencies.gradle"
          firebaseCpp.dependencies {
            // earlier entries
            auth
            firestore
          }
          

• 二進制依賴關係。同樣，獲取二進制依賴項的推薦方法是將以下內容添加到CMakeLists.txt文件中：

          add_subdirectory(${FIREBASE_CPP_SDK_DIR} bin/ EXCLUDE_FROM_ALL)
          set(firebase_libs firebase_auth firebase_firestore firebase_app)
          # Replace the target name below with the actual name of your target,
          # for example, "native-lib".
          target_link_libraries(${YOUR_TARGET_NAME_HERE} "${firebase_libs}")
          

3. 要設置桌面集成，請參閱將 Firebase 添加到您的 C++ 項目。

統一

1. 按照說明將Firebase 添加到您的 Unity 項目。
2. 使用 Unity 界面配置您的項目以縮小 Android 構建。

您必須縮小構建以避免出現Error while merging dex archives消息。

• 該選項可以在Player Settings > Android > Publishing Settings > Minify中找到。
• 不同版本的 Unity 中的選項可能有所不同，因此請參閱官方Unity 文檔和Firebase Unity 構建調試指南。
• 如果啟用縮小後，引用的方法數量仍然超過限制，另一個選擇是啟用multidex ：
  • mainTemplate.gradle如果啟用了播放器設置下的自定義 Gradle 模板
  • 或者，如果您使用 Android Studio 構建導出的項目，則為模塊級build.gradle文件。

Node.js

1. 將 Firebase Admin SDK 添加到您的應用：

   npm install firebase-admin --save

2. 按照以下說明，使用您環境中的正確憑據初始化 Cloud Firestore。

去

1. 將 Firebase Admin SDK 添加到您的 Go 應用：

   go get firebase.google.com/go
   

2. 按照以下說明，使用您環境中的正確憑據初始化 Cloud Firestore。

PHP

1. Cloud Firestore 服務器客戶端庫（Java、Node.js、Python、Go、PHP、C# 和 Ruby）使用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

C＃

1. Cloud Firestore 服務器客戶端庫（Java、Node.js、Python、Go、PHP、C# 和 Ruby）使用Google 應用程序默認憑據進行身份驗證。
   • 要從開發環境進行身份驗證，請將GOOGLE_APPLICATION_CREDENTIALS環境變量設置為指向 JSON 服務帳戶密鑰文件。您可以在API控制台憑證頁面創建密鑰文件。

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

   • 在生產環境中，如果您使用與 Cloud Firestore 相同的項目在 App Engine 或 Compute Engine 上運行應用程序，則無需進行身份驗證。否則，請設置一個服務帳戶。
2. 將 Cloud Firestore C# 庫添加到應用程序的.csproj文件中：

   <ItemGroup>
     <PackageReference Include="Google.Cloud.Firestore" Version="1.1.0-beta01" />
   </ItemGroup>

3. 將以下內容添加到您的Program.cs文件中：

   using Google.Cloud.Firestore;

紅寶石

1. Cloud Firestore 服務器客戶端庫（Java、Node.js、Python、Go、PHP、C# 和 Ruby）使用Google 應用程序默認憑據進行身份驗證。
   • 要從開發環境進行身份驗證，請將GOOGLE_APPLICATION_CREDENTIALS環境變量設置為指向 JSON 服務帳戶密鑰文件。您可以在API控制台憑證頁面創建密鑰文件。

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

   • 在生產環境中，如果您使用與 Cloud Firestore 相同的項目在 App Engine 或 Compute Engine 上運行應用程序，則無需進行身份驗證。否則，請設置一個服務帳戶。
2. 將 Cloud Firestore Ruby 庫添加到您的應用程序的Gemfile中：

   gem "google-cloud-firestore"

3. 使用以下命令從Gemfile安裝依賴項：

   bundle install

（可選）使用 Firebase 本地模擬器套件進行原型設計和測試

對於移動開發人員，在討論應用如何寫入 Cloud Firestore 和從 Cloud Firestore 讀取之前，我們先介紹一組可用於原型設計和測試 Cloud Firestore 功能的工具：Firebase Local Emulator Suite。如果您正在嘗試不同的數據模型、優化安全規則或努力尋找與後端交互的最具成本效益的方式，那麼能夠在本地工作而不部署實時服務可能是一個好主意。

Cloud Firestore 模擬器是本地模擬器套件的一部分，它使您的應用能夠與模擬的數據庫內容和配置以及可選的模擬項目資源（函數、其他數據庫和安全規則）進行交互。

使用 Cloud Firestore 模擬器只需幾個步驟：

1. 將一行代碼添加到應用程序的測試配置中以連接到模擬器。
2. 從本地項目目錄的根目錄中，運行firebase emulators:start 。
3. 像往常一樣使用 Cloud Firestore 平台 SDK 從應用的原型代碼進行調用。

提供了涉及 Cloud Firestore 和 Cloud Functions 的詳細演練。您還應該看看本地仿真器套件的介紹。

初始化 Cloud Firestore

初始化 Cloud Firestore 實例：

Web modular API

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);


// Initialize Cloud Firestore and get a reference to the service
const db = getFirestore(app);

將FIREBASE_CONFIGURATION替換為您的網絡應用程序的firebaseConfig 。

要在設備失去連接時保留數據，請參閱啟用脫機數據文檔。

Web namespaced API

import firebase from "firebase/app";
import "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
firebase.initializeApp(firebaseConfig);


// Initialize Cloud Firestore and get a reference to the service
const db = firebase.firestore();

將FIREBASE_CONFIGURATION替換為您的網絡應用程序的firebaseConfig 。

要在設備失去連接時保留數據，請參閱啟用脫機數據文檔。

迅速

注意：此產品不適用於 watchOS 和 App Clip 目標。

import FirebaseCore
import FirebaseFirestore

FirebaseApp.configure()

let db = Firestore.firestore()
AppDelegate.swift

Objective-C

注意：此產品不適用於 watchOS 和 App Clip 目標。

@import FirebaseCore;
@import FirebaseFirestore;

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

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

Kotlin+KTX

// Access a Cloud Firestore instance from your Activity

val db = Firebase.firestore
DocSnippets.kt

Java

// Access a Cloud Firestore instance from your Activity

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

Dart

db = FirebaseFirestore.instance;

爪哇

Cloud Firestore SDK 根據您的環境以不同的方式初始化。以下是最常見的方法。有關完整參考，請參閱初始化 Admin SDK 。

在 Google Cloud

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，請使用服務帳號。

轉到 Google Cloud 控制台中的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

import firebase_admin
from firebase_admin import firestore

# Application Default credentials are automatically created.
app = firebase_admin.initialize_app()
db = firestore.client()
firestore.py

上初始化

現有的應用程序默認憑據也可用於初始化 SDK。

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)
db = firestore.client()
firestore.py

在自己的服務器上初始化

要在您自己的服務器上使用 Firebase Admin SDK，請使用服務帳號。

轉到 Google Cloud 控制台中的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')

app = firebase_admin.initialize_app(cred)

db = firestore.client()
firestore.py

Python

Cloud Firestore SDK 根據您的環境以不同的方式初始化。以下是最常見的方法。有關完整參考，請參閱初始化 Admin SDK 。

在 Google Cloud

import firebase_admin
from firebase_admin import firestore_async

# Application Default credentials are automatically created.
app = firebase_admin.initialize_app()
db = firestore_async.client()
firestore_async.py

上初始化

現有的應用程序默認憑據也可用於初始化 SDK。

import firebase_admin
from firebase_admin import credentials
from firebase_admin import firestore_async

# Use the application default credentials.
cred = credentials.ApplicationDefault()

firebase_admin.initialize_app(cred)
db = firestore_async.client()
firestore_async.py

在自己的服務器上初始化

要在您自己的服務器上使用 Firebase Admin SDK，請使用服務帳號。

轉到 Google Cloud 控制台中的IAM 和管理 > 服務帳號。生成新的私鑰並保存 JSON 文件。然後使用該文件初始化SDK：

import firebase_admin
from firebase_admin import credentials
from firebase_admin import firestore_async

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

app = firebase_admin.initialize_app(cred)

db = firestore_async.client()
firestore_async.py

C++

// Make sure the call to `Create()` happens some time before you call Firestore::GetInstance().
App::Create();
Firestore* db = Firestore::GetInstance();
AppDelegate.mm

Node.js

Cloud Firestore SDK 根據您的環境以不同的方式初始化。以下是最常見的方法。有關完整參考，請參閱初始化 Admin SDK 。

• 在 Cloud Functions 上初始化

  const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
  const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');

  initializeApp();
  
  const db = getFirestore();
  index.js

• 在 Google Cloud 上初始化

  const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
  const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');

  initializeApp({
    credential: applicationDefault()
  });
  
  const db = getFirestore();
  index.js

• 在自己的服務器上初始化

  要在您自己的服務器（或任何其他 Node.js 環境）上使用 Firebase Admin SDK，請使用服務帳戶。轉到 Google Cloud 控制台中的IAM 和管理 > 服務帳號。生成新的私鑰並保存 JSON 文件。然後使用該文件初始化SDK：

  const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
  const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');

  const serviceAccount = require('./path/to/serviceAccountKey.json');
  
  initializeApp({
    credential: cert(serviceAccount)
  });
  
  const db = getFirestore();
  index.js

去

Cloud Firestore SDK 根據您的環境以不同的方式初始化。以下是最常見的方法。有關完整參考，請參閱初始化 Admin SDK 。

在 Google Cloud

import (
  "log"

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

// Use the application default credentials
ctx := context.Background()
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，請使用服務帳號。

轉到 Google Cloud 控制台中的IAM 和管理 > 服務帳號。生成新的私鑰並保存 JSON 文件。然後使用該文件初始化SDK：

import (
  "log"

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

// Use a service account
ctx := context.Background()
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

PHP

有關安裝和創建 Cloud Firestore 客戶端的更多信息，請參閱Cloud Firestore 客戶端庫。

use Google\Cloud\Firestore\FirestoreClient;

/**
 * Initialize Cloud Firestore with default project ID.
 */
function setup_client_create(string $projectId = null)
{
    // Create the Cloud Firestore client
    if (empty($projectId)) {
        // The `projectId` parameter is optional and represents which project the
        // client will act on behalf of. If not supplied, the client falls back to
        // the default project inferred from the environment.
        $db = new FirestoreClient();
        printf('Created Cloud Firestore client with default project ID.' . PHP_EOL);
    } else {
        $db = new FirestoreClient([
            'projectId' => $projectId,
        ]);
        printf('Created Cloud Firestore client with project ID: %s' . PHP_EOL, $projectId);
    }
}
setup_client_create.php

統一

using Firebase.Firestore;
using Firebase.Extensions;

FirebaseFirestore db = FirebaseFirestore.DefaultInstance;

C＃

C＃

有關安裝和創建 Cloud Firestore 客戶端的更多信息，請參閱Cloud Firestore 客戶端庫。

FirestoreDb db = FirestoreDb.Create(project);
Console.WriteLine("Created Cloud Firestore client with project ID: {0}", project);
Program.cs

紅寶石

require "google/cloud/firestore"

# The `project_id` parameter is optional and represents which project the
# client will act on behalf of. If not supplied, the client falls back to the
# default project inferred from the environment.
firestore = Google::Cloud::Firestore.new project_id: project_id

puts "Created Cloud Firestore client with given project ID."
quickstart.rb

添加數據

Cloud Firestore 將數據存儲在文檔中，文檔存儲在集合中。當您第一次將數據添加到文檔時，Cloud Firestore 會隱式創建集合和文檔。您不需要顯式創建集合或文檔。

使用以下示例代碼創建新集合和文檔。

Web modular API

詳細了解可樹搖動的模塊化 Web API 以及從命名空間 API進行升級。

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);
}
add_ada_lovelace.js

Web namespaced API

詳細了解可樹搖動的模塊化 Web API 以及從命名空間 API進行升級。

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);
});
test.firestore.js

迅速

注意：此產品不適用於 watchOS 和 App Clip 目標。

// 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

注意：此產品不適用於 watchOS 和 App Clip 目標。

// 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

Kotlin+KTX

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

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

Dart

// Create a new user with a first and last name
final user = <String, dynamic>{
  "first": "Ada",
  "last": "Lovelace",
  "born": 1815
};

// Add a new document with a generated ID
db.collection("users").add(user).then((DocumentReference doc) =>
    print('DocumentSnapshot added with ID: ${doc.id}'));
firestore.dart

爪哇

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("users").document("alovelace")
doc_ref.set({"first": "Ada", "last": "Lovelace", "born": 1815})
snippets.py

Python

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

C++

// Add a new document with a generated ID
Future<DocumentReference> user_ref =
    db->Collection("users").Add({{"first", FieldValue::String("Ada")},
                                 {"last", FieldValue::String("Lovelace")},
                                 {"born", FieldValue::Integer(1815)}});

user_ref.OnCompletion([](const Future<DocumentReference>& future) {
  if (future.error() == Error::kErrorOk) {
    std::cout << "DocumentSnapshot added with ID: " << future.result()->id()
              << std::endl;
  } else {
    std::cout << "Error adding document: " << future.error_message() << std::endl;
  }
});
snippets.cpp

Node.js

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

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

去

_, _, 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

PHP

有關安裝和創建 Cloud Firestore 客戶端的更多信息，請參閱Cloud Firestore 客戶端庫。

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

統一

DocumentReference docRef = db.Collection("users").Document("alovelace");
Dictionary<string, object> user = new Dictionary<string, object>
{
	{ "First", "Ada" },
	{ "Last", "Lovelace" },
	{ "Born", 1815 },
};
docRef.SetAsync(user).ContinueWithOnMainThread(task => {
	Debug.Log("Added data to the alovelace document in the users collection.");
});

C＃

DocumentReference docRef = db.Collection("users").Document("alovelace");
Dictionary<string, object> user = new Dictionary<string, object>
{
    { "First", "Ada" },
    { "Last", "Lovelace" },
    { "Born", 1815 }
};
await docRef.SetAsync(user);
Program.cs

紅寶石

doc_ref = firestore.doc "#{collection_path}/alovelace"

doc_ref.set(
  {
    first: "Ada",
    last:  "Lovelace",
    born:  1815
  }
)

puts "Added data to the alovelace document in the users collection."
quickstart.rb

現在將另一個文檔添加到users集合中。請注意，此文檔包含一個未出現在第一個文檔中的鍵值對（中間名）。集合中的文檔可以包含不同的信息集。

Web modular API

詳細了解可樹搖動的模塊化 Web API 以及從命名空間 API進行升級。

// 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);
}
add_alan_turing.js

Web namespaced API

詳細了解可樹搖動的模塊化 Web API 以及從命名空間 API進行升級。

// 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);
});
test.firestore.js

迅速

注意：此產品不適用於 watchOS 和 App Clip 目標。

// 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

注意：此產品不適用於 watchOS 和 App Clip 目標。

// 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

Kotlin+KTX

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

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

Dart

// Create a new user with a first and last name
final user = <String, dynamic>{
  "first": "Alan",
  "middle": "Mathison",
  "last": "Turing",
  "born": 1912
};

// Add a new document with a generated ID
db.collection("users").add(user).then((DocumentReference doc) =>
    print('DocumentSnapshot added with ID: ${doc.id}'));
firestore.dart

爪哇

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("users").document("aturing")
doc_ref.set({"first": "Alan", "middle": "Mathison", "last": "Turing", "born": 1912})
snippets.py

Python

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

C++

db->Collection("users")
    .Add({{"first", FieldValue::String("Alan")},
          {"middle", FieldValue::String("Mathison")},
          {"last", FieldValue::String("Turing")},
          {"born", FieldValue::Integer(1912)}})
    .OnCompletion([](const Future<DocumentReference>& future) {
      if (future.error() == Error::kErrorOk) {
        std::cout << "DocumentSnapshot added with ID: "
                  << future.result()->id() << std::endl;
      } else {
        std::cout << "Error adding document: " << future.error_message()
                  << std::endl;
      }
    });
snippets.cpp

Node.js

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

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

去

_, _, 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

PHP

有關安裝和創建 Cloud Firestore 客戶端的更多信息，請參閱Cloud Firestore 客戶端庫。

$docRef = $db->collection('samples/php/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);
setup_dataset.php

統一

DocumentReference docRef = db.Collection("users").Document("aturing");
Dictionary<string, object> user = new Dictionary<string, object>
{
	{ "First", "Alan" },
	{ "Middle", "Mathison" },
	{ "Last", "Turing" },
	{ "Born", 1912 }
};
docRef.SetAsync(user).ContinueWithOnMainThread(task => {
	Debug.Log("Added data to the aturing document in the users collection.");
});

C＃

DocumentReference docRef = db.Collection("users").Document("aturing");
Dictionary<string, object> user = new Dictionary<string, object>
{
    { "First", "Alan" },
    { "Middle", "Mathison" },
    { "Last", "Turing" },
    { "Born", 1912 }
};
await docRef.SetAsync(user);
Program.cs

紅寶石

doc_ref = firestore.doc "#{collection_path}/aturing"

doc_ref.set(
  {
    first:  "Alan",
    middle: "Mathison",
    last:   "Turing",
    born:   1912
  }
)

puts "Added data to the aturing document in the users collection."
quickstart.rb

讀取數據

使用Firebase 控制台中的數據查看器快速驗證您是否已將數據添加到 Cloud Firestore。

您還可以使用“get”方法來檢索整個集合。

Web modular API

詳細了解可樹搖動的模塊化 Web API 以及從命名空間 API進行升級。

import { collection, getDocs } from "firebase/firestore"; 

const querySnapshot = await getDocs(collection(db, "users"));
querySnapshot.forEach((doc) => {
  console.log(`${doc.id} => ${doc.data()}`);
});
get_all_users.js

Web namespaced API

詳細了解可樹搖動的模塊化 Web API 以及從命名空間 API進行升級。

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

迅速

注意：此產品不適用於 watchOS 和 App Clip 目標。

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

注意：此產品不適用於 watchOS 和 App Clip 目標。

[[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

Kotlin+KTX

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)
    }
DocSnippets.kt

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

Dart

await db.collection("users").get().then((event) {
  for (var doc in event.docs) {
    print("${doc.id} => ${doc.data()}");
  }
});
firestore.dart

爪哇

// 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("users")
docs = users_ref.stream()

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

Python

users_ref = db.collection("users")
docs = users_ref.stream()

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

C++

Future<QuerySnapshot> users = db->Collection("users").Get();
users.OnCompletion([](const Future<QuerySnapshot>& future) {
  if (future.error() == Error::kErrorOk) {
    for (const DocumentSnapshot& document : future.result()->documents()) {
      std::cout << document << std::endl;
    }
  } else {
    std::cout << "Error getting documents: " << future.error_message()
              << std::endl;
  }
});
snippets.cpp

Node.js

const snapshot = await db.collection('users').get();
snapshot.forEach((doc) => {
  console.log(doc.id, '=>', doc.data());
});
index.js

去

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

PHP

有關安裝和創建 Cloud Firestore 客戶端的更多信息，請參閱Cloud Firestore 客戶端庫。

$usersRef = $db->collection('samples/php/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);
setup_dataset_read.php

統一

CollectionReference usersRef = db.Collection("users");
usersRef.GetSnapshotAsync().ContinueWithOnMainThread(task =>
{
  QuerySnapshot snapshot = task.Result;
  foreach (DocumentSnapshot document in snapshot.Documents)
  {
    Debug.Log(String.Format("User: {0}", document.Id));
    Dictionary<string, object> documentDictionary = document.ToDictionary();
    Debug.Log(String.Format("First: {0}", documentDictionary["First"]));
    if (documentDictionary.ContainsKey("Middle"))
    {
      Debug.Log(String.Format("Middle: {0}", documentDictionary["Middle"]));
    }

    Debug.Log(String.Format("Last: {0}", documentDictionary["Last"]));
    Debug.Log(String.Format("Born: {0}", documentDictionary["Born"]));
  }

  Debug.Log("Read all data from the users collection.");
});

C＃

CollectionReference usersRef = db.Collection("users");
QuerySnapshot snapshot = await usersRef.GetSnapshotAsync();
foreach (DocumentSnapshot document in snapshot.Documents)
{
    Console.WriteLine("User: {0}", document.Id);
    Dictionary<string, object> documentDictionary = document.ToDictionary();
    Console.WriteLine("First: {0}", documentDictionary["First"]);
    if (documentDictionary.ContainsKey("Middle"))
    {
        Console.WriteLine("Middle: {0}", documentDictionary["Middle"]);
    }
    Console.WriteLine("Last: {0}", documentDictionary["Last"]);
    Console.WriteLine("Born: {0}", documentDictionary["Born"]);
    Console.WriteLine();
}
Program.cs

紅寶石

users_ref = firestore.col collection_path
users_ref.get do |user|
  puts "#{user.document_id} data: #{user.data}."
end
quickstart.rb

保護您的數據

如果您使用的是 Web、Android 或 Apple 平台 SDK，請使用Firebase 身份驗證和Cloud Firestore 安全規則來保護 Cloud Firestore 中的數據。

以下是一些可用於入門的基本規則集。您可以在控制台的“規則”選項卡中修改安全規則。

需要身份驗證

// Allow read/write access on all documents to any user signed in to the application
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if request.auth != null;
    }
  }
}

鎖定模式

// Deny read/write access to all users under any conditions
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if false;
    }
  }
}

測試模式

// Allow read/write access to all users under any conditions
// Warning: **NEVER** use this rule set in production; it allows
// anyone to overwrite your entire database.
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if true;
    }
  }
}

在將 Web、Android 或 iOS 應用部署到生產環境之前，還應採取措施確保只有您的應用客戶端才能訪問您的 Cloud Firestore 數據。請參閱應用程序檢查文檔。

如果您使用的是服務器 SDK 之一，請使用身份和訪問管理 (IAM)來保護 Cloud Firestore 中的數據。

觀看視頻教程

有關 Cloud Firestore 移動客戶端庫入門的詳細指南，請觀看以下視頻教程之一：

網絡

iOS+

安卓

您可以在 Firebase YouTube 頻道中找到更多視頻。

下一步

通過以下主題加深您的知識：

• Codelabs — 按照Android 、 iOS或Web的 Codelab 學習如何在實際應用中使用 Cloud Firestore。
• 數據模型- 詳細了解 Cloud Firestore 中的數據結構，包括分層數據和子集合。
• 添加數據— 詳細了解如何在 Cloud Firestore 中創建和更新數據。
• 獲取數據— 了解有關如何檢索數據的更多信息。
• 執行簡單和復合查詢- 了解如何運行簡單和復合查詢。
• 對查詢進行排序和限制了解如何對查詢返回的數據進行排序和限制。