Membuat dan Menggunakan Kunci Entity

Setiap entity dalam Datastore memiliki kunci yang secara unik mengidentifikasinya. Kunci ini terdiri dari komponen berikut:

  • Namespace entity, yang memungkinkan multitenancy
  • Jenis entity, yang mengategorikannya untuk tujuan kueri Datastore
  • Jalur ancestor opsional yang mencari entity dalam hierarki Datastore.

  • ID untuk masing-masing entitas, yang dapat berupa

    • string nama kunci
    • ID numerik bilangan bulat

Karena ID adalah bagian dari kunci entity, ID-nya terkait secara permanen dengan entity dan tidak dapat diubah. Anda menetapkan ID ini dengan salah satu dari dua cara berikut:

  • Tentukan string key name Anda sendiri untuk entity.
  • Biarkan Datastore secara otomatis menetapkan ID numerik bilangan bulat ke entity.

Menentukan nama kunci untuk entitas

Untuk menetapkan nama kunci ke suatu entity, berikan nama sebagai argumen kedua kepada konstruktor saat Anda membuat entity:

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

Agar Datastore dapat menetapkan ID numerik secara otomatis, hapus argumen ini:

Entity employee = new Entity("Employee");

Menetapkan ID

Anda dapat mengonfigurasi Datastore untuk menghasilkan ID otomatis menggunakan dua kebijakan ID otomatis yang berbeda:

  • Kebijakan default menghasilkan urutan acak dari ID yang tidak digunakan yang kira-kira didistribusikan secara seragam. Setiap ID dapat memiliki maksimal 16 digit desimal.
  • Kebijakan legacy membuat urutan ID bilangan bulat yang lebih kecil dan tidak berurutan.

Jika Anda ingin menampilkan ID entity kepada pengguna, dan/atau bergantung pada urutannya, sebaiknya Anda menggunakan alokasi manual.

Menggunakan jalur ancestor

Entity dalam Cloud Datastore membentuk ruang terstruktur secara hierarkis yang mirip dengan struktur direktori sistem file. Saat membuat entity, Anda dapat memilih untuk menetapkan entity lain sebagai parent; entity barunya adalah turunan dari parent entity tersebut (perlu diperhatikan bahwa tidak seperti dalam sistem file, parent entity tidak harus benar-benar ada). Entity tanpa parent adalah root entity. Kaitan entity dan induknya bersifat permanen, dan tidak dapat diubah setelah entity tersebut dibuat. Cloud Datastore tidak akan pernah menetapkan ID numerik yang sama ke dua entity dengan parent yang sama, atau ke dua root entity (yang tidak memiliki parent).

Induk, induk dari induk, dan seterusnya dari suatu entity secara rekursif adalah ancestor-nya; turunannya, turunan dari turunannya, dan seterusnya adalah turunannya. Root entity dan semua turunannya termasuk dalam entity group yang sama. Urutan entity yang dimulai dengan root entity dan berlanjut dari parent ke turunan, yang mengarah ke entity tertentu, merupakan jalur ancestor entity tersebut. Kunci lengkap yang mengidentifikasi entity terdiri dari urutan pasangan jenis-ID yang menentukan jalur ancestor-nya dan berakhir dengan entity itu sendiri:

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

Untuk root entity, jalur ancestor kosong dan kuncinya hanya terdiri dari jenis dan ID entity itu sendiri:

[Person:GreatGrandpa]

Konsep ini diilustrasikan oleh diagram berikut:

Menampilkan hubungan root entity dengan entity turunan dalam entity group

Untuk menetapkan induk entity, berikan kunci entity induk sebagai argumen ke konstruktor Entity() saat membuat entity turunan. Anda bisa mendapatkan kunci dengan memanggil metode getKey() entity induk:

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

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

Jika entity baru juga memiliki nama kunci, berikan nama kunci sebagai argumen kedua ke konstruktor Entity() dan kunci entity induk sebagai argumen ketiga:

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

Membuat kunci

Aplikasi dapat menggunakan class KeyFactory untuk membuat objek Key bagi entity dari komponen yang diketahui, seperti jenis dan ID entity. Untuk entity tanpa induk, teruskan jenis dan ID (baik string nama kunci maupun ID numerik) ke metode statis KeyFactory.createKey() untuk membuat kunci. Contoh berikut membuat kunci untuk entity jenis Person dengan nama kunci "GreatGrandpa" atau ID numerik 74219:

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

Jika kunci menyertakan komponen jalur, Anda dapat menggunakan class bantuan KeyFactory.Builder untuk membangun jalur. Metode addChild class ini menambahkan satu entity ke jalur dan menampilkan builder itu sendiri sehingga Anda dapat merangkai serangkaian panggilan, dimulai dengan root entity, untuk membangun jalur satu entity pada satu waktu. Setelah membangun jalur lengkap, panggil getKey untuk mengambil kunci yang dihasilkan:

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

Class KeyFactory juga menyertakan metode statis keyToString dan stringToKey untuk melakukan konversi antara kunci dan representasi string-nya:

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

Representasi string kunci adalah "web-safe": tidak berisi karakter yang dianggap spesial dalam HTML atau URL.