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 o versioni successive, 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 è composta dai seguenti componenti:

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

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

  • una stringa del nome della chiave
  • un ID numerico intero

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

• Specifica la stringa del nome della chiave per l'entità.
• Consenti a Datastore di assegnare automaticamente all'entità un ID numerico intero.

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

Specifica 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 diversi criteri di ID automatico:

• Il criterio default genera una sequenza casuale di ID inutilizzati distribuiti in modo approssimativamente uniforme. Ogni ID può essere composto da un massimo di 16 cifre decimali.
• Il criterio legacy crea una sequenza di ID interi più piccoli non consecutivi.

Se vuoi mostrare all'utente gli ID entità e/o dipendere dal loro ordine, ti consigliamo di 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 c'è 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 di ID automatico 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.

Utilizzare i 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 optionally designare un'altra entità come principale; la nuova entità è secondaria dell'entità padre (tieni presente che, a differenza di un file system, l'entità principale non deve necessariamente 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à principali (quelle senza un elemento principale).

L'entità principale, l'entità principale dell'entità principale e così via in modo ricorsivo sono i suoi antenati; le sue entità figlio, le entità figlio delle entità figlio e così via sono i suoi discendenti. Un'entità base e tutti i suoi discendenti appartengono allo stesso gruppo di entità. La sequenza di entità che inizia con un'entità principale e procede da una entità principale a una secondaria, fino a una determinata entità, costituisce il percorso degli antenati di quell'entità. La chiave completa che identifica l'entità è costituita da una sequenza di coppie di tipo-identificatore che specificano il percorso dell'antenato e termina con quelli dell'entità stessa:

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

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

[Person:GreatGrandpa]

Questo concetto è illustrato dal seguente diagramma:

Per designare l'entità principale, 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 principale:

// 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)