Начните работу с Cloud Firestore Standard Edition, используя серверные клиентские библиотеки.

В этом кратком руководстве показано, как настроить Cloud Firestore Enterprise Edition, добавить данные, а затем просмотреть только что добавленные данные в консоли Firebase используя серверные клиентские библиотеки для C#, Go, Java, Node.js, PHP, Python и Ruby.

Используйте эти клиентские библиотеки для настройки привилегированных серверных сред с полным доступом к вашей базе данных.

Создайте базу данных Cloud Firestore

  1. Если вы еще этого не сделали, создайте проект Firebase: в консоли Firebase нажмите «Добавить проект» , а затем следуйте инструкциям на экране, чтобы создать проект Firebase или добавить сервисы Firebase в существующий проект Google Cloud .

  2. Откройте свой проект в консоли Firebase . В левой панели разверните раздел «Сборка» , а затем выберите базу данных Firestore .

  3. Нажмите «Создать базу данных» .

  4. Выберите местоположение для вашей базы данных.

    Если вы не можете выбрать местоположение, значит, «местоположение для ресурсов Google Cloud по умолчанию» в вашем проекте уже задано. Некоторые ресурсы вашего проекта (например, экземпляр Cloud Firestore по умолчанию) имеют общую зависимость от местоположения, и их местоположение можно задать либо при создании проекта, либо при настройке другой службы, которая также имеет эту зависимость от местоположения.

  5. Выберите режим запуска Cloud Firestore Security Rules :

    Тестовый режим

    Подходит для начала работы с библиотеками мобильного и веб-клиента, но позволяет любому читать и перезаписывать ваши данные. После тестирования обязательно ознакомьтесь с разделом «Защита данных» .

    Для начала работы с веб-версией, платформами Apple или Android SDK выберите тестовый режим.

    Режим производства

    Запрещает все операции чтения и записи с мобильных и веб-клиентов. Ваши аутентифицированные серверы приложений (C#, Go, Java, Node.js, PHP, Python или Ruby) по-прежнему смогут получать доступ к вашей базе данных.

    Для начала работы с серверно-клиентской библиотекой на C#, Go, Java, Node.js, PHP, Python или Ruby выберите производственный режим.

    Первоначальный набор Cloud Firestore Security Rules будет применяться к вашей базе данных Cloud Firestore по умолчанию. Если вы создадите несколько баз данных для своего проекта, вы можете развернуть Cloud Firestore Security Rules для каждой из них.

  6. Нажмите «Создать» .

При включении Cloud Firestore также активируется API в Cloud API Manager .

Настройте среду разработки.

Добавьте необходимые зависимости и клиентские библиотеки в ваше приложение.

Java
  1. Добавьте Firebase Admin SDK в своё приложение:
    • Использование Gradle:
      implementation 'com.google.firebase:firebase-admin:9.7.0'
    • Использование Maven:
      <dependency>
        <groupId>com.google.firebase</groupId>
        <artifactId>firebase-admin</artifactId>
        <version>9.7.0</version>
      </dependency>
           
  2. Следуйте приведенным ниже инструкциям, чтобы инициализировать Cloud Firestore с использованием соответствующих учетных данных в вашей среде.
Python
  1. Добавьте Firebase Admin SDK в ваше приложение на Python:
    pip install --upgrade firebase-admin
  2. Следуйте приведенным ниже инструкциям, чтобы инициализировать Cloud Firestore с использованием соответствующих учетных данных в вашей среде.
Node.js
  1. Добавьте Firebase Admin SDK в своё приложение:
    npm install firebase-admin --save
  2. Следуйте приведенным ниже инструкциям, чтобы инициализировать Cloud Firestore с использованием соответствующих учетных данных в вашей среде.
Идти
  1. Добавьте Firebase Admin SDK в ваше приложение Go:
    go get firebase.google.com/go
  2. Следуйте приведенным ниже инструкциям, чтобы инициализировать Cloud Firestore с использованием соответствующих учетных данных в вашей среде.
PHP
  1. Клиентские библиотеки сервера Cloud Firestore (Java, Node.js, Python, Go, PHP, C# и Ruby) используют учетные данные Google Application Default Credentials для аутентификации.
    • Для аутентификации из среды разработки установите переменную среды GOOGLE_APPLICATION_CREDENTIALS так, чтобы она указывала на файл ключа сервисной учетной записи в формате JSON. Создать файл ключа можно на странице «Учетные данные» в консоли API .
      export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/keyfile.json"
    • В производственной среде аутентификация не требуется, если вы запускаете приложение на App Engine или Compute Engine, используя тот же проект, что и для Cloud Firestore . В противном случае настройте учетную запись службы .
  2. Установите и включите расширение gRPC для PHP, которое вам понадобится для использования клиентской библиотеки.
  3. Добавьте PHP-библиотеку Cloud Firestore в свое приложение:
    composer require google/cloud-firestore
Руби
  1. Клиентские библиотеки сервера Cloud Firestore (Java, Node.js, Python, Go, PHP, C# и Ruby) используют учетные данные Google Application Default Credentials для аутентификации.
    • Для аутентификации из среды разработки установите переменную среды GOOGLE_APPLICATION_CREDENTIALS так, чтобы она указывала на файл ключа сервисной учетной записи в формате JSON. Создать файл ключа можно на странице «Учетные данные» в консоли API .
      export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/keyfile.json"
    • В производственной среде аутентификация не требуется, если вы запускаете приложение на App Engine или Compute Engine, используя тот же проект, что и для Cloud Firestore . В противном случае настройте учетную запись службы .
  2. Добавьте библиотеку Cloud Firestore Ruby в ваше приложение в Gemfile :
    gem "google-cloud-firestore"
  3. Установите зависимости из вашего Gemfile , используя:
    bundle install

(Необязательно) Создайте прототип и протестируйте его с помощью Firebase Local Emulator Suite

Прежде чем говорить о том, как ваше приложение записывает и читает данные в Cloud Firestore , разработчикам мобильных приложений следует ознакомиться с набором инструментов, которые можно использовать для прототипирования и тестирования функциональности Cloud Firestore : Firebase Local Emulator Suite . Если вы экспериментируете с различными моделями данных, оптимизируете правила безопасности или ищете наиболее экономичный способ взаимодействия с бэкэндом, возможность работать локально без развертывания работающих сервисов может оказаться отличной идеей.

Эмулятор Cloud Firestore является частью Local Emulator Suite , который позволяет вашему приложению взаимодействовать с содержимым и конфигурацией эмулируемой базы данных, а также, при необходимости, с ресурсами эмулируемого проекта (функциями, другими базами данных и правилами безопасности).

Использование эмулятора Cloud Firestore включает всего несколько шагов:

  1. Добавление строки кода в конфигурацию тестирования вашего приложения для подключения к эмулятору.
  2. В корневом каталоге вашего локального проекта выполните firebase emulators:start .
  3. Выполнение вызовов из прототипа кода вашего приложения с использованием SDK платформы Cloud Firestore как обычно.

Подробное пошаговое руководство по Cloud Firestore и Cloud Functions доступно. Также рекомендуем ознакомиться с вводной информацией о Local Emulator Suite .

Инициализация Cloud Firestore

Инициализируйте экземпляр Cloud Firestore :

Java
Инициализация Cloud Firestore SDK осуществляется различными способами в зависимости от вашей среды. Ниже приведены наиболее распространенные методы. Для получения полной информации см. раздел «Инициализация Admin SDK» .
  • Инициализация в Google Cloud
    import com.google.auth.oauth2.GoogleCredentials;
    import com.google.cloud.firestore.Firestore;
    
    import com.google.firebase.FirebaseApp;
    import com.google.firebase.FirebaseOptions;
    
    // Use the application default credentials
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
    FirebaseOptions options = new FirebaseOptions.Builder()
        .setCredentials(credentials)
        .setProjectId(projectId)
        .build();
    FirebaseApp.initializeApp(options);
    
    Firestore db = FirestoreClient.getFirestore();
  • Инициализируйте на собственном сервере.

    Для использования Firebase Admin SDK на собственном сервере используйте учетную запись службы .

    В консоли Google Cloud перейдите в раздел IAM и администрирование > Сервисные учетные записи . Сгенерируйте новый закрытый ключ и сохраните 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 на собственном сервере используйте учетную запись службы .

    В консоли 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» .
  • Инициализация в 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 на собственном сервере используйте учетную запись службы .

    В консоли Google Cloud перейдите в раздел IAM и администрирование > Сервисные учетные записи . Сгенерируйте новый закрытый ключ и сохраните JSON-файл. Затем используйте этот файл для инициализации SDK:

    import firebase_admin
    from firebase_admin import credentials
    from firebase_admin import firestore_async
    
    # Use a service account.
    cred = credentials.Certificate('path/to/serviceAccount.json')
    
    app = firebase_admin.initialize_app(cred)
    
    db = firestore_async.client()
  • 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();
    • Инициализируйте на собственном сервере.

      Чтобы использовать Firebase Admin SDK на собственном сервере (или в любой другой среде Node.js), используйте сервисную учетную запись . Перейдите в раздел IAM и администрирование > Сервисные учетные записи в консоли Google Cloud. Сгенерируйте новый закрытый ключ и сохраните 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();
      
    Идти
    Инициализация Cloud Firestore SDK осуществляется различными способами в зависимости от вашей среды. Ниже приведены наиболее распространенные методы. Для получения полной информации см. раздел «Инициализация Admin SDK» .
  • Инициализация в Google Cloud
    import (
      "log"
    
      firebase "firebase.google.com/go"
      "google.golang.org/api/option"
    )
    
    // Use the application default credentials
    ctx := context.Background()
    conf := &firebase.Config{ProjectID: projectID}
    app, err := firebase.NewApp(ctx, conf)
    if err != nil {
      log.Fatalln(err)
    }
    
    client, err := app.Firestore(ctx)
    if err != nil {
      log.Fatalln(err)
    }
    defer client.Close()
  • Инициализируйте на собственном сервере.

    Для использования Firebase Admin SDK на собственном сервере используйте учетную запись службы .

    В консоли Google Cloud перейдите в раздел IAM и администрирование > Сервисные учетные записи . Сгенерируйте новый закрытый ключ и сохраните 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);
        }
    }
    C#

    C#

    Для получения дополнительной информации об установке и создании клиента Cloud Firestore см. раздел «Библиотеки клиентов Cloud Firestore .

    FirestoreDb db = FirestoreDb.Create(project);
    Console.WriteLine("Created Cloud Firestore client with project ID: {0}", project);
    Руби
    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."

    Добавить данные

    Cloud Firestore хранит данные в документах, которые хранятся в коллекциях. Cloud Firestore создает коллекции и документы автоматически при первом добавлении данных в документ. Вам не нужно явно создавать коллекции или документы.

    Создайте новую коллекцию и документ, используя следующий пример кода.

    Java
    DocumentReference docRef = db.collection("users").document("alovelace");
    // Add document data  with id "alovelace" using a hashmap
    Map<String, Object> data = new HashMap<>();
    data.put("first", "Ada");
    data.put("last", "Lovelace");
    data.put("born", 1815);
    //asynchronously write data
    ApiFuture<WriteResult> result = docRef.set(data);
    // ...
    // result.get() blocks on response
    System.out.println("Update time : " + result.get().getUpdateTime());
    Python
    doc_ref = db.collection("users").document("alovelace")
    doc_ref.set({"first": "Ada", "last": "Lovelace", "born": 1815})

    Python

    doc_ref = db.collection("users").document("alovelace")
    await doc_ref.set({"first": "Ada", "last": "Lovelace", "born": 1815})
    Node.js
    const docRef = db.collection('users').doc('alovelace');
    
    await docRef.set({
      first: 'Ada',
      last: 'Lovelace',
      born: 1815
    });
    Идти
    _, _, err := client.Collection("users").Add(ctx, map[string]interface{}{
    	"first": "Ada",
    	"last":  "Lovelace",
    	"born":  1815,
    })
    if err != nil {
    	log.Fatalf("Failed adding alovelace: %v", err)
    }
    PHP

    PHP

    Для получения дополнительной информации об установке и создании клиента Cloud Firestore см. раздел «Библиотеки клиентов Cloud Firestore .

    $docRef = $db->collection('samples/php/users')->document('alovelace');
    $docRef->set([
        'first' => 'Ada',
        'last' => 'Lovelace',
        'born' => 1815
    ]);
    printf('Added data to the lovelace document in the users collection.' . PHP_EOL);
    C#
    DocumentReference docRef = db.Collection("users").Document("alovelace");
    Dictionary<string, object> user = new Dictionary<string, object>
    {
        { "First", "Ada" },
        { "Last", "Lovelace" },
        { "Born", 1815 }
    };
    await docRef.SetAsync(user);
    Руби
    doc_ref = firestore.doc "#{collection_path}/alovelace"
    
    doc_ref.set(
      {
        first: "Ada",
        last:  "Lovelace",
        born:  1815
      }
    )
    
    puts "Added data to the alovelace document in the users collection."

    Теперь добавьте еще один документ в коллекцию users . Обратите внимание, что этот документ содержит пару ключ-значение (отчество), которой нет в первом документе. Документы в коллекции могут содержать разные наборы информации.

    Java
    DocumentReference docRef = db.collection("users").document("aturing");
    // Add document data with an additional field ("middle")
    Map<String, Object> data = new HashMap<>();
    data.put("first", "Alan");
    data.put("middle", "Mathison");
    data.put("last", "Turing");
    data.put("born", 1912);
    
    ApiFuture<WriteResult> result = docRef.set(data);
    System.out.println("Update time : " + result.get().getUpdateTime());
    Python
    doc_ref = db.collection("users").document("aturing")
    doc_ref.set({"first": "Alan", "middle": "Mathison", "last": "Turing", "born": 1912})

    Python

    doc_ref = db.collection("users").document("aturing")
    await doc_ref.set(
        {"first": "Alan", "middle": "Mathison", "last": "Turing", "born": 1912}
    )
    Node.js
    const aTuringRef = db.collection('users').doc('aturing');
    
    await aTuringRef.set({
      'first': 'Alan',
      'middle': 'Mathison',
      'last': 'Turing',
      'born': 1912
    });
    Идти
    _, _, err = client.Collection("users").Add(ctx, map[string]interface{}{
    	"first":  "Alan",
    	"middle": "Mathison",
    	"last":   "Turing",
    	"born":   1912,
    })
    if err != nil {
    	log.Fatalf("Failed adding aturing: %v", err)
    }
    PHP

    PHP

    Для получения дополнительной информации об установке и создании клиента Cloud Firestore см. раздел «Библиотеки клиентов Cloud Firestore .

    $docRef = $db->collection('samples/php/users')->document('aturing');
    $docRef->set([
        'first' => 'Alan',
        'middle' => 'Mathison',
        'last' => 'Turing',
        'born' => 1912
    ]);
    printf('Added data to the aturing document in the users collection.' . PHP_EOL);
    C#
    DocumentReference docRef = db.Collection("users").Document("aturing");
    Dictionary<string, object> user = new Dictionary<string, object>
    {
        { "First", "Alan" },
        { "Middle", "Mathison" },
        { "Last", "Turing" },
        { "Born", 1912 }
    };
    await docRef.SetAsync(user);
    Руби
    doc_ref = firestore.doc "#{collection_path}/aturing"
    
    doc_ref.set(
      {
        first:  "Alan",
        middle: "Mathison",
        last:   "Turing",
        born:   1912
      }
    )
    
    puts "Added data to the aturing document in the users collection."

    Прочитать данные

    Воспользуйтесь средством просмотра данных в консоли Firebase , чтобы быстро убедиться, что вы добавили данные в Cloud Firestore .

    Также можно использовать метод `get` для получения всей коллекции целиком.

    Java
    // asynchronously retrieve all users
    ApiFuture<QuerySnapshot> query = db.collection("users").get();
    // ...
    // query.get() blocks on response
    QuerySnapshot querySnapshot = query.get();
    List<QueryDocumentSnapshot> documents = querySnapshot.getDocuments();
    for (QueryDocumentSnapshot document : documents) {
      System.out.println("User: " + document.getId());
      System.out.println("First: " + document.getString("first"));
      if (document.contains("middle")) {
        System.out.println("Middle: " + document.getString("middle"));
      }
      System.out.println("Last: " + document.getString("last"));
      System.out.println("Born: " + document.getLong("born"));
    }
    Python
    users_ref = db.collection("users")
    docs = users_ref.stream()
    
    for doc in docs:
        print(f"{doc.id} => {doc.to_dict()}")

    Python

    users_ref = db.collection("users")
    docs = users_ref.stream()
    
    async for doc in docs:
        print(f"{doc.id} => {doc.to_dict()}")
    Node.js
    const snapshot = await db.collection('users').get();
    snapshot.forEach((doc) => {
      console.log(doc.id, '=>', doc.data());
    });
    Идти
    iter := client.Collection("users").Documents(ctx)
    for {
    	doc, err := iter.Next()
    	if err == iterator.Done {
    		break
    	}
    	if err != nil {
    		log.Fatalf("Failed to iterate: %v", err)
    	}
    	fmt.Println(doc.Data())
    }
    PHP

    PHP

    Для получения дополнительной информации об установке и создании клиента Cloud Firestore см. раздел «Библиотеки клиентов Cloud Firestore .

    $usersRef = $db->collection('samples/php/users');
    $snapshot = $usersRef->documents();
    foreach ($snapshot as $user) {
        printf('User: %s' . PHP_EOL, $user->id());
        printf('First: %s' . PHP_EOL, $user['first']);
        if (!empty($user['middle'])) {
            printf('Middle: %s' . PHP_EOL, $user['middle']);
        }
        printf('Last: %s' . PHP_EOL, $user['last']);
        printf('Born: %d' . PHP_EOL, $user['born']);
        printf(PHP_EOL);
    }
    printf('Retrieved and printed out all documents from the users collection.' . PHP_EOL);
    C#
    CollectionReference usersRef = db.Collection("users");
    QuerySnapshot snapshot = await usersRef.GetSnapshotAsync();
    foreach (DocumentSnapshot document in snapshot.Documents)
    {
        Console.WriteLine("User: {0}", document.Id);
        Dictionary<string, object> documentDictionary = document.ToDictionary();
        Console.WriteLine("First: {0}", documentDictionary["First"]);
        if (documentDictionary.ContainsKey("Middle"))
        {
            Console.WriteLine("Middle: {0}", documentDictionary["Middle"]);
        }
        Console.WriteLine("Last: {0}", documentDictionary["Last"]);
        Console.WriteLine("Born: {0}", documentDictionary["Born"]);
        Console.WriteLine();
    }
    Руби
    users_ref = firestore.col collection_path
    users_ref.get do |user|
      puts "#{user.document_id} data: #{user.data}."
    end

    Следующие шаги

    Углубите свои знания по следующим темам: