Avviso: nei prossimi mesi, stiamo riorganizzando il sito della documentazione di App Engine per semplificarti la ricerca dei contenuti e l'allineamento con il resto dei prodotti Google Cloud. Saranno disponibili gli stessi contenuti, ma ora la navigazione corrisponderà al resto dei prodotti Cloud. Se hai feedback o domande durante la navigazione del sito, fai clic su Invia feedback.

Metadati

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Datastore fornisce accesso programmatico ad alcuni dei suoi metadati per supportare la metaprogrammazione, l'implementazione di funzioni amministrative di backend, semplificare la memorizzazione nella cache coerente e scopi simili; puoi usarlo, ad esempio, per creare un visualizzatore Datastore personalizzato per la tua applicazione. I metadati disponibili includono informazioni sui gruppi di entità, gli spazi dei nomi, i tipi di entità e le proprietà che la tua applicazione utilizza, nonché le rappresentazioni delle proprietà per ogni proprietà.

Anche la Dashboard del datastore all'interno di Google Cloud Console fornisce alcuni metadati relativi alla tua applicazione, ma i dati visualizzati al suo interno differiscono per alcuni importanti aspetti rispetto a quelli restituiti da queste funzioni.

  • Aggiornamento. La lettura dei metadati tramite l'API riceve i dati correnti, mentre i dati nella dashboard vengono aggiornati solo una volta al giorno.
  • Sommario. Alcuni metadati nella dashboard non sono disponibili tramite le API; è vero anche il contrario.
  • Velocità. I metadati e le query vengono fatturati alla stessa stregua dei dati e delle query di Datastore. Le query sui metadati che recuperano informazioni su spazi dei nomi, tipi e proprietà sono generalmente lente da eseguire. Come regola generale, una query sui metadati che restituisce N entità richiede all'incirca lo stesso tempo di N query ordinarie ciascuna delle quali restituisce una singola entità. Inoltre, le query di rappresentazione delle proprietà (query di proprietà non chiave) sono più lente delle query di proprietà solo chiavi. I metadati dei metadati dei gruppi di entità sono leggermente più veloci di quelli di un'entità standard.

Metadati del gruppo di entità

Cloud Datastore fornisce l'accesso alla "versione" di un gruppo di entità, un numero strettamente positivo che garantisce un aumento ad ogni modifica del gruppo di entità.

Le versioni dei gruppi di entità vengono ottenute chiamando get() per una pseudo-entità speciale che contiene una proprietà __version__ strettamente positiva. La chiave pseudo-entità's può essere creata utilizzando il metodo Entities.createEntityGroupKey():

appengine-java8/datastore/src/test/java/com/example/appengine/MetadataEntityGroupTest.java 
private static long getEntityGroupVersion(DatastoreService ds, Transaction tx, Key entityKey) {
  try {
    return Entities.getVersionProperty(ds.get(tx, Entities.createEntityGroupKey(entityKey)));
  } catch (EntityNotFoundException e) {
    // No entity group information, return a value strictly smaller than any
    // possible version
    return 0;
  }
}

private static void printEntityGroupVersions(DatastoreService ds, PrintWriter writer) {
  Entity entity1 = new Entity("Simple");
  Key key1 = ds.put(entity1);
  Key entityGroupKey = Entities.createEntityGroupKey(key1);

  // Print entity1's entity group version
  writer.println("version " + getEntityGroupVersion(ds, null, key1));

  // Write to a different entity group
  Entity entity2 = new Entity("Simple");
  ds.put(entity2);

  // Will print the same version, as entity1's entity group has not changed
  writer.println("version " + getEntityGroupVersion(ds, null, key1));

  // Change entity1's entity group by adding a new child entity
  Entity entity3 = new Entity("Simple", entity1.getKey());
  ds.put(entity3);

  // Will print a higher version, as entity1's entity group has changed
  writer.println("version " + getEntityGroupVersion(ds, null, key1));
}

Comportamento precedente

Nel comportamento della versione del gruppo di entità precedente, la versione del gruppo di entità aumenta solo in caso di modifiche al gruppo di entità. È possibile utilizzare il comportamento precedente dei metadati del gruppo di entità, ad esempio per conservare una cache coerente di una query predecessore complessa su un gruppo di entità.

In questo esempio vengono memorizzati nella cache i risultati delle query (un conteggio dei risultati corrispondenti) e viene utilizzato il comportamento precedente delle versioni dei gruppi di entità per utilizzare il valore memorizzato nella cache se è attuale:

appengine-java8/datastore/src/test/java/com/example/appengine/MetadataEntityGroupTest.java 
// A simple class for tracking consistent entity group counts.
private static class EntityGroupCount implements Serializable {

  long version; // Version of the entity group whose count we are tracking
  int count;

  EntityGroupCount(long version, int count) {
    this.version = version;
    this.count = count;
  }

  // Display count of entities in an entity group, with consistent caching
  void showEntityGroupCount(
      DatastoreService ds, MemcacheService cache, PrintWriter writer, Key entityGroupKey) {
    EntityGroupCount egCount = (EntityGroupCount) cache.get(entityGroupKey);
    // Reuses getEntityGroupVersion method from the previous example.
    if (egCount != null && egCount.version == getEntityGroupVersion(ds, null, entityGroupKey)) {
      // Cached value matched current entity group version, use that
      writer.println(egCount.count + " entities (cached)");
    } else {
      // Need to actually count entities. Using a transaction to get a consistent count
      // and entity group version.
      Transaction tx = ds.beginTransaction();
      PreparedQuery pq = ds.prepare(tx, new Query(entityGroupKey));
      int count = pq.countEntities(FetchOptions.Builder.withLimit(5000));
      cache.put(
          entityGroupKey,
          new EntityGroupCount(getEntityGroupVersion(ds, tx, entityGroupKey), count));
      tx.rollback();
      writer.println(count + " entities");
    }
  }
}

Le entità __entity_group__ non possono esistere per gruppi di entità che non sono mai stati scritti.

Query dei metadati

La classe Java Entities, definita nel pacchetto com.google.appengine.api.datastore, fornisce tre tipi di entità speciali riservati per le query di metadati. Sono indicati da costanti statiche della classe Entities:

Costante statica Tipo di entità
Entities.NAMESPACE_METADATA_KIND __namespace__
Entities.KIND_METADATA_KIND __kind__
Entities.PROPERTY_METADATA_KIND __property__

Questi tipi non saranno in conflitto con altri con gli stessi nomi che potrebbero già esistere nella tua applicazione. Inviando una query su questi tipi speciali, puoi recuperare le entità contenenti i metadati desiderati.

Le entità restituite dalle query sui metadati vengono generate in modo dinamico, sulla base dello stato corrente di Datastore. Sebbene sia possibile creare oggetti Entity locali di tipo __namespace__, __kind__ o __property__, qualsiasi tentativo di archiviarli in Datastore non riuscirà con un elemento IllegalArgumentException.

Il modo più semplice per emettere query sui metadati è utilizzare l'API Datastore di basso livello. L'esempio seguente stampa i nomi di tutti gli spazi dei nomi in un'applicazione:

appengine-java8/datastore/src/test/java/com/example/appengine/MetadataNamespacesTest.java 
void printAllNamespaces(DatastoreService ds, PrintWriter writer) {
  Query q = new Query(Entities.NAMESPACE_METADATA_KIND);

  for (Entity e : ds.prepare(q).asIterable()) {
    // A nonzero numeric id denotes the default namespace;
    // see <a href="#Namespace_Queries">Namespace Queries</a>, below
    if (e.getKey().getId() != 0) {
      writer.println("<default>");
    } else {
      writer.println(e.getKey().getName());
    }
  }
}

Query sullo spazio dei nomi

Se la tua applicazione utilizza l'API Namespaces, puoi utilizzare una query dello spazio dei nomi per trovare tutti gli spazi dei nomi utilizzati nelle entità dell'applicazione. Ciò consente di eseguire attività come le funzioni amministrative in più spazi dei nomi.

Le query sullo spazio dei nomi restituiscono entità del tipo speciale __namespace__ il cui nome chiave è il nome di uno spazio dei nomi. Un'eccezione è lo spazio dei nomi predefinito designato dalla stringa vuota "": poiché la stringa vuota non è un nome di chiave valido, questo spazio dei nomi viene chiave con l'ID numerico 1. Le query di questo tipo supportano solo i filtri per gli intervalli nella pseudoproprietà speciale __key__, il cui valore è la chiave dell'entità. I risultati possono essere ordinati in base al valore __key__ crescente (ma non decrescente). Poiché le entità __namespace__ non hanno proprietà, le query contenenti solo chiavi e non solo chiavi restituiscono le stesse informazioni.

L'esempio seguente restituisce un elenco degli spazi dei nomi di un'applicazione nell'intervallo compreso tra due nomi specificati, start e end:

appengine-java8/datastore/src/test/java/com/example/appengine/MetadataNamespacesTest.java 
List<String> getNamespaces(DatastoreService ds, String start, String end) {

  // Start with unrestricted namespace query
  Query q = new Query(Entities.NAMESPACE_METADATA_KIND);
  List<Filter> subFilters = new ArrayList();
  // Limit to specified range, if any
  if (start != null) {
    subFilters.add(
        new FilterPredicate(
            Entity.KEY_RESERVED_PROPERTY,
            FilterOperator.GREATER_THAN_OR_EQUAL,
            Entities.createNamespaceKey(start)));
  }
  if (end != null) {
    subFilters.add(
        new FilterPredicate(
            Entity.KEY_RESERVED_PROPERTY,
            FilterOperator.LESS_THAN_OR_EQUAL,
            Entities.createNamespaceKey(end)));
  }

  q.setFilter(CompositeFilterOperator.and(subFilters));

  // Initialize result list
  List<String> results = new ArrayList<String>();

  // Build list of query results
  for (Entity e : ds.prepare(q).asIterable()) {
    results.add(Entities.getNamespaceFromNamespaceKey(e.getKey()));
  }

  // Return result list
  return results;
}

Query gentili

Le query tipo restituiscono entità di tipo __kind__ il cui nome chiave è il nome di un tipo di entità. Le query di questo tipo sono implicitamente limitate all'attuale spazio dei nomi e supportano il filtro solo per intervalli relativi alla proprietà __key__. I risultati possono essere ordinati in base al valore __key__ (non in ordine crescente). Poiché le entità __kind__ non hanno proprietà, le query contenenti solo chiavi o solo chiavi non restituiscono le stesse informazioni.

L'esempio seguente stampa tutti i tipi i cui nomi iniziano con una lettera minuscola:

appengine-java8/datastore/src/test/java/com/example/appengine/MetadataKindsTest.java 
void printLowercaseKinds(DatastoreService ds, PrintWriter writer) {

  // Start with unrestricted kind query
  Query q = new Query(Entities.KIND_METADATA_KIND);

  List<Filter> subFils = new ArrayList();

  // Limit to lowercase initial letters
  subFils.add(
      new FilterPredicate(
          Entity.KEY_RESERVED_PROPERTY,
          FilterOperator.GREATER_THAN_OR_EQUAL,
          Entities.createKindKey("a")));

  String endChar = Character.toString((char) ('z' + 1)); // Character after 'z'

  subFils.add(
      new FilterPredicate(
          Entity.KEY_RESERVED_PROPERTY,
          FilterOperator.LESS_THAN,
          Entities.createKindKey(endChar)));

  q.setFilter(CompositeFilterOperator.and(subFils));

  // Print heading
  writer.println("Lowercase kinds:");

  // Print query results
  for (Entity e : ds.prepare(q).asIterable()) {
    writer.println("  " + e.getKey().getName());
  }
}

Query della proprietà

Le query proprietà restituiscono le entità di tipo __property__ che indicano le proprietà associate a un tipo di entità. L'entità che rappresenta la proprietà P di tipo K è creata come segue:

  • La chiave dell'entità ha il tipo __property__ e il nome chiave P.
  • La chiave dell'entità padre ha il tipo __kind__ e il nome chiave K.

Il comportamento di una query di una proprietà dipende dal fatto che si tratti di una query solo chiavi o solo non chiavi (rappresentazione della proprietà), come descritto di seguito nelle sottosezioni.

Query della proprietà: solo chiavi

Le query di proprietà solo chiavi restituiscono una chiave per ogni proprietà indicizzata di un tipo di entità specificato. Le proprietà non indicizzate non sono incluse. L'esempio seguente stampa i nomi di tutti i tipi di entità di un'applicazione e le proprietà associate a ciascuno di essi:

appengine-java8/datastore/src/test/java/com/example/appengine/MetadataPropertiesTest.java 
void printProperties(DatastoreService ds, PrintWriter writer) {

  // Create unrestricted keys-only property query
  Query q = new Query(Entities.PROPERTY_METADATA_KIND).setKeysOnly();

  // Print query results
  for (Entity e : ds.prepare(q).asIterable()) {
    writer.println(e.getKey().getParent().getName() + ": " + e.getKey().getName());
  }
}

Le query di questo tipo sono implicitamente limitate allo spazio dei nomi corrente e supportano i filtri solo per gli intervalli sulla pseudoproprietà __key__, dove le chiavi indicano le entità __kind__ o __property__. I risultati possono essere ordinati in base al valore __key__ crescente (ma non decrescente). Il filtro viene applicato alle coppie proprietà-tipo, ordinate prima per tipo e seconda per proprietà: ad esempio, supponiamo che tu abbia un'entità con queste proprietà:

  • tipo Account con proprietà
    • balance
    • company
  • tipo Employee con proprietà
    • name
    • ssn
  • tipo Invoice con proprietà
    • date
    • amount
  • tipo Manager con proprietà
    • name
    • title
  • tipo Product con proprietà
    • description
    • price

La query che restituisce i dati della proprietà sarà simile alla seguente:

appengine-java8/datastore/src/test/java/com/example/appengine/MetadataPropertiesTest.java 
void printPropertyRange(DatastoreService ds, PrintWriter writer) {

  // Start with unrestricted keys-only property query
  Query q = new Query(Entities.PROPERTY_METADATA_KIND).setKeysOnly();

  // Limit range
  q.setFilter(
      CompositeFilterOperator.and(
          new FilterPredicate(
              Entity.KEY_RESERVED_PROPERTY,
              Query.FilterOperator.GREATER_THAN_OR_EQUAL,
              Entities.createPropertyKey("Employee", "salary")),
          new FilterPredicate(
              Entity.KEY_RESERVED_PROPERTY,
              Query.FilterOperator.LESS_THAN_OR_EQUAL,
              Entities.createPropertyKey("Manager", "salary"))));
  q.addSort(Entity.KEY_RESERVED_PROPERTY, SortDirection.ASCENDING);

  // Print query results
  for (Entity e : ds.prepare(q).asIterable()) {
    writer.println(e.getKey().getParent().getName() + ": " + e.getKey().getName());
  }
}

La query riportata sopra restituirà:

Employee: ssn
Invoice: date
Invoice: amount
Manager: name

Tieni presente che i risultati non includono la proprietà name di tipo Employee e la proprietà title di tipo Manager, né qualsiasi proprietà di tipo Account e Product, perché non rientrano nell'intervallo specificato per la query.

Le query delle proprietà supportano anche il filtro predecessore su una chiave __kind__ o __property__ per limitare i risultati della query a un singolo tipo o una sola proprietà. Puoi utilizzarlo, ad esempio, per ottenere le proprietà associate a un determinato tipo di entità, come nell'esempio seguente:

appengine-java8/datastore/src/test/java/com/example/appengine/MetadataPropertiesTest.java 
List<String> propertiesOfKind(DatastoreService ds, String kind) {

  // Start with unrestricted keys-only property query
  Query q = new Query(Entities.PROPERTY_METADATA_KIND).setKeysOnly();

  // Limit to specified kind
  q.setAncestor(Entities.createKindKey(kind));

  // Initialize result list
  ArrayList<String> results = new ArrayList<String>();

  //Build list of query results
  for (Entity e : ds.prepare(q).asIterable()) {
    results.add(e.getKey().getName());
  }

  // Return result list
  return results;
}

Query della proprietà: non basate su chiavi (rappresentazione della proprietà)

Le query delle proprietà non basate su chiavi, note come query di rappresentazione delle proprietà, restituiscono informazioni aggiuntive sulle rappresentazioni utilizzate da ogni coppia di proprietà di tipo. Le proprietà non indicizzate non sono incluse. L'entità restituita per la proprietà P di tipo K ha la stessa chiave di una query contenente solo chiavi corrispondente, insieme a un'ulteriore proprietà property_representation che restituisce le rappresentazioni della proprietà. Il valore di questa proprietà è un'istanza di classe java.util.Collection<String> contenente una stringa per ogni rappresentazione della proprietà P trovata in qualsiasi entità di tipo K.

Tieni presente che le rappresentazioni non sono come le classi di proprietà; più classi di proprietà possono essere mappate alla stessa rappresentazione. Ad esempio, java.lang.String e com.google.appengine.api.datastore.PhoneNumber utilizzano entrambi la rappresentazione STRING.

La tabella seguente viene mappata dalle classi di proprietà alle relative rappresentazioni:

Classe proprietà Rappresentanza
java.lang.Byte INT64
java.lang.Short INT64
java.lang.Integer INT64
java.lang.Long INT64
java.lang.Float DOUBLE
java.lang.Double DOUBLE
java.lang.Boolean BOOLEAN
java.lang.String STRING
com.google.appengine.api.datastore.ShortBlob STRING
java.util.Date INT64
com.google.appengine.api.datastore.GeoPt POINT
com.google.appengine.api.datastore.PostalAddress STRING
com.google.appengine.api.datastore.PhoneNumber STRING
com.google.appengine.api.datastore.Email STRING
com.google.appengine.api.users.User USER
com.google.appengine.api.datastore.IMHandle STRING
com.google.appengine.api.datastore.Link STRING
com.google.appengine.api.datastore.Category STRING
com.google.appengine.api.datastore.Rating INT64
com.google.appengine.api.datastore.Key REFERENCE
com.google.appengine.api.blobstore.BlobKey STRING
java.util.Collection<T> Rappresentazione di T

L'esempio seguente trova tutte le rappresentazioni di una proprietà specificata per un determinato tipo di entità:

appengine-java8/datastore/src/test/java/com/example/appengine/MetadataPropertiesTest.java 
Collection<String> representationsOfProperty(DatastoreService ds, String kind, String property) {

  // Start with unrestricted non-keys-only property query
  Query q = new Query(Entities.PROPERTY_METADATA_KIND);

  // Limit to specified kind and property
  q.setFilter(
      new FilterPredicate(
          "__key__", Query.FilterOperator.EQUAL, Entities.createPropertyKey(kind, property)));

  // Get query result
  Entity propInfo = ds.prepare(q).asSingleEntity();

  // Return collection of property representations
  return (Collection<String>) propInfo.getProperty("property_representation");
}