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 la multitenancy
• Il kind dell'entità, che la classifica per le query 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à, l'identificatore è associato permanentemente con l'entità e non può essere modificata. Devi assegnare l'identificatore in in uno dei due seguenti modi:

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

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

Specifica di un nome chiave per un'entità

Per assegnare un nome 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 in modo che generi ID automatici utilizzando due diversi criteri per gli ID automatici:

• Il criterio default genera una sequenza casuale di ID inutilizzati distribuiti approssimativamente in modo 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 chiave o generare ID numerici automaticamente, le applicazioni avanzate a volte 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 in modo gerarchico 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à principale (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à principale e tutti i suoi discendenti appartengono allo stesso gruppo di entità. La sequenza di entità che inizia con una radice dell'entità e procedere da principale a figlio, portando a una determinata entità, costituiscono il percorso predecessore dell'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 un'entità principale, 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'elemento principale di un'entità, utilizza l'argomento parent per datastore.NewKey Il valore di questo argomento dovrebbe essere la chiave dell'entità padre. Nell'esempio che segue crea un'entità di tipo Address e designa un'entità Employee come sua 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)