Guía de inicio rápido para usar una biblioteca cliente del servidor

En esta guía de inicio rápido, se muestra cómo configurar Firestore, agregar datos y leerlos mediante la biblioteca cliente del servidor de C#, Go, Java, Node.js, PHP, Python o Ruby.

Antes de comenzar

  • Accede a tu Cuenta de Google.

    Si todavía no tienes una cuenta, regístrate para obtener una nueva.

  • En la página de selección de proyectos de Cloud Console, selecciona o crea un proyecto de Cloud.

    Ir a la página Selector de proyectos

Crea una base de datos de Firestore en modo nativo

Si se trata de un proyecto nuevo, debes crear una instancia de base de datos de Firestore.

  1. Ve al visualizador de Firestore.

  2. En la pantalla Seleccionar un servicio de base de datos, elige Firestore en modo nativo.

  3. Selecciona una ubicación para tu Firestore.

    Esta configuración es la ubicación predeterminada de los recursos de Google Cloud Platform (GCP) del proyecto. Ten en cuenta que esta ubicación se usará para los servicios de GCP del proyecto que requieren una configuración de ubicación. Específicamente, el depósito predeterminado de Cloud Storage y la app de App Engine (que es obligatoria si usas Cloud Scheduler).

  4. Haz clic en Crear base de datos.

Cuando creas un proyecto de Firestore, también se habilita la API en el Administrador de API de Cloud.

Configura la autenticación

A fin de ejecutar la biblioteca cliente, primero debes configurar la autenticación. Para esto, crea una cuenta de servicio y configura una variable de entorno.

Cloud Console

  1. En Cloud Console, ve a la página Crear una clave de cuenta de servicio.

    Ir a la página Crear clave de la cuenta de servicio
  2. En la lista Cuenta de servicio, selecciona Cuenta de servicio nueva.
  3. Ingresa un nombre en el campo Nombre de cuenta de servicio.
  4. En la lista Función, selecciona Proyecto > Propietario.

    Nota: El campo Función autoriza tu cuenta de servicio para acceder a los recursos. Puedes ver y cambiar este campo más adelante mediante Cloud Console. Si desarrollas una app de producción, especifica permisos más detallados que Proyecto > Propietario. Para obtener más información, consulta Cómo otorgar funciones a las cuentas de servicio.
  5. Haz clic en Crear. Se descargará un archivo JSON que contiene tus claves a tu computadora.

Línea de comandos

Puedes ejecutar los siguientes comandos mediante el SDK de Cloud en tu máquina local o en Cloud Shell.

  1. Crea la cuenta de servicio. Reemplaza [NAME] por un nombre para la cuenta de servicio.

    gcloud iam service-accounts create [NAME]
  2. Otorga permisos a la cuenta de servicio. Reemplaza [PROJECT_ID] por el ID del proyecto.

    gcloud projects add-iam-policy-binding [PROJECT_ID] --member "serviceAccount:[NAME]@[PROJECT_ID].iam.gserviceaccount.com" --role "roles/owner"
    Nota: El campo Función autoriza a la cuenta de servicio a acceder a los recursos. Puedes ver y cambiar este campo más adelante mediante Cloud Console. Si desarrollas una app de producción, especifica permisos más detallados que Proyecto > Propietario. Para obtener más información, consulta Otorga funciones a las cuentas de servicio.
  3. Genera el archivo de claves. Reemplaza [FILE_NAME] por un nombre para el archivo de claves.

    gcloud iam service-accounts keys create [FILE_NAME].json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS para proporcionar credenciales de autenticación al código de la aplicación. Reemplaza [PATH] por la ruta de acceso del archivo JSON que contiene la clave de tu cuenta de servicio. Esta variable solo se aplica a la sesión actual de shell. Por lo tanto, si abres una sesión nueva, deberás volver a configurar la variable.

Linux o macOS

export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

Por ejemplo:

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/my-key.json"

Windows

Con PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

Por ejemplo:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\my-key.json"

Con el símbolo del sistema:

set GOOGLE_APPLICATION_CREDENTIALS=[PATH]

Agrega la biblioteca cliente del servidor a la app

Agrega las dependencias y las bibliotecas cliente necesarias a tu app.

Java

Agrega la biblioteca de Firestore para Java a la app:

  • Con Gradle:
    compile 'com.google.cloud:google-cloud-firestore:1.32.0'
    
  • Con Maven:
    <dependencyManagement>
      <dependencies>
        <dependency>
          <groupId>com.google.cloud</groupId>
          <artifactId>libraries-bom</artifactId>
          <version>12.0.0</version>
          <type>pom</type>
          <scope>import</scope>
        </dependency>
      </dependencies>
    </dependencyManagement>
    
    <dependencies>
      <dependency>
        <groupId>com.google.cloud</groupId>
        <artifactId>google-cloud-firestore</artifactId>
      </dependency>
  • Cómo usar un IDE:

    Si usas IntelliJ o Eclipse, puedes agregar bibliotecas cliente a tu proyecto con los siguientes complementos IDE:

    Los complementos brindan funcionalidades adicionales, como administración de claves para las cuentas de servicio. Consulta la documentación de cada complemento para obtener más detalles.

Python

Agrega la biblioteca de Firestore para Python a la app:

pip install --upgrade google-cloud-firestore

Node.js

Agrega la biblioteca de Firestore para Node.js a la app:

npm install --save @google-cloud/firestore
Go

Instala la biblioteca de Firestore para Go:

go get cloud.google.com/go/firestore

Agrega la biblioteca de Firestore para Go a la app:

import "cloud.google.com/go/firestore"
PHP
  1. Instala y habilita la extensión de gRPC para PHP, que necesitarás a fin de usar la biblioteca cliente.
  2. Agrega la biblioteca de Firestore para PHP a la app:
    composer require google/cloud-firestore
C#
  1. Agrega la biblioteca de Firestore para C# a la app en el archivo .csproj:
    <ItemGroup>
      <PackageReference Include="Google.Cloud.Firestore" Version="1.1.0-beta01" />
    </ItemGroup>
  2. Agrega lo siguiente al archivo Program.cs:
    using Google.Cloud.Firestore;
Ruby
  1. Agrega la biblioteca de Firestore para Ruby a la app en el archivo Gemfile:
    gem "google-cloud-firestore"
  2. Instala dependencias del Gemfile con el siguiente comando:
    bundle install

Inicializa Firestore

Inicializa una instancia de 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."

Agrega datos

Firestore almacena datos en documentos, que se almacenan en colecciones. Firestore crea colecciones y documentos de forma implícita la primera vez que agregas datos al documento. No es necesario que crees colecciones o documentos de forma explícita.

Crea una colección nueva y un documento con el siguiente código de ejemplo.

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

Ahora agrega otro documento a la colección users. Observa que este documento incluye un par clave-valor (segundo nombre) que no aparece en el primer documento. Los documentos de una colección pueden contener diferentes conjuntos de información.

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

Leer datos

Para verificar de manera rápida que agregaste datos a Firestore, usa el visualizador de datos en Firebase console.

También puedes usar el método get para recuperar toda la colección.

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
  

Próximos pasos

Profundiza tus conocimientos con los siguientes temas:

  • Modelo de datos: Obtén más información sobre cómo se estructuran los datos en Firestore, incluidos los datos jerárquicos y las subcolecciones.
  • Agrega datos: Obtén más información sobre la creación y la actualización de datos en Firestore.
  • Obtén datos: Obtén más información sobre cómo recuperar datos.
  • Haz consultas simples y compuestas: Obtén información sobre cómo ejecutar consultas simples y compuestas.
  • Ordena y limita consultas: Obtén información sobre cómo ordenar y limitar los datos que muestran las consultas.