Esta página foi traduzida pela API Cloud Translation.

Transações

Uma transação é um conjunto de operações numa ou mais entidades. Cada transação tem a garantia de ser atómica, o que significa que as transações nunca são aplicadas parcialmente. Todas as operações na transação são aplicadas ou nenhuma delas é aplicada.

Usar transações

As transações expiram após 270 segundos ou se estiverem inativas durante 60 segundos.

Uma operação pode falhar quando:

Foram tentadas demasiadas modificações simultâneas na mesma entidade.
A transação excede um limite de recursos.
A base de dados do modo Datastore encontra um erro interno.

Em todos estes casos, a API Datastore devolve um erro.

As transações são uma funcionalidade opcional. Não tem de usar transações para realizar operações na base de dados.

Uma aplicação pode executar um conjunto de declarações e operações numa única transação, de modo que, se qualquer declaração ou operação gerar uma exceção, nenhuma das operações da base de dados no conjunto é aplicada. A aplicação define as ações a realizar na transação.

O fragmento seguinte mostra como realizar uma transação. Transfere dinheiro de uma conta para outra.

C#

Para saber como instalar e usar a biblioteca cliente do Cloud Datastore, consulte as bibliotecas cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# Cloud Datastore.

Para se autenticar no Cloud Datastore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento 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

Tenha em atenção que, para manter os nossos exemplos mais concisos, por vezes, omitimos o elemento rollback se a transação falhar. No código de produção, é importante garantir que cada transação é explicitamente confirmada ou revertida.

O que pode ser feito numa transação

As transações podem consultar ou procurar qualquer número de entidades. O tamanho máximo de uma transação é de 10 MiB. Pode usar uma transação de leitura/escrita ou uma transação de só leitura.

Isolamento e consistência

As bases de dados do modo Datastore aplicam o isolamento serializável. Os dados lidos ou modificados por uma transação não podem ser modificados em simultâneo.

As consultas e as pesquisas numa transação veem um resumo consistente do estado da base de dados. Este resumo tem a garantia de conter o efeito de todas as transações e gravações concluídas antes do início da transação.

Esta vista de instantâneo consistente também se aplica a leituras após escritas em transações. Ao contrário da maioria das bases de dados, as consultas e as pesquisas numa transação do modo Datastore não veem os resultados das escritas anteriores nessa transação. Especificamente, se uma entidade for modificada ou eliminada numa transação, uma consulta ou uma pesquisa devolve a versão original da entidade a partir do início da transação ou nada, se a entidade não existir nesse momento.

Fora das transações, as consultas e as pesquisas também têm isolamento serializável.

Modos de simultaneidade

O Firestore no modo Datastore suporta três modos de simultaneidade. O modo de concorrência é uma definição da base de dados que determina como as transações concorrentes interagem. Pode selecionar um dos seguintes modos de concorrência:

Pessimistic

As transações de leitura/escrita usam bloqueios de leitor/escritor para aplicar o isolamento e a serialização. Quando duas ou mais transações de leitura/escrita simultâneas leem ou escrevem os mesmos dados, o bloqueio mantido por uma transação pode atrasar as outras transações. Se a sua transação não exigir gravações, pode melhorar o desempenho e evitar contestações com outras transações através de uma transação só de leitura. As transações só de leitura não requerem bloqueios.

As bases de dados do Firestore no modo Datastore usam o modo de concorrência pessimista por predefinição.
Otimista

Quando duas ou mais transações de leitura/escrita simultâneas leem ou escrevem os mesmos dados, apenas a primeira transação a confirmar as respetivas alterações é bem-sucedida. Outras transações que executam escritas falham na confirmação.

Nota: anteriormente, as bases de dados do Cloud Datastore antigas eram atualizadas para o Firestore no modo Datastore. A maioria das bases de dados atualizadas foi inicialmente configurada para usar o modo de concorrência otimista.
Otimista com grupos de entidades

Use este modo de simultaneidade apenas se a sua app depender da semântica transacional do grupo de entidades do Cloud Datastore antigo. Este modo de concorrência impõe limites adicionais às transações:
- As transações estão limitadas a 25 grupos de entidades.
- As escritas num grupo de entidades estão limitadas a 1 por segundo.
- As consultas em transações têm de ser consultas antecessoras.
Nota: anteriormente, as bases de dados do Cloud Datastore antigas eram atualizadas para o Firestore no modo Datastore. As bases de dados que dependiam da semântica transacional do grupo de entidades foram inicialmente configuradas para usar o modo de simultaneidade otimista com grupos de entidades.

Para remover as limitações de débito de OPTIMISTIC_WITH_ENTITY_GROUPSconsultas, transações e escrita, altere o modo de simultaneidade do seu projeto para Otimista. Para garantir que esta alteração é compatível com o seu projeto:
1. Crie um projeto de teste no Firestore no modo Datastore.
2. Altere o modo de simultaneidade do projeto de teste para OPTIMISTIC. Emita um pedido HTTP PATCH, conforme demonstrado abaixo.
3. Execute testes no projeto de teste para garantir que a carga de trabalho tem o desempenho esperado sem grupos de entidades.
4. Altere o modo de simultaneidade do projeto principal de OPTIMISTIC_WITH_ENTITY_GROUPS para OPTIMISTIC.
Nota: a biblioteca API Remote requer grupos de entidades e não funciona no modo de concorrência OPTIMISTIC. Se usar a API Remote, migre desta API ou, para continuar a usar esta biblioteca, mantenha o seu projeto no modo OPTIMISTIC_WITH_ENTITY_GROUPS.

Veja o modo de simultaneidade

Use o recurso REST projects.databases do Firestore para ver o modo de simultaneidade da sua base de dados:

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

Altere o modo de simultaneidade

Para alterar o modo de simultaneidade da sua base de dados, envie um pedido PATCH para o recurso REST projects.databases:

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"

where:

CONCURRENCY_MODE é PESSIMISTIC, OPTIMISTIC ou OPTIMISTIC_WITH_ENTITY_GROUPS.
PROJECT_ID é o ID do seu Google Cloud projeto.

Usos para transações

Uma utilização das transações é atualizar uma entidade com um novo valor de propriedade relativo ao seu valor atual. O transferFunds exemplo acima faz isso para duas entidades, retirando dinheiro de uma conta e transferindo-o para outra. A API Datastore não tenta novamente as transações automaticamente, mas pode adicionar a sua própria lógica para as tentar novamente, por exemplo, para processar conflitos quando outro pedido atualiza a mesma entidade ao mesmo tempo.

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

Isto requer uma transação porque o valor de balance numa entidade pode ser atualizado por outro utilizador depois de este código obter o objeto, mas antes de guardar o objeto modificado. Sem uma transação, o pedido do utilizador usa o valor de balance antes da atualização do outro utilizador, e a gravação substitui o novo valor. Com uma transação, a aplicação é informada sobre a atualização do outro utilizador.

Outra utilização comum das transações é obter uma entidade com uma chave com nome ou criá-la se ainda não existir (este exemplo baseia-se no exemplo TaskList de criar uma entidade):

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

Tal como antes, é necessária uma transação para processar o caso em que outro utilizador está a tentar criar ou atualizar uma entidade com o mesmo ID de string. Sem uma transação, se a entidade não existir e dois utilizadores tentarem criá-la, o segundo substitui o primeiro sem saber que isso aconteceu.

Quando uma transação falha, pode fazer com que a sua app tente novamente a transação até ter êxito ou pode permitir que os utilizadores lidem com o erro propagando-o ao nível da interface do utilizador da sua app. Não tem de criar um ciclo de repetição em torno de cada transação.

Transações só de leitura

Por último, pode usar uma transação para ler uma imagem consistente da base de dados. Isto pode ser útil quando precisa de várias leituras para renderizar uma página ou para exportar dados que têm de ser consistentes. Pode criar uma transação só de leitura para estes casos.

As transações só de leitura não podem modificar entidades, mas, em contrapartida, não competem com outras transações e não precisam de ser repetidas. Se realizar apenas leituras numa transação de leitura/escrita normal, essa transação pode competir com transações que modificam os mesmos dados.

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

O que se segue?

Saiba mais sobre as consultas.

Transações Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Usar transações

C#

Go

Java

Node.js

PHP

Python

Ruby

O que pode ser feito numa transação

Isolamento e consistência

Modos de simultaneidade

Veja o modo de simultaneidade

Altere o modo de simultaneidade

Usos para transações

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

Transações só de leitura

C#

Go

Java

Node.js

PHP

Python

Ruby

O que se segue?

Transações