Este guia de início rápido mostra como configurar o Firestore, adicionar e ler dados usando a biblioteca de cliente do servidor C#, Go, Java, Node.js, PHP, Python ou Ruby.
Antes de começar
-
Faça login na sua conta do Google.
Se você ainda não tiver uma, inscreva-se.
-
No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.
Criar um banco de dados do Firestore no modo nativo
Caso esteja trabalhando em um novo projeto, você precisará criar uma instância de banco de dados do Firestore.
Na tela Selecionar um serviço de banco de dados, escolha Firestore no modo nativo.
Selecione um local para o Firestore.
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 localização. No caso, especificamente, o bucket padrão do Cloud Storage e o aplicativo do App Engine, que é obrigatório se você usa o Cloud Scheduler.
Clique em Criar banco de dados.
Ao criar um projeto do Firestore, a API no Cloud API Manager é ativada.
Configurar a autenticação
Para executar a biblioteca de cliente, você precisa primeiro configurar a autenticação. Para isso, crie uma conta de serviço e defina uma variável de ambiente.
Console do Cloud
-
No Console do Cloud, acesse a página Criar chave da conta de serviço.
Acessar página "Criar chave da conta de serviço" - Na lista Conta de serviço, selecione Nova conta de serviço.
- No campo Nome da conta de serviço, insira um nome.
Na lista Papel, selecione Projeto > Proprietário.
- Clique em Criar. O download de um arquivo JSON que contém sua chave é feito no seu computador.
Linha de comando
É possível executar os seguintes comandos usando o SDK do Cloud na máquina local ou no Cloud Shell.
-
Crie a conta de serviço. Substitua NAME por um nome para a conta de serviço.
gcloud iam service-accounts create NAME
-
Conceda permissões à conta de serviço. Substitua PROJECT_ID pelo ID do seu projeto.
gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/owner"
-
Gere o arquivo de chave. Substitua FILE_NAME pelo nome do arquivo de chave.
gcloud iam service-accounts keys create FILE_NAME.json --iam-account=NAME@PROJECT_ID.iam.gserviceaccount.com
Forneça credenciais de autenticação ao código do aplicativo
definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS
.
Substitua [PATH] pelo caminho do arquivo JSON que contém sua
chave da conta de serviço. Essa variável só se aplica à sessão de shell atual.
Assim, se você abrir uma nova sessão, precisará definir a variável novamente.
Linux ou macOS
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Exemplo:
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/my-key.json"
Windows
Com o PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Exemplo:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\my-key.json"
Com prompt de comando:
set GOOGLE_APPLICATION_CREDENTIALS=[PATH]
Adicionar a biblioteca de cliente do servidor ao aplicativo
Adicione as dependências e as bibliotecas de cliente necessárias ao app.
Java
Adicione a biblioteca Java do Firestore ao aplicativo:
-
Com o Gradle:
compile 'com.google.cloud:google-cloud-firestore:1.32.0'
-
Com o Maven:
<dependencyManagement> <dependencies> <dependency> <groupId>com.google.cloud</groupId> <artifactId>libraries-bom</artifactId> <version>16.3.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>com.google.cloud</groupId> <artifactId>google-cloud-firestore</artifactId> </dependency>
- Como usar um ambiente de desenvolvimento integrado:
Se estiver usando o IntelliJ ou o Eclipse, será possível adicionar bibliotecas de cliente ao projeto usando estes plug-ins de ambiente de desenvolvimento integrado:
Os plug-ins também oferecem outras funcionalidades, como gerenciamento de chaves de contas de serviço. Para mais detalhes, consulte a documentação de cada plug-in.
Python
Adicione a biblioteca Python do Firestore ao aplicativo:
pip install --upgrade google-cloud-firestore
Node.js
Adicione a biblioteca Node.js do Firestore ao aplicativo:
npm install --save @google-cloud/firestore
Go
Instale a biblioteca do Firestore Go:
go get cloud.google.com/go/firestore
Adicione a biblioteca do Firestore Go ao aplicativo:
import "cloud.google.com/go/firestore"
PHP
- Instale e ative a extensão gRPC para PHP, necessária para usar a biblioteca de cliente.
-
Adicione a biblioteca PHP do Firestore ao aplicativo:
composer require google/cloud-firestore
C#
-
Adicione a biblioteca C# do Firestore ao arquivo
.csproj
:<ItemGroup> <PackageReference Include="Google.Cloud.Firestore" Version="1.1.0-beta01" /> </ItemGroup>
- Adicione a instrução a seguir ao seu arquivo
Program.cs
:using Google.Cloud.Firestore;
Ruby
-
Adicione a biblioteca Ruby do Firestore ao aplicativo no
Gemfile
:gem "google-cloud-firestore"
-
Instale as dependências do seu
Gemfile
usando:bundle install
Como inicializar o Firestore
Como inicializar uma instância do Firestore:
Java
import com.google.cloud.firestore.Firestore; import com.google.cloud.firestore.FirestoreOptions; FirestoreOptions firestoreOptions = FirestoreOptions.getDefaultInstance().toBuilder() .setProjectId(projectId) .setCredentials(GoogleCredentials.getApplicationDefault()) .build(); Firestore db = firestoreOptions.getService();
Python
from google.cloud import firestore # Project ID is determined by the GCLOUD_PROJECT environment variable db = firestore.Client()
Node.js
const Firestore = require('@google-cloud/firestore'); const db = new Firestore({ projectId: 'YOUR_PROJECT_ID', keyFilename: '/path/to/keyfile.json', });
Go
import ( "context" "fmt" "log" "google.golang.org/api/iterator" "cloud.google.com/go/firestore" ) func createClient(ctx context.Context) *firestore.Client { // Sets your Google Cloud Platform project ID. projectID := "YOUR_PROJECT_ID" client, err := firestore.NewClient(ctx, projectID) if err != nil { log.Fatalf("Failed to create client: %v", err) } // Close client when done with // defer client.Close() return client }
PHP
use Google\Cloud\Firestore\FirestoreClient; /** * Initialize Cloud Firestore with default project ID. * ``` * initialize(); * ``` */ function initialize() { // Create the Cloud Firestore client $db = new FirestoreClient(); printf('Created Cloud Firestore client with default project ID.' . PHP_EOL); }
C#
FirestoreDb db = FirestoreDb.Create(project); Console.WriteLine("Created Cloud Firestore client with project ID: {0}", project);
Ruby
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new project_id: project_id puts "Created Cloud Firestore client with given project ID."
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.
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(u'users').document(u'alovelace') doc_ref.set({ u'first': u'Ada', u'last': u'Lovelace', u'born': 1815 })
Node.js
const docRef = db.collection('users').doc('alovelace'); await docRef.set({ first: 'Ada', last: 'Lovelace', born: 1815 });
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) }
PHP
$docRef = $db->collection('users')->document('lovelace'); $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);
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."
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());
Python
doc_ref = db.collection(u'users').document(u'aturing') doc_ref.set({ u'first': u'Alan', u'middle': u'Mathison', u'last': u'Turing', u'born': 1912 })
Node.js
const aTuringRef = db.collection('users').doc('aturing'); await aTuringRef.set({ 'first': 'Alan', 'middle': 'Mathison', 'last': 'Turing', 'born': 1912 });
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) }
PHP
$docRef = $db->collection('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);
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."
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.
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(u'users') docs = users_ref.stream() 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()); });
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()) }
PHP
$usersRef = $db->collection('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(); }
Ruby
users_ref = firestore.col collection_path users_ref.get do |user| puts "#{user.document_id} data: #{user.data}." end
A seguir
Aprofunde seu conhecimento com os seguintes tópicos:
- Modelo de dados: saiba mais sobre como os dados são estruturados no Firestore, incluindo dados hierárquicos e subcoleções.
- Adicionar dados: saiba mais sobre como criar e atualizar dados no Firestore.
- Recuperar dados: saiba mais sobre como recuperar dados.
- Executar consultas simples e compostas: saiba como executar consultas simples e compostas.
- Ordenar e limitar consultas: saiba como ordenar e limitar os dados retornados por suas consultas.