Creazione e utilizzo delle chiavi di entità

Ogni entità è identificata da una chiave univoca all'interno dell'istanza Datastore dell'applicazione e composta da:

  • kind. Il tipo è in genere il nome della classe di modello a cui appartiene l'entità, ma puoi modificarlo in un'altra stringa eseguendo l'override del metodo di classe _get_kind().
  • identificatore. Specifica il tuo nome chiave come identificatore o lascia che Datastore generi automaticamente un ID numerico intero.

Specificare il proprio nome della chiave

Il seguente esempio crea implicitamente una chiave con un identificatore 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 degli antenati nella chiave

La sequenza di entità che inizia con unentità base e procede da quella padre a quella figlio, fino a un'entità specifica, costituisce il percorso degli antenati di quell'entità. Un'entità, la relativa entità principale, l'entità principale dell'entità principale e così via in modo ricorsivo sono gli antenati dell'entità. Le entità in Datastore formano uno spazio delle chiavi gerarchico simile alla struttura di directory gerarchica di un file system.

La chiave completa che identifica un'entità è costituita da una sequenza di coppie tipo-identificatore che specificano il percorso degli antenati e terminano con quelli dell'entità stessa. Il metodo costruttore per la classe Key accetta una sequenza di tipi e identificatori e restituisce un oggetto che rappresenta la chiave per l'entità corrispondente.

L'esempio seguente mostra un servizio di blogging che archivia i messaggi per revisione. I messaggi sono organizzati per account e le revisioni per messaggio.

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.

Tieni presente che Message non è una classe di modello; viene utilizzata solo per raggruppare le revisioni, non per archiviare i dati.

Come mostrato nel codice campione, il tipo di entità è indicato 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 ancestrale. 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 degli antenati è vuoto e la chiave è costituita unicamente dal tipo e dall'identificatore dell'entità.

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

Specificare un'entità con antenati

Per inserire un nuovo messaggio con le chiavi genitore

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()

Utilizzo degli ID tasto 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 di lasciare che Datastore ne generi automaticamente altri, potresti violare il requisito delle chiavi univoche. Per evitare questo problema, riserva un intervallo di numeri da utilizzare per scegliere gli ID o utilizza ID stringa.

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

  • per allocare un numero specificato di ID
  • per allocare tutti gli ID fino a un determinato valore massimo.

Allocazione degli ID

Per allocare 100 ID per una determinata classe di modello MyModel:

first, last = MyModel.allocate_ids(100)

Per allocare 100 ID per le entità con la chiave principale 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. Puoi utilizzarli per creare 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 dell'archivio dati e non verranno restituite da chiamate future al generatore di ID interno. Tuttavia, il metodo allocate_ids() non verifica se gli ID restituiti sono presenti neldatastorei, 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 inferiori o uguali a N vengano considerati assegnati. I valori restituiti, first e last, indicano l'intervallo di ID riservati 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.