開始使用 Cloud Firestore

本快速入門導覽課程說明如何設定 Cloud Firestore、新增資料，然後在 Firebase 控制台中查看剛才新增的資料。

建立 Cloud Firestore 資料庫

  1. 如果尚未建立 Firebase 專案，請在 Firebase 控制台中按一下「新增專案」，然後按照畫面上的指示建立 Firebase 專案，或將 Firebase 服務新增至現有的 Google Cloud 專案。

  2. 在 Firebase 控制台中開啟專案。在左側面板中展開「Build」，然後選取「Firestore database」。

  3. 按一下 [Create database] (建立資料庫)。

  4. 選取資料庫的位置。

    如果無法選取位置，表示專案的「預設 Google Cloud 資源位置」已設定完畢。專案的部分資源 (例如預設 Cloud Firestore 執行個體) 共用位置依附元件，您可以在建立專案時或設定共用此位置依附元件的其他服務時，設定這些資源的位置。

  5. 選取 Cloud Firestore Security Rules 的起始模式：

    測試模式

    適合用來開始使用行動和網路用戶端程式庫，但允許任何人讀取及覆寫您的資料。測試完成後，請務必查看「保護資料」一節。

    如要開始使用網頁、Apple 平台或 Android SDK，請選取測試模式。

    鎖定模式

    拒絕行動和網路用戶端的所有讀寫要求。 通過驗證的應用程式伺服器 (C#、Go、Java、Node.js、PHP、Python 或 Ruby) 仍可存取資料庫。

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

    初始設定的 Cloud Firestore Security Rules 會套用至預設Cloud Firestore資料庫。如果為專案建立多個資料庫，可以為每個資料庫部署 Cloud Firestore Security Rules。

  6. 點選「建立」。

啟用 Cloud Firestore 時，系統也會在 Cloud API 管理工具中啟用 API。

設定開發環境

將必要的依附元件和用戶端程式庫新增至應用程式。

Web

  1. 按照操作說明將 Firebase 新增至您的網頁應用程式。
  2. Cloud Firestore SDK 以 npm 套件的形式提供。
    npm install firebase@11.10.0 --save
     您需要匯入 Firebase 和 Cloud Firestore。 
    import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";

Web

  1. 按照操作說明將 Firebase 新增至您的網頁應用程式。
  2. 將 Firebase 和 Cloud Firestore 程式庫新增至應用程式： 
    <script src="https://www.gstatic.com/firebasejs/11.10.0/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/11.10.0/firebase-firestore-compat.js"></script>
     Cloud Firestore SDK 也提供 npm 套件。
    npm install firebase@11.10.0 --save
     您必須手動要求 Firebase 和 Cloud Firestore。 
    import firebase from "firebase/compat/app";
// Required for side-effects
import "firebase/firestore";
iOS+

按照操作說明將 Firebase 新增至 Apple 應用程式。

使用 Swift Package Manager 安裝及管理 Firebase 依附元件。

  1. 在 Xcode 中保持開啟應用程式專案，然後依序點選「File」>「Swift Packages」>「Add Package Dependency」。
  2. 系統提示時，請新增 Firebase Apple 平台 SDK 存放區：
    3.   https://github.com/firebase/firebase-ios-sdk
  3. 選擇 Firestore 程式庫。
  4. 完成後，Xcode 會自動開始在背景中解析並下載依附元件。
Android
  1. 按照操作說明將 Firebase 新增至 Android 應用程式。
  2. 使用 Firebase Android BoM，在模組 (應用程式層級) Gradle 檔案 (通常為 app/build.gradle.kts 或 app/build.gradle) 中，宣告 Android 適用的 Cloud Firestore 程式庫依附元件。
    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.16.0"))

    // 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:25.1.4")
}

    想尋找 Kotlin 專屬的程式庫模組嗎？自 2023 年 10 月發布版本起，Kotlin 和 Java 開發人員都可以依附於主要程式庫模組 (詳情請參閱這項計畫的常見問題)。

Dart

  1. 如果尚未完成，請在 Flutter 應用程式中設定及初始化 Firebase。
  2. 在 Flutter 專案的根目錄中，執行下列指令來安裝外掛程式：
    flutter pub add cloud_firestore
  3. 完成後，請重建 Flutter 應用程式： 
    flutter run
  4. 選用：加入預先編譯的架構，縮短 iOS 和 macOS 的建構時間。

    目前，iOS 版 Firestore SDK 依賴的程式碼可能需要 5 分鐘以上的時間，才能在 Xcode 中建構完成。如要大幅縮短建構時間，請在 Podfile 的 target 'Runner' do 區塊中加入這行程式碼，使用預先編譯的版本：

    target 'Runner' do
  use_frameworks!
  use_modular_headers!

  pod 'FirebaseFirestore',
    :git => 'https://github.com/invertase/firestore-ios-sdk-frameworks.git',
    :tag => 'IOS_SDK_VERSION'

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
  target 'RunnerTests' do
    inherit! :search_paths
  end
end

    將 IOS_SDK_VERSION 替換為 firebase_core 的 firebase_sdk_version.rb 檔案中指定的 Firebase iOS SDK 版本。如果未使用最新版 firebase_core，請在本地 Pub 套件快取 (通常是 ~/.pub-cache) 中尋找這個檔案。

    此外，請確認您已將 CocoaPods 升級至 1.9.1 以上版本：

    gem install cocoapods

    詳情請參閱 GitHub 上的問題。

Java
  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 依附元件。將以下內容加入模組 (應用程式層級) 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++ 專案」。
Unity
  1. 按照操作說明將 Firebase 新增至您的 Unity 專案。
  2. 使用 Unity 介面設定專案，縮減 Android 建構作業。

    3. 您必須縮減建構作業，才能避免收到 Error while merging dex archives 訊息。

    • 這個選項位於「Player Settings」>「Android」>「Publishing Settings」>「Minify」。
    • 不同版本的 Unity 可能會提供不同的選項，因此請參閱官方 Unity 說明文件和 Firebase Unity 建構偵錯指南。
    • 如果啟用縮減功能後，參照的方法數量仍超過限制，可以啟用 multidex：
      • 如果已啟用「Player Settings」下的「Custom Gradle Template」mainTemplate.gradle
      • 或者，如果您使用 Android Studio 建構匯出的專案，則為模組層級的 build.gradle 檔案。
Node.js
  1. 在應用程式中新增 Firebase Admin SDK： 
    npm install firebase-admin --save
  2. 請按照下列操作說明，在環境中以適當的憑證初始化 Cloud Firestore。
Go
  1. 在 Go 應用程式中新增 Firebase Admin SDK： 
    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. 在 .csproj 檔案中，將 Cloud Firestore C# 程式庫新增至應用程式： 
    <ItemGroup>
  <PackageReference Include="Google.Cloud.Firestore" Version="1.1.0-beta01" />
</ItemGroup>
  3. 請將以下內容新增到 Program.cs 檔案中： 
    using Google.Cloud.Firestore;
Ruby
  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. 在 Gemfile 中，將 Cloud Firestore Ruby 程式庫新增至應用程式：
    gem "google-cloud-firestore"
  3. 使用下列指令從 Gemfile 安裝依附元件： 
    bundle install

(選用) 使用 Firebase Local Emulator Suite 製作原型並進行測試

對於行動應用程式開發人員，在說明應用程式如何寫入及讀取 Cloud Firestore 之前，讓我們先介紹一組可用於原型設計和測試 Cloud Firestore 功能的工具： Firebase Local Emulator Suite。如果您正在嘗試不同的資料模型、調整安全性規則，或是尋找與後端互動時最經濟實惠的方式，那麼在不部署即時服務的情況下，於本機作業會是個好主意。

Cloud Firestore模擬器是 Local Emulator Suite 的一部分，可讓應用程式與模擬的資料庫內容和設定互動，以及選擇性地與模擬的專案資源 (函式、其他資料庫和安全性規則) 互動。

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

  1. 在應用程式的測試設定中加入一行程式碼，即可連線至模擬器。
  2. 從本機專案目錄的根目錄執行 firebase emulators:start。
  3. 照常使用Cloud Firestore平台 SDK，從應用程式的原型程式碼發出呼叫。

我們提供詳細的逐步操作說明，其中包含 Cloud Firestore 和 Cloud Functions。建議您也參閱 Local Emulator Suite 簡介。

初始化 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);


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

將 FIREBASE_CONFIGURATION 替換成網頁應用程式的firebaseConfig。

如要在裝置失去連線時保留資料，請參閱「啟用離線資料」說明文件。

Web

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。

如要在裝置失去連線時保留資料，請參閱「啟用離線資料」說明文件。

Swift
注意：這項產品不適用於 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

// 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;
Java
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 & admin」(IAM 與管理) >「Service accounts」(服務帳戶)。產生新的私密金鑰，並儲存 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 & admin」(IAM 與管理) >「Service accounts」(服務帳戶)。產生新的私密金鑰，並儲存 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 & admin」(IAM 與管理) >「Service accounts」(服務帳戶)。產生新的私密金鑰，並儲存 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 & admin」(IAM 與管理) >「Service accounts」(服務帳戶)。產生新的私密金鑰，並儲存 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
    Go
    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 & admin」(IAM 與管理) >「Service accounts」(服務帳戶)。產生新的私密金鑰，並儲存 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
    Unity
    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
    Ruby
    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

    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

    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
    Swift
    注意：這項產品不適用於 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)")
}
    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

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

    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
    Unity
    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
    Ruby
    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

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

    // 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
    Swift
    注意：這項產品不適用於 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)")
}
    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

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

    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
    Unity
    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
    Ruby
    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

    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

    db.collection("users").get().then((querySnapshot) => {
    querySnapshot.forEach((doc) => {
        console.log(`${doc.id} => ${doc.data()}`);
    });
});
    test.firestore.js
    Swift
    注意：這項產品不適用於 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)")
}
    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

    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
    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("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
    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

    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
    Unity
    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
    Ruby
    users_ref = firestore.col collection_path
users_ref.get do |user|
  puts "#{user.document_id} data: #{user.data}."
end
    quickstart.rb

    確保資料安全

    如果您使用網頁、Android 或 Apple 平台 SDK，請使用 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 資料。請參閱 App Check 說明文件。

    如果您使用其中一個伺服器 SDK，請使用身分與存取權管理 (IAM)，確保 Cloud Firestore 中的資料安全無虞。

    觀看教學影片

    如需開始使用 Cloud Firestore 行動版用戶端程式庫的詳細指引，請觀看下列其中一個影片教學課程：

    網頁
    iOS+
    Android

    如要觀看更多影片，請前往 Firebase YouTube 頻道。

    後續步驟

    深入瞭解下列主題：

    • 程式碼研究室：按照 Android、iOS 或網頁的程式碼研究室，瞭解如何在實際應用程式中使用 Cloud Firestore。
    • 資料模型：進一步瞭解 Cloud Firestore 中的資料結構，包括階層式資料和子集合。
    • 新增資料：進一步瞭解如何在 Cloud Firestore 中建立及更新資料。
    • 取得資料：進一步瞭解如何擷取資料。
    • 執行簡單和複合查詢：瞭解如何執行簡單和複合查詢。
    • 排序及限制查詢：瞭解如何排序及限制查詢傳回的資料。