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 la multitenancy.
- Il tipo di entità, che lo classifica ai fini delle query Datastore
- Un percorso predecessore facoltativo che individua l'entità all'interno della gerarchia di Datastore.
Un identificatore per la singola entità, che può essere
- una stringa nome chiave
- un ID numerico intero
Poiché fa parte della chiave dell'entità, è associato definitivamente all'entità e non può essere modificato. Puoi assegnare l'identificatore in due modi:
- Specifica la tua stringa nome chiave per l'entità.
- Lascia che Datastore assegni automaticamente all'entità un ID numerico intero.
Specifica di un nome chiave per un'entità
Per assegnare un nome a una chiave a un'entità, fornisci il nome come secondo argomento al costruttore quando crei l'entità:
Per consentire a Datastore di assegnare automaticamente un ID numerico, ometti questo argomento:
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 non utilizzati che sono distribuiti casualmente. 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 dipende dal suo ordine, la cosa migliore da fare è utilizzare l'allocazione manuale.
Utilizzo dei percorsi predecessori
Le entità in Cloud Datastore formano uno spazio strutturato in modo gerarchico simile alla directory di un file system. Quando crei un'entità, puoi facoltativamente designare un'altra entità come principale; la nuova entità è un secondario dell'entità principale (tieni presente che, a differenza di un file system, l'entità principale non deve esistere effettivamente). Un'entità senza entità padre è un'entità root. L'associazione tra un'entità e la relativa entità è permanente e non può essere modificata una volta creata l'entità. Cloud Datastore non assegnerà mai lo stesso ID numerico a due entità con lo stesso padre o a due entità radice (quelle senza un padre).
Il genitore di un'entità, il genitore e così via sono i suoi antenati, i suoi figli, i loro figli, ecc. Un'entità radice e tutti i relativi discendenti appartengono allo stesso gruppo di entità. La sequenza di entità che iniziano con un'entità radice e procedono da un'entità padre all'altra, generando un'entità specifica, costituendo il percorso dell'antenato. La chiave completa che identifica l'entità è costituita da una sequenza di coppie tipo-identificatore che specificano il percorso del predecessore e terminano con quelle dell'entità stessa:
[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]
Per un'entità radice, il percorso del predecessore è vuoto e la chiave è composta esclusivamente dal tipo e dall'identificatore dell'entità:
[Person:GreatGrandpa]
Questo concetto è illustrato dal seguente diagramma:
Per designare l'entità padre, fornisci la chiave dell'entità padre come argomento
al costruttore
Entity()
durante la creazione dell'entità secondaria. Puoi ottenere la chiave chiamando il metodo getKey()
dell'entità principale:
Se la nuova entità ha anche un nome di chiave, fornisci il nome della chiave come secondo argomento
del costruttore Entity()
e la chiave dell'entità padre come
terzo argomento:
Generazione di chiavi
Le applicazioni possono utilizzare la classe KeyFactory
per creare un oggetto Key
per un'entità da componenti noti, come il tipo e l'identificatore dell'entità. Per un'entità senza principale, trasmetti il tipo e l'identificatore (una stringa del nome della chiave o un ID numerico) al metodo statico KeyFactory.createKey()
per creare la chiave. I seguenti esempi creano una chiave per un'entità di tipo Person
con nome della chiave "GreatGrandpa"
o ID numerico 74219
:
Se la chiave include un componente del percorso, puoi utilizzare la classe helper KeyFactory.Builder
per crearlo. Questo metodo di classe addChild
di questa classe aggiunge una singola entità al percorso e restituisce il generatore stesso, in modo da poter concatenare una serie di chiamate, a partire dall'entità radice, per creare il percorso di un'entità alla volta. Dopo aver creato il percorso completo, richiama getKey
per recuperare la chiave risultante:
La classe KeyFactory
include anche i metodi statici keyToString
e stringToKey
per la conversione tra chiavi e relative rappresentazioni delle stringhe:
La rappresentazione della stringa di una chiave è "web-safe": non contiene caratteri considerati speciali in HTML o negli URL.