本快速入門導覽課程說明如何設定 Cloud Firestore、新增資料,以及查看剛才在 Firebase 控制台新增的資料。
建立 Cloud Firestore 資料庫
如果您尚未建立 Firebase 專案,請先建立 Firebase 專案:在 Firebase 控制台按一下「Add project」(新增專案),然後按照畫面上的指示建立 Firebase 專案,或將 Firebase 服務新增至現有的 GCP 專案。
前往 Firebase 控制台的 Cloud Firestore 部分。系統會提示您選取現有的 Firebase 專案。按照資料庫建立工作流程操作。
選取 Cloud Firestore 安全性規則的啟動模式:
- 測試模式
很適合開始使用行動和網路用戶端程式庫,但允許任何人讀取及覆寫您的資料。測試完畢後,請務必查看「保護資料」一節。
如要開始使用網站、Apple 平台或 Android SDK,請選取測試模式。
- 鎖定模式
拒絕來自行動裝置和網路用戶端的所有讀寫作業。 經過驗證的應用程式伺服器 (C#、Go、Java、Node.js、PHP、Python 或 Ruby) 仍可存取您的資料庫。
如要開始使用 C#、Go、Java、Node.js、PHP、Python 或 Ruby 伺服器用戶端程式庫,請選取鎖定模式。
初始的 Cloud Firestore 安全性規則會套用至預設的 Cloud Firestore 資料庫。如果為專案建立多個資料庫 您可以為每個資料庫部署 Cloud Firestore 安全性規則
選取資料庫的位置。
此位置設定是您專案的預設 Google Cloud Platform (GCP) 資源位置。請注意,這個位置將用於專案中需要位置設定的 GCP 服務,具體而言,此位置是指預設的 Cloud Storage 值區,以及 App Engine 應用程式 (如果您使用 Cloud Scheduler)。
如果無法選取位置,表示專案已有預設的 GCP 資源位置。可在建立專案期間或在設定需要位置設定的其他服務時設定。
點選「完成」。
啟用 Cloud Firestore 時,也會在 Cloud API Manager 中啟用 API。
設定開發環境
將必要的依附元件和用戶端程式庫新增至應用程式。
網路命名空間 API
- 按照操作說明將 Firebase 新增至網頁應用程式。
- 將 Firebase 和 Cloud Firestore 程式庫新增至應用程式:
<script src="https://www.gstatic.com/firebasejs/10.12.2/firebase-app-compat.js"></script> <script src="https://www.gstatic.com/firebasejs/10.12.2/firebase-firestore-compat.js"></script>
此外,您也可以使用 Cloud Firestore SDK 做為 npm 套件。npm install firebase@10.12.2 --save
您必須手動同時使用 Firebase 和 Cloud Firestore。import firebase from "firebase/compat/app"; // Required for side-effects import "firebase/firestore";
網頁模組 API
- 按照操作說明將 Firebase 新增至網頁應用程式。
-
Cloud Firestore SDK 是以 npm 套件的形式提供。
npm install firebase@10.12.2 --save
您必須匯入 Firebase 和 Cloud Firestore。import { initializeApp } from "firebase/app"; import { getFirestore } from "firebase/firestore";
iOS+
按照操作說明將 Firebase 新增至 Apple 應用程式。
使用 Swift Package Manager 安裝及管理 Firebase 依附元件。
- 在 Xcode 中保持開啟應用程式專案,然後依序前往「File」>「Swift Packages」>「Add Package Dependency」。
- 在系統提示時,新增 Firebase Apple 平台 SDK 存放區:
- 選擇 Firestore 程式庫。
- 完成後,Xcode 會自動開始在背景解析並下載依附元件。
https://github.com/firebase/firebase-ios-sdk
Android
- 按照操作說明將 Firebase 新增至您的 Android 應用程式。
- 使用 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.1.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 程式庫版本。
(替代做法) 宣告 Firebase 程式庫依附元件,「不要」使用 BoM
如果選擇不使用 Firebase BoM,就必須在依附元件行中指定各個 Firebase 程式庫版本。
請注意,如果您在應用程式中使用多個 Firebase 程式庫,強烈建議您使用 BoM 來管理程式庫版本,以確保所有版本都相容。
dependencies { // Declare the dependency for the Cloud Firestore library // When NOT using the BoM, you must specify versions in Firebase library dependencies implementation("com.google.firebase:firebase-firestore:25.0.0") }
在尋找 Kotlin 專用的程式庫模組嗎?從 2023 年 10 月版本開始,Kotlin 和 Java 開發人員都能使用主要的程式庫模組 (詳情請參閱這項計畫的常見問題)。
Dart
- 如果您尚未在 Flutter 應用程式中設定及初始化 Firebase,請先完成這項操作。
- 在 Flutter 專案的根目錄中執行下列指令,安裝外掛程式:
flutter pub add cloud_firestore
- 完成後,請重新建構 Flutter 應用程式:
flutter run
- 選用:加入預先編譯的架構,縮短 iOS 和 macOS 的建構時間。
目前,適用於 iOS 的 Firestore SDK 取決於程式碼,在 Xcode 中建構最多可能需要 5 分鐘。如要大幅縮短建構時間,您可以使用預先編譯的版本,方法是在 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
- 將 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>
-
使用 Gradle:
- 請按照下列操作說明,使用環境中的適當憑證初始化 Cloud Firestore。
Python
- 在 Python 應用程式中加入 Firebase Admin SDK:
pip install --upgrade firebase-admin
- 請按照下列操作說明,使用環境中的適當憑證初始化 Cloud Firestore。
C++
- 按照操作說明將 Firebase 新增至您的 C++ 專案。
- 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}")
- 如要設定電腦整合,請參閱「將 Firebase 新增至 C++ 專案」一文。
Unity
- 按照操作說明將 Firebase 新增至您的 Unity 專案。
- 使用 Unity 介面設定專案,壓縮 Android 版本。
- 依序點選「Player Settings」>「Android」>「Publish Settings」>「Minify」,即可找到這個選項。
- 選項可能因 Unity 版本而異,請參閱官方的 Unity 說明文件和 Firebase Unity 建構偵錯指南。
-
啟用壓縮功能後,如果參照的方法數量仍超出限制,則可選擇在以下位置啟用
multidex
:-
如果已啟用「Player Settings」下的「Custom Gradle Template」就會傳回
mainTemplate.gradle
-
或模組層級的
build.gradle
檔案 (如果您使用 Android Studio 建構匯出的專案)。
-
如果已啟用「Player Settings」下的「Custom Gradle Template」就會傳回
您必須壓縮版本,以避免顯示 Error while merging dex archives
訊息。
Node.js
-
將 Firebase Admin SDK 新增至應用程式:
npm install firebase-admin --save
- 請按照下列操作說明,使用環境中的適當憑證初始化 Cloud Firestore。
Go
- 在 Go 應用程式中加入 Firebase Admin SDK:
go get firebase.google.com/go
- 請按照下列操作說明,使用環境中的適當憑證初始化 Cloud Firestore。
PHP
-
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"
- 如果您是在 App Engine 或 Compute Engine 上執行應用程式,並使用與 Cloud Firestore 相同的專案進行驗證,就不需要進行驗證。否則請設定服務帳戶。
-
如要從開發環境進行驗證,請將
- 為 PHP 安裝並啟用 gRPC 擴充功能,您將需要使用用戶端程式庫。
-
將 Cloud Firestore PHP 程式庫新增至應用程式:
composer require google/cloud-firestore
C#
-
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"
- 如果您是在 App Engine 或 Compute Engine 上執行應用程式,並使用與 Cloud Firestore 相同的專案進行驗證,就不需要進行驗證。否則請設定服務帳戶。
-
如要從開發環境進行驗證,請將
-
在
.csproj
檔案中,將 Cloud Firestore C# 程式庫新增至應用程式:<ItemGroup> <PackageReference Include="Google.Cloud.Firestore" Version="1.1.0-beta01" /> </ItemGroup>
-
請將以下內容新增到
Program.cs
檔案中:using Google.Cloud.Firestore;
小茹
-
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"
- 如果您是在 App Engine 或 Compute Engine 上執行應用程式,並使用與 Cloud Firestore 相同的專案進行驗證,就不需要進行驗證。否則請設定服務帳戶。
-
如要從開發環境進行驗證,請將
-
在
Gemfile
中將 Cloud Firestore Ruby 程式庫新增至應用程式:gem "google-cloud-firestore"
-
使用:
bundle install
從Gemfile
安裝依附元件
(選用) 使用 Firebase 本機模擬器套件設計原型並進行測試
針對行動開發人員,在討論您的應用程式如何寫入 Cloud Firestore 及讀取資料前,我們先介紹一組工具,可用來建立原型及測試 Cloud Firestore 功能:Firebase 本機模擬器套件。如果您正在試用不同的資料模型、讓安全性規則發揮最佳效能,或努力尋找最符合成本效益的方式與後端互動,那麼即使不部署即時服務,也能在本機工作。
Cloud Firestore 模擬器是本機模擬器套件的一部分,可讓應用程式與模擬資料庫內容和設定互動,並可選擇模擬專案資源 (函式、其他資料庫和安全性規則)。
使用 Cloud Firestore 模擬器只需要幾個步驟:
- 將一行程式碼新增至應用程式的測試設定,即可與模擬器連線。
- 從本機專案目錄的根目錄中執行
firebase emulators:start
。 - 照常使用 Cloud Firestore 平台 SDK 從應用程式的原型程式碼發出呼叫。
如需詳細的有關 Cloud Firestore 和 Cloud Functions 的逐步操作說明,請參閱。建議您也參閱「本機模擬器套件簡介」一文。
初始化 Cloud Firestore
初始化 Cloud Firestore 執行個體:
網頁模組 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
。
如要在裝置連線中斷時保留資料,請參閱「啟用離線資料」說明文件。
網路命名空間 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
。
如要在裝置連線中斷時保留資料,請參閱「啟用離線資料」說明文件。
快速
import FirebaseCore import FirebaseFirestore
FirebaseApp.configure() let db = Firestore.firestore()
Objective-C
@import FirebaseCore; @import FirebaseFirestore; // Use Firebase library to configure APIs [FIRApp configure];
FIRFirestore *defaultFirestore = [FIRFirestore firestore];
Kotlin+KTX
// Access a Cloud Firestore instance from your Activity
val db = Firebase.firestore
Java
// Access a Cloud Firestore instance from your Activity
FirebaseFirestore db = FirebaseFirestore.getInstance();
Dart
db = FirebaseFirestore.instance;
Java
Cloud Firestore SDK 的初始化方式會因環境而異。最常見的做法如下。如需完整參考資料,請參閱「初始化 Admin SDK」。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」。import firebase_admin from firebase_admin import firestore # Application Default credentials are automatically created. app = firebase_admin.initialize_app() db = firestore.client()
現有的應用程式預設憑證也可用來初始化 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()
如要在自己的伺服器上使用 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()
Python
Cloud Firestore SDK 的初始化方式會因環境而異。最常見的做法如下。如需完整參考資料,請參閱「初始化 Admin SDK」。import firebase_admin from firebase_admin import firestore_async # Application Default credentials are automatically created. app = firebase_admin.initialize_app() db = firestore_async.client()
現有的應用程式預設憑證也可用來初始化 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()
如要在自己的伺服器上使用 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()
C++
// Make sure the call to `Create()` happens some time before you call Firestore::GetInstance(). App::Create(); Firestore* db = Firestore::GetInstance();
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();
-
在 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();
-
在自己的伺服器上初始化
如要在自己的伺服器 (或任何其他 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();
Go
Cloud Firestore SDK 的初始化方式會因環境而異。最常見的做法如下。如需完整參考資料,請參閱「初始化 Admin SDK」。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 用戶端程式庫。
Unity
using Firebase.Firestore; using Firebase.Extensions;
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
C#
C#
如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端,請參閱 Cloud Firestore 用戶端程式庫。
小茹
新增資料
Cloud Firestore 將資料儲存在文件中,而文件會儲存在「集合」中。在您第一次將資料新增至文件時 Cloud Firestore 會以隱含形式建立集合和文件您不必明確建立集合或文件。
使用以下程式碼範例建立新集合和文件。
網頁模組 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); }
網路命名空間 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); });
Swift
// Add a new document with a generated ID do { let ref = try await db.collection("users").addDocument(data: [ "first": "Ada", "last": "Lovelace", "born": 1815 ]) print("Document added with ID: \(ref.documentID)") } catch { print("Error adding document: \(error)") }
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); } }];
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) }
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); } });
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}'));
Java
Python
Python
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; } });
Node.js
Go
PHP
PHP
如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端,請參閱 Cloud Firestore 用戶端程式庫。
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#
小茹
現在,請將另一份文件新增至 users
集合。請注意,本文件中的鍵/值組合 (中間名稱) 並未出現在第一份文件中。集合中的文件可以包含不同資訊組合。
網頁模組 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); }
網路命名空間 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); });
Swift
// Add a second document with a generated ID. do { let ref = try await db.collection("users").addDocument(data: [ "first": "Alan", "middle": "Mathison", "last": "Turing", "born": 1912 ]) print("Document added with ID: \(ref.documentID)") } catch { print("Error adding document: \(error)") }
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); } }];
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) }
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); } });
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}'));
Java
Python
Python
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; } });
Node.js
Go
PHP
PHP
如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端,請參閱 Cloud Firestore 用戶端程式庫。
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#
小茹
讀取資料
請使用 Firebase 主控台中的資料檢視器,快速確認您已將資料新增至 Cloud Firestore。
您也可以使用「get」方法擷取整個集合。
網頁模組 API
import { collection, getDocs } from "firebase/firestore"; const querySnapshot = await getDocs(collection(db, "users")); querySnapshot.forEach((doc) => { console.log(`${doc.id} => ${doc.data()}`); });
網路命名空間 API
db.collection("users").get().then((querySnapshot) => { querySnapshot.forEach((doc) => { console.log(`${doc.id} => ${doc.data()}`); }); });
Swift
do { let snapshot = try await db.collection("users").getDocuments() for document in snapshot.documents { print("\(document.documentID) => \(document.data())") } } catch { print("Error getting documents: \(error)") }
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); } } }];
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) }
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()); } } });
Dart
await db.collection("users").get().then((event) { for (var doc in event.docs) { print("${doc.id} => ${doc.data()}"); } });
Java
Python
users_ref = db.collection("users") docs = users_ref.stream() for doc in docs: print(f"{doc.id} => {doc.to_dict()}")
Python
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; } });
Node.js
Go
PHP
PHP
如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端,請參閱 Cloud Firestore 用戶端程式庫。
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#
小茹
確保資料安全
如果您使用網頁、Android 或 Apple 平台 SDK,請使用 Firebase 驗證和 Cloud Firestore 安全性規則來保護 Cloud Firestore 中的資料。
我們一開始會提供幾項基本規則組合。您可以在控制台的「Rules」分頁中修改安全性規則。
需要驗證
// Allow read/write access to a document keyed by the user's UID
service cloud.firestore {
match /databases/{database}/documents {
match /users/{uid} {
allow read, write: if request.auth != null && request.auth.uid == uid;
}
}
}
鎖定模式
// Deny read/write access to all users under any conditions
service cloud.firestore {
match /databases/{database}/documents {
match /{document=**} {
allow read, write: if false;
}
}
}
在您將網頁、Android 或 iOS 應用程式部署至實際工作環境之前,也請先採取相關步驟,確保只有您的應用程式用戶端可以存取 Cloud Firestore 資料。請參閱 App Check 說明文件。
如果您使用其中一個伺服器 SDK,請使用 Identity and Access Management (IAM) 保護 Cloud Firestore 中的資料。
觀看教學影片
如需開始使用 Cloud Firestore 行動用戶端程式庫的詳細指南,請觀看以下的影片教學課程:
網站
iOS+
Android
您可以在 Firebase YouTube 頻道中查看更多影片。
後續步驟
透過以下主題加深您的知識:
- 程式碼研究室:請按照 Android、iOS 或網頁版的程式碼研究室,瞭解如何在實際應用程式中使用 Cloud Firestore。
- 資料模型 - 進一步瞭解 Cloud Firestore 中的資料如何結構化,包括階層式資料和子集合。
- 新增資料:進一步瞭解如何在 Cloud Firestore 中建立及更新資料。
- 取得資料 - 進一步瞭解如何擷取資料。
- 執行簡單和複合查詢:瞭解如何執行簡單和複合查詢。
- 排序及限制查詢:瞭解如何排序及限制查詢傳回的資料。