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

Transacciones

Una transacción es un conjunto de operaciones en una o varias entidades. Se garantiza que cada transacción es atómica, lo que significa que las transacciones nunca se aplican parcialmente. Se aplican todas las operaciones de la transacción o no se aplica ninguna.

Usar transacciones

Las transacciones caducan al cabo de 270 segundos o si permanecen inactivas durante 60 segundos.

Una operación puede fallar en los siguientes casos:

Se han intentado realizar demasiadas modificaciones simultáneas en la misma entidad.
La transacción supera un límite de recursos.
La base de datos en modo Datastore detecta un error interno.

En todos estos casos, la API Datastore devuelve un error.

Las transacciones son una función opcional. No es obligatorio usar transacciones para realizar operaciones en la base de datos.

Una aplicación puede ejecutar un conjunto de instrucciones y operaciones en una sola transacción, de forma que, si alguna instrucción u operación genera una excepción, no se aplique ninguna de las operaciones de la base de datos del conjunto. La aplicación define las acciones que se deben realizar en la transacción.

En el siguiente fragmento se muestra cómo realizar una transacción. Transfiere dinero de una cuenta a otra.

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.

private void TransferFunds(Key fromKey, Key toKey, long amount)
{
    using (var transaction = _db.BeginTransaction())
    {
        var entities = transaction.Lookup(fromKey, toKey);
        entities[0]["balance"].IntegerValue -= amount;
        entities[1]["balance"].IntegerValue += amount;
        transaction.Update(entities);
        transaction.Commit();
    }
}

Go

type BankAccount struct {
	Balance int
}

const amount = 50
keys := []*datastore.Key{to, from}
tx, err := client.NewTransaction(ctx)
if err != nil {
	log.Fatalf("client.NewTransaction: %v", err)
}
accs := make([]BankAccount, 2)
if err := tx.GetMulti(keys, accs); err != nil {
	tx.Rollback()
	log.Fatalf("tx.GetMulti: %v", err)
}
accs[0].Balance += amount
accs[1].Balance -= amount
if _, err := tx.PutMulti(keys, accs); err != nil {
	tx.Rollback()
	log.Fatalf("tx.PutMulti: %v", err)
}
if _, err = tx.Commit(); err != nil {
	log.Fatalf("tx.Commit: %v", err)
}

Java

void transferFunds(Key fromKey, Key toKey, long amount) {
  Transaction txn = datastore.newTransaction();
  try {
    List<Entity> entities = txn.fetch(fromKey, toKey);
    Entity from = entities.get(0);
    Entity updatedFrom =
        Entity.newBuilder(from).set("balance", from.getLong("balance") - amount).build();
    Entity to = entities.get(1);
    Entity updatedTo =
        Entity.newBuilder(to).set("balance", to.getLong("balance") + amount).build();
    txn.put(updatedFrom, updatedTo);
    txn.commit();
  } finally {
    if (txn.isActive()) {
      txn.rollback();
    }
  }
}

Node.js

async function transferFunds(fromKey, toKey, amount) {
  const transaction = datastore.transaction();
  await transaction.run();
  const results = await Promise.all([
    transaction.get(fromKey),
    transaction.get(toKey),
  ]);
  const accounts = results.map(result => result[0]);

  accounts[0].balance -= amount;
  accounts[1].balance += amount;

  transaction.save([
    {
      key: fromKey,
      data: accounts[0],
    },
    {
      key: toKey,
      data: accounts[1],
    },
  ]);

  return await transaction.commit();
}

PHP

/**
 * Update two entities in a transaction.
 *
 * @param string $fromKeyId
 * @param string $toKeyId
 * @param int $amount
 * @param string $namespaceId
 */
function transfer_funds(
    string $fromKeyId,
    string $toKeyId,
    int $amount,
    string $namespaceId = null
) {
    $datastore = new DatastoreClient(['namespaceId' => $namespaceId]);
    $transaction = $datastore->transaction();
    $fromKey = $datastore->key('Account', $fromKeyId);
    $toKey = $datastore->key('Account', $toKeyId);
    // The option 'sort' is important here, otherwise the order of the result
    // might be different from the order of the keys.
    $result = $transaction->lookupBatch([$fromKey, $toKey], ['sort' => true]);
    if (count($result['found']) != 2) {
        $transaction->rollback();
    }
    $fromAccount = $result['found'][0];
    $toAccount = $result['found'][1];
    $fromAccount['balance'] -= $amount;
    $toAccount['balance'] += $amount;
    $transaction->updateBatch([$fromAccount, $toAccount]);
    $transaction->commit();
}

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

def transfer_funds(client, from_key, to_key, amount):
    with client.transaction():
        from_account = client.get(from_key)
        to_account = client.get(to_key)

        from_account["balance"] -= amount
        to_account["balance"] += amount

        client.put_multi([from_account, to_account])

Ruby

def transfer_funds from_key, to_key, amount
  datastore.transaction do |tx|
    from = tx.find from_key
    from["balance"] -= amount
    to = tx.find to_key
    to["balance"] += amount
    tx.save from, to
  end
end

Ten en cuenta que, para que nuestros ejemplos sean más concisos, a veces omitimos el rollback si la transacción falla. En el código de producción, es importante asegurarse de que cada transacción se confirma o se revierte de forma explícita.

Qué se puede hacer en una transacción

Las transacciones pueden consultar o buscar cualquier número de entidades. El tamaño máximo de una transacción es de 10 MiB. Puedes usar una transacción de lectura y escritura o una transacción de solo lectura.

Aislamiento y coherencia

Las bases de datos en modo Datastore aplican el aislamiento serializable. Los datos leídos o modificados por una transacción no se pueden modificar simultáneamente.

Las consultas y las búsquedas de una transacción ven una vista coherente del estado de la base de datos. Esta instantánea tiene la garantía de contener el efecto de todas las transacciones y escrituras que se hayan completado antes del inicio de la transacción.

Esta vista de la instantánea coherente también se aplica a las lecturas posteriores a las escrituras dentro de las transacciones. A diferencia de la mayoría de las bases de datos, las consultas y las búsquedas dentro de una transacción en modo Datastore no ven los resultados de las escrituras anteriores dentro de esa transacción. En concreto, si una entidad se modifica o se elimina en una transacción, una consulta o una búsqueda devolverá la versión original de la entidad en el momento en que se inició la transacción, o nada si la entidad no existía en ese momento.

Además de las transacciones, las consultas y las búsquedas también tienen aislamiento serializable.

Modos de simultaneidad

Firestore en el modo de Datastore admite tres modos de simultaneidad. El modo de simultaneidad es un ajuste de la base de datos que determina cómo interactúan las transacciones simultáneas. Puedes seleccionar uno de los siguientes modos de simultaneidad:

Pesimista

Las transacciones de lectura y escritura usan bloqueos de lectura y escritura para aplicar el aislamiento y la serialización. Cuando dos o más transacciones de lectura y escritura simultáneas leen o escriben los mismos datos, el bloqueo que mantiene una transacción puede retrasar las demás. Si tu transacción no requiere ninguna escritura, puedes mejorar el rendimiento y evitar conflictos con otras transacciones usando una transacción de solo lectura. Las transacciones de solo lectura no requieren ningún bloqueo.

Las bases de datos de Firestore en el modo de Datastore usan el modo de simultaneidad pesimista de forma predeterminada.
Optimista

Cuando dos o más transacciones de lectura y escritura simultáneas leen o escriben los mismos datos, solo se completa la primera transacción que confirma sus cambios. Otras transacciones que realizan escrituras fallan al confirmar.

Nota: Antes, las bases de datos de Cloud Datastore antiguas se actualizaban a Firestore en el modo de Datastore. La mayoría de las bases de datos actualizadas se configuraron inicialmente para usar el modo de simultaneidad optimista.
Optimista con grupos de entidades

Usa este modo de simultaneidad solo si tu aplicación depende de la semántica transaccional de grupos de entidades de la versión antigua de Cloud Datastore. Este modo de simultaneidad impone límites adicionales a las transacciones:
- Las transacciones están limitadas a 25 grupos de entidades.
- Las escrituras en un grupo de entidades están limitadas a 1 por segundo.
- Las consultas de las transacciones deben ser consultas de ancestros.
Nota: Antes, las bases de datos antiguas de Cloud Datastore se actualizaban a Firestore en el modo de Datastore. Las bases de datos que dependían de la semántica transaccional de los grupos de entidades se configuraron inicialmente para usar el modo de simultaneidad Optimista con grupos de entidades.

Para eliminar las limitaciones de consultas, transacciones y escritura de OPTIMISTIC_WITH_ENTITY_GROUPS, cambia el modo de simultaneidad de tu proyecto a Optimista. Para asegurarte de que este cambio es compatible con tu proyecto, haz lo siguiente:
1. Crea un proyecto de prueba en Firestore en modo Datastore.
2. Cambia el modo de simultaneidad del proyecto de prueba a OPTIMISTIC. Envía una solicitud HTTP PATCH, como se muestra a continuación.
3. Ejecuta pruebas en el proyecto de prueba para asegurarte de que tu carga de trabajo funciona como se espera sin grupos de entidades.
4. Cambiar el modo de simultaneidad del proyecto principal de OPTIMISTIC_WITH_ENTITY_GROUPS a OPTIMISTIC.
Nota: La biblioteca de la API remota requiere grupos de entidades y no funcionará en el modo de simultaneidad OPTIMISTIC. Si usas la API remota, migra de esta API o, para seguir usando esta biblioteca, mantén tu proyecto en el modo OPTIMISTIC_WITH_ENTITY_GROUPS
.

Ver el modo de simultaneidad

Usa el recurso REST Firestore projects.databases para ver el modo de simultaneidad de tu base de datos:

curl -X GET -H "Authorization: Bearer "$(gcloud auth print-access-token) \
"https://firestore.googleapis.com/v1/projects/PROJECT_ID/databases"

Cambiar el modo de simultaneidad

Para cambiar el modo de simultaneidad de tu base de datos, envía una solicitud PATCH al recurso REST projects.databases de Firestore:

curl --request PATCH \
--header "Authorization: Bearer "$(gcloud auth print-access-token) \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"concurrencyMode":"CONCURRENCY_MODE"}' \
"https://firestore.googleapis.com/v1/projects/PROJECT_ID/databases/(default)?updateMask=concurrencyMode"

donde:

CONCURRENCY_MODE es PESSIMISTIC, OPTIMISTIC o OPTIMISTIC_WITH_ENTITY_GROUPS.
PROJECT_ID es el ID de tu Google Cloud proyecto.

Usos de las transacciones

Una de las aplicaciones de las transacciones es actualizar una entidad con un nuevo valor de propiedad relativo a su valor actual. En el ejemplo transferFunds anterior se hace esto con dos entidades, retirando dinero de una cuenta y transfiriéndolo a otra. La API Datastore no vuelve a intentar las transacciones automáticamente, pero puedes añadir tu propia lógica para volver a intentarlas, por ejemplo, para gestionar los conflictos cuando otra solicitud actualiza la misma entidad al mismo tiempo.

C#

/// <summary>
/// Retry the action when a Grpc.Core.RpcException is thrown.
/// </summary>
private T RetryRpc<T>(Func<T> action)
{
    List<Grpc.Core.RpcException> exceptions = null;
    var delayMs = _retryDelayMs;
    for (int tryCount = 0; tryCount < _retryCount; ++tryCount)
    {
        try
        {
            return action();
        }
        catch (Grpc.Core.RpcException e)
        {
            if (exceptions == null)
                exceptions = new List<Grpc.Core.RpcException>();
            exceptions.Add(e);
        }
        System.Threading.Thread.Sleep(delayMs);
        delayMs *= 2;  // Exponential back-off.
    }
    throw new AggregateException(exceptions);
}

private void RetryRpc(Action action)
{
    RetryRpc(() => { action(); return 0; });
}

[Fact]
public void TestTransactionalRetry()
{
    int tryCount = 0;
    var keys = UpsertBalances();
    RetryRpc(() =>
    {
        using (var transaction = _db.BeginTransaction())
        {
            TransferFunds(keys[0], keys[1], 10, transaction);
            // Insert a conflicting transaction on the first try.
            if (tryCount++ == 0)
                TransferFunds(keys[1], keys[0], 5);
            transaction.Commit();
        }
    });
    Assert.Equal(2, tryCount);
}

Go

type BankAccount struct {
	Balance int
}

const amount = 50
_, err := client.RunInTransaction(ctx, func(tx *datastore.Transaction) error {
	keys := []*datastore.Key{to, from}
	accs := make([]BankAccount, 2)
	if err := tx.GetMulti(keys, accs); err != nil {
		return err
	}
	accs[0].Balance += amount
	accs[1].Balance -= amount
	_, err := tx.PutMulti(keys, accs)
	return err
})

Java

int retries = 5;
while (true) {
  try {
    transferFunds(fromKey, toKey, 10);
    break;
  } catch (DatastoreException e) {
    if (retries == 0) {
      throw e;
    }
    --retries;
  }
}
// Retry handling can also be configured and automatically applied using google-cloud-java.

Node.js

async function transferFundsWithRetry() {
  const maxTries = 5;

  async function tryRequest(currentAttempt, delay) {
    try {
      await transferFunds(fromKey, toKey, 10);
    } catch (err) {
      if (currentAttempt <= maxTries) {
        // Use exponential backoff
        setTimeout(async () => {
          await tryRequest(currentAttempt + 1, delay * 2);
        }, delay);
      }
      throw err;
    }
  }

  await tryRequest(1, 100);
}

PHP

$retries = 5;
for ($i = 0; $i < $retries; $i++) {
    try {
        require_once __DIR__ . '/transfer_funds.php';
        transfer_funds($fromKeyId, $toKeyId, 10, $namespaceId);
    } catch (\Google\Cloud\Core\Exception\ConflictException $e) {
        // if $i >= $retries, the failure is final
        continue;
    }
    // Succeeded!
    break;
}

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

import google.cloud.exceptions

for _ in range(5):
    try:
        transfer_funds(client, account1.key, account2.key, 50)
        break
    except google.cloud.exceptions.Conflict:
        continue
else:
    print("Transaction failed.")

Ruby

(1..5).each do |i|
  begin
    return transfer_funds from_key, to_key, amount
  rescue Google::Cloud::Error => e
    raise e if i == 5
  end
end

Esto requiere una transacción porque otro usuario puede actualizar el valor de balance en una entidad después de que este código obtenga el objeto, pero antes de que guarde el objeto modificado. Si no hay ninguna transacción, la solicitud del usuario usará el valor de balance anterior a la actualización del otro usuario y la acción de guardar sobrescribirá el nuevo valor. Con una transacción, la aplicación recibe información sobre la actualización del otro usuario.

Otro uso habitual de las transacciones es obtener una entidad con una clave con nombre o crearla si aún no existe (este ejemplo se basa en el ejemplo TaskList de crear una entidad):

C#

Entity task;
using (var transaction = _db.BeginTransaction())
{
    task = transaction.Lookup(_sampleTask.Key);
    if (task == null)
    {
        transaction.Insert(_sampleTask);
        transaction.Commit();
    }
}

Go

_, err := client.RunInTransaction(ctx, func(tx *datastore.Transaction) error {
	var task Task
	if err := tx.Get(key, &task); err != datastore.ErrNoSuchEntity {
		return err
	}
	_, err := tx.Put(key, &Task{
		Category:    "Personal",
		Done:        false,
		Priority:    4,
		Description: "Learn Cloud Datastore",
	})
	return err
})

Java

Entity task;
Transaction txn = datastore.newTransaction();
try {
  task = txn.get(taskKey);
  if (task == null) {
    task = Entity.newBuilder(taskKey).build();
    txn.put(task);
    txn.commit();
  }
} finally {
  if (txn.isActive()) {
    txn.rollback();
  }
}

Node.js

async function getOrCreate(taskKey, taskData) {
  const taskEntity = {
    key: taskKey,
    data: taskData,
  };
  const transaction = datastore.transaction();

  try {
    await transaction.run();
    const [task] = await transaction.get(taskKey);
    if (task) {
      // The task entity already exists.
      await transaction.rollback();
    } else {
      // Create the task entity.
      transaction.save(taskEntity);
      await transaction.commit();
    }
    return taskEntity;
  } catch (err) {
    await transaction.rollback();
  }
}

PHP

$transaction = $datastore->transaction();
$entity = $transaction->lookup($task->key());
if ($entity === null) {
    $entity = $transaction->insert($task);
    $transaction->commit();
}

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

import datetime

with client.transaction():
    key = client.key(
        "Task", datetime.datetime.now(tz=datetime.timezone.utc).isoformat()
    )

    task = client.get(key)

    if not task:
        task = datastore.Entity(key)
        task.update({"description": "Example task"})
        client.put(task)

    return task

Ruby

task = nil
datastore.transaction do |tx|
  task = tx.find task_key
  if task.nil?
    task = datastore.entity task_key do |t|
      t["category"] = "Personal"
      t["done"] = false
      t["priority"] = 4
      t["description"] = "Learn Cloud Datastore"
    end
    tx.save task
  end
end

Al igual que antes, las transacciones son necesarias en caso de que un usuario intente crear o modificar una entidad con el mismo ID de cadena que otro. Sin una transacción, si la entidad no existe y dos usuarios intentan crearla, la operación del segundo sobrescribe la del primero sin saberlo.

Cuando falla una transacción, puedes hacer que tu aplicación vuelva a intentarla hasta que se complete correctamente o dejar que tus usuarios gestionen el error propagándolo al nivel de la interfaz de usuario de tu aplicación. No es necesario crear un loop de nuevo intento para cada transacción.

Transacciones de solo lectura

Por último, puedes usar una transacción para leer una captura coherente de la base de datos. Esto puede ser útil cuando necesitas varias lecturas para renderizar una página o para exportar datos que deben ser coherentes. Puede crear transacciones de solo lectura para estos casos.

Las transacciones de solo lectura no pueden modificar entidades, pero, a cambio, no compiten con ninguna otra transacción y no es necesario volver a intentarlas. Si solo realizas lecturas en una transacción normal de lectura y escritura, esa transacción puede entrar en conflicto con transacciones que modifiquen los mismos datos.

C#

Entity taskList;
IReadOnlyList<Entity> tasks;
using (var transaction = _db.BeginTransaction(TransactionOptions.CreateReadOnly()))
{
    taskList = transaction.Lookup(taskListKey);
    var query = new Query("Task")
    {
        Filter = Filter.HasAncestor(taskListKey)
    };
    tasks = transaction.RunQuery(query).Entities;
    transaction.Commit();
}

Go

tx, err := client.NewTransaction(ctx, datastore.ReadOnly)
if err != nil {
	log.Fatalf("client.NewTransaction: %v", err)
}
defer tx.Rollback() // Transaction only used for read.

ancestor := datastore.NameKey("TaskList", "default", nil)
query := datastore.NewQuery("Task").Ancestor(ancestor).Transaction(tx)
var tasks []Task
_, err = client.GetAll(ctx, query, &tasks)

Java

Entity taskList;
QueryResults<Entity> tasks;
Transaction txn =
    datastore.newTransaction(
        TransactionOptions.newBuilder().setReadOnly(ReadOnly.newBuilder().build()).build());
try {
  taskList = txn.get(taskListKey);
  Query<Entity> query =
      Query.newEntityQueryBuilder()
          .setKind("Task")
          .setFilter(PropertyFilter.hasAncestor(taskListKey))
          .build();
  tasks = txn.run(query);
  txn.commit();
} finally {
  if (txn.isActive()) {
    txn.rollback();
  }
}

Node.js

async function getTaskListEntities() {
  const transaction = datastore.transaction({readOnly: true});
  try {
    const taskListKey = datastore.key(['TaskList', 'default']);

    await transaction.run();
    const [taskList] = await transaction.get(taskListKey);
    const query = datastore.createQuery('Task').hasAncestor(taskListKey);
    const [taskListEntities] = await transaction.runQuery(query);
    await transaction.commit();
    return [taskList, taskListEntities];
  } catch (err) {
    await transaction.rollback();
  }
}

PHP

$transaction = $datastore->readOnlyTransaction();
$taskListKey = $datastore->key('TaskList', 'default');
$query = $datastore->query()
    ->kind('Task')
    ->hasAncestor($taskListKey);
$result = $transaction->runQuery($query);
$taskListEntities = [];
$num = 0;
/* @var Entity $task */
foreach ($result as $task) {
    $taskListEntities[] = $task;
    $num += 1;
}

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

with client.transaction(read_only=True):
    task_list_key = client.key("TaskList", "default")

    task_list = client.get(task_list_key)

    query = client.query(kind="Task", ancestor=task_list_key)
    tasks_in_list = list(query.fetch())

    return task_list, tasks_in_list

Ruby

# task_list_name = "default"
task_list_key = datastore.key "TaskList", task_list_name
datastore.read_only_transaction do |tx|
  task_list = tx.find task_list_key
  query = datastore.query("Task").ancestor(task_list)
  tasks_in_list = tx.run query
end

Siguientes pasos

Consulta información sobre las consultas.

Transacciones Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Usar transacciones

C#

Go

Java

Node.js

PHP

Python

Ruby

Qué se puede hacer en una transacción

Aislamiento y coherencia

Modos de simultaneidad

Ver el modo de simultaneidad

Cambiar el modo de simultaneidad

Usos de las transacciones

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

Transacciones de solo lectura

C#

Go

Java

Node.js

PHP

Python

Ruby

Siguientes pasos

Transacciones