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

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

    • una stringa nome chiave
    • un ID numerico intero

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

  • Specifica la tua stringa key name per l'entità.
  • Consenti a Datastore di assegnare automaticamente all'entità un ID numerico intero.

Specificare un nome chiave per un'entità

Per assegnare un nome di 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 per generare ID automatici utilizzando due diverse norme per gli ID automatici:

  • Il criterio default genera una sequenza casuale di ID non utilizzati distribuiti in modo approssimativamente uniforme. 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 dipendere dal loro ordine, la cosa migliore da fare è utilizzare l'allocazione manuale.

Utilizzo dei 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 designare facoltativamente un'altra entità come genitore; la nuova entità è un elemento secondario dell'entità padre (tieni presente che, a differenza di un file system, l'entità genitore non deve 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à radice (quelle senza un elemento principale).

Il genitore di un'entità, il genitore del genitore e così via in modo ricorsivo sono i suoi antenati; i suoi figli, i figli dei figli e così via sono i suoi discendenti. Un'entità base e tutti i relativi discendenti appartengono allo stesso gruppo di entità. La sequenza di entità che inizia con un'entità principale e procede da genitore a figlio, fino a un'entità specifica, costituisce il percorso degli antenati dell'entità. La chiave completa che identifica l'entità è costituita da una sequenza di coppie tipo-identificatore che specificano il percorso degli antenati e terminano con quelli dell'entità stessa:

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

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

[Person:GreatGrandpa]

Questo concetto è illustrato nel seguente diagramma:

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

Per designare l'elemento 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 del 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 elemento principale, 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 della chiave "GreatGrandpa" o ID numerico 74219:

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

Se la chiave include un componente di 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 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 stringhe:

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 una chiave come stringa è "sicura per il web": non contiene caratteri considerati speciali in HTML o negli URL.