Cloud Firestore 支援讀取和寫入資料的原子操作。在一組原子操作中，要麼所有操作都成功，要麼都不應用。 Cloud Firestore 中有兩種類型的原子操作：
透過交易更新數據
使用 Cloud Firestore 用戶端程式庫，您可以將多個操作分組到單一交易中。當您想要根據欄位的目前值或其他欄位的值更新欄位的值時，交易非常有用。
交易由任意數量的get()操作組成，後面跟著任意數量的寫入操作，例如set() 、 update()或delete() 。如果是同時編輯，Cloud Firestore 會再次執行整個事務。例如，如果事務讀取文檔並且另一個客戶端修改其中任何文檔，則 Cloud Firestore 會重試該事務。此功能可確保交易在最新且一致的資料上運作。
事務永遠不會部分應用寫入。所有寫入都在成功事務結束時執行。
使用交易時需要注意：
- 讀取操作必須在寫入操作之前進行。
- 如果並發編輯影響事務讀取的文檔，則呼叫事務（事務函數）的函數可能會執行多次。
- 事務函數不應直接修改應用程式狀態。
- 當客戶端離線時，交易將會失敗。
以下範例展示如何建立和運行事務：
Web modular API
import { runTransaction } from "firebase/firestore";
try {
await runTransaction(db, async (transaction) => {
const sfDoc = await transaction.get(sfDocRef);
if (!sfDoc.exists()) {
throw "Document does not exist!";
}
const newPopulation = sfDoc.data().population + 1;
transaction.update(sfDocRef, { population: newPopulation });
});
console.log("Transaction successfully committed!");
} catch (e) {
console.log("Transaction failed: ", e);
}Web namespaced API
// Create a reference to the SF doc.
var sfDocRef = db.collection("cities").doc("SF");
// Uncomment to initialize the doc.
// sfDocRef.set({ population: 0 });
return db.runTransaction((transaction) => {
// This code may get re-run multiple times if there are conflicts.
return transaction.get(sfDocRef).then((sfDoc) => {
if (!sfDoc.exists) {
throw "Document does not exist!";
}
// Add one person to the city population.
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
var newPopulation = sfDoc.data().population + 1;
transaction.update(sfDocRef, { population: newPopulation });
});
}).then(() => {
console.log("Transaction successfully committed!");
}).catch((error) => {
console.log("Transaction failed: ", error);
});迅速
注意：此產品不適用於 watchOS 和 App Clip 目標。
let sfReference = db.collection("cities").document("SF")
db.runTransaction({ (transaction, errorPointer) -> Any? in
let sfDocument: DocumentSnapshot
do {
try sfDocument = transaction.getDocument(sfReference)
} catch let fetchError as NSError {
errorPointer?.pointee = fetchError
return nil
}
guard let oldPopulation = sfDocument.data()?["population"] as? Int else {
let error = NSError(
domain: "AppErrorDomain",
code: -1,
userInfo: [
NSLocalizedDescriptionKey: "Unable to retrieve population from snapshot \(sfDocument)"
]
)
errorPointer?.pointee = error
return nil
}
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
transaction.updateData(["population": oldPopulation + 1], forDocument: sfReference)
return nil
}) { (object, error) in
if let error = error {
print("Transaction failed: \(error)")
} else {
print("Transaction successfully committed!")
}
}Objective-C
注意：此產品不適用於 watchOS 和 App Clip 目標。
FIRDocumentReference *sfReference =
[[self.db collectionWithPath:@"cities"] documentWithPath:@"SF"];
[self.db runTransactionWithBlock:^id (FIRTransaction *transaction, NSError **errorPointer) {
FIRDocumentSnapshot *sfDocument = [transaction getDocument:sfReference error:errorPointer];
if (*errorPointer != nil) { return nil; }
if (![sfDocument.data[@"population"] isKindOfClass:[NSNumber class]]) {
*errorPointer = [NSError errorWithDomain:@"AppErrorDomain" code:-1 userInfo:@{
NSLocalizedDescriptionKey: @"Unable to retreive population from snapshot"
}];
return nil;
}
NSInteger oldPopulation = [sfDocument.data[@"population"] integerValue];
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
[transaction updateData:@{ @"population": @(oldPopulation + 1) } forDocument:sfReference];
return nil;
} completion:^(id result, NSError *error) {
if (error != nil) {
NSLog(@"Transaction failed: %@", error);
} else {
NSLog(@"Transaction successfully committed!");
}
}];Kotlin+KTX
val sfDocRef = db.collection("cities").document("SF")
db.runTransaction { transaction ->
val snapshot = transaction.get(sfDocRef)
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
val newPopulation = snapshot.getDouble("population")!! + 1
transaction.update(sfDocRef, "population", newPopulation)
// Success
null
}.addOnSuccessListener { Log.d(TAG, "Transaction success!") }
.addOnFailureListener { e -> Log.w(TAG, "Transaction failure.", e) }Java
final DocumentReference sfDocRef = db.collection("cities").document("SF");
db.runTransaction(new Transaction.Function<Void>() {
@Override
public Void apply(@NonNull Transaction transaction) throws FirebaseFirestoreException {
DocumentSnapshot snapshot = transaction.get(sfDocRef);
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
double newPopulation = snapshot.getDouble("population") + 1;
transaction.update(sfDocRef, "population", newPopulation);
// Success
return null;
}
}).addOnSuccessListener(new OnSuccessListener<Void>() {
@Override
public void onSuccess(Void aVoid) {
Log.d(TAG, "Transaction success!");
}
})
.addOnFailureListener(new OnFailureListener() {
@Override
public void onFailure(@NonNull Exception e) {
Log.w(TAG, "Transaction failure.", e);
}
});Dart
final sfDocRef = db.collection("cities").doc("SF");
db.runTransaction((transaction) async {
final snapshot = await transaction.get(sfDocRef);
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
final newPopulation = snapshot.get("population") + 1;
transaction.update(sfDocRef, {"population": newPopulation});
}).then(
(value) => print("DocumentSnapshot successfully updated!"),
onError: (e) => print("Error updating document $e"),
);爪哇
Python
Python
C++
DocumentReference sf_doc_ref = db->Collection("cities").Document("SF");
db->RunTransaction([sf_doc_ref](Transaction& transaction,
std::string& out_error_message) -> Error {
Error error = Error::kErrorOk;
DocumentSnapshot snapshot =
transaction.Get(sf_doc_ref, &error, &out_error_message);
// Note: this could be done without a transaction by updating the
// population using FieldValue::Increment().
std::int64_t new_population =
snapshot.Get("population").integer_value() + 1;
transaction.Update(
sf_doc_ref,
{{"population", FieldValue::Integer(new_population)}});
return Error::kErrorOk;
}).OnCompletion([](const Future<void>& future) {
if (future.error() == Error::kErrorOk) {
std::cout << "Transaction success!" << std::endl;
} else {
std::cout << "Transaction failure: " << future.error_message() << std::endl;
}
});Node.js
去
PHP
統一
DocumentReference cityRef = db.Collection("cities").Document("SF");
db.RunTransactionAsync(transaction =>
{
return transaction.GetSnapshotAsync(cityRef).ContinueWith((snapshotTask) =>
{
DocumentSnapshot snapshot = snapshotTask.Result;
long newPopulation = snapshot.GetValue<long>("Population") + 1;
Dictionary<string, object> updates = new Dictionary<string, object>
{
{ "Population", newPopulation}
};
transaction.Update(cityRef, updates);
});
});C＃
紅寶石
從交易中傳遞訊息
不要修改事務函數內的應用程式狀態。這樣做會引入並發問題，因為事務函數可以運行多次，並且不能保證在 UI 執行緒上運行。相反，從交易功能中傳遞您需要的資訊。以下範例基於前面的範例，展示如何從事務中傳遞訊息：
Web modular API
import { doc, runTransaction } from "firebase/firestore";
// Create a reference to the SF doc.
const sfDocRef = doc(db, "cities", "SF");
try {
const newPopulation = await runTransaction(db, async (transaction) => {
const sfDoc = await transaction.get(sfDocRef);
if (!sfDoc.exists()) {
throw "Document does not exist!";
}
const newPop = sfDoc.data().population + 1;
if (newPop <= 1000000) {
transaction.update(sfDocRef, { population: newPop });
return newPop;
} else {
return Promise.reject("Sorry! Population is too big");
}
});
console.log("Population increased to ", newPopulation);
} catch (e) {
// This will be a "population is too big" error.
console.error(e);
}Web namespaced API
// Create a reference to the SF doc.
var sfDocRef = db.collection("cities").doc("SF");
db.runTransaction((transaction) => {
return transaction.get(sfDocRef).then((sfDoc) => {
if (!sfDoc.exists) {
throw "Document does not exist!";
}
var newPopulation = sfDoc.data().population + 1;
if (newPopulation <= 1000000) {
transaction.update(sfDocRef, { population: newPopulation });
return newPopulation;
} else {
return Promise.reject("Sorry! Population is too big.");
}
});
}).then((newPopulation) => {
console.log("Population increased to ", newPopulation);
}).catch((err) => {
// This will be an "population is too big" error.
console.error(err);
});迅速
注意：此產品不適用於 watchOS 和 App Clip 目標。
let sfReference = db.collection("cities").document("SF")
db.runTransaction({ (transaction, errorPointer) -> Any? in
let sfDocument: DocumentSnapshot
do {
try sfDocument = transaction.getDocument(sfReference)
} catch let fetchError as NSError {
errorPointer?.pointee = fetchError
return nil
}
guard let oldPopulation = sfDocument.data()?["population"] as? Int else {
let error = NSError(
domain: "AppErrorDomain",
code: -1,
userInfo: [
NSLocalizedDescriptionKey: "Unable to retrieve population from snapshot \(sfDocument)"
]
)
errorPointer?.pointee = error
return nil
}
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
let newPopulation = oldPopulation + 1
guard newPopulation <= 1000000 else {
let error = NSError(
domain: "AppErrorDomain",
code: -2,
userInfo: [NSLocalizedDescriptionKey: "Population \(newPopulation) too big"]
)
errorPointer?.pointee = error
return nil
}
transaction.updateData(["population": newPopulation], forDocument: sfReference)
return newPopulation
}) { (object, error) in
if let error = error {
print("Error updating population: \(error)")
} else {
print("Population increased to \(object!)")
}
}Objective-C
注意：此產品不適用於 watchOS 和 App Clip 目標。
FIRDocumentReference *sfReference =
[[self.db collectionWithPath:@"cities"] documentWithPath:@"SF"];
[self.db runTransactionWithBlock:^id (FIRTransaction *transaction, NSError **errorPointer) {
FIRDocumentSnapshot *sfDocument = [transaction getDocument:sfReference error:errorPointer];
if (*errorPointer != nil) { return nil; }
if (![sfDocument.data[@"population"] isKindOfClass:[NSNumber class]]) {
*errorPointer = [NSError errorWithDomain:@"AppErrorDomain" code:-1 userInfo:@{
NSLocalizedDescriptionKey: @"Unable to retreive population from snapshot"
}];
return nil;
}
NSInteger population = [sfDocument.data[@"population"] integerValue];
population++;
if (population >= 1000000) {
*errorPointer = [NSError errorWithDomain:@"AppErrorDomain" code:-2 userInfo:@{
NSLocalizedDescriptionKey: @"Population too big"
}];
return @(population);
}
[transaction updateData:@{ @"population": @(population) } forDocument:sfReference];
return nil;
} completion:^(id result, NSError *error) {
if (error != nil) {
NSLog(@"Transaction failed: %@", error);
} else {
NSLog(@"Population increased to %@", result);
}
}];Kotlin+KTX
val sfDocRef = db.collection("cities").document("SF")
db.runTransaction { transaction ->
val snapshot = transaction.get(sfDocRef)
val newPopulation = snapshot.getDouble("population")!! + 1
if (newPopulation <= 1000000) {
transaction.update(sfDocRef, "population", newPopulation)
newPopulation
} else {
throw FirebaseFirestoreException(
"Population too high",
FirebaseFirestoreException.Code.ABORTED,
)
}
}.addOnSuccessListener { result ->
Log.d(TAG, "Transaction success: $result")
}.addOnFailureListener { e ->
Log.w(TAG, "Transaction failure.", e)
}Java
final DocumentReference sfDocRef = db.collection("cities").document("SF");
db.runTransaction(new Transaction.Function<Double>() {
@Override
public Double apply(@NonNull Transaction transaction) throws FirebaseFirestoreException {
DocumentSnapshot snapshot = transaction.get(sfDocRef);
double newPopulation = snapshot.getDouble("population") + 1;
if (newPopulation <= 1000000) {
transaction.update(sfDocRef, "population", newPopulation);
return newPopulation;
} else {
throw new FirebaseFirestoreException("Population too high",
FirebaseFirestoreException.Code.ABORTED);
}
}
}).addOnSuccessListener(new OnSuccessListener<Double>() {
@Override
public void onSuccess(Double result) {
Log.d(TAG, "Transaction success: " + result);
}
})
.addOnFailureListener(new OnFailureListener() {
@Override
public void onFailure(@NonNull Exception e) {
Log.w(TAG, "Transaction failure.", e);
}
});Dart
final sfDocRef = db.collection("cities").doc("SF");
db.runTransaction((transaction) {
return transaction.get(sfDocRef).then((sfDoc) {
final newPopulation = sfDoc.get("population") + 1;
transaction.update(sfDocRef, {"population": newPopulation});
return newPopulation;
});
}).then(
(newPopulation) => print("Population increased to $newPopulation"),
onError: (e) => print("Error updating document $e"),
);爪哇
Python
Python
C++
// This is not yet supported.
Node.js
去
PHP
統一
DocumentReference cityRef = db.Collection("cities").Document("SF");
db.RunTransactionAsync(transaction =>
{
return transaction.GetSnapshotAsync(cityRef).ContinueWith((task) =>
{
long newPopulation = task.Result.GetValue<long>("Population") + 1;
if (newPopulation <= 1000000)
{
Dictionary<string, object> updates = new Dictionary<string, object>
{
{ "Population", newPopulation}
};
transaction.Update(cityRef, updates);
return true;
}
else
{
return false;
}
});
}).ContinueWith((transactionResultTask) =>
{
if (transactionResultTask.Result)
{
Console.WriteLine("Population updated successfully.");
}
else
{
Console.WriteLine("Sorry! Population is too big.");
}
});C＃
紅寶石
交易失敗
交易可能因以下原因失敗：
- 該事務包含寫入操作之後的讀取操作。讀取操作必須始終在任何寫入操作之前進行。
- 事務讀取在事務外部修改的文檔。在這種情況下，事務會自動再次運作。事務重試有限次數。
該交易超出了 10 MiB 的最大請求大小。
事務大小取決於交易修改的文件和索引條目的大小。對於刪除操作，這包括目標文件的大小以及響應於該操作而刪除的索引條目的大小。
失敗的交易會傳回錯誤並且不會寫入任何內容到資料庫。您不需要回滾事務； Cloud Firestore 會自動執行此操作。
大量寫入
如果您不需要讀取操作集中的任何文檔，則可以將多個寫入操作作為包含set() 、 update()或delete()操作的任意組合的單一批次執行。一批寫入以原子方式完成，並且可以寫入多個文件。以下範例展示如何建置和提交寫入批次：
Web modular API
import { writeBatch, doc } from "firebase/firestore";
// Get a new write batch
const batch = writeBatch(db);
// Set the value of 'NYC'
const nycRef = doc(db, "cities", "NYC");
batch.set(nycRef, {name: "New York City"});
// Update the population of 'SF'
const sfRef = doc(db, "cities", "SF");
batch.update(sfRef, {"population": 1000000});
// Delete the city 'LA'
const laRef = doc(db, "cities", "LA");
batch.delete(laRef);
// Commit the batch
await batch.commit();Web namespaced API
// Get a new write batch
var batch = db.batch();
// Set the value of 'NYC'
var nycRef = db.collection("cities").doc("NYC");
batch.set(nycRef, {name: "New York City"});
// Update the population of 'SF'
var sfRef = db.collection("cities").doc("SF");
batch.update(sfRef, {"population": 1000000});
// Delete the city 'LA'
var laRef = db.collection("cities").doc("LA");
batch.delete(laRef);
// Commit the batch
batch.commit().then(() => {
// ...
});迅速
注意：此產品不適用於 watchOS 和 App Clip 目標。
// Get new write batch
let batch = db.batch()
// Set the value of 'NYC'
let nycRef = db.collection("cities").document("NYC")
batch.setData([:], forDocument: nycRef)
// Update the population of 'SF'
let sfRef = db.collection("cities").document("SF")
batch.updateData(["population": 1000000 ], forDocument: sfRef)
// Delete the city 'LA'
let laRef = db.collection("cities").document("LA")
batch.deleteDocument(laRef)
// Commit the batch
batch.commit() { err in
if let err = err {
print("Error writing batch \(err)")
} else {
print("Batch write succeeded.")
}
}Objective-C
注意：此產品不適用於 watchOS 和 App Clip 目標。
// Get new write batch
FIRWriteBatch *batch = [self.db batch];
// Set the value of 'NYC'
FIRDocumentReference *nycRef =
[[self.db collectionWithPath:@"cities"] documentWithPath:@"NYC"];
[batch setData:@{} forDocument:nycRef];
// Update the population of 'SF'
FIRDocumentReference *sfRef =
[[self.db collectionWithPath:@"cities"] documentWithPath:@"SF"];
[batch updateData:@{ @"population": @1000000 } forDocument:sfRef];
// Delete the city 'LA'
FIRDocumentReference *laRef =
[[self.db collectionWithPath:@"cities"] documentWithPath:@"LA"];
[batch deleteDocument:laRef];
// Commit the batch
[batch commitWithCompletion:^(NSError * _Nullable error) {
if (error != nil) {
NSLog(@"Error writing batch %@", error);
} else {
NSLog(@"Batch write succeeded.");
}
}];Kotlin+KTX
val nycRef = db.collection("cities").document("NYC")
val sfRef = db.collection("cities").document("SF")
val laRef = db.collection("cities").document("LA")
// Get a new write batch and commit all write operations
db.runBatch { batch ->
// Set the value of 'NYC'
batch.set(nycRef, City())
// Update the population of 'SF'
batch.update(sfRef, "population", 1000000L)
// Delete the city 'LA'
batch.delete(laRef)
}.addOnCompleteListener {
// ...
}Java
// Get a new write batch
WriteBatch batch = db.batch();
// Set the value of 'NYC'
DocumentReference nycRef = db.collection("cities").document("NYC");
batch.set(nycRef, new City());
// Update the population of 'SF'
DocumentReference sfRef = db.collection("cities").document("SF");
batch.update(sfRef, "population", 1000000L);
// Delete the city 'LA'
DocumentReference laRef = db.collection("cities").document("LA");
batch.delete(laRef);
// Commit the batch
batch.commit().addOnCompleteListener(new OnCompleteListener<Void>() {
@Override
public void onComplete(@NonNull Task<Void> task) {
// ...
}
});Dart
// Get a new write batch
final batch = db.batch();
// Set the value of 'NYC'
var nycRef = db.collection("cities").doc("NYC");
batch.set(nycRef, {"name": "New York City"});
// Update the population of 'SF'
var sfRef = db.collection("cities").doc("SF");
batch.update(sfRef, {"population": 1000000});
// Delete the city 'LA'
var laRef = db.collection("cities").doc("LA");
batch.delete(laRef);
// Commit the batch
batch.commit().then((_) {
// ...
});爪哇
Python
Python
C++
// Get a new write batch
WriteBatch batch = db->batch();
// Set the value of 'NYC'
DocumentReference nyc_ref = db->Collection("cities").Document("NYC");
batch.Set(nyc_ref, {});
// Update the population of 'SF'
DocumentReference sf_ref = db->Collection("cities").Document("SF");
batch.Update(sf_ref, {{"population", FieldValue::Integer(1000000)}});
// Delete the city 'LA'
DocumentReference la_ref = db->Collection("cities").Document("LA");
batch.Delete(la_ref);
// Commit the batch
batch.Commit().OnCompletion([](const Future<void>& future) {
if (future.error() == Error::kErrorOk) {
std::cout << "Write batch success!" << std::endl;
} else {
std::cout << "Write batch failure: " << future.error_message() << std::endl;
}
});Node.js
去
PHP
統一
WriteBatch batch = db.StartBatch();
// Set the data for NYC
DocumentReference nycRef = db.Collection("cities").Document("NYC");
Dictionary<string, object> nycData = new Dictionary<string, object>
{
{ "name", "New York City" }
};
batch.Set(nycRef, nycData);
// Update the population for SF
DocumentReference sfRef = db.Collection("cities").Document("SF");
Dictionary<string, object> updates = new Dictionary<string, object>
{
{ "Population", 1000000}
};
batch.Update(sfRef, updates);
// Delete LA
DocumentReference laRef = db.Collection("cities").Document("LA");
batch.Delete(laRef);
// Commit the batch
batch.CommitAsync();C＃
紅寶石
批次寫入最多可以包含 500 個操作。批次中的每個操作均單獨計入您的 Cloud Firestore 使用量。
與事務一樣，批量寫入是原子的。與事務不同，批次寫入不需要確保讀取的文件保持不變，這會減少失敗情況。它們不會受到重試或因重試過多而失敗的影響。即使使用者的裝置處於離線狀態，也會執行批次寫入。
原子操作的資料驗證
對於行動/Web 用戶端程式庫，您可以使用Cloud Firestore 安全規則驗證資料。您可以確保相關文件始終以原子方式更新，並且始終作為交易或批次寫入的一部分。使用getAfter()安全規則函數可以在一組操作完成之後、Cloud Firestore 提交作業之前存取和驗證文件的狀態。
例如，假設cities範例的資料庫也包含countries集合。每個country文件都使用last_updated欄位來追蹤與該國家/地區相關的任何城市的上次更新時間。以下安全規則要求對city文件的更新也必須自動更新相關國家/地區的last_updated欄位：
service cloud.firestore {
match /databases/{database}/documents {
// If you update a city doc, you must also
// update the related country's last_updated field.
match /cities/{city} {
allow write: if request.auth != null &&
getAfter(
/databases/$(database)/documents/countries/$(request.resource.data.country)
).data.last_updated == request.time;
}
match /countries/{country} {
allow write: if request.auth != null;
}
}
}
安全規則限制
在交易或批次寫入的安全性規則中，除了批次中每個文件操作的正常 10 次呼叫限制之外，整個原子操作的文件存取呼叫限制為 20 次。
例如，請考慮聊天應用程式的以下規則：
service cloud.firestore {
match /databases/{db}/documents {
function prefix() {
return /databases/{db}/documents;
}
match /chatroom/{roomId} {
allow read, write: if request.auth != null && roomId in get(/$(prefix())/users/$(request.auth.uid)).data.chats
|| exists(/$(prefix())/admins/$(request.auth.uid));
}
match /users/{userId} {
allow read, write: if request.auth != null && request.auth.uid == userId
|| exists(/$(prefix())/admins/$(request.auth.uid));
}
match /admins/{userId} {
allow read, write: if request.auth != null && exists(/$(prefix())/admins/$(request.auth.uid));
}
}
}
下面的片段說明了用於一些資料存取模式的文件存取呼叫的數量：
// 0 document access calls used, because the rules evaluation short-circuits
// before the exists() call is invoked.
db.collection('user').doc('myuid').get(...);
// 1 document access call used. The maximum total allowed for this call
// is 10, because it is a single document request.
db.collection('chatroom').doc('mygroup').get(...);
// Initializing a write batch...
var batch = db.batch();
// 2 document access calls used, 10 allowed.
var group1Ref = db.collection("chatroom").doc("group1");
batch.set(group1Ref, {msg: "Hello, from Admin!"});
// 1 document access call used, 10 allowed.
var newUserRef = db.collection("users").doc("newuser");
batch.update(newUserRef, {"lastSignedIn": new Date()});
// 1 document access call used, 10 allowed.
var removedAdminRef = db.collection("admin").doc("otheruser");
batch.delete(removedAdminRef);
// The batch used a total of 2 + 1 + 1 = 4 document access calls, out of a total
// 20 allowed.
batch.commit();
有關如何解決由大量寫入和批量寫入引起的延遲問題、由於重疊事務爭用而導致的錯誤以及其他問題的更多信息，請考慮查看故障排除頁面。