本快速入門會說明如何設定 Cloud Firestore、新增資料,然後在 Firebase 控制台中查看剛新增的資料。
建立 Cloud Firestore 資料庫
如果您尚未建立 Firebase 專案,請按照下列步驟操作:在 Firebase 控制台中,按一下「Add project」,然後按照畫面上的指示建立 Firebase 專案,或將 Firebase 服務新增至現有的 Google Cloud 專案。
在 Firebase 控制台中開啟專案。在左側面板中,展開「Build」,然後選取「Firestore database」。
按一下 [Create database] (建立資料庫)。
選取資料庫的位置。
如果無法選取位置,就表示專案「預設 Google Cloud 資源的位置」已設定完成。部分專案資源 (例如預設 Cloud Firestore 執行個體) 會共用相同的位置依附元件,您可以在建立專案時或設定其他共用此位置依附元件的服務時,設定這些資源的位置。
為 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。
按一下「建立」。
啟用 Cloud Firestore 時,也會在 Cloud API Manager 中啟用 API。
設定開發環境
將必要的依附元件和用戶端程式庫新增至應用程式。
Web
- 按照操作說明將 Firebase 新增至網頁應用程式。
- 將 Firebase 和 Cloud Firestore 程式庫新增至應用程式:
Cloud Firestore SDK 也可做為 npm 套件使用。<script src="https://www.gstatic.com/firebasejs/11.0.1/firebase-app-compat.js"></script> <script src="https://www.gstatic.com/firebasejs/11.0.1/firebase-firestore-compat.js"></script>
您必須手動要求 Firebase 和 Cloud Firestore。npm install firebase@11.0.1 --save
import firebase from "firebase/compat/app"; // Required for side-effects import "firebase/firestore";
Web
- 請按照操作說明將 Firebase 新增至您的網路應用程式。
-
Cloud Firestore SDK 可做為 npm 套件。
必須匯入 Firebase 和 Cloud Firestore。npm install firebase@11.0.1 --save
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.5.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:25.1.1") }
想尋找 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
- 將 Firebase Admin SDK 新增至 Python 應用程式:
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
- 將 Firebase Admin SDK 新增至 Go 應用程式:
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"
- 在實際環境中,如果您使用與 Cloud Firestore 相同的專案,在 App Engine 或 Compute Engine 上執行應用程式,就不需要進行驗證。否則請設定服務帳戶。
-
如要從開發環境進行驗證,請將
- 安裝並啟用 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 相同的專案進行驗證,無需進行驗證。否則請設定服務帳戶。
-
如要從開發環境進行驗證,請將
-
將 Cloud Firestore C# 程式庫新增至
.csproj
檔案中的應用程式:<ItemGroup> <PackageReference Include="Google.Cloud.Firestore" Version="1.1.0-beta01" /> </ItemGroup>
-
請將以下內容新增到
Program.cs
檔案中:using Google.Cloud.Firestore;
Ruby
-
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 上執行應用程式,就不需要進行驗證。否則請設定服務帳戶。
-
如要從開發環境進行驗證,請將
-
將 Cloud Firestore Ruby 程式庫新增至
Gemfile
中的應用程式:gem "google-cloud-firestore"
-
使用以下方式從
Gemfile
安裝依附元件:bundle install
(選用) 使用 Firebase Local Emulator Suite 設計原型並進行測試
行動應用程式開發人員,在討論應用程式如何寫入及讀取 Cloud Firestore 之前,讓我們先介紹一組工具,可用於製作原型並測試 Cloud Firestore 功能:Firebase Local Emulator Suite。如果您想嘗試不同的資料模型、最佳化安全性規則,或是尋找與後端互動最具成本效益的方式,不妨考慮在本機作業,而無需部署實際服務。
Cloud Firestore 模擬器是 Local Emulator Suite 的一部分,可讓應用程式與模擬資料庫內容和設定互動,以及視需要與模擬的專案資源 (函式、其他資料庫和安全性規則) 互動。
使用 Cloud Firestore 模擬器只需幾個步驟:
- 在應用程式的測試設定中加入一行程式碼,以便連線至模擬器。
- 在本機專案目錄的根目錄中執行
firebase emulators:start
。 - 照常使用 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
。
如要在裝置連線中斷時保留資料,請參閱「啟用離線資料」說明文件。
快速
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 與管理」>「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」。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 與管理」>「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()
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 與管理」>「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();
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 與管理」>「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 用戶端程式庫。
Unity
using Firebase.Firestore; using Firebase.Extensions;
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
C#
C#
如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端,請參閱 Cloud Firestore 用戶端程式庫。
Ruby
新增資料
Cloud Firestore 會將資料儲存在文件中,而文件則儲存在集合中。Cloud Firestore 會在您第一次將資料新增至文件時,隱含地建立集合和文件。您不必明確建立集合或文件。
使用以下範例程式碼建立新的集合和文件。
Web
import { collection, addDoc } from "firebase/firestore"; try { const docRef = await addDoc(collection(db, "users"), { first: "Ada", last: "Lovelace", born: 1815 }); console.log("Document written with ID: ", docRef.id); } catch (e) { console.error("Error adding document: ", e); }
Web
db.collection("users").add({ first: "Ada", last: "Lovelace", born: 1815 }) .then((docRef) => { console.log("Document written with ID: ", docRef.id); }) .catch((error) => { console.error("Error adding document: ", error); });
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#
Ruby
接著,將另一份文件新增至 users
集合。請注意,本文件中含有未出現在第一份文件的鍵/值組合 (中間名稱)。集合中的文件可以包含不同的資訊組合。
Web
// Add a second document with a generated ID. import { addDoc, collection } from "firebase/firestore"; try { const docRef = await addDoc(collection(db, "users"), { first: "Alan", middle: "Mathison", last: "Turing", born: 1912 }); console.log("Document written with ID: ", docRef.id); } catch (e) { console.error("Error adding document: ", e); }
Web
// Add a second document with a generated ID. db.collection("users").add({ first: "Alan", middle: "Mathison", last: "Turing", born: 1912 }) .then((docRef) => { console.log("Document written with ID: ", docRef.id); }) .catch((error) => { console.error("Error adding document: ", error); });
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#
Ruby
讀取資料
使用 Firebase 控制台中的資料檢視器,快速確認您已將資料新增至 Cloud Firestore。
您也可以使用「get」方法擷取整個集合。
Web
import { collection, getDocs } from "firebase/firestore"; const querySnapshot = await getDocs(collection(db, "users")); querySnapshot.forEach((doc) => { console.log(`${doc.id} => ${doc.data()}`); });
Web
db.collection("users").get().then((querySnapshot) => { querySnapshot.forEach((doc) => { console.log(`${doc.id} => ${doc.data()}`); }); });
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#
Ruby
確保資料安全
如果您使用的是 Web、Android 或 Apple 平台 SDK,請使用 Firebase 驗證和 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 中建立及更新資料。
- 取得資料:進一步瞭解如何擷取資料。
- 執行簡單和複合查詢:瞭解如何執行簡單和複合查詢。
- 排序及限制查詢 瞭解如何排序及限制查詢傳回的資料。