Criar, obter, atualizar e eliminar entidades

Os objetos de dados no Datastore são conhecidos como entidades, cada uma das quais é categorizada num tipo específico para fins de consultas. Por exemplo, se estiver a escrever uma aplicação de recursos humanos, pode representar cada funcionário com uma entidade do tipo Employee. Tenha em atenção que os valores dos dados das entidades estão sob a forma de propriedades. Para mais informações sobre entidades, consulte o documento conceptual Entidades, propriedades e chaves.

Criar entidades e definir propriedades

Em Go, cria uma nova entidade construindo uma instância de uma struct Go, preenchendo os respetivos campos e chamando datastore.Put para a guardar no Datastore. Apenas os campos exportados (que começam com uma letra maiúscula) são guardados no Datastore. Pode especificar o nome da chave da entidade transmitindo um argumento stringID não vazio a datastore.NewKey.

O exemplo seguinte cria uma entidade do tipo Employee, preenche os respetivos valores das propriedades e guarda-a no Datastore:

import (
	"context"
	"time"

	"google.golang.org/appengine/datastore"
)

type Employee struct {
	FirstName          string
	LastName           string
	HireDate           time.Time
	AttendedHRTraining bool
}

func f(ctx context.Context) {
	// ...
	employee := &Employee{
		FirstName: "Antonio",
		LastName:  "Salieri",
		HireDate:  time.Now(),
	}
	employee.AttendedHRTraining = true

	key := datastore.NewIncompleteKey(ctx, "Employee", nil)
	if _, err := datastore.Put(ctx, key, employee); err != nil {
		// Handle err
	}
	// ...
}

O tipo Employee declara quatro campos para o modelo de dados: FirstName, LastName, HireDate e AttendedHRTraining.

Se fornecer um nome de chave vazio ou usar datastore.NewIncompleteKey, o Datastore gera automaticamente um ID numérico para a chave da entidade:

employee := &Employee{
	FirstName: "Antonio",
	LastName:  "Salieri",
	HireDate:  time.Now(),
}
employee.AttendedHRTraining = true
key := datastore.NewIncompleteKey(ctx, "Employee", nil)
_, err = datastore.Put(ctx, key, employee)

A obter entidades

Para obter uma entidade identificada por uma determinada chave, transmita o *datastore.Key como um argumento para a função datastore.Get. Pode gerar o *datastore.Key através da função datastore.NewKey.

employeeKey := datastore.NewKey(ctx, "Employee", "asalieri", 0, nil)
addressKey := datastore.NewKey(ctx, "Address", "", 1, employeeKey)
var addr Address
err = datastore.Get(ctx, addressKey, &addr)

datastore.Get preenche uma instância da estrutura Go adequada.

A atualizar entidades

Para atualizar uma entidade existente, modifique os atributos da struct e, em seguida, chame datastore.Put. Os dados substituem a entidade existente. O objeto completo é enviado para o Datastore com cada chamada para datastore.Put.

Eliminar entidades

Dada a chave de uma entidade, pode eliminar a entidade com a função datastore.Delete:

key := datastore.NewKey(ctx, "Employee", "asalieri", 0, nil)
err = datastore.Delete(ctx, key)

Eliminar entidades em massa

Se precisar de eliminar um grande número de entidades, recomendamos que use o Dataflow para eliminar entidades em massa.

Usar operações em lote

Pode usar as seguintes operações em lote se quiser operar em várias entidades numa única chamada do Datastore:

Segue-se um exemplo de uma chamada em lote:

// A batch put.
_, err = datastore.PutMulti(ctx, []*datastore.Key{k1, k2, k3}, []interface{}{e1, e2, e3})

// A batch get.
var entities = make([]*T, 3)
err = datastore.GetMulti(ctx, []*datastore.Key{k1, k2, k3}, entities)

// A batch delete.
err = datastore.DeleteMulti(ctx, []*datastore.Key{k1, k2, k3})

As operações em lote não alteram os seus custos. É-lhe cobrado o valor de cada chave numa operação em lote, quer a chave exista ou não. A dimensão das entidades envolvidas numa operação não afeta o custo.