Crear y usar claves de entidad

Esta API es compatible con entornos de ejecución de primera generación y se puede usar en actualizaciones a los entornos de ejecución de segunda generación correspondientes. Si actualizas al entorno de ejecución de Java 11/17 de App Engine, consulta la guía de migración para obtener información acerca de tus opciones de migración para servicios agrupados en paquetes heredados.

Cada entidad en Datastore tiene una clave que la identifica de manera única. La clave consta de los siguientes componentes:

• El espacio de nombres de la entidad, que permite la función de multiusuario
• El tipo de entidad, que la clasifica para realizar consultas de Datastore
• Una ruta principal opcional que ubica la entidad dentro de la jerarquía de Datastore

• Un identificador de la entidad individual, que puede ser alguna de las siguientes opciones:

  • una string de nombre de clave
  • un ID numérico de enteros

Debido a que es parte de la clave de la entidad, el identificador se encuentra asociado de forma permanente a la entidad y no se puede cambiar. El identificador se puede asignar de las siguientes dos maneras:

• Especifica tu propia string de nombre de clave para la entidad.
• Permite que Datastore asigne de forma automática un ID numérico entero a la entidad.

No asignes el nombre “clave” para una propiedad. Este nombre se reserva para una propiedad especial que se usa a fin de almacenar la clave Model. Aunque pueda funcionar de manera local, la existencia de una propiedad llamada “clave” impedirá la implementación en App Engine.

Cómo especificar un nombre de clave para una entidad

Cuando asignes un nombre de clave a la entidad, proporciona el nombre como el segundo argumento en el constructor cuando crees la entidad:

Entity employee = new Entity("Employee", "asalieri");

Para que Datastore asigne un ID numérico de forma automática, omite el siguiente argumento:

Entity employee = new Entity("Employee");

Asigna identificadores

Puedes configurar Datastore para generar ID automáticos mediante dos políticas de ID automática distintas:

• La política default genera una secuencia aleatoria de ID sin usar con una distribución bastante uniforme. Cada ID puede tener hasta 16 dígitos decimales.
• La política legacy crea una secuencia de ID de números enteros no consecutivos más breves.

Si quieres mostrar al usuario los ID de la entidad o depender de su pedido, lo mejor que puedes hacer es usar la asignación manual.

Nota: En lugar de usar strings de nombre de clave o generar ID numéricos de forma automática, en las aplicaciones avanzadas, tal vez resulte más conveniente asignar ID numéricos propios de forma manual a las entidades creadas. Sin embargo, ten en cuenta que nada impide que Datastore asigne uno de tus ID numéricos manuales a otra entidad. La única forma de impedir ese conflicto es pedir a la aplicación que obtenga un bloque de varios ID con los métodos DatastoreService.allocateIds() o AsyncDatastoreService.allocateIds(). El generador automático de ID de Datastore hará un seguimiento de los ID asignados con estos métodos y evitará que se vuelvan a usar en otra entidad; de esta manera, podrás usarlos sin que se generen conflictos.

Usa rutas principales

Las entidades de Cloud Datastore conforman un espacio con estructura jerárquica similar a la estructura de directorios de un sistema de archivos. Cuando creas una entidad, tienes la opción de designar otra entidad como superior, en cuyo caso la nueva entidad es secundaria respecto de la entidad superior (ten en cuenta que, a diferencia de lo que ocurre en un sistema de archivos, no es necesario que efectivamente exista una entidad superior). Las entidades que no tienen una principal se denominan entidades raíz. La asociación entre una entidad secundaria y la entidad superior es permanente, y no puede cambiarse una vez creada la entidad. Cloud Datastore nunca asignará el mismo ID numérico a dos entidades asociadas a la misma entidad superior ni a dos entidades raíz (no asociadas a una entidad superior).

La entidad superior de una entidad determinada, la superior de la superior y así sucesivamente son sus principales. Las entidades secundarias respecto de una entidad determinada, las secundarias de las secundarias y así sucesivamente son sus descendientes. Una entidad raíz y todos sus descendientes pertenecen al mismo grupo de entidad. La secuencia de entidades que comienza con una entidad raíz y sigue de principal a secundaria, hasta llegar a una entidad determinada, constituye la ruta de principal de esa entidad. La clave completa que identifica una entidad consta de una secuencia de pares de tipo-identificador que especifican la ruta de principales y terminan con el tipo y el identificador de la propia entidad:

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

En el caso de una entidad raíz, la ruta de principales está vacía, y la clave consta solo del tipo y el identificador de la entidad:

[Person:GreatGrandpa]

Este concepto se ilustra en el diagrama siguiente:

Para designar la entidad principal respecto de una secundaria, proporciona la clave de la entidad principal como argumento al constructor Entity() cuando creas la entidad secundaria. Para obtener la clave, llama al método getKey() de la entidad principal:

Entity employee = new Entity("Employee");
datastore.put(employee);

Entity address = new Entity("Address", employee.getKey());
datastore.put(address);

Si la entidad nueva también tiene un nombre de clave, proporciona el nombre de clave como el segundo argumento al constructor Entity() y la clave de la entidad principal como tercer argumento:

Entity address = new Entity("Address", "addr1", employee.getKey());

Genera claves

Las aplicaciones pueden usar la clase KeyFactory a fin de crear un objeto Key para una entidad de componentes conocidos, como el identificador y el tipo de entidad. Para una entidad sin superior, pasa el tipo y el identificador (ya sea un ID numérico o una string de nombre de clave) al método estático KeyFactory.createKey() a fin de crear la clave. En los ejemplos siguientes, se crea una clave para una entidad del tipo Person con el nombre de clave "GreatGrandpa" o el ID numérico 74219:

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

Si la clave incluye un componente de ruta de acceso, puedes usar la clase auxiliar KeyFactory.Builder para crear la ruta. El método addChild de esta clase agrega una sola entidad a la ruta de acceso y muestra el compilador, para que puedas encadenar una serie de llamadas a partir de la entidad raíz, y así crear la ruta de acceso de una entidad a la vez. Después de compilar toda la ruta de acceso, llama a getKey para recuperar la clave resultante de la siguiente manera:

Key k =
    new KeyFactory.Builder("Person", "GreatGrandpa")
        .addChild("Person", "Grandpa")
        .addChild("Person", "Dad")
        .addChild("Person", "Me")
        .getKey();

La clase KeyFactory también incluye los métodos estáticos keyToString y stringToKey para la conversión entre claves y sus representaciones de strings:

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 representación de string de una clave es "segura para la Web": no contiene caracteres que se consideren especiales en HTML o en URLs.

Nota: El método KeyFactory.keyToString es diferente de Key.toString, que muestra una string legible adecuada para su uso en la depuración y en el registro. Si necesitas un valor de string que se pueda convertir en una clave utilizable, usa KeyFactory.keyToString.

Ten en cuenta también que la representación de string de una clave no está encriptada: un usuario puede decodificar la string de clave para extraer sus componentes, incluidos los tipos y los identificadores de la entidad y sus principales. Si es importante ocultar esta información del usuario, debes encriptar tú mismo la string de clave antes de enviarla al usuario.