Creazione e utilizzo delle chiavi di entità

Questa API è supportata per runtime di prima generazione e può essere utilizzata quando eseguire l'upgrade ai runtime di seconda generazione corrispondenti. Se esegui l'aggiornamento al runtime App Engine Go 1.12+, consulta la guida alla migrazione per scoprire di più sulle opzioni di migrazione per i servizi in bundle legacy.

Ogni entità in Datastore ha una chiave che la identifica in modo univoco. La chiave è costituita dai seguenti componenti:

• Lo spazio dei nomi dell'entità, che consente il multitenancy
• Il tipo dell'entità, che la classifica ai fini delle query Datastore
• Un percorso degli antenati facoltativo che individua l'entità all'interno della gerarchia Datastore.

• Un identificatore per la singola entità, che può essere

  • una stringa nome chiave
  • un ID numerico intero

Poiché l'identificatore fa parte della chiave dell'entità, è associato in modo permanente all'entità e non può essere modificato. Assegni l'identificatore in uno dei due modi seguenti:

• Specifica la tua stringa key name per l'entità.
• Consenti a Datastore di assegnare automaticamente all'entità un ID numerico intero.

Non assegnare a una proprietà il nome "key". Questo nome è riservato a una proprietà speciale utilizzata per archiviare la chiave del modello. Sebbene possa funzionare localmente, una proprietà denominata "key" impedirà il deployment in App Engine.

Specificare un nome chiave per un'entità

Per assegnare un nome di chiave a un'entità, fornisci un argomento stringID non vuoto a datastore.NewKey:

// Create a key with a key name "asalieri".
key := datastore.NewKey(
	ctx,        // context.Context
	"Employee", // Kind
	"asalieri", // String ID; empty means no string ID
	0,          // Integer ID; if 0, generate automatically. Ignored if string ID specified.
	nil,        // Parent Key; nil means no parent
)

Per consentire a Datastore di assegnare automaticamente un ID numerico, utilizza un argomento stringID vuoto:

// Create a key such as Employee:8261.
key := datastore.NewKey(ctx, "Employee", "", 0, nil)
// This is equivalent:
key = datastore.NewIncompleteKey(ctx, "Employee", nil)

Assegnazione degli identificatori

Puoi configurare Datastore per generare ID automatici utilizzando due diverse norme per gli ID automatici:

• Il criterio default genera una sequenza casuale di ID non utilizzati distribuiti in modo approssimativamente uniforme. Ogni ID può contenere fino a 16 cifre decimali.
• Il criterio legacy crea una sequenza di ID interi più piccoli non consecutivi.

Se vuoi mostrare gli ID entità all'utente e/o dipendere dal loro ordine, la cosa migliore da fare è utilizzare l'allocazione manuale.

Nota: anziché utilizzare stringhe di nomi di chiavi o generare automaticamente ID numerici, a volte le applicazioni avanzate potrebbero voler assegnare manualmente i propri ID numerici alle entità che creano. Tieni presente, tuttavia, che non esiste nulla che impedisca a Datastore di assegnare uno dei tuoi ID numerici manuali a un'altra entità. L'unico modo per evitare questi conflitti è fare in modo che l'applicazione ottenga un blocco di ID con la funzione datastore.AllocateIDs. Il generatore automatico di ID di Datastore tiene traccia degli ID allocati con questa funzione ed evita di riutilizzarli per un'altra entità, in modo da poterli utilizzare in sicurezza senza conflitti.

Utilizzo dei percorsi degli antenati

Le entità in Cloud Datastore formano uno spazio strutturato gerarchicamente simile alla struttura di directory di un file system. Quando crei un'entità, puoi designare facoltativamente un'altra entità come genitore; la nuova entità è un elemento secondario dell'entità padre (tieni presente che, a differenza di un file system, l'entità genitore non deve esistere). Un'entità senza un elemento principale è un'entità radice. L'associazione tra un'entità e la relativa entità principale è permanente e non può essere modificata dopo la creazione dell'entità. Cloud Datastore non assegnerà mai lo stesso ID numerico a due entità con lo stesso elemento principale o a due entità radice (quelle senza un elemento principale).

Il genitore di un'entità, il genitore del genitore e così via in modo ricorsivo sono i suoi antenati; i suoi figli, i figli dei figli e così via sono i suoi discendenti. Un'entità base e tutti i relativi discendenti appartengono allo stesso gruppo di entità. La sequenza di entità che inizia con un'entità principale e procede da genitore a figlio, fino a un'entità specifica, costituisce il percorso degli antenati dell'entità. La chiave completa che identifica l'entità è costituita da una sequenza di coppie tipo-identificatore che specificano il percorso degli antenati e terminano con quelli dell'entità stessa:

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

Per unentità base, il percorso degli antenati è vuoto e la chiave è costituita unicamente dal tipo e dall'identificatore dell'entità:

[Person:GreatGrandpa]

Questo concetto è illustrato nel seguente diagramma:

Per designare l'entità principale di un'entità, utilizza l'argomento parent per datastore.NewKey. Il valore di questo argomento deve essere la chiave dell'entità padre. L'esempio seguente crea un'entità di tipo Address e designa un'entità Employee come genitore:

// Create Employee entity
employee := &Employee{ /* ... */ }
employeeKey, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Employee", nil), employee)

// Use Employee as Address entity's parent
// and save Address entity to datastore
address := &Address{ /* ... */ }
addressKey := datastore.NewIncompleteKey(ctx, "Address", employeeKey)
_, err = datastore.Put(ctx, addressKey, address)