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:
Agar Datastore dapat menetapkan ID numerik secara otomatis, hapus argumen ini:
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:
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:
Jika entity baru juga memiliki nama kunci, berikan nama kunci sebagai argumen kedua
ke konstruktor Entity()
dan kunci entity induk sebagai
argumen ketiga:
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
:
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:
Class KeyFactory
juga menyertakan metode statis keyToString
dan stringToKey
untuk melakukan konversi antara kunci dan representasi string-nya:
Representasi string kunci adalah "web-safe": tidak berisi karakter yang dianggap spesial dalam HTML atau URL.