Para começar com o Cloud Firestore

Neste guia de início rápido, mostramos como configurar o Cloud Firestore, adicionar dados e usar operações principais ou de pipeline para consultar os dados que você acabou de adicionar no console do Firebase.

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.

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

  2. Clique em Criar banco de dados.

  3. Selecione Enterprise para o modo de banco de dados.

  4. Selecione Firestore no modo nativo para o modo de operação, que é compatível com operações principais e de pipeline.

  5. Selecione um local para seu banco de dados.

  6. 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 (Python) ainda podem acessar seu banco de dados.

    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.

  7. 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.

Web

  1. Siga as instruções para adicionar o Firebase ao seu app da Web.

  2. O SDK do Cloud Firestore para pré-lançamento particular está disponível como um pacote npm.

    Use o comando a seguir para instalar o SDK do Firestore no seu projeto npm.

    npm install --save firebase@eap-firestore-pipelines
iOS+
  1. Siga as instruções para adicionar o Firebase ao seu app para iOS.
  2. Clone o SDK do Firebase do GitHub e confira a ramificação "pipelines". Anote o local em que você vai clonar, porque ele será necessário na próxima etapa: 
    git clone https://github.com/firebase/firebase-ios-sdk.git
# or git clone git@github.com:firebase/firebase-ios-sdk.git
cd firebase-ios-sdk

# check out pipeline feature branch
git fetch origin feat/pipeline/private-preview
git checkout feat/pipeline/private-preview
  3. Em seguida, adicione o diretório (firebase-ios-sdk) como uma dependência local ao seu projeto do Xcode:
    1. No menu Arquivo, escolha Adicionar dependências de pacote.
    2. Clique no botão Adicionar local… e localize o diretório firebase-ios-sdk com a ramificação de recurso que você extraiu.
Android
  1. Siga as instruções para adicionar o Firebase ao seu app Android.
  2. Clone o SDK do Firebase no GitHub, confira a ramificação de pipelines e publique no Maven local: 
    # Prerequisites before you start:
# Install Java 17
# Setup Android Development environments (having proper ANDROID_HOME, etc)

git clone https://github.com/firebase/firebase-android-sdk.git
# or git clone git@github.com:firebase/firebase-android-sdk.git
cd firebase-android-sdk

# check out pipeline feature branch
git fetch origin feat/pipeline/private-preview
git checkout feat/pipeline/private-preview

# publish firebase SDK (without crashlytics) to maven local
./gradlew publishToMavenLocal -x :firebase-crashlytics:publishToMavenLocal -x :firebase-crashlytics-ndk:publishToMavenLocal

# Optionally, if you want crashlytics built and published to mavel local
# Make sure you have Android NDK 21 installed
git submodule update --init --recursive
./gradlew publishToMavenLocal
  3. Adicione mavenLocal ao settings.gradle.kts no nível do projeto: 
    dependencyResolutionManagement {
  repositories {
    mavenLocal() // Add this line
    ..
  }
}
  4. Em seguida, adicione a versão local do SDK: 
    ...
// Firestore 99.0.0-pipeline.preview.1 has pipelines
implementation("com.google.firebase:firebase-firestore:99.0.0-pipeline.preview.1")

// Firebase Authentication
implementation("com.google.firebase:firebase-auth")
...
Python
  1. Clone o SDK do Python do Firestore e confira a ramificação de visualização do pipeline: 
    git clone https://github.com/googleapis/python-firestore.git
# or git clone git@github.com:googleapis/python-firestore.git
cd python-firestore

# check out pipeline preview branch
git fetch origin pipeline-preview
git checkout pipeline-preview
  2. Instale o SDK do servidor local python-firestore: 
    python -m pip install -e .
  3. Instale o SDK Admin do Firebase para Python normalmente: 
    pip install --user firebase-admin

Inicializar o Cloud Firestore

Inicialize uma instância do 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);


// When initializing Firestore, remember to use the name of the database you created earlier:
const db = initializeFirestore(app, {}, 'your-new-enterprise-database');

Substitua FIREBASE_CONFIGURATION pelo firebaseConfig do seu app da Web.

Para manter os dados se o dispositivo perder a conexão, consulte a documentação Ativar dados off-line.

Swift
import FirebaseCore
import FirebaseFirestore

FirebaseApp.configure()

// When initializing Firestore, remember to use the name of the database you created earlier:
let db = Firestore.firestore(database: "your-new-enterprise-database")

Kotlin

// Access a Cloud Firestore instance from your Activity
// When initializing Firestore, remember to use the name of the database you created earlier:
val firestore = FirebaseFirestore.getInstance("your-new-enterprise-database")

Java

// Access a Cloud Firestore instance from your Activity
// When initializing Firestore, remember to use the name of the database you created earlier:
FirebaseFirestore firestore = FirebaseFirestore.getInstance("your-new-enterprise-database");
Python

Faça a autenticação com seu banco de dados empresarial usando o SDK Admin:

import firebase_admin
from firebase_admin import firestore

def main():
  default_app = firebase_admin.initialize_app()
  client = firestore.client(default_app, "your-new-enterprise-database")
  query = client.pipeline().database().limit(5)
  for result in query.execute():
    print(result.data())

if __name__ == "__main__":
    main()

Adicionar dados usando operações principais

Para explorar as operações principais e de pipeline para consultar dados, adicione dados ao seu banco de dados usando as operações principais.

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.

Web

import { collection, addDoc } from "firebase/firestore"; 

try {
  const docRef = await addDoc(collection(db, "users"), {
    first: "Ada",
    last: "Lovelace",
    born: 1815
  });
  console.log("Document written with ID: ", docRef.id);
} catch (e) {
  console.error("Error adding document: ", e);
}
add_ada_lovelace.js

Web

db.collection("users").add({
    first: "Ada",
    last: "Lovelace",
    born: 1815
})
.then((docRef) => {
    console.log("Document written with ID: ", docRef.id);
})
.catch((error) => {
    console.error("Error adding document: ", error);
});
test.firestore.js
Swift
Observação: esse produto não está disponível para destinos watchOS e de clipes de apps. 
// Add a new document with a generated ID
do {
  let ref = try await db.collection("users").addDocument(data: [
    "first": "Ada",
    "last": "Lovelace",
    "born": 1815
  ])
  print("Document added with ID: \(ref.documentID)")
} catch {
  print("Error adding document: \(error)")
}
ViewController.swift

Kotlin

// Create a new user with a first and last name
val user = hashMapOf(
    "first" to "Ada",
    "last" to "Lovelace",
    "born" to 1815,
)

// Add a new document with a generated ID
db.collection("users")
    .add(user)
    .addOnSuccessListener { documentReference ->
        Log.d(TAG, "DocumentSnapshot added with ID: ${documentReference.id}")
    }
    .addOnFailureListener { e ->
        Log.w(TAG, "Error adding document", e)
    }
DocSnippets.kt

Java

// Create a new user with a first and last name
Map<String, Object> user = new HashMap<>();
user.put("first", "Ada");
user.put("last", "Lovelace");
user.put("born", 1815);

// Add a new document with a generated ID
db.collection("users")
        .add(user)
        .addOnSuccessListener(new OnSuccessListener<DocumentReference>() {
            @Override
            public void onSuccess(DocumentReference documentReference) {
                Log.d(TAG, "DocumentSnapshot added with ID: " + documentReference.getId());
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                Log.w(TAG, "Error adding document", e);
            }
        });
DocSnippets.java
Python
doc_ref = db.collection("users").document("alovelace")
doc_ref.set({"first": "Ada", "last": "Lovelace", "born": 1815})
snippets.py

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.

Web

// Add a second document with a generated ID.
import { addDoc, collection } from "firebase/firestore"; 

try {
  const docRef = await addDoc(collection(db, "users"), {
    first: "Alan",
    middle: "Mathison",
    last: "Turing",
    born: 1912
  });

  console.log("Document written with ID: ", docRef.id);
} catch (e) {
  console.error("Error adding document: ", e);
}
add_alan_turing.js

Web

// Add a second document with a generated ID.
db.collection("users").add({
    first: "Alan",
    middle: "Mathison",
    last: "Turing",
    born: 1912
})
.then((docRef) => {
    console.log("Document written with ID: ", docRef.id);
})
.catch((error) => {
    console.error("Error adding document: ", error);
});
test.firestore.js
Swift
Observação: esse produto não está disponível para destinos watchOS e de clipes de apps. 
// Add a second document with a generated ID.
do {
  let ref = try await db.collection("users").addDocument(data: [
    "first": "Alan",
    "middle": "Mathison",
    "last": "Turing",
    "born": 1912
  ])
  print("Document added with ID: \(ref.documentID)")
} catch {
  print("Error adding document: \(error)")
}
ViewController.swift

Kotlin

// Create a new user with a first, middle, and last name
val user = hashMapOf(
    "first" to "Alan",
    "middle" to "Mathison",
    "last" to "Turing",
    "born" to 1912,
)

// Add a new document with a generated ID
db.collection("users")
    .add(user)
    .addOnSuccessListener { documentReference ->
        Log.d(TAG, "DocumentSnapshot added with ID: ${documentReference.id}")
    }
    .addOnFailureListener { e ->
        Log.w(TAG, "Error adding document", e)
    }
DocSnippets.kt

Java

// Create a new user with a first, middle, and last name
Map<String, Object> user = new HashMap<>();
user.put("first", "Alan");
user.put("middle", "Mathison");
user.put("last", "Turing");
user.put("born", 1912);

// Add a new document with a generated ID
db.collection("users")
        .add(user)
        .addOnSuccessListener(new OnSuccessListener<DocumentReference>() {
            @Override
            public void onSuccess(DocumentReference documentReference) {
                Log.d(TAG, "DocumentSnapshot added with ID: " + documentReference.getId());
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                Log.w(TAG, "Error adding document", e);
            }
        });
DocSnippets.java
Python
doc_ref = db.collection("users").document("aturing")
doc_ref.set({"first": "Alan", "middle": "Mathison", "last": "Turing", "born": 1912})
snippets.py

Ler dados usando operações principais

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.

Web

import { collection, getDocs } from "firebase/firestore"; 

const querySnapshot = await getDocs(collection(db, "users"));
querySnapshot.forEach((doc) => {
  console.log(`${doc.id} => ${doc.data()}`);
});
get_all_users.js

Web

db.collection("users").get().then((querySnapshot) => {
    querySnapshot.forEach((doc) => {
        console.log(`${doc.id} => ${doc.data()}`);
    });
});
test.firestore.js
Swift
Observação: esse produto não está disponível para destinos watchOS e de clipes de apps. 
do {
  let snapshot = try await db.collection("users").getDocuments()
  for document in snapshot.documents {
    print("\(document.documentID) => \(document.data())")
  }
} catch {
  print("Error getting documents: \(error)")
}
ViewController.swift

Kotlin

db.collection("users")
    .get()
    .addOnSuccessListener { result ->
        for (document in result) {
            Log.d(TAG, "${document.id} => ${document.data}")
        }
    }
    .addOnFailureListener { exception ->
        Log.w(TAG, "Error getting documents.", exception)
    }
DocSnippets.kt

Java

db.collection("users")
        .get()
        .addOnCompleteListener(new OnCompleteListener<QuerySnapshot>() {
            @Override
            public void onComplete(@NonNull Task<QuerySnapshot> task) {
                if (task.isSuccessful()) {
                    for (QueryDocumentSnapshot document : task.getResult()) {
                        Log.d(TAG, document.getId() + " => " + document.getData());
                    }
                } else {
                    Log.w(TAG, "Error getting documents.", task.getException());
                }
            }
        });
DocSnippets.java
Python
users_ref = db.collection("users")
docs = users_ref.stream()

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

Ler dados usando operações de pipeline

Agora é possível comparar a experiência de consulta do pipeline com a experiência de consulta do Core.

Web

const readDataPipeline = db.pipeline()
  .collection("users");

// Execute the pipeline and handle the result
try {
  const querySnapshot = await execute(readDataPipeline);
  querySnapshot.results.forEach((result) => {
    console.log(`${result.id} => ${result.data()}`);
  });
} catch (error) {
    console.error("Error getting documents: ", error);
}
test.firestore.js
Swift
do {
  // Initialize a Firestore Pipeline instance and specify the "users" collection as the
  // input stage.
  let snapshot = try await db.pipeline()
    .collection("users")
    .execute() // Execute the pipeline to retrieve documents.

  // Iterate through the documents in the pipeline results, similar to a regular query
  // snapshot.
  for result in snapshot.results {
    print("\(result.id ?? "no ID") => \(result.data)")
  }
} catch {
  print("Error getting documents with pipeline: \(error)")
}
PipelineSnippets.swift

Kotlin

val readDataPipeline = db.pipeline()
    .collection("users")

// Execute the pipeline and handle the result
readDataPipeline.execute()
    .addOnSuccessListener { result ->
        for (document in result) {
            println("${document.getId()} => ${document.getData()}")
        }
    }
    .addOnFailureListener { exception ->
        println("Error getting documents: $exception")
    }
DocSnippets.kt

Java

Pipeline readDataPipeline = db.pipeline()
.collection("users");

readDataPipeline.execute()
.addOnSuccessListener(new OnSuccessListener<Pipeline.Snapshot>() {
    @Override
    public void onSuccess(Pipeline.Snapshot snapshot) {
        for (PipelineResult result : snapshot.getResults()) {
            System.out.println(result.getId() + " => " + result.getData());
        }
    }
})
.addOnFailureListener(new OnFailureListener() {
    @Override
    public void onFailure(@NonNull Exception e) {
        System.out.println("Error getting documents: " + e);
    }
});
Python
pipeline = client.pipeline().collection("users")
for result in pipeline.execute():
    print(f"{result.id} => {result.data()}")
firestore_pipelines.py

Proteger seus dados

Se você estiver usando o SDK para Web, Android ou plataformas Apple, utilize o Firebase Authentication e o Cloud Firestore Security Rules para proteger seus dados no Cloud Firestore.

Veja a seguir alguns conjuntos de regras básicas que podem ser usadas para começar. É possível modificar as regras de segurança na guia Regras do console.

Autenticação obrigatória

// Allow read/write access to a document keyed by the user's UID
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{uid} {
      allow read, write: if request.auth != null && request.auth.uid == uid;
    }
  }
}

Modo de produção

// Deny read/write access to all users under any conditions
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if false;
    }
  }
}

Antes de implantar o app da Web, Android ou iOS para produção, tome algumas medidas para garantir que somente seus clientes do app possam acessar os dados do Cloud Firestore. Consulte a documentação do App Check.

Se você estiver usando um dos SDKs do servidor, utilize o Identity and Access Management (IAM) para proteger os dados no Cloud Firestore.

Próximas etapas

Aprofunde seu conhecimento sobre operações principais e de pipeline com os seguintes tópicos: