Esta página foi traduzida pela API Cloud Translation.
Switch to English

Guia de início rápido "Como usar uma biblioteca de cliente da Web ou para dispositivos móveis"

Este guia de início rápido mostra como configurar o Firestore, adicionar e ler dados usando a biblioteca de cliente do Android, iOS ou Web.

Crie um banco de dados Firestore

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

  2. No painel de navegação do Console do Firebase, selecione Firebase e clique em Criar banco de dados para o Firestore.

  3. Selecione o Modo de teste para as regras de segurança do Firestore:

    Modo de teste
    Ideal para dar os primeiros passos com as bibliotecas de cliente de dispositivos móveis e da Web. No entanto, esse modo permite que qualquer pessoa leia e substitua seus dados. Depois do teste, lembre-se de revisar a seção Proteger seus dados.
  4. Selecione um local para seu banco de dados.

    • Essa configuração de localização é o local padrão dos recursos do Google Cloud Platform (GCP) no seu projeto. Esse local será usado para serviços do GCP no projeto que exigem uma configuração de local, especificamente o bucket padrão do Cloud Storage e o aplicativo do App Engine que é obrigatório se você usa o Cloud Scheduler.

    • Se você não conseguir selecionar um local, isso significa que seu projeto já tem um local padrão dos recursos do GCP. Ele foi definido durante a criação do projeto ou na configuração de outro serviço que exigia uma configuração de local.

  5. Clique em Concluído.

Quando você ativa o 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. Adicione as bibliotecas do Firebase e do Firestore ao seu app:
    <script src="https://www.gstatic.com/firebasejs/8.2.2/firebase-app.js"></script>
    <script src="https://www.gstatic.com/firebasejs/8.2.2/firebase-firestore.js"></script>
    O Firestore SDK também está disponível como um pacote npm.
    npm install firebase@8.2.2 --save
    
    Você precisará requisitar manualmente o Firebase e o Firestore.
    const firebase = require("firebase");
    // Required for side-effects
    require("firebase/firestore");
    
iOS
  1. Siga as instruções para adicionar o Firebase ao seu app para iOS.
  2. Adicione o pod do Firestore ao seu Podfile
    pod 'Firebase/Firestore'
    
    # Optionally, include the Swift extensions if you're using Swift.
    pod 'FirebaseFirestoreSwift'
    
  3. Salve o arquivo e execute pod install
Java
Android
  1. Siga as instruções para adicionar o Firebase ao seu app para Android.
  2. Declare a dependência da biblioteca do Firestore no Android no seu arquivo Gradle do módulo (nível do app), geralmente app/build.gradle:
    implementation 'com.google.firebase:firebase-firestore:22.0.1'

    Caso seu app use várias bibliotecas do Firebase, use a Firebase Android BoM (lista de materiais), que garante que as versões de biblioteca do Firebase do app sejam sempre compatíveis.

Kotlin+KTX
Android
  1. Siga as instruções para adicionar o Firebase ao seu app para Android.
  2. Declare a dependência da biblioteca do Firestore no Android no seu arquivo Gradle do módulo (nível do app), geralmente app/build.gradle:
    implementation 'com.google.firebase:firebase-firestore-ktx:22.0.1'

    Caso seu app use várias bibliotecas do Firebase, use a Firebase Android BoM (lista de materiais), que garante que as versões de biblioteca do Firebase do app sejam sempre compatíveis.

Inicializar o Firestore

Como inicializar uma instância do Firestore:

Web
// Initialize Firestore through Firebase
firebase.initializeApp({
  apiKey: '### FIREBASE API KEY ###',
  authDomain: '### FIREBASE AUTH DOMAIN ###',
  projectId: '### CLOUD FIRESTORE PROJECT ID ###'
});

var db = firebase.firestore();
Para manter os dados quando o dispositivo perder a conexão, consulte a documentação Ativar dados off-line.
Swift
import Firebase

FirebaseApp.configure()

let db = Firestore.firestore()
Objective-C
@import Firebase;

// Use Firebase library to configure APIs
[FIRApp configure];

FIRFirestore *defaultFirestore = [FIRFirestore firestore];
  
Java
Android
// Access a Firestore instance from your Activity
  FirebaseFirestore db = FirebaseFirestore.getInstance();
Kotlin+KTX
Android
  // Access a Firestore instance from your Activity
  val db = Firebase.firestore

Adicionar dados

O 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. 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
db.collection("users").add({
    first: "Ada",
    last: "Lovelace",
    born: 1815
})
.then(function(docRef) {
    console.log("Document written with ID: ", docRef.id);
})
.catch(function(error) {
    console.error("Error adding document: ", error);
});
Swift
// Add a new document with a generated ID
var ref: DocumentReference? = nil
ref = db.collection("users").addDocument(data: [
    "first": "Ada",
    "last": "Lovelace",
    "born": 1815
]) { err in
    if let err = err {
        print("Error adding document: \(err)")
    } else {
        print("Document added with ID: \(ref!.documentID)")
    }
}
Objective-C
// Add a new document with a generated ID
__block FIRDocumentReference *ref =
    [[self.db collectionWithPath:@"users"] addDocumentWithData:@{
      @"first": @"Ada",
      @"last": @"Lovelace",
      @"born": @1815
    } completion:^(NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error adding document: %@", error);
      } else {
        NSLog(@"Document added with ID: %@", ref.documentID);
      }
    }];
  
Java
Android
// 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);
            }
        });
Kotlin+KTX
Android
// 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)
    }

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.
db.collection("users").add({
    first: "Alan",
    middle: "Mathison",
    last: "Turing",
    born: 1912
})
.then(function(docRef) {
    console.log("Document written with ID: ", docRef.id);
})
.catch(function(error) {
    console.error("Error adding document: ", error);
});
Swift
// Add a second document with a generated ID.
ref = db.collection("users").addDocument(data: [
    "first": "Alan",
    "middle": "Mathison",
    "last": "Turing",
    "born": 1912
]) { err in
    if let err = err {
        print("Error adding document: \(err)")
    } else {
        print("Document added with ID: \(ref!.documentID)")
    }
}
Objective-C
// Add a second document with a generated ID.
__block FIRDocumentReference *ref =
    [[self.db collectionWithPath:@"users"] addDocumentWithData:@{
      @"first": @"Alan",
      @"middle": @"Mathison",
      @"last": @"Turing",
      @"born": @1912
    } completion:^(NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error adding document: %@", error);
      } else {
        NSLog(@"Document added with ID: %@", ref.documentID);
      }
    }];
  
Java
Android
// 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);
            }
        });
Kotlin+KTX
Android
// 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)
    }

Ler dados

Para verificar rapidamente se você adicionou dados ao Firestore, use o visualizador de dados no Console do Firebase.

Também é possível usar o método get para recuperar a coleção inteira.

Web
db.collection("users").get().then((querySnapshot) => {
    querySnapshot.forEach((doc) => {
        console.log(`${doc.id} => ${doc.data()}`);
    });
});
Swift
db.collection("users").getDocuments() { (querySnapshot, err) in
    if let err = err {
        print("Error getting documents: \(err)")
    } else {
        for document in querySnapshot!.documents {
            print("\(document.documentID) => \(document.data())")
        }
    }
}
Objective-C
[[self.db collectionWithPath:@"users"]
    getDocumentsWithCompletion:^(FIRQuerySnapshot * _Nullable snapshot,
                                 NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error getting documents: %@", error);
      } else {
        for (FIRDocumentSnapshot *document in snapshot.documents) {
          NSLog(@"%@ => %@", document.documentID, document.data);
        }
      }
    }];
  
Java
Android
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());
                }
            }
        });
Kotlin+KTX
Android
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)
        }

Proteja seus dados.

Use o Firebase Authentication e as regras de segurança do Firestore para proteger os dados no Firestore.

Veja a seguir alguns conjuntos de regras básicas que é possível usar para dar os primeiros passos. É possível modificar as regras de segurança na guia Regras no Console do Firebase.

Autenticação obrigatória

// Allow read/write access on all documents to any user signed in to the application
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if request.auth != null;
    }
  }
}

Modo bloqueado

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

Modo de teste

// Allow read/write access to all users under any conditions
// Warning: **NEVER** use this rule set in production; it allows
// anyone to overwrite your entire database.
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if true;
    }
  }
}

Assistir a um tutorial em vídeo

Para orientações detalhadas sobre como começar com as bibliotecas de cliente móveis e Web do Firestore, assista a um dos seguintes tutoriais em vídeo:

Web v8

iOS
Android

Você pode encontrar mais vídeos no canal do Firebase no YouTube.

Próximas etapas

Aprofunde seu conhecimento com os seguintes tópicos: