Creazione e utilizzo delle chiavi di entità

Ogni entità è identificata da una chiave univoca all'interno dell'istanza del datastore dell'applicazione ed è composta da quanto segue:

  • kind. Normalmente il tipo è il nome della classe del modello a cui appartiene l'entità, ma puoi modificarlo in un'altra stringa sostituendo classmethod _get_kind().
  • identificatore. Puoi specificare il tuo nome chiave come identificatore o lasciare che Datastore generi automaticamente un ID numerico intero.

Specificare il nome della chiave

L'esempio seguente crea in modo implicito una chiave con identificatore di stringa utilizzando il parametro denominato id:

account = Account(
    username='Sandy', userid=1234, email='sandy@example.com',
    id='sandy@example.com')

return account.key.id()  # returns 'sandy@example.com'

In alternativa, puoi impostare direttamente il nome della chiave:

account.key = ndb.Key('Account', 'sandy@example.com')

# You can also use the model class object itself, rather than its name,
# to specify the entity's kind:
account.key = ndb.Key(Account, 'sandy@example.com')

Consentire a Datastore di generare un ID da utilizzare per la chiave

Questo codice mostra come utilizzare un ID generato automaticamente come chiave:

# note: no id kwarg
account = Account(username='Sandy', userid=1234, email='sandy@example.com')
account.put()
# account.key will now have a key of the form: ndb.Key(Account, 71321839)
# where the value 71321839 was generated by Datastore for us.

Utilizzo del percorso predecessore nella chiave

La sequenza di entità che inizia con un'entità base e procedi dalla risorsa padre a quella figlio e conduce a una determinata entità, costituisce il percorso predecessore di tale entità. Un'entità, l'entità padre, l'entità padre e così via in modo ricorsivo, sono i antenati dell'entità. Le entità in Datastore formano uno spazio di chiavi gerarchico simile alla struttura di directory gerarchica di un file system.

La chiave completa che identifica un'entità è composta da una sequenza di coppie di tipo-identifier che specificano il percorso dei predecessori e che termina con quelli dell'entità stessa. Il metodo del costruttore per la classe Key accetta questa sequenza di tipi e identificatori e restituisce un oggetto che rappresenta la chiave dell'entità corrispondente.

Nell'esempio seguente viene mostrato un servizio di blogging che archivia i messaggi in base a revisione. I messaggi sono organizzati in account e le revisioni sono sotto i messaggi.

class Revision(ndb.Model):
    message_text = ndb.StringProperty()
... 
ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '1')
ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '2')
ndb.Key('Account', 'larry@example.com', 'Message', 456, 'Revision', '1')
ndb.Key('Account', 'larry@example.com', 'Message', 789, 'Revision', '2')

Nell'esempio, ('Account', 'sandy@example.com'), ('Message', 123) e ('Revision', '1') sono tutti esempi di coppie tipo-identificatore.

Nota che Message non è una classe di modello; viene utilizzato solo come modo per raggruppare le revisioni, non per archiviare i dati.

Come mostrato nel codice campione, il tipo di entità è designato dall'ultima coppia nome-tipo nell'elenco: ndb.Key('Revision', '1').

Utilizzo di parametri denominati

Puoi utilizzare il parametro denominato parent per designare direttamente qualsiasi entità nel percorso del predecessore. Tutte le seguenti notazioni rappresentano la stessa chiave:

ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '1')

ndb.Key('Revision', '1', parent=ndb.Key(
    'Account', 'sandy@example.com', 'Message', 123))

ndb.Key('Revision', '1', parent=ndb.Key(
    'Message', 123, parent=ndb.Key('Account', 'sandy@example.com')))

Specifica di un'entità base

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

sandy_key = ndb.Key(Account, 'sandy@example.com')

Specifica di un'entità con i predecessori

Inserire un nuovo messaggio con chiavi padre

account_key = ndb.Key(Account, 'sandy@example.com')

# Ask Datastore to allocate an ID.
new_id = ndb.Model.allocate_ids(size=1, parent=account_key)[0]

# Datastore returns us an integer ID that we can use to create the message
# key
message_key = ndb.Key('Message', new_id, parent=account_key)

# Now we can put the message into Datastore
initial_revision = Revision(
    message_text='Hello', id='1', parent=message_key)
initial_revision.put()

Per le chiavi create con un elemento padre, il metodo parent() restituisce una chiave che rappresenta l'entità padre:

message_key = initial_revision.key.parent()

Uso degli ID dei tasti numerici

Puoi creare un'entità senza specificare un ID, nel qual caso il datastore genera automaticamente un ID numerico. Se scegli di specificare alcuni ID e poi consenti a Datastore di generare automaticamente alcuni ID, potresti violare il requisito relativo alle chiavi univoche. Per evitare che ciò accada, riserva un intervallo di numeri da usare per scegliere gli ID oppure utilizza gli ID stringa per evitare completamente il problema.

Per prenotare un intervallo di ID, utilizza il metodo della classe allocate_ids() della classe del modello:

  • per assegnare un numero specifico di ID
  • per assegnare tutti gli ID fino a un determinato valore massimo.

Allocazione degli ID

Per assegnare 100 ID per una determinata classe di modelli MyModel:

first, last = MyModel.allocate_ids(100)

Per assegnare 100 ID per entità con chiave padre p:

first, last = MyModel.allocate_ids(100, parent=p)

I valori restituiti, first e last, sono il primo e l'ultimo ID (inclusi) che vengono allocati. È possibile usarle per creare le chiavi nel seguente modo:

keys = [ndb.Key(MyModel, id) for id in range(first, last+1)]

È garantito che queste chiavi non siano state restituite in precedenza dal generatore di ID interno del datastore, né che vengano restituite da chiamate future al generatore di ID interno. Tuttavia, il metodo allocate_ids() non controlla se gli ID restituiti sono presenti nel datastore, ma interagisce solo con il generatore di ID.

Per allocare tutti gli ID fino a un determinato valore massimo:

first, last = MyModel.allocate_ids(max=N)

Questo modulo garantisce che tutti gli ID minori o uguali a N vengano considerati allocati. I valori restituiti, first e last, indicano l'intervallo di ID prenotati da questa operazione. Non è un errore tentare di prenotare ID già allocati; in questo caso, first indica il primo ID non ancora allocato e last è l'ultimo ID allocato.