Creazione e utilizzo delle chiavi di entità

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 kind dell'entità, che la classifica ai fini delle query Datastore
  • Un percorso predecessore facoltativo che individua l'entità all'interno della gerarchia Datastore.

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

    • una stringa di nome chiave
    • un ID numerico intero

Poiché l'identificatore fa parte della chiave dell'entità, viene 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à.
  • Consenti a Datastore di assegnare automaticamente all'entità un ID numerico intero.

Specificare il nome di una chiave per un'entità

Per assegnare un nome chiave a un'entità, fornisci il nome come secondo argomento al costruttore quando crei l'entità:

Entity employee = new Entity("Employee", "asalieri");

Per consentire a Datastore di assegnare automaticamente un ID numerico, ometti questo argomento:

Entity employee = new Entity("Employee");

Assegnazione degli identificatori

Puoi configurare Datastore in modo da generare ID automatici utilizzando due criteri ID automatici diversi:

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

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

Utilizzo dei percorsi dei predecessori

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 scegliere di indicare un'altra entità come parent;; la nuova entità è un elemento parent; dell'entità padre (tieni presente che, a differenza di un file system, l'entità padre non deve necessariamente esistere effettivamente. Un'entità senza un elemento padre è un'entità root. L'associazione tra un'entità e l'entità padre è 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 elemento padre o a due entità principali (quelle senza un elemento padre).

L'entità padre, l'entità padre e così via in modo ricorsivo, sono i suoi antenati; i relativi figli, figli 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à radice e procede dalla risorsa principale a quella secondaria e conduce a una determinata entità, costituisce il percorso predecessore dell'entità. La chiave completa che identifica l'entità è composta da una sequenza di coppie tipo-identificatore che specifica il percorso predecessore e termina con quelli dell'entità stessa:

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

Per unentità base, il percorso predecessore è vuoto e la chiave è composta esclusivamente dal tipo e dall'identificatore dell'entità:

[Person:GreatGrandpa]

Questo concetto è illustrato dal seguente diagramma:

Mostra la relazione tra l'entità base e le entità figlio nel gruppo di entità

Per designare l'entità padre, fornisci la chiave dell'entità padre come argomento al costruttore Entity() durante la creazione dell'entità figlio. Puoi ottenere la chiave chiamando il metodo getKey() dell'entità padre:

Entity employee = new Entity("Employee");
datastore.put(employee);

Entity address = new Entity("Address", employee.getKey());
datastore.put(address);

Se la nuova entità ha anche un nome della chiave, fornisci il nome della chiave come secondo argomento al costruttore Entity() e la chiave dell'entità padre come terzo argomento:

Entity address = new Entity("Address", "addr1", employee.getKey());

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 elemento principale, trasmetti il tipo e l'identificatore (una stringa con il 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 chiave "GreatGrandpa" o ID numerico 74219:

Key k1 = KeyFactory.createKey("Person", "GreatGrandpa");
Key k2 = KeyFactory.createKey("Person", 74219);

Se la chiave include un componente del percorso, puoi utilizzare la classe helper KeyFactory.Builder per creare il percorso. Il metodo addChild di questa classe aggiunge una singola entità al percorso e restituisce il generatore stesso, quindi puoi concatenare una serie di chiamate, a partire dall'entità base, per creare il percorso un'entità alla volta. Dopo aver creato il percorso completo, chiama getKey per recuperare la chiave risultante:

Key k =
    new KeyFactory.Builder("Person", "GreatGrandpa")
        .addChild("Person", "Grandpa")
        .addChild("Person", "Dad")
        .addChild("Person", "Me")
        .getKey();

La classe KeyFactory include anche i metodi statici keyToString e stringToKey per la conversione tra chiavi e le relative rappresentazioni di stringa:

String personKeyStr = KeyFactory.keyToString(k);

// Some time later (for example, after using personKeyStr in a link).
Key personKey = KeyFactory.stringToKey(personKeyStr);
Entity person = datastore.get(personKey);

La rappresentazione stringa di una chiave è "sicuro per il web": non contiene caratteri considerati speciali nel codice HTML o negli URL.