Esta página se ha traducido con Cloud Translation API.

Empezar a usar la API de Firestore en modo Datastore

En esta página se propone un breve ejercicio para crear una aplicación de lista de tareas de línea de comandos con la API de Firestore en modo Datastore. La aplicación TaskList almacena, crea listas, actualiza y elimina tareas.

Requisitos previos

Capacidad para escribir y ejecutar una aplicación de línea de comandos en los lenguajes de programación que se usan en este tema
Además de tener conocimientos básicos sobre cómo desarrollar aplicaciones, debes poder descargar e instalar bibliotecas adicionales antes de intentar completar este tutorial.
Un proyecto de Google Cloud con la API del modo Datastore habilitada
Las aplicaciones que usan el modo Datastore están asociadas a un proyecto de Google Cloud con la API del modo Datastore habilitada. Este proyecto proporciona las credenciales de autenticación que usas en tu aplicación para identificarla en Google y autorizar su uso de la API del modo Datastore.
Sigue estas instrucciones para crear un proyecto, habilitar el modo Datastore API y configurar tu entorno de desarrollo local con credenciales de autenticación mediante el comando gcloud auth login. Anota el ID del proyecto, que usarás más adelante.

Instalación y configuración

Instala las bibliotecas de cliente y configura los ajustes adicionales de tu entorno de desarrollo.

C#

Asegúrate de tener instalado Visual Studio (versión 2013 o posterior).
Descarga la aplicación de ejemplo TaskList del repositorio de ejemplos.
Extrae los archivos del archivo ZIP en un directorio de la carpeta Documentos.
En Visual Studio, abre el archivo dotnet-docs-samples-master\datastore\api\Datastore.sln.
En la ventana Explorador de soluciones de Visual Studio, haz clic con el botón derecho en el proyecto TaskList y elige Establecer como proyecto de inicio.
Vuelve a hacer clic con el botón derecho en el proyecto TaskList y elige Propiedades.
En la ventana Propiedades, haga clic en Depurar y escriba el ID de su Google Cloud proyecto en el cuadro Argumentos de línea de comandos:.
Haz clic en Archivo y, a continuación, en Guardar para guardar los cambios.
Ejecuta la aplicación. Pulsa F5 en el teclado.

Go

Clona la aplicación de ejemplo TaskList.

go get github.com/GoogleCloudPlatform/golang-samples/datastore/tasks

Cambia al directorio donde hayas clonado el ejemplo:

cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/datastore/tasks

En el símbolo del sistema, ejecuta el siguiente comando, donde <project-id> es el ID de tu proyecto Google Cloud .
```
export DATASTORE_PROJECT_ID=<project-id>
```
(Usuarios de Windows: usen set en lugar de export).
Ejecuta la aplicación.
```
go run tasks.go
```

Java

Asegúrate de que tienes instalados Maven y Java (versión 8 o posterior).
Descarga la aplicación de ejemplo TaskList del repositorio de ejemplos.
En el símbolo del sistema, extrae la descarga:
```
unzip main.zip
```
Cambia de directorio a la aplicación TaskList:
```
cd java-datastore-main/samples/snippets
```
Ejecuta lo siguiente, donde <project-id> es el ID de tu Google Cloud proyecto.
```
gcloud config set project <project-id>
```

Compila y ejecuta la aplicación.

mvn clean compile
mvn exec:java -Dexec.mainClass="com.google.datastore.snippets.TaskList"

Node.js

Prepara tu entorno para el desarrollo de Node.js.
Descarga la aplicación de ejemplo TaskList del repositorio de ejemplos.
Extrae la descarga:
```
unzip master.zip
```
Cambia de directorio a la aplicación TaskList:
```
cd nodejs-datastore-master/samples
```
Instala las dependencias y vincula la aplicación:
```
npm install
```
En el símbolo del sistema, ejecuta el siguiente comando, donde <project-id> es el ID de tu proyecto Google Cloud .
```
export GCLOUD_PROJECT=<project-id>
```
(Usuarios de Windows: usen set en lugar de export).
Ejecuta la aplicación.
```
node tasks.js
```

PHP

Asegúrate de que tienes instalados PHP (versión 5.6 o posterior) y Composer.
Descarga la aplicación de ejemplo TaskList del repositorio de ejemplos.
Extrae la descarga:
```
unzip master.zip
```

Cambia de directorio a la aplicación TaskList:

cd php-docs-samples-master/datastore/tutorial

Instala las dependencias.
```
composer install
```
Ejecuta la aplicación.
```
php src/list_tasks.php
```

Python

Asegúrate de que tienes instalados Python (versión 2.7.9 o posterior), pip y virtualenv.

Activa una sesión de virtualenv.

virtualenv venv
source venv/bin/activate

Descarga la aplicación de ejemplo TaskList del repositorio de ejemplos.
Extrae la descarga:
```
unzip master.zip
```

Cambia de directorio a la aplicación TaskList:

cd python-docs-samples-master/datastore/cloud-client

Instala las dependencias:
```
pip install -r requirements.txt
```
Ejecuta la aplicación. Usa el ID de tu proyecto de Google Cloud para <project-id>.
```
python tasks.py new project-id
```

Ruby

Asegúrate de que tienes instalados Ruby y Bundler.
Descarga la aplicación de ejemplo TaskList del repositorio de ejemplos.
Extrae la descarga:
```
unzip master.zip
```

Cambia de directorio a la aplicación TaskList:

cd google-cloud-ruby-master/google-cloud-datastore/samples

Instala las dependencias:
```
bundle install
```
En el símbolo del sistema, ejecuta el siguiente comando, donde <project-id> es el ID de tu proyecto Google Cloud .
```
export GOOGLE_CLOUD_PROJECT=<project-id>
```
(Usuarios de Windows: usen set en lugar de export).
Ejecuta la aplicación.
```
bundle exec ruby tasks.rb
```

Crear un objeto de servicio autorizado

Para hacer solicitudes autenticadas a las APIs de Google mediante las bibliotecas de cliente de las APIs de Google, debes hacer lo siguiente: Google Cloud

Obtén la credencial que se va a usar en las solicitudes.
Crea un objeto de servicio que use esa credencial.

Después, puedes hacer llamadas a la API llamando a métodos en el objeto de servicio del modo Datastore.

En este ejemplo, obtendrás las credenciales predeterminadas de la aplicación del entorno y las pasarás como argumento para crear el objeto de servicio.

Esta es la llamada para crear el objeto de servicio autorizado en el modo Datastore:

C#

Para saber cómo instalar y usar la biblioteca de cliente de Cloud Datastore, consulta las bibliotecas de cliente de Cloud Datastore. Para obtener más información, consulta la documentación de referencia de la API C# de Cloud Datastore.

Para autenticarte en Cloud Datastore, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.

// Create an authorized Datastore service using Application Default Credentials.
_db = DatastoreDb.Create(projectId);
// Create a Key factory to construct keys associated with this project.
_keyFactory = _db.CreateKeyFactory("Task");

Go

import (
	"context"
	"log"

	"cloud.google.com/go/datastore"
)

func createClient(projectID string) (*datastore.Client, error) {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectID)
	if err != nil {
		log.Fatalf("Could not create datastore client: %v", err)
	}
	// Note: call the following from main() to ensure the client
	// properly frees all resources.
	// defer client.Close()
	return client, nil
}

Java

// Create an authorized Datastore service using Application Default Credentials.
private final Datastore datastore = DatastoreOptions.getDefaultInstance().getService();

// Create a Key factory to construct keys associated with this project.
private final KeyFactory keyFactory = datastore.newKeyFactory().setKind("Task");

Node.js

// By default, the client will authenticate using the service account file
// specified by the GOOGLE_APPLICATION_CREDENTIALS environment variable and use
// the project specified by the GCLOUD_PROJECT environment variable. See
// https://googlecloudplatform.github.io/google-cloud-node/#/docs/datastore/latest/guides/authentication
const {Datastore} = require('@google-cloud/datastore');

// Creates a client
const datastore = new Datastore();

PHP

use Google\Cloud\Datastore\DatastoreClient;

/**
 * Create a Cloud Datastore client.
 *
 * @param string $projectId The Google Cloud project ID.
 */
function build_service(string $projectId)
{
    $datastore = new DatastoreClient(['projectId' => $projectId]);
    return $datastore;
}

Python

from google.cloud import datastore

def create_client(project_id):
    return datastore.Client(project_id)

Ruby

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

Almacenamiento de datos

Los objetos del modo Datastore se denominan entidades y cada entidad es de un tipo concreto. La aplicación TaskList almacenará entidades de tipo Task con las siguientes propiedades:

description: cadena especificada por el usuario como descripción de la tarea
created: fecha en la que se creó la tarea.
done: valor booleano que indica si la tarea se ha completado.

Cuando el usuario añade una tarea, la aplicación TaskList crea una Task entidad con los valores de las propiedades que hemos indicado anteriormente:

C#

/// <summary>
///  Adds a task entity to the Datastore
/// </summary>
/// <param name="description">The task description.</param>
/// <returns>The key of the entity.</returns>
Key AddTask(string description)
{
    Entity task = new Entity()
    {
        Key = _keyFactory.CreateIncompleteKey(),
        ["description"] = new Value()
        {
            StringValue = description,
            ExcludeFromIndexes = true
        },
        ["created"] = DateTime.UtcNow,
        ["done"] = false
    };
    return _db.Insert(task);
}

Go

import (
	"context"
	"log"
	"time"

	"cloud.google.com/go/datastore"
)

// Task is the model used to store tasks in the datastore.
type Task struct {
	Desc    string    `datastore:"description"`
	Created time.Time `datastore:"created"`
	Done    bool      `datastore:"done"`
	id      int64     // The integer ID used in the datastore.
}

// AddTask adds a task with the given description to the datastore,
// returning the key of the newly created entity.
func AddTask(projectID string, desc string) (*datastore.Key, error) {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectID)
	if err != nil {
		log.Fatalf("Could not create datastore client: %v", err)
	}
	defer client.Close()
	task := &Task{
		Desc:    desc,
		Created: time.Now(),
	}
	key := datastore.IncompleteKey("Task", nil)
	return client.Put(ctx, key, task)

}

Java

/**
 * Adds a task entity to the Datastore.
 *
 * @param description The task description
 * @return The {@link Key} of the entity
 * @throws DatastoreException if the ID allocation or put fails
 */
Key addTask(String description) {
  Key key = datastore.allocateId(keyFactory.newKey());
  Entity task =
      Entity.newBuilder(key)
          .set(
              "description",
              StringValue.newBuilder(description).setExcludeFromIndexes(true).build())
          .set("created", Timestamp.now())
          .set("done", false)
          .build();
  datastore.put(task);
  return key;
}

Node.js

async function addTask(description) {
  const taskKey = datastore.key('Task');
  const entity = {
    key: taskKey,
    data: [
      {
        name: 'created',
        value: new Date().toJSON(),
      },
      {
        name: 'description',
        value: description,
        excludeFromIndexes: true,
      },
      {
        name: 'done',
        value: false,
      },
    ],
  };

  try {
    await datastore.save(entity);
    console.log(`Task ${taskKey.id} created successfully.`);
  } catch (err) {
    console.error('ERROR:', err);
  }
}

PHP

use Google\Cloud\Datastore\DatastoreClient;

/**
 * Create a new task with a given description.
 *
 * @param string $projectId The Google Cloud project ID.
 * @param string $description
 */
function add_task(string $projectId, string $description)
{
    $datastore = new DatastoreClient(['projectId' => $projectId]);

    $taskKey = $datastore->key('Task');
    $task = $datastore->entity(
        $taskKey,
        [
            'created' => new DateTime(),
            'description' => $description,
            'done' => false
        ],
        ['excludeFromIndexes' => ['description']]
    );
    $datastore->insert($task);
    printf('Created new task with ID %d.' . PHP_EOL, $task->key()->pathEnd()['id']);
}

Python

from google.cloud import datastore

def add_task(client: datastore.Client, description: str):
    # Create an incomplete key for an entity of kind "Task". An incomplete
    # key is one where Datastore will automatically generate an Id
    key = client.key("Task")

    # Create an unsaved Entity object, and tell Datastore not to index the
    # `description` field
    task = datastore.Entity(key, exclude_from_indexes=("description",))

    # Apply new field values and save the Task entity to Datastore
    task.update(
        {
            "created": datetime.datetime.now(tz=datetime.timezone.utc),
            "description": description,
            "done": False,
        }
    )
    client.put(task)
    return task.key

Ruby

def add_task description
  require "google/cloud/datastore"

  datastore = Google::Cloud::Datastore.new

  task = datastore.entity "Task" do |t|
    t["description"] = description
    t["created"]     = Time.now
    t["done"]        = false
    t.exclude_from_indexes! "description", true
  end

  datastore.save task

  puts task.key.id

  task.key.id
end

En esta aplicación, también proporcionamos un método para actualizar la propiedad done para indicar que la tarea se ha completado:

C#

/// <summary>
/// Marks a task entity as done.
/// </summary>
/// <param name="id">The ID of the task entity as given by Key.</param>
/// <returns>true if the task was found.</returns>
bool MarkDone(long id)
{
    using (var transaction = _db.BeginTransaction())
    {
        Entity task = transaction.Lookup(_keyFactory.CreateKey(id));
        if (task != null)
        {
            task["done"] = true;
            transaction.Update(task);
        }
        transaction.Commit();
        return task != null;
    }
}

Go

import (
	"context"
	"log"

	"cloud.google.com/go/datastore"
)

// MarkDone marks the task done with the given ID.
func MarkDone(projectID string, taskID int64) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectID)
	if err != nil {
		log.Fatalf("Could not create datastore client: %v", err)
	}
	defer client.Close()
	// Create a key using the given integer ID.
	key := datastore.IDKey("Task", taskID, nil)

	// In a transaction load each task, set done to true and store.
	_, err = client.RunInTransaction(ctx, func(tx *datastore.Transaction) error {
		var task Task
		if err := tx.Get(key, &task); err != nil {
			return err
		}
		task.Done = true
		_, err := tx.Put(key, &task)
		return err
	})
	return err
}

Java

/**
 * Marks a task entity as done.
 *
 * @param id The ID of the task entity as given by {@link Key#id()}
 * @return true if the task was found, false if not
 * @throws DatastoreException if the transaction fails
 */
boolean markDone(long id) {
  Transaction transaction = datastore.newTransaction();
  try {
    Entity task = transaction.get(keyFactory.newKey(id));
    if (task != null) {
      transaction.put(Entity.newBuilder(task).set("done", true).build());
    }
    transaction.commit();
    return task != null;
  } finally {
    if (transaction.isActive()) {
      transaction.rollback();
    }
  }
}

Node.js

async function markDone(taskId) {
  const transaction = datastore.transaction();
  const taskKey = datastore.key(['Task', datastore.int(taskId)]);

  try {
    await transaction.run();
    const [task] = await transaction.get(taskKey);
    task.done = true;
    transaction.save({
      key: taskKey,
      data: task,
    });
    await transaction.commit();
    console.log(`Task ${taskId} updated successfully.`);
  } catch (err) {
    await transaction.rollback();
  }
}

PHP

use Google\Cloud\Datastore\DatastoreClient;

/**
 * Mark a task with a given id as done.
 *
 * @param string $projectId The Google Cloud project ID.
 * @param string $taskId
 */
function mark_done(string $projectId, string $taskId)
{
    $datastore = new DatastoreClient(['projectId' => $projectId]);

    $taskKey = $datastore->key('Task', $taskId);
    $transaction = $datastore->transaction();
    $task = $transaction->lookup($taskKey);
    $task['done'] = true;
    $transaction->upsert($task);
    $transaction->commit();
    printf('Task %d updated successfully.' . PHP_EOL, $taskId);
}

Python

from google.cloud import datastore

def mark_done(client: datastore.Client, task_id: str | int):
    with client.transaction():
        # Create a key for an entity of kind "Task", and with the supplied
        # `task_id` as its Id
        key = client.key("Task", task_id)
        # Use that key to load the entity
        task = client.get(key)

        if not task:
            raise ValueError(f"Task {task_id} does not exist.")

        # Update a field indicating that the associated
        # work has been completed
        task["done"] = True

        # Persist the change back to Datastore
        client.put(task)

Ruby

def mark_done task_id
  require "google/cloud/datastore"

  datastore = Google::Cloud::Datastore.new

  task = datastore.find "Task", task_id

  task["done"] = true

  datastore.save task
end

Este es el método para eliminar una entidad Task mediante la clave de la entidad Task:

C#

/// <summary>
/// Deletes a task entity.
/// </summary>
/// <param name="id">The ID of the task entity as given by Key.</param>
void DeleteTask(long id)
{
    _db.Delete(_keyFactory.CreateKey(id));
}

Go

import (
	"context"
	"log"

	"cloud.google.com/go/datastore"
)

// DeleteTask deletes the task with the given ID.
func DeleteTask(projectID string, taskID int64) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectID)
	if err != nil {
		log.Fatalf("Could not create datastore client: %v", err)
	}
	return client.Delete(ctx, datastore.IDKey("Task", taskID, nil))
}

Java

/**
 * Deletes a task entity.
 *
 * @param id The ID of the task entity as given by {@link Key#id()}
 * @throws DatastoreException if the delete fails
 */
void deleteTask(long id) {
  datastore.delete(keyFactory.newKey(id));
}

Node.js

async function deleteTask(taskId) {
  const taskKey = datastore.key(['Task', datastore.int(taskId)]);

  await datastore.delete(taskKey);
  console.log(`Task ${taskId} deleted successfully.`);
}

PHP

use Google\Cloud\Datastore\DatastoreClient;

/**
 * Delete a task with a given id.
 *
 * @param string $projectId The Google Cloud project ID.
 * @param string $taskId
 */
function delete_task(string $projectId, string $taskId)
{
    $datastore = new DatastoreClient(['projectId' => $projectId]);

    $taskKey = $datastore->key('Task', $taskId);
    $datastore->delete($taskKey);

    printf('Task %d deleted successfully.' . PHP_EOL, $taskId);
}

Python

from google.cloud import datastore

def delete_task(client: datastore.Client, task_id: str | int):
    # Create a key for an entity of kind "Task", and with the supplied
    # `task_id` as its Id
    key = client.key("Task", task_id)
    # Use that key to delete its associated document, if it exists
    client.delete(key)

Ruby

def delete_task task_id
  require "google/cloud/datastore"

  datastore = Google::Cloud::Datastore.new

  task = datastore.find "Task", task_id

  datastore.delete task
end

Ejecutar una consulta

Además de obtener entidades del modo Datastore directamente por sus claves, una aplicación puede realizar una consulta para obtenerlas por los valores de sus propiedades. Una consulta típica incluye lo siguiente:

Tipo de entidad al que se aplica la consulta.
Cero o más filtros, por ejemplo, para seleccionar tipos cuyas propiedades coincidan con un valor.
Cero o más criterios de ordenación para secuenciar los resultados.

En esta aplicación, consultaremos el modo Datastore para obtener entidades Task ordenadas por hora de creación:

C#

/// <summary>
/// Returns a list of all task entities in ascending order of creation time.
/// </summary>
IEnumerable<Entity> ListTasks()
{
    Query query = new Query("Task")
    {
        Order = { { "created", PropertyOrder.Types.Direction.Descending } }
    };
    return _db.RunQuery(query).Entities;
}

Go

import (
	"context"
	"log"

	"cloud.google.com/go/datastore"
)

// ListTasks returns all the tasks in ascending order of creation time.
func ListTasks(projectID string) ([]*Task, error) {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectID)
	if err != nil {
		log.Fatalf("Could not create datastore client: %v", err)
	}

	var tasks []*Task
	// Create a query to fetch all Task entities, ordered by "created".
	query := datastore.NewQuery("Task").Order("created")
	keys, err := client.GetAll(ctx, query, &tasks)
	if err != nil {
		return nil, err
	}

	// Set the id field on each Task from the corresponding key.
	for i, key := range keys {
		tasks[i].id = key.ID
	}

	return tasks, nil
}

Java

/**
 * Returns a list of all task entities in ascending order of creation time.
 *
 * @throws DatastoreException if the query fails
 */
Iterator<Entity> listTasks() {
  Query<Entity> query =
      Query.newEntityQueryBuilder().setKind("Task").setOrderBy(OrderBy.asc("created")).build();
  return datastore.run(query);
}

Node.js

async function listTasks() {
  const query = datastore.createQuery('Task').order('created');

  const [tasks] = await datastore.runQuery(query);
  console.log('Tasks:');
  tasks.forEach(task => {
    const taskKey = task[datastore.KEY];
    console.log(taskKey.id, task);
  });
}

PHP

use Google\Cloud\Datastore\DatastoreClient;

/**
 * Return an iterator for all the tasks in ascending order of creation time.
 *
 * @param string $projectId The Google Cloud project ID.
 */
function list_tasks(string $projectId)
{
    $datastore = new DatastoreClient(['projectId' => $projectId]);

    $query = $datastore->query()
        ->kind('Task')
        ->order('created');
    $result = $datastore->runQuery($query);
    /* @var Entity $task */
    foreach ($result as $index => $task) {
        printf('ID: %s' . PHP_EOL, $task->key()->pathEnd()['id']);
        printf('  Description: %s' . PHP_EOL, $task['description']);
        printf('  Status: %s' . PHP_EOL, $task['done'] ? 'done' : 'created');
        printf('  Created: %s' . PHP_EOL, $task['created']->format('Y-m-d H:i:s e'));
        print(PHP_EOL);
    }
}

Python

from google.cloud import datastore

def list_tasks(client: datastore.Client):
    # Create a query against all of your objects of kind "Task"
    query = client.query(kind="Task")
    query.order = ["created"]

    return list(query.fetch())

Ruby

def list_tasks
  require "google/cloud/datastore"

  datastore = Google::Cloud::Datastore.new

  query = datastore.query("Task").order("created")
  tasks = datastore.run query

  tasks.each do |t|
    puts t["description"]
    puts t["done"] ? "  Done" : "  Not Done"
    puts "  ID: #{t.key.id}"
  end
end

Pasos siguientes

En este tutorial solo se explican los pasos más básicos necesarios para hacer llamadas a la API del modo Datastore desde una aplicación de línea de comandos. El modo Datastore admite transacciones ACID rápidas y altamente escalables, consultas tipo SQL, índices y más.

Para obtener más información sobre las funciones del modo Datastore, consulta ¿Qué es Firestore en modo Datastore?
Para obtener información sobre cómo usar el emulador del modo Datastore mientras desarrollas tu aplicación, consulta Emulador del modo Datastore.

Empezar a usar la API de Firestore en modo Datastore Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Requisitos previos

Instalación y configuración

C#

Go

Java

Node.js

PHP

Python

Ruby

Crear un objeto de servicio autorizado

C#

Go

Java

Node.js

PHP

Python

Ruby

Almacenamiento de datos

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

Ejecutar una consulta

C#

Go

Java

Node.js

PHP

Python

Ruby

Pasos siguientes

Empezar a usar la API de Firestore en modo Datastore