透過 Cloud Firestore 取得資料

您可以透過三種方式擷取儲存在 Cloud Firestore 中的資料。任一 這些方法可用於文件、文件集合或 查詢結果:

  • 呼叫方法來取得資料一次。
  • 設定用於接收資料變更事件的事件監聽器。
  • 透過以下方式從外部來源載入大量 Firestore 快照資料: 資料組合。詳情請參閱套裝組合說明文件 詳細資料。

設定事件監聽器時,Cloud Firestore 會將初始值傳送給事件監聽器 ,然後每次文件變更時再建立另一個快照。

事前準備

請參閱開始使用 Cloud Firestore, 建立 Cloud Firestore 資料庫

初始化 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()
Objective-C
注意:這項產品不適用於 watchOS 和 App Clip 目標。
@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
  • 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,請使用 服務帳戶

    前往 IAM 與管理員 >服務帳戶 也能前往 Google Cloud 控制台產生新的私密金鑰並儲存 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()

    現有的應用程式預設憑證也可用來初始化 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,請使用 服務帳戶

    前往 IAM 與管理員 >服務帳戶 也能前往 Google Cloud 控制台產生新的私密金鑰並儲存 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
  • 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()

    現有的應用程式預設憑證也可用來初始化 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,請使用 服務帳戶

    前往 IAM 與管理員 >服務帳戶 也能前往 Google Cloud 控制台產生新的私密金鑰並儲存 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, 請使用服務帳戶。 前往 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
  • 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,請使用 服務帳戶

    前往 IAM 與管理員 >服務帳戶 也能前往 Google Cloud 控制台產生新的私密金鑰並儲存 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);
        }
    }
    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);
    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."

    資料範例

    一開始請先撰寫一些城市相關資料,以便我們瞭解 朗讀:

    Web

    import { collection, doc, setDoc } from "firebase/firestore"; 
    
    const citiesRef = collection(db, "cities");
    
    await setDoc(doc(citiesRef, "SF"), {
        name: "San Francisco", state: "CA", country: "USA",
        capital: false, population: 860000,
        regions: ["west_coast", "norcal"] });
    await setDoc(doc(citiesRef, "LA"), {
        name: "Los Angeles", state: "CA", country: "USA",
        capital: false, population: 3900000,
        regions: ["west_coast", "socal"] });
    await setDoc(doc(citiesRef, "DC"), {
        name: "Washington, D.C.", state: null, country: "USA",
        capital: true, population: 680000,
        regions: ["east_coast"] });
    await setDoc(doc(citiesRef, "TOK"), {
        name: "Tokyo", state: null, country: "Japan",
        capital: true, population: 9000000,
        regions: ["kanto", "honshu"] });
    await setDoc(doc(citiesRef, "BJ"), {
        name: "Beijing", state: null, country: "China",
        capital: true, population: 21500000,
        regions: ["jingjinji", "hebei"] });

    Web

    var citiesRef = db.collection("cities");
    
    citiesRef.doc("SF").set({
        name: "San Francisco", state: "CA", country: "USA",
        capital: false, population: 860000,
        regions: ["west_coast", "norcal"] });
    citiesRef.doc("LA").set({
        name: "Los Angeles", state: "CA", country: "USA",
        capital: false, population: 3900000,
        regions: ["west_coast", "socal"] });
    citiesRef.doc("DC").set({
        name: "Washington, D.C.", state: null, country: "USA",
        capital: true, population: 680000,
        regions: ["east_coast"] });
    citiesRef.doc("TOK").set({
        name: "Tokyo", state: null, country: "Japan",
        capital: true, population: 9000000,
        regions: ["kanto", "honshu"] });
    citiesRef.doc("BJ").set({
        name: "Beijing", state: null, country: "China",
        capital: true, population: 21500000,
        regions: ["jingjinji", "hebei"] });
    Swift
    注意:這項產品不適用於 watchOS 和 App Clip 目標。
    let citiesRef = db.collection("cities")
    
    citiesRef.document("SF").setData([
      "name": "San Francisco",
      "state": "CA",
      "country": "USA",
      "capital": false,
      "population": 860000,
      "regions": ["west_coast", "norcal"]
    ])
    citiesRef.document("LA").setData([
      "name": "Los Angeles",
      "state": "CA",
      "country": "USA",
      "capital": false,
      "population": 3900000,
      "regions": ["west_coast", "socal"]
    ])
    citiesRef.document("DC").setData([
      "name": "Washington D.C.",
      "country": "USA",
      "capital": true,
      "population": 680000,
      "regions": ["east_coast"]
    ])
    citiesRef.document("TOK").setData([
      "name": "Tokyo",
      "country": "Japan",
      "capital": true,
      "population": 9000000,
      "regions": ["kanto", "honshu"]
    ])
    citiesRef.document("BJ").setData([
      "name": "Beijing",
      "country": "China",
      "capital": true,
      "population": 21500000,
      "regions": ["jingjinji", "hebei"]
    ])
    Objective-C
    注意:這項產品不適用於 watchOS 和 App Clip 目標。
    FIRCollectionReference *citiesRef = [self.db collectionWithPath:@"cities"];
    [[citiesRef documentWithPath:@"SF"] setData:@{
      @"name": @"San Francisco",
      @"state": @"CA",
      @"country": @"USA",
      @"capital": @(NO),
      @"population": @860000,
      @"regions": @[@"west_coast", @"norcal"]
    }];
    [[citiesRef documentWithPath:@"LA"] setData:@{
      @"name": @"Los Angeles",
      @"state": @"CA",
      @"country": @"USA",
      @"capital": @(NO),
      @"population": @3900000,
      @"regions": @[@"west_coast", @"socal"]
    }];
    [[citiesRef documentWithPath:@"DC"] setData:@{
      @"name": @"Washington D.C.",
      @"country": @"USA",
      @"capital": @(YES),
      @"population": @680000,
      @"regions": @[@"east_coast"]
    }];
    [[citiesRef documentWithPath:@"TOK"] setData:@{
      @"name": @"Tokyo",
      @"country": @"Japan",
      @"capital": @(YES),
      @"population": @9000000,
      @"regions": @[@"kanto", @"honshu"]
    }];
    [[citiesRef documentWithPath:@"BJ"] setData:@{
      @"name": @"Beijing",
      @"country": @"China",
      @"capital": @(YES),
      @"population": @21500000,
      @"regions": @[@"jingjinji", @"hebei"]
    }];

    Kotlin+KTX

    val cities = db.collection("cities")
    
    val data1 = hashMapOf(
        "name" to "San Francisco",
        "state" to "CA",
        "country" to "USA",
        "capital" to false,
        "population" to 860000,
        "regions" to listOf("west_coast", "norcal"),
    )
    cities.document("SF").set(data1)
    
    val data2 = hashMapOf(
        "name" to "Los Angeles",
        "state" to "CA",
        "country" to "USA",
        "capital" to false,
        "population" to 3900000,
        "regions" to listOf("west_coast", "socal"),
    )
    cities.document("LA").set(data2)
    
    val data3 = hashMapOf(
        "name" to "Washington D.C.",
        "state" to null,
        "country" to "USA",
        "capital" to true,
        "population" to 680000,
        "regions" to listOf("east_coast"),
    )
    cities.document("DC").set(data3)
    
    val data4 = hashMapOf(
        "name" to "Tokyo",
        "state" to null,
        "country" to "Japan",
        "capital" to true,
        "population" to 9000000,
        "regions" to listOf("kanto", "honshu"),
    )
    cities.document("TOK").set(data4)
    
    val data5 = hashMapOf(
        "name" to "Beijing",
        "state" to null,
        "country" to "China",
        "capital" to true,
        "population" to 21500000,
        "regions" to listOf("jingjinji", "hebei"),
    )
    cities.document("BJ").set(data5)

    Java

    CollectionReference cities = db.collection("cities");
    
    Map<String, Object> data1 = new HashMap<>();
    data1.put("name", "San Francisco");
    data1.put("state", "CA");
    data1.put("country", "USA");
    data1.put("capital", false);
    data1.put("population", 860000);
    data1.put("regions", Arrays.asList("west_coast", "norcal"));
    cities.document("SF").set(data1);
    
    Map<String, Object> data2 = new HashMap<>();
    data2.put("name", "Los Angeles");
    data2.put("state", "CA");
    data2.put("country", "USA");
    data2.put("capital", false);
    data2.put("population", 3900000);
    data2.put("regions", Arrays.asList("west_coast", "socal"));
    cities.document("LA").set(data2);
    
    Map<String, Object> data3 = new HashMap<>();
    data3.put("name", "Washington D.C.");
    data3.put("state", null);
    data3.put("country", "USA");
    data3.put("capital", true);
    data3.put("population", 680000);
    data3.put("regions", Arrays.asList("east_coast"));
    cities.document("DC").set(data3);
    
    Map<String, Object> data4 = new HashMap<>();
    data4.put("name", "Tokyo");
    data4.put("state", null);
    data4.put("country", "Japan");
    data4.put("capital", true);
    data4.put("population", 9000000);
    data4.put("regions", Arrays.asList("kanto", "honshu"));
    cities.document("TOK").set(data4);
    
    Map<String, Object> data5 = new HashMap<>();
    data5.put("name", "Beijing");
    data5.put("state", null);
    data5.put("country", "China");
    data5.put("capital", true);
    data5.put("population", 21500000);
    data5.put("regions", Arrays.asList("jingjinji", "hebei"));
    cities.document("BJ").set(data5);

    Dart

    final cities = db.collection("cities");
    final data1 = <String, dynamic>{
      "name": "San Francisco",
      "state": "CA",
      "country": "USA",
      "capital": false,
      "population": 860000,
      "regions": ["west_coast", "norcal"]
    };
    cities.doc("SF").set(data1);
    
    final data2 = <String, dynamic>{
      "name": "Los Angeles",
      "state": "CA",
      "country": "USA",
      "capital": false,
      "population": 3900000,
      "regions": ["west_coast", "socal"],
    };
    cities.doc("LA").set(data2);
    
    final data3 = <String, dynamic>{
      "name": "Washington D.C.",
      "state": null,
      "country": "USA",
      "capital": true,
      "population": 680000,
      "regions": ["east_coast"]
    };
    cities.doc("DC").set(data3);
    
    final data4 = <String, dynamic>{
      "name": "Tokyo",
      "state": null,
      "country": "Japan",
      "capital": true,
      "population": 9000000,
      "regions": ["kanto", "honshu"]
    };
    cities.doc("TOK").set(data4);
    
    final data5 = <String, dynamic>{
      "name": "Beijing",
      "state": null,
      "country": "China",
      "capital": true,
      "population": 21500000,
      "regions": ["jingjinji", "hebei"],
    };
    cities.doc("BJ").set(data5);
    Java
    CollectionReference cities = db.collection("cities");
    List<ApiFuture<WriteResult>> futures = new ArrayList<>();
    futures.add(
        cities
            .document("SF")
            .set(
                new City(
                    "San Francisco",
                    "CA",
                    "USA",
                    false,
                    860000L,
                    Arrays.asList("west_coast", "norcal"))));
    futures.add(
        cities
            .document("LA")
            .set(
                new City(
                    "Los Angeles",
                    "CA",
                    "USA",
                    false,
                    3900000L,
                    Arrays.asList("west_coast", "socal"))));
    futures.add(
        cities
            .document("DC")
            .set(
                new City(
                    "Washington D.C.", null, "USA", true, 680000L, Arrays.asList("east_coast"))));
    futures.add(
        cities
            .document("TOK")
            .set(
                new City(
                    "Tokyo", null, "Japan", true, 9000000L, Arrays.asList("kanto", "honshu"))));
    futures.add(
        cities
            .document("BJ")
            .set(
                new City(
                    "Beijing",
                    null,
                    "China",
                    true,
                    21500000L,
                    Arrays.asList("jingjinji", "hebei"))));
    // (optional) block on operation
    ApiFutures.allAsList(futures).get();
    Python
    class City:
        def __init__(self, name, state, country, capital=False, population=0, regions=[]):
            self.name = name
            self.state = state
            self.country = country
            self.capital = capital
            self.population = population
            self.regions = regions
    
        @staticmethod
        def from_dict(source):
            # ...
    
        def to_dict(self):
            # ...
    
        def __repr__(self):
            return f"City(\
                    name={self.name}, \
                    country={self.country}, \
                    population={self.population}, \
                    capital={self.capital}, \
                    regions={self.regions}\
                )"
    cities_ref = db.collection("cities")
    cities_ref.document("BJ").set(
        City("Beijing", None, "China", True, 21500000, ["hebei"]).to_dict()
    )
    cities_ref.document("SF").set(
        City(
            "San Francisco", "CA", "USA", False, 860000, ["west_coast", "norcal"]
        ).to_dict()
    )
    cities_ref.document("LA").set(
        City(
            "Los Angeles", "CA", "USA", False, 3900000, ["west_coast", "socal"]
        ).to_dict()
    )
    cities_ref.document("DC").set(
        City("Washington D.C.", None, "USA", True, 680000, ["east_coast"]).to_dict()
    )
    cities_ref.document("TOK").set(
        City("Tokyo", None, "Japan", True, 9000000, ["kanto", "honshu"]).to_dict()
    )

    Python

    cities_ref = db.collection("cities")
    await cities_ref.document("BJ").set(
        City("Beijing", None, "China", True, 21500000, ["hebei"]).to_dict()
    )
    await cities_ref.document("SF").set(
        City(
            "San Francisco", "CA", "USA", False, 860000, ["west_coast", "norcal"]
        ).to_dict()
    )
    await cities_ref.document("LA").set(
        City(
            "Los Angeles", "CA", "USA", False, 3900000, ["west_coast", "socal"]
        ).to_dict()
    )
    await cities_ref.document("DC").set(
        City("Washington D.C.", None, "USA", True, 680000, ["east_coast"]).to_dict()
    )
    await cities_ref.document("TOK").set(
        City("Tokyo", None, "Japan", True, 9000000, ["kanto", "honshu"]).to_dict()
    )
    C++
    CollectionReference cities = db->Collection("cities");
    
    cities.Document("SF").Set({
        {"name", FieldValue::String("San Francisco")},
        {"state", FieldValue::String("CA")},
        {"country", FieldValue::String("USA")},
        {"capital", FieldValue::Boolean(false)},
        {"population", FieldValue::Integer(860000)},
        {"regions", FieldValue::Array({FieldValue::String("west_coast"),
                                       FieldValue::String("norcal")})},
    });
    
    cities.Document("LA").Set({
        {"name", FieldValue::String("Los Angeles")},
        {"state", FieldValue::String("CA")},
        {"country", FieldValue::String("USA")},
        {"capital", FieldValue::Boolean(false)},
        {"population", FieldValue::Integer(3900000)},
        {"regions", FieldValue::Array({FieldValue::String("west_coast"),
                                       FieldValue::String("socal")})},
    });
    
    cities.Document("DC").Set({
        {"name", FieldValue::String("Washington D.C.")},
        {"state", FieldValue::Null()},
        {"country", FieldValue::String("USA")},
        {"capital", FieldValue::Boolean(true)},
        {"population", FieldValue::Integer(680000)},
        {"regions",
         FieldValue::Array({FieldValue::String("east_coast")})},
    });
    
    cities.Document("TOK").Set({
        {"name", FieldValue::String("Tokyo")},
        {"state", FieldValue::Null()},
        {"country", FieldValue::String("Japan")},
        {"capital", FieldValue::Boolean(true)},
        {"population", FieldValue::Integer(9000000)},
        {"regions", FieldValue::Array({FieldValue::String("kanto"),
                                       FieldValue::String("honshu")})},
    });
    
    cities.Document("BJ").Set({
        {"name", FieldValue::String("Beijing")},
        {"state", FieldValue::Null()},
        {"country", FieldValue::String("China")},
        {"capital", FieldValue::Boolean(true)},
        {"population", FieldValue::Integer(21500000)},
        {"regions", FieldValue::Array({FieldValue::String("jingjinji"),
                                       FieldValue::String("hebei")})},
    });
    Node.js
    const citiesRef = db.collection('cities');
    
    await citiesRef.doc('SF').set({
      name: 'San Francisco', state: 'CA', country: 'USA',
      capital: false, population: 860000
    });
    await citiesRef.doc('LA').set({
      name: 'Los Angeles', state: 'CA', country: 'USA',
      capital: false, population: 3900000
    });
    await citiesRef.doc('DC').set({
      name: 'Washington, D.C.', state: null, country: 'USA',
      capital: true, population: 680000
    });
    await citiesRef.doc('TOK').set({
      name: 'Tokyo', state: null, country: 'Japan',
      capital: true, population: 9000000
    });
    await citiesRef.doc('BJ').set({
      name: 'Beijing', state: null, country: 'China',
      capital: true, population: 21500000
    });
    Go
    
    import (
    	"context"
    
    	"cloud.google.com/go/firestore"
    )
    
    func prepareRetrieve(ctx context.Context, client *firestore.Client) error {
    	cities := []struct {
    		id string
    		c  City
    	}{
    		{id: "SF", c: City{Name: "San Francisco", State: "CA", Country: "USA", Capital: false, Population: 860000}},
    		{id: "LA", c: City{Name: "Los Angeles", State: "CA", Country: "USA", Capital: false, Population: 3900000}},
    		{id: "DC", c: City{Name: "Washington D.C.", Country: "USA", Capital: true, Population: 680000}},
    		{id: "TOK", c: City{Name: "Tokyo", Country: "Japan", Capital: true, Population: 9000000}},
    		{id: "BJ", c: City{Name: "Beijing", Country: "China", Capital: true, Population: 21500000}},
    	}
    	for _, c := range cities {
    		_, err := client.Collection("cities").Doc(c.id).Set(ctx, c.c)
    		if err != nil {
    			return err
    		}
    	}
    	return nil
    }
    
    PHP

    PHP

    如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端,請參閱 Cloud Firestore 用戶端程式庫

    $citiesRef = $db->collection('samples/php/cities');
    $citiesRef->document('SF')->set([
        'name' => 'San Francisco',
        'state' => 'CA',
        'country' => 'USA',
        'capital' => false,
        'population' => 860000,
        'density' => 18000,
    ]);
    $citiesRef->document('LA')->set([
        'name' => 'Los Angeles',
        'state' => 'CA',
        'country' => 'USA',
        'capital' => false,
        'population' => 3900000,
        'density' => 8000,
    ]);
    $citiesRef->document('DC')->set([
        'name' => 'Washington D.C.',
        'state' => null,
        'country' => 'USA',
        'capital' => true,
        'population' => 680000,
        'density' => 11000,
    ]);
    $citiesRef->document('TOK')->set([
        'name' => 'Tokyo',
        'state' => null,
        'country' => 'Japan',
        'capital' => true,
        'population' => 9000000,
        'density' => 16000,
    
    ]);
    $citiesRef->document('BJ')->set([
        'name' => 'Beijing',
        'state' => null,
        'country' => 'China',
        'capital' => true,
        'population' => 21500000,
        'density' => 3500,
    ]);
    printf('Added example cities data to the cities collection.' . PHP_EOL);
    Unity
    CollectionReference citiesRef = db.Collection("cities");
    citiesRef.Document("SF").SetAsync(new Dictionary<string, object>(){
            { "Name", "San Francisco" },
            { "State", "CA" },
            { "Country", "USA" },
            { "Capital", false },
            { "Population", 860000 }
        }).ContinueWithOnMainThread(task =>
            citiesRef.Document("LA").SetAsync(new Dictionary<string, object>(){
                { "Name", "Los Angeles" },
                { "State", "CA" },
                { "Country", "USA" },
                { "Capital", false },
                { "Population", 3900000 }
            })
    ).ContinueWithOnMainThread(task =>
        citiesRef.Document("DC").SetAsync(new Dictionary<string, object>(){
                { "Name", "Washington D.C." },
                { "State", null },
                { "Country", "USA" },
                { "Capital", true },
                { "Population", 680000 }
        })
    ).ContinueWithOnMainThread(task =>
        citiesRef.Document("TOK").SetAsync(new Dictionary<string, object>(){
                { "Name", "Tokyo" },
                { "State", null },
                { "Country", "Japan" },
                { "Capital", true },
                { "Population", 9000000 }
        })
    ).ContinueWithOnMainThread(task =>
        citiesRef.Document("BJ").SetAsync(new Dictionary<string, object>(){
                { "Name", "Beijing" },
                { "State", null },
                { "Country", "China" },
                { "Capital", true },
                { "Population", 21500000 }
        })
    );
    C#
    CollectionReference citiesRef = db.Collection("cities");
    await citiesRef.Document("SF").SetAsync(new Dictionary<string, object>(){
        { "Name", "San Francisco" },
        { "State", "CA" },
        { "Country", "USA" },
        { "Capital", false },
        { "Population", 860000 }
    });
    await citiesRef.Document("LA").SetAsync(new Dictionary<string, object>(){
        { "Name", "Los Angeles" },
        { "State", "CA" },
        { "Country", "USA" },
        { "Capital", false },
        { "Population", 3900000 }
    });
    await citiesRef.Document("DC").SetAsync(new Dictionary<string, object>(){
        { "Name", "Washington D.C." },
        { "State", null },
        { "Country", "USA" },
        { "Capital", true },
        { "Population", 680000 }
    });
    await citiesRef.Document("TOK").SetAsync(new Dictionary<string, object>(){
        { "Name", "Tokyo" },
        { "State", null },
        { "Country", "Japan" },
        { "Capital", true },
        { "Population", 9000000 }
    });
    await citiesRef.Document("BJ").SetAsync(new Dictionary<string, object>(){
        { "Name", "Beijing" },
        { "State", null },
        { "Country", "China" },
        { "Capital", true },
        { "Population", 21500000 }
    });
    Console.WriteLine("Added example cities data to the cities collection.");
    Ruby
    cities_ref = firestore.col collection_path
    cities_ref.doc("SF").set(
      {
        name:       "San Francisco",
        state:      "CA",
        country:    "USA",
        capital:    false,
        population: 860_000
      }
    )
    cities_ref.doc("LA").set(
      {
        name:       "Los Angeles",
        state:      "CA",
        country:    "USA",
        capital:    false,
        population: 3_900_000
      }
    )
    cities_ref.doc("DC").set(
      {
        name:       "Washington D.C.",
        state:      nil,
        country:    "USA",
        capital:    true,
        population: 680_000
      }
    )
    cities_ref.doc("TOK").set(
      {
        name:       "Tokyo",
        state:      nil,
        country:    "Japan",
        capital:    true,
        population: 9_000_000
      }
    )
    cities_ref.doc("BJ").set(
      {
        name:       "Beijing",
        state:      nil,
        country:    "China",
        capital:    true,
        population: 21_500_000
      }
    )

    取得文件

    以下範例說明如何擷取單一文件的內容 使用 get()

    Web

    import { doc, getDoc } from "firebase/firestore";
    
    const docRef = doc(db, "cities", "SF");
    const docSnap = await getDoc(docRef);
    
    if (docSnap.exists()) {
      console.log("Document data:", docSnap.data());
    } else {
      // docSnap.data() will be undefined in this case
      console.log("No such document!");
    }

    Web

    var docRef = db.collection("cities").doc("SF");
    
    docRef.get().then((doc) => {
        if (doc.exists) {
            console.log("Document data:", doc.data());
        } else {
            // doc.data() will be undefined in this case
            console.log("No such document!");
        }
    }).catch((error) => {
        console.log("Error getting document:", error);
    });
    Swift
    注意:這項產品不適用於 watchOS 和 App Clip 目標。
    let docRef = db.collection("cities").document("SF")
    
    do {
      let document = try await docRef.getDocument()
      if document.exists {
        let dataDescription = document.data().map(String.init(describing:)) ?? "nil"
        print("Document data: \(dataDescription)")
      } else {
        print("Document does not exist")
      }
    } catch {
      print("Error getting document: \(error)")
    }
    Objective-C
    注意:這項產品不適用於 watchOS 和 App Clip 目標。
    FIRDocumentReference *docRef =
        [[self.db collectionWithPath:@"cities"] documentWithPath:@"SF"];
    [docRef getDocumentWithCompletion:^(FIRDocumentSnapshot *snapshot, NSError *error) {
      if (snapshot.exists) {
        // Document data may be nil if the document exists but has no keys or values.
        NSLog(@"Document data: %@", snapshot.data);
      } else {
        NSLog(@"Document does not exist");
      }
    }];

    Kotlin+KTX

    val docRef = db.collection("cities").document("SF")
    docRef.get()
        .addOnSuccessListener { document ->
            if (document != null) {
                Log.d(TAG, "DocumentSnapshot data: ${document.data}")
            } else {
                Log.d(TAG, "No such document")
            }
        }
        .addOnFailureListener { exception ->
            Log.d(TAG, "get failed with ", exception)
        }

    Java

    DocumentReference docRef = db.collection("cities").document("SF");
    docRef.get().addOnCompleteListener(new OnCompleteListener<DocumentSnapshot>() {
        @Override
        public void onComplete(@NonNull Task<DocumentSnapshot> task) {
            if (task.isSuccessful()) {
                DocumentSnapshot document = task.getResult();
                if (document.exists()) {
                    Log.d(TAG, "DocumentSnapshot data: " + document.getData());
                } else {
                    Log.d(TAG, "No such document");
                }
            } else {
                Log.d(TAG, "get failed with ", task.getException());
            }
        }
    });

    Dart

    final docRef = db.collection("cities").doc("SF");
    docRef.get().then(
      (DocumentSnapshot doc) {
        final data = doc.data() as Map<String, dynamic>;
        // ...
      },
      onError: (e) => print("Error getting document: $e"),
    );
    Java
    DocumentReference docRef = db.collection("cities").document("SF");
    // asynchronously retrieve the document
    ApiFuture<DocumentSnapshot> future = docRef.get();
    // ...
    // future.get() blocks on response
    DocumentSnapshot document = future.get();
    if (document.exists()) {
      System.out.println("Document data: " + document.getData());
    } else {
      System.out.println("No such document!");
    }
    Python
    doc_ref = db.collection("cities").document("SF")
    
    doc = doc_ref.get()
    if doc.exists:
        print(f"Document data: {doc.to_dict()}")
    else:
        print("No such document!")

    Python

    doc_ref = db.collection("cities").document("SF")
    
    doc = await doc_ref.get()
    if doc.exists:
        print(f"Document data: {doc.to_dict()}")
    else:
        print("No such document!")
    C++
    DocumentReference doc_ref = db->Collection("cities").Document("SF");
    doc_ref.Get().OnCompletion([](const Future<DocumentSnapshot>& future) {
      if (future.error() == Error::kErrorOk) {
        const DocumentSnapshot& document = *future.result();
        if (document.exists()) {
          std::cout << "DocumentSnapshot id: " << document.id() << std::endl;
        } else {
          std::cout << "no such document" << std::endl;
        }
      } else {
        std::cout << "Get failed with: " << future.error_message() << std::endl;
      }
    });
    Node.js
    const cityRef = db.collection('cities').doc('SF');
    const doc = await cityRef.get();
    if (!doc.exists) {
      console.log('No such document!');
    } else {
      console.log('Document data:', doc.data());
    }
    Go
    
    import (
    	"context"
    	"fmt"
    
    	"cloud.google.com/go/firestore"
    )
    
    func docAsMap(ctx context.Context, client *firestore.Client) (map[string]interface{}, error) {
    	dsnap, err := client.Collection("cities").Doc("SF").Get(ctx)
    	if err != nil {
    		return nil, err
    	}
    	m := dsnap.Data()
    	fmt.Printf("Document data: %#v\n", m)
    	return m, nil
    }
    
    PHP

    PHP

    如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端,請參閱 Cloud Firestore 用戶端程式庫

    $docRef = $db->collection('samples/php/cities')->document('SF');
    $snapshot = $docRef->snapshot();
    
    if ($snapshot->exists()) {
        printf('Document data:' . PHP_EOL);
        print_r($snapshot->data());
    } else {
        printf('Document %s does not exist!' . PHP_EOL, $snapshot->id());
    }
    Unity
    DocumentReference docRef = db.Collection("cities").Document("SF");
    docRef.GetSnapshotAsync().ContinueWithOnMainThread(task =>
    {
      DocumentSnapshot snapshot = task.Result;
      if (snapshot.Exists) {
        Debug.Log(String.Format("Document data for {0} document:", snapshot.Id));
        Dictionary<string, object> city = snapshot.ToDictionary();
        foreach (KeyValuePair<string, object> pair in city) {
          Debug.Log(String.Format("{0}: {1}", pair.Key, pair.Value));
        }
      } else {
        Debug.Log(String.Format("Document {0} does not exist!", snapshot.Id));
      }
    });
    C#
    DocumentReference docRef = db.Collection("cities").Document("SF");
    DocumentSnapshot snapshot = await docRef.GetSnapshotAsync();
    if (snapshot.Exists)
    {
        Console.WriteLine("Document data for {0} document:", snapshot.Id);
        Dictionary<string, object> city = snapshot.ToDictionary();
        foreach (KeyValuePair<string, object> pair in city)
        {
            Console.WriteLine("{0}: {1}", pair.Key, pair.Value);
        }
    }
    else
    {
        Console.WriteLine("Document {0} does not exist!", snapshot.Id);
    }
    Ruby
    doc_ref  = firestore.doc "#{collection_path}/SF"
    snapshot = doc_ref.get
    if snapshot.exists?
      puts "#{snapshot.document_id} data: #{snapshot.data}."
    else
      puts "Document #{snapshot.document_id} does not exist!"
    end

    來源選項

    針對支援離線功能的平台,您可以將 source 選項設為 get 呼叫如何使用離線快取

    根據預設,get 呼叫會嘗試擷取下列來源的最新文件快照: 資料庫。在支援離線功能的平台上,用戶端程式庫會使用 在無法連線或要求逾時的情況下,離線快取。

    您可以在 get() 呼叫中指定 source 選項以變更 預設行為您只能從資料庫擷取,並忽略 您也可以從離線快取中擷取。例如:

    Web

    import { doc, getDocFromCache } from "firebase/firestore";
    
    const docRef = doc(db, "cities", "SF");
    
    // Get a document, forcing the SDK to fetch from the offline cache.
    try {
      const doc = await getDocFromCache(docRef);
    
      // Document was found in the cache. If no cached document exists,
      // an error will be returned to the 'catch' block below.
      console.log("Cached document data:", doc.data());
    } catch (e) {
      console.log("Error getting cached document:", e);
    }

    Web

    var docRef = db.collection("cities").doc("SF");
    
    // Valid options for source are 'server', 'cache', or
    // 'default'. See https://firebase.google.com/docs/reference/js/v8/firebase.firestore.GetOptions
    // for more information.
    var getOptions = {
        source: 'cache'
    };
    
    // Get a document, forcing the SDK to fetch from the offline cache.
    docRef.get(getOptions).then((doc) => {
        // Document was found in the cache. If no cached document exists,
        // an error will be returned to the 'catch' block below.
        console.log("Cached document data:", doc.data());
    }).catch((error) => {
        console.log("Error getting cached document:", error);
    });
    Swift
    注意:這項產品不適用於 watchOS 和 App Clip 目標。
    let docRef = db.collection("cities").document("SF")
    
    do {
      // Force the SDK to fetch the document from the cache. Could also specify
      // FirestoreSource.server or FirestoreSource.default.
      let document = try await docRef.getDocument(source: .cache)
      if document.exists {
        let dataDescription = document.data().map(String.init(describing:)) ?? "nil"
        print("Cached document data: \(dataDescription)")
      } else {
        print("Document does not exist in cache")
      }
    } catch {
      print("Error getting document: \(error)")
    }
    Objective-C
    注意:這項產品不適用於 watchOS 和 App Clip 目標。
    FIRDocumentReference *docRef =
    [[self.db collectionWithPath:@"cities"] documentWithPath:@"SF"];
    
    // Force the SDK to fetch the document from the cache. Could also specify
    // FIRFirestoreSourceServer or FIRFirestoreSourceDefault.
    [docRef getDocumentWithSource:FIRFirestoreSourceCache
                       completion:^(FIRDocumentSnapshot *snapshot, NSError *error) {
      if (snapshot != NULL) {
        // The document data was found in the cache.
        NSLog(@"Cached document data: %@", snapshot.data);
      } else {
        // The document data was not found in the cache.
        NSLog(@"Document does not exist in cache: %@", error);
      }
    }];

    Kotlin+KTX

    val docRef = db.collection("cities").document("SF")
    
    // Source can be CACHE, SERVER, or DEFAULT.
    val source = Source.CACHE
    
    // Get the document, forcing the SDK to use the offline cache
    docRef.get(source).addOnCompleteListener { task ->
        if (task.isSuccessful) {
            // Document found in the offline cache
            val document = task.result
            Log.d(TAG, "Cached document data: ${document?.data}")
        } else {
            Log.d(TAG, "Cached get failed: ", task.exception)
        }
    }

    Java

    DocumentReference docRef = db.collection("cities").document("SF");
    
    // Source can be CACHE, SERVER, or DEFAULT.
    Source source = Source.CACHE;
    
    // Get the document, forcing the SDK to use the offline cache
    docRef.get(source).addOnCompleteListener(new OnCompleteListener<DocumentSnapshot>() {
        @Override
        public void onComplete(@NonNull Task<DocumentSnapshot> task) {
            if (task.isSuccessful()) {
                // Document found in the offline cache
                DocumentSnapshot document = task.getResult();
                Log.d(TAG, "Cached document data: " + document.getData());
            } else {
                Log.d(TAG, "Cached get failed: ", task.getException());
            }
        }
    });

    Dart

    final docRef = db.collection("cities").doc("SF");
    
    // Source can be CACHE, SERVER, or DEFAULT.
    const source = Source.cache;
    
    docRef.get(const GetOptions(source: source)).then(
          (res) => print("Successfully completed"),
          onError: (e) => print("Error completing: $e"),
        );
    Java

    Java SDK 不支援。

    Python

    Python SDK 不支援。

    C++
    DocumentReference doc_ref = db->Collection("cities").Document("SF");
    Source source = Source::kCache;
    doc_ref.Get(source).OnCompletion([](const Future<DocumentSnapshot>& future) {
      if (future.error() == Error::kErrorOk) {
        const DocumentSnapshot& document = *future.result();
        if (document.exists()) {
          std::cout << "Cached document id: " << document.id() << std::endl;
        } else {
        }
      } else {
        std::cout << "Cached get failed: " << future.error_message() << std::endl;
      }
    });
    Node.js

    Node.js SDK 不支援。

    Go

    Go SDK 不支援。

    PHP

    PHP SDK 不支援。

    Unity

    Unity SDK 不支援。

    C#

    C# SDK 不支援。

    Ruby

    Ruby SDK 不支援。

    自訂物件

    上述範例擷取了 但在某些語言中,使用 自訂物件類型在「Add Data」(新增資料) 中,您已定義 City 類別 用來定義每個城市你可以將文件重新轉換成City 物件:

    如要使用自訂物件,您必須定義 FirestoreDataConverter 函式。例如:

    Web

    class City {
        constructor (name, state, country ) {
            this.name = name;
            this.state = state;
            this.country = country;
        }
        toString() {
            return this.name + ', ' + this.state + ', ' + this.country;
        }
    }
    
    // Firestore data converter
    const cityConverter = {
        toFirestore: (city) => {
            return {
                name: city.name,
                state: city.state,
                country: city.country
                };
        },
        fromFirestore: (snapshot, options) => {
            const data = snapshot.data(options);
            return new City(data.name, data.state, data.country);
        }
    };

    如要使用自訂物件,您必須定義 FirestoreDataConverter 函式。例如:

    Web

    class City {
        constructor (name, state, country ) {
            this.name = name;
            this.state = state;
            this.country = country;
        }
        toString() {
            return this.name + ', ' + this.state + ', ' + this.country;
        }
    }
    
    // Firestore data converter
    var cityConverter = {
        toFirestore: function(city) {
            return {
                name: city.name,
                state: city.state,
                country: city.country
                };
        },
        fromFirestore: function(snapshot, options){
            const data = snapshot.data(options);
            return new City(data.name, data.state, data.country);
        }
    };

    使用讀取作業呼叫資料轉換器。轉換完成後 存取自訂物件方法:

    Web

    import { doc, getDoc} from "firebase/firestore"; 
    
    const ref = doc(db, "cities", "LA").withConverter(cityConverter);
    const docSnap = await getDoc(ref);
    if (docSnap.exists()) {
      // Convert to City object
      const city = docSnap.data();
      // Use a City instance method
      console.log(city.toString());
    } else {
      console.log("No such document!");
    }

    使用讀取作業呼叫資料轉換器。轉換完成後 存取自訂物件方法:

    Web

    db.collection("cities").doc("LA")
      .withConverter(cityConverter)
      .get().then((doc) => {
        if (doc.exists){
          // Convert to City object
          var city = doc.data();
          // Use a City instance method
          console.log(city.toString());
        } else {
          console.log("No such document!");
        }}).catch((error) => {
          console.log("Error getting document:", error);
        });
    Swift
    注意:這項產品不適用於 watchOS 和 App Clip 目標。

    如要在 Swift 中支援自動類型序列化,您的類型必須符合 可複製的通訊協定

    let docRef = db.collection("cities").document("BJ")
    
    do {
      let city = try await docRef.getDocument(as: City.self)
      print("City: \(city)")
    } catch {
      print("Error decoding city: \(error)")
    }
    Objective-C
    注意:這項產品不適用於 watchOS 和 App Clip 目標。

    在 Objective-C 中,您必須手動進行這項操作。

    FIRDocumentReference *docRef =
    [[self.db collectionWithPath:@"cities"] documentWithPath:@"BJ"];
    [docRef getDocumentWithCompletion:^(FIRDocumentSnapshot *snapshot, NSError *error) {
      FSTCity *city = [[FSTCity alloc] initWithDictionary:snapshot.data];
      if (city != nil) {
        NSLog(@"City: %@", city);
      } else {
        NSLog(@"Document does not exist");
      }
    }];

    Kotlin+KTX

    val docRef = db.collection("cities").document("BJ")
    docRef.get().addOnSuccessListener { documentSnapshot ->
        val city = documentSnapshot.toObject<City>()
    }

    Java

    重要事項:每個自訂類別都必須有一個公開建構函式,而且這個建構函式不會 引數。此外,類別也必須為每個類別加入一個公開 getter 資源。

    DocumentReference docRef = db.collection("cities").document("BJ");
    docRef.get().addOnSuccessListener(new OnSuccessListener<DocumentSnapshot>() {
        @Override
        public void onSuccess(DocumentSnapshot documentSnapshot) {
            City city = documentSnapshot.toObject(City.class);
        }
    });

    Dart

    如要使用自訂物件,您必須定義 Firestore 資料轉換函式 。例如:

    class City {
      final String? name;
      final String? state;
      final String? country;
      final bool? capital;
      final int? population;
      final List<String>? regions;
    
      City({
        this.name,
        this.state,
        this.country,
        this.capital,
        this.population,
        this.regions,
      });
    
      factory City.fromFirestore(
        DocumentSnapshot<Map<String, dynamic>> snapshot,
        SnapshotOptions? options,
      ) {
        final data = snapshot.data();
        return City(
          name: data?['name'],
          state: data?['state'],
          country: data?['country'],
          capital: data?['capital'],
          population: data?['population'],
          regions:
              data?['regions'] is Iterable ? List.from(data?['regions']) : null,
        );
      }
    
      Map<String, dynamic> toFirestore() {
        return {
          if (name != null) "name": name,
          if (state != null) "state": state,
          if (country != null) "country": country,
          if (capital != null) "capital": capital,
          if (population != null) "population": population,
          if (regions != null) "regions": regions,
        };
      }
    }

    接著,請使用資料轉換函式建立文件參照。不限 使用此參照執行的讀取作業會傳回 自訂類別:

    final ref = db.collection("cities").doc("LA").withConverter(
          fromFirestore: City.fromFirestore,
          toFirestore: (City city, _) => city.toFirestore(),
        );
    final docSnap = await ref.get();
    final city = docSnap.data(); // Convert to City object
    if (city != null) {
      print(city);
    } else {
      print("No such document.");
    }
    Java

    每個自訂類別都必須有一個公開的建構函式 引數。此外,類別也必須為每個類別加入一個公開 getter 資源。

    DocumentReference docRef = db.collection("cities").document("BJ");
    // asynchronously retrieve the document
    ApiFuture<DocumentSnapshot> future = docRef.get();
    // block on response
    DocumentSnapshot document = future.get();
    City city = null;
    if (document.exists()) {
      // convert document to POJO
      city = document.toObject(City.class);
      System.out.println(city);
    } else {
      System.out.println("No such document!");
    }
    Python
    doc_ref = db.collection("cities").document("BJ")
    
    doc = doc_ref.get()
    city = City.from_dict(doc.to_dict())
    print(city)

    Python

    doc_ref = db.collection("cities").document("BJ")
    
    doc = await doc_ref.get()
    city = City.from_dict(doc.to_dict())
    print(city)
    C++
    // This is not yet supported.
    Node.js

    Node.js 使用 JavaScript 物件。

    Go
    
    import (
    	"context"
    	"fmt"
    
    	"cloud.google.com/go/firestore"
    )
    
    func docAsEntity(ctx context.Context, client *firestore.Client) (*City, error) {
    	dsnap, err := client.Collection("cities").Doc("BJ").Get(ctx)
    	if err != nil {
    		return nil, err
    	}
    	var c City
    	dsnap.DataTo(&c)
    	fmt.Printf("Document data: %#v\n", c)
    	return &c, nil
    }
    
    PHP

    PHP

    如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端,請參閱 Cloud Firestore 用戶端程式庫

    $docRef = $db->collection('samples/php/cities')->document('SF');
    $snapshot = $docRef->snapshot();
    $city = City::fromArray($snapshot->data());
    
    if ($snapshot->exists()) {
        printf('Document data:' . PHP_EOL);
        print((string) $city);
    } else {
        pr