Creazione e utilizzo delle chiavi di entità

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 di nome 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.

Specifica un nome chiave per un'entità

Per assegnare un nome alla chiave di un'entità, fornisci il nome come secondo argomento al constructor 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 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.

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:

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

Per designare l'entità principale di un'entità, fornisci la chiave dell'entità principale come argomento al costruttore Entity() quando crei l'entità secondaria. 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 delle 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 elementi principali, passa il tipo e l'identificatore (una stringa del nome della chiave o un ID numerico) al metodo statico KeyFactory.createKey() per creare la chiave. Gli esempi seguenti 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 di supporto KeyFactory.Builder per creare il percorso. Il metodo addChild di questa classe aggiunge una singola entità al percorso e restituisce il builder stesso, in modo da poter 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 le 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 di stringa di una chiave è "sicura per il web": non contiene caratteri considerati speciali in HTML o negli URL.