Começar a usar a edição Standard do Cloud Firestore com bibliotecas de cliente do servidor

Neste guia de início rápido, mostramos como configurar a edição Enterprise do Cloud Firestore, adicionar dados e visualizar os dados adicionados no console do Firebase usando bibliotecas de cliente do servidor para C#, Go, Java, Node.js, PHP, Python e Ruby.

Use-as para configurar ambientes de servidor privilegiados com acesso total ao seu banco de dados.

Criar um banco de dados do Cloud Firestore

  1. Crie um projeto do Firebase se você ainda não fez isso: no console do Firebase, clique em Adicionar projeto e siga as instruções na tela para criar um projeto do Firebase ou para adicionar serviços do Firebase a um projeto do Google Cloud.

  2. Abra seu projeto no console do Firebase. No painel à esquerda, expanda Build e selecione Banco de dados do Firestore.

  3. Clique em Criar banco de dados.

  4. Selecione um local para seu banco de dados.

    Se você não conseguir selecionar um local, isso significa que o "local padrão para recursos do Google Cloud" do projeto já foi definido. Alguns dos recursos do projeto (como a instância padrão do Cloud Firestore) compartilham uma dependência de local comum, e o local deles pode ser definido durante a criação do projeto ou ao configurar outro serviço que compartilha essa dependência.

  5. Selecione um modo inicial para as Cloud Firestore Security Rules:

    Modo de teste

    Ideal para começar a usar as bibliotecas de cliente de dispositivos móveis e Web. No entanto, esse modo permite que qualquer pessoa leia e modifique os dados. Depois do teste, revise a seção Proteger seus dados.

    Selecione o modo de teste para começar a usar as plataformas Apple, da Web ou o SDK do Android.

    Modo de produção

    Nega todas as leituras e gravações de clientes de dispositivos móveis e Web. Seus servidores de aplicativos autenticados (C#, Go, Java, Node.js, PHP, Python ou Ruby) ainda podem acessar o banco de dados.

    Selecione o Modo de Produção para começar a usar a biblioteca de cliente do servidor para C#, Go, Java, Node.js, PHP, Python ou Ruby.

    O conjunto inicial de Cloud Firestore Security Rules será aplicado ao banco de dados padrão do Cloud Firestore. Se você criar vários bancos de dados para seu projeto, poderá implantar Cloud Firestore Security Rules para cada um deles.

  6. Clique em Criar.

Quando você ativa o Cloud Firestore, ele também ativa a API no Gerenciador de APIs do Cloud.

Configurar o ambiente de desenvolvimento

Adicione as dependências e as bibliotecas de cliente necessárias ao app.

Java
  1. Adicione o SDK Admin do Firebase ao seu app:
    • Com o Gradle: 
      implementation 'com.google.firebase:firebase-admin:9.7.0'
    • Com o Maven: 
      <dependency>
  <groupId>com.google.firebase</groupId>
  <artifactId>firebase-admin</artifactId>
  <version>9.7.0</version>
</dependency>
  2. Siga as instruções abaixo para inicializar o Cloud Firestore com as credenciais adequadas no seu ambiente.
Python
  1. Adicione o SDK Admin do Firebase ao seu app para Python: 
    pip install --upgrade firebase-admin
  2. Siga as instruções abaixo para inicializar o Cloud Firestore com as credenciais adequadas no seu ambiente.
Node.js
  1. Adicione o SDK Admin do Firebase ao seu app: 
    npm install firebase-admin --save
  2. Siga as instruções abaixo para inicializar o Cloud Firestore com as credenciais adequadas no seu ambiente.
Go
  1. Adicione o SDK Admin do Firebase ao seu app para Go: 
    go get firebase.google.com/go
  2. Siga as instruções abaixo para inicializar o Cloud Firestore com as credenciais adequadas no seu ambiente.
PHP
  1. As bibliotecas de cliente do servidor do Cloud Firestore (Java, Node.js, Python, Go, PHP, C# e Ruby) usam o Application Default Credentials do Google para realizar a autenticação.
    • Para autenticar usando seu ambiente de desenvolvimento, defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para indicar um arquivo de chave de conta do serviço JSON. É possível criar um arquivo de chave na página Credenciais, do Console de APIs. 
      export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/keyfile.json"
    • No seu ambiente de produção, não é necessário fazer a autenticação quando o aplicativo é executado no App Engine ou no Compute Engine usando o mesmo projeto utilizado para o Cloud Firestore. Caso contrário, configure uma conta de serviço.
  2. Instale e ative a extensão gRPC para PHP, necessária para usar a biblioteca de cliente.
  3. Adicione a biblioteca PHP do Cloud Firestore ao aplicativo: 
    composer require google/cloud-firestore
Ruby
  1. As bibliotecas de cliente do servidor do Cloud Firestore (Java, Node.js, Python, Go, PHP, C# e Ruby) usam o Application Default Credentials do Google para realizar a autenticação.
    • Para autenticar usando seu ambiente de desenvolvimento, defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para indicar um arquivo de chave de conta do serviço JSON. É possível criar um arquivo de chave na página Credenciais, do Console de APIs. 
      export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/keyfile.json"
    • No seu ambiente de produção, não é necessário fazer a autenticação quando o aplicativo é executado no App Engine ou no Compute Engine usando o mesmo projeto utilizado para o Cloud Firestore. Caso contrário, configure uma conta de serviço.
  2. Adicione a biblioteca Ruby do Cloud Firestore ao aplicativo no Gemfile: 
    gem "google-cloud-firestore"
  3. Instale as dependências do seu Gemfile usando: 
    bundle install

Criar protótipos e fazer testes com Firebase Local Emulator Suite (opcional)

Para desenvolvedores de dispositivos móveis, antes de conversar sobre como o app grava e lê no Cloud Firestore, vamos apresentar um conjunto de ferramentas que podem ser usadas para prototipar e testar a funcionalidade do Cloud Firestore: Firebase Local Emulator Suite. Conseguir trabalhar localmente sem precisar implantar serviços existentes será uma ótima ideia se você estiver testando diferentes modelos de dados, otimizando suas regras de segurança ou procurando a maneira mais econômica de interagir com o back-end.

Um emulador do Cloud Firestore faz parte do Local Emulator Suite, que permite que o app interaja com o conteúdo e a configuração do banco de dados emulado e também com os recursos do projeto emulado (funções, outros bancos de dados e regras de segurança).

O uso do emulador do Cloud Firestore envolve apenas algumas etapas:

  1. Para se conectar ao emulador, adicione uma linha de código à configuração de teste do app.
  2. Execute firebase emulators:start na raiz do diretório do projeto local.
  3. Faça chamadas pelo código de protótipo do seu app usando o SDK da plataforma do Cloud Firestore como de costume.

Confira um tutorial detalhado sobre o Cloud Firestore e o Cloud Functions. Consulte também a introdução do Local Emulator Suite.

Inicializar o Cloud Firestore

Inicialize uma instância do Cloud Firestore:

Java
O SDK do Cloud Firestore é inicializado de maneiras diferentes, dependendo do seu ambiente. Veja abaixo os métodos mais comuns. Para uma referência completa, consulte Inicializar o SDK Admin.
  • Inicializar o 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();
  • Inicializar no seu próprio servidor

    Para usar o SDK Admin do Firebase no seu próprio servidor, use uma conta de serviço.

    Acesse IAM e administrador > Contas de serviço no console do Google Cloud. Gere uma nova chave privada e salve o arquivo JSON. Em seguida, use o arquivo para inicializar o 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
    O SDK do Cloud Firestore é inicializado de maneiras diferentes, dependendo do seu ambiente. Veja abaixo os métodos mais comuns. Para uma referência completa, consulte Inicializar o SDK Admin.
  • Inicializar o Google Cloud 
    import firebase_admin
from firebase_admin import firestore

# Application Default credentials are automatically created.
app = firebase_admin.initialize_app()
db = firestore.client()
    firestore.py

    Uma credencial padrão do aplicativo também pode ser usada para inicializar o 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()
    firestore.py
  • Inicializar no seu próprio servidor

    Para usar o SDK Admin do Firebase no seu próprio servidor, use uma conta de serviço.

    Acesse IAM e administrador > Contas de serviço no console do Google Cloud. Gere uma nova chave privada e salve o arquivo JSON. Em seguida, use o arquivo para inicializar o 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()
    firestore.py

    • Python

    O SDK do Cloud Firestore é inicializado de maneiras diferentes, dependendo do seu ambiente. Veja abaixo os métodos mais comuns. Para uma referência completa, consulte Inicializar o SDK Admin.
  • Inicializar o 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()
    firestore_async.py

    Uma credencial padrão do aplicativo também pode ser usada para inicializar o 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()
    firestore_async.py
  • Inicializar no seu próprio servidor

    Para usar o SDK Admin do Firebase no seu próprio servidor, use uma conta de serviço.

    Acesse IAM e administrador > Contas de serviço no console do Google Cloud. Gere uma nova chave privada e salve o arquivo JSON. Em seguida, use o arquivo para inicializar o 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()
    firestore_async.py
    • Node.js
    O SDK do Cloud Firestore é inicializado de maneiras diferentes, dependendo do seu ambiente. Veja abaixo os métodos mais comuns. Para uma referência completa, consulte Inicializar o SDK Admin.
    • Inicializar o Cloud Functions 
      const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
       
      initializeApp();

const db = getFirestore();

      index.js
    • Inicializar o 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();
      index.js
    • Inicializar no seu próprio servidor

      Para usar o SDK Admin do Firebase no seu próprio servidor, ou em qualquer outro ambiente com Node.js, use uma conta de serviço. Acesse IAM e administrador > Contas de serviço no console do Google Cloud. Gere uma nova chave privada e salve o arquivo JSON. Em seguida, use o arquivo para inicializar o 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();

      index.js
    Go
    O SDK do Cloud Firestore é inicializado de maneiras diferentes, dependendo do seu ambiente. Veja abaixo os métodos mais comuns. Para uma referência completa, consulte Inicializar o SDK Admin.
  • Inicializar o 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()
  • Inicializar no seu próprio servidor

    Para usar o SDK Admin do Firebase no seu próprio servidor, use uma conta de serviço.

    Acesse IAM e administrador > Contas de serviço no console do Google Cloud. Gere uma nova chave privada e salve o arquivo JSON. Em seguida, use o arquivo para inicializar o 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

    Para mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente 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);
    }
}
    setup_client_create.php
    C#

    C#

    Para mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente Cloud Firestore. 

    FirestoreDb db = FirestoreDb.Create(project);
Console.WriteLine("Created Cloud Firestore client with project ID: {0}", project);
    Program.cs
    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."
    quickstart.rb

    Adicionar dados

    O Cloud Firestore armazena dados nos documentos, que são armazenados nas coleções. O Firestore cria coleções e documentos de modo implícito na primeira vez que você adiciona dados ao documento.Cloud Firestore Não é necessário criar coleções ou documentos explicitamente.

    Crie uma nova coleção e um documento usando o código de exemplo a seguir.

    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());
    Quickstart.java
    Python
    doc_ref = db.collection("users").document("alovelace")
doc_ref.set({"first": "Ada", "last": "Lovelace", "born": 1815})
    snippets.py

    Python

    doc_ref = db.collection("users").document("alovelace")
await doc_ref.set({"first": "Ada", "last": "Lovelace", "born": 1815})
    snippets.py
    Node.js
    const docRef = db.collection('users').doc('alovelace');

await docRef.set({
  first: 'Ada',
  last: 'Lovelace',
  born: 1815
});
    index.js
    Go
    _, _, 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)
}
    main.go
    PHP

    PHP

    Para mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente 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);
    setup_dataset.php
    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);
    Program.cs
    Ruby
    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."
    quickstart.rb

    Agora, adicione outro documento à coleção users. Observe que esse documento inclui um par de valores-chave (nome do meio) que não aparece no primeiro documento. Os documentos em uma coleção podem conter diferentes conjuntos de informações.

    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());
    Quickstart.java
    Python
    doc_ref = db.collection("users").document("aturing")
doc_ref.set({"first": "Alan", "middle": "Mathison", "last": "Turing", "born": 1912})
    snippets.py

    Python

    doc_ref = db.collection("users").document("aturing")
await doc_ref.set(
    {"first": "Alan", "middle": "Mathison", "last": "Turing", "born": 1912}
)
    snippets.py
    Node.js
    const aTuringRef = db.collection('users').doc('aturing');

await aTuringRef.set({
  'first': 'Alan',
  'middle': 'Mathison',
  'last': 'Turing',
  'born': 1912
});
    index.js
    Go
    _, _, 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)
}
    main.go
    PHP

    PHP

    Para mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente 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);
    setup_dataset.php
    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);
    Program.cs
    Ruby
    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."
    quickstart.rb

    Ler dados

    Use o visualizador de dados no console do Firebase para verificar rapidamente se você adicionou dados ao Cloud Firestore.

    É possível usar o método "get" para recuperar toda a coleção.

    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"));
}
    Quickstart.java
    Python
    users_ref = db.collection("users")
docs = users_ref.stream()

for doc in docs:
    print(f"{doc.id} => {doc.to_dict()}")
    snippets.py

    Python

    users_ref = db.collection("users")
docs = users_ref.stream()

async for doc in docs:
    print(f"{doc.id} => {doc.to_dict()}")
    snippets.py
    Node.js
    const snapshot = await db.collection('users').get();
snapshot.forEach((doc) => {
  console.log(doc.id, '=>', doc.data());
});
    index.js
    Go
    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())
}
    main.go
    PHP

    PHP

    Para mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente 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);
    setup_dataset_read.php
    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();
}
    Program.cs
    Ruby
    users_ref = firestore.col collection_path
users_ref.get do |user|
  puts "#{user.document_id} data: #{user.data}."
end
    quickstart.rb

    Próximas etapas

    Aprofunde seu conhecimento com os seguintes tópicos: