Tujuan
Tutorial ini akan memandu Anda melalui langkah-langkah berikut menggunakan Cloud Spanner API dengan REST:
- Buat instance dan database Spanner.
- Menulis, membaca, dan menjalankan kueri SQL pada data di database.
- Perbarui skema database.
- Tambahkan indeks sekunder ke database.
- Gunakan indeks untuk membaca dan menjalankan kueri SQL pada data.
- Mengambil data menggunakan transaksi hanya baca.
Jika Anda ingin menggunakan library klien Spanner, bukan menggunakan REST API, lihat Tutorial.
Biaya
Tutorial ini menggunakan Spanner, yang merupakan komponenGoogle Cloudyang dapat ditagih. Untuk mengetahui informasi tentang biaya penggunaan Spanner, lihat Harga.
Sebelum memulai
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- Fitur Coba! yang ada di dokumentasi referensi Spanner API. Contoh yang ditampilkan di halaman ini menggunakan fitur Coba!.
- Google APIs Explorer, yang berisi Cloud Spanner API dan Google API lainnya.
- Alat atau framework lain yang mendukung panggilan HTTP REST.
Contoh menggunakan
[PROJECT_ID]
sebagai ID project Google Cloud . Ganti Google Cloud project ID Anda dengan[PROJECT_ID]
. Jangan sertakan[
dan]
dalam project ID Anda.Contoh membuat dan menggunakan ID instance
test-instance
. Ganti ID instance Anda jika Anda tidak menggunakantest-instance
.Contoh ini membuat dan menggunakan ID database
example-db
. Ganti ID database Anda jika Anda tidak menggunakanexample-db
.Contoh menggunakan
[SESSION]
sebagai bagian dari nama sesi. Ganti nilai yang Anda terima saat membuat sesi untuk[SESSION]
. (Jangan sertakan[
dan]
dalam nama sesi Anda.)Contoh menggunakan ID transaksi
[TRANSACTION_ID]
. Ganti nilai yang Anda terima saat membuat transaksi untuk[TRANSACTION_ID]
. (Jangan sertakan[
dan]
dalam ID transaksi Anda.)Fungsi Coba! mendukung penambahan setiap kolom permintaan HTTP secara interaktif. Sebagian besar contoh dalam topik ini memberikan seluruh permintaan, bukan menjelaskan cara menambahkan setiap kolom ke permintaan secara interaktif.
- Klik
projects.instanceConfigs.list
. Untuk parent, masukkan:
projects/[PROJECT_ID]
Klik Jalankan. Konfigurasi instance yang tersedia ditampilkan dalam respons. Berikut adalah contoh respons (project Anda mungkin memiliki konfigurasi instance yang berbeda):
{ "instanceConfigs": [ { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-asia-south1", "displayName": "asia-south1" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-asia-east1", "displayName": "asia-east1" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-asia-northeast1", "displayName": "asia-northeast1" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-europe-west1", "displayName": "europe-west1" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-us-east4", "displayName": "us-east4" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-us-central1", "displayName": "us-central1" } ] }
- Klik
projects.instances.create
. Untuk parent, masukkan:
projects/[PROJECT_ID]
Klik Tambahkan parameter isi permintaan, lalu pilih
instance
.Klik balon petunjuk untuk instance guna melihat kemungkinan kolom. Tambahkan nilai untuk kolom berikut:
nodeCount
: Masukkan1
.config
: Masukkan nilainame
dari salah satu konfigurasi instance regional yang ditampilkan saat Anda mencantumkan konfigurasi instance.displayName
: MasukkanTest Instance
.
Klik balon petunjuk yang mengikuti tanda kurung penutup untuk instance dan pilih instanceId.
Untuk
instanceId
, masukkantest-instance
.
Halaman pembuatan instance Coba! Anda sekarang akan terlihat seperti ini:Klik Jalankan. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
- Klik
projects.instances.databases.create
. Untuk parent, masukkan:
projects/[PROJECT_ID]/instances/test-instance
Klik Tambahkan parameter isi permintaan, lalu pilih
createStatement
.Untuk
createStatement
, masukkan:CREATE DATABASE `example-db`
(Nama database,
example-db
, berisi tanda hubung, jadi harus diapit dengan tanda petik terbalik (`
).Klik Jalankan. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
- Klik
projects.instances.databases.updateDdl
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Untuk Isi permintaan, gunakan yang berikut:
{ "statements": [ "CREATE TABLE Singers ( SingerId INT64 NOT NULL, FirstName STRING(1024), LastName STRING(1024), SingerInfo BYTES(MAX) ) PRIMARY KEY (SingerId)", "CREATE TABLE Albums ( SingerId INT64 NOT NULL, AlbumId INT64 NOT NULL, AlbumTitle STRING(MAX)) PRIMARY KEY (SingerId, AlbumId), INTERLEAVE IN PARENT Singers ON DELETE CASCADE" ] }
Array
statements
berisi pernyataan DDL yang menentukan skema.Klik Jalankan. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
- Klik
projects.instances.databases.sessions.create
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Klik Jalankan.
Respons menampilkan sesi yang Anda buat, dalam formulir
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Anda akan menggunakan sesi ini saat membaca atau menulis ke database Anda.
- Klik
projects.instances.databases.sessions.commit
. Untuk session, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan yang berikut:
{ "singleUseTransaction": { "readWrite": {} }, "mutations": [ { "insertOrUpdate": { "table": "Singers", "columns": [ "SingerId", "FirstName", "LastName" ], "values": [ [ "1", "Marc", "Richards" ], [ "2", "Catalina", "Smith" ], [ "3", "Alice", "Trentor" ], [ "4", "Lea", "Martin" ], [ "5", "David", "Lomond" ] ] } }, { "insertOrUpdate": { "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "values": [ [ "1", "1", "Total Junk" ], [ "1", "2", "Go, Go, Go" ], [ "2", "1", "Green" ], [ "2", "2", "Forever Hold Your Peace" ], [ "2", "3", "Terrified" ] ] } } ] }
Klik Jalankan. Respons menampilkan stempel waktu commit.
- Klik
projects.instances.databases.sessions.executeSql
. Untuk session, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan yang berikut:
{ "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums" }
Klik Jalankan. Respons akan menampilkan hasil kueri.
- Klik
projects.instances.databases.sessions.read
. Untuk session, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan yang berikut:
{ "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "keySet": { "all": true } }
Klik Jalankan. Respons akan menampilkan hasil baca.
- Klik
projects.instances.databases.updateDdl
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Untuk Isi permintaan, gunakan yang berikut:
{ "statements": [ "ALTER TABLE Albums ADD COLUMN MarketingBudget INT64" ] }
Array
statements
berisi pernyataan DDL yang menentukan skema.Klik Jalankan. Proses ini mungkin memerlukan waktu beberapa menit untuk diselesaikan, bahkan setelah panggilan REST menampilkan respons. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
- Klik
projects.instances.databases.sessions.commit
. Untuk session, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan yang berikut:
{ "singleUseTransaction": { "readWrite": {} }, "mutations": [ { "update": { "table": "Albums", "columns": [ "SingerId", "AlbumId", "MarketingBudget" ], "values": [ [ "1", "1", "100000" ], [ "2", "2", "500000" ] ] } } ] }
Klik Jalankan. Respons menampilkan stempel waktu commit.
- Klik
projects.instances.databases.sessions.executeSql
. Untuk session, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan yang berikut:
{ "sql": "SELECT SingerId, AlbumId, MarketingBudget FROM Albums" }
Klik Jalankan. Sebagai bagian dari respons, Anda akan melihat dua baris yang berisi nilai
MarketingBudget
yang diperbarui:"rows": [ [ "1", "1", "100000" ], [ "1", "2", null ], [ "2", "1", null ], [ "2", "2", "500000" ], [ "2", "3", null ] ]
- Klik
projects.instances.databases.updateDdl
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Untuk Isi permintaan, gunakan yang berikut:
{ "statements": [ "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)" ] }
Klik Jalankan. Proses ini mungkin memerlukan waktu beberapa menit untuk diselesaikan, bahkan setelah panggilan REST menampilkan respons. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
- Klik
projects.instances.databases.sessions.executeSql
. Untuk session, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan yang berikut:
{ "sql": "SELECT AlbumId, AlbumTitle, MarketingBudget FROM Albums WHERE AlbumTitle >= 'Aardvark' AND AlbumTitle < 'Goo'" }
Klik Jalankan. Sebagai bagian dari respons, Anda akan melihat baris berikut:
"rows": [ [ "2", "Go, Go, Go", null ], [ "2", "Forever Hold Your Peace", "500000" ] ]
- Klik
projects.instances.databases.sessions.read
. Untuk session, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan yang berikut:
{ "table": "Albums", "columns": [ "AlbumId", "AlbumTitle" ], "keySet": { "all": true }, "index": "AlbumsByAlbumTitle" }
Klik Jalankan. Sebagai bagian dari respons, Anda akan melihat baris berikut:
"rows": [ [ "2", "Forever Hold Your Peace" ], [ "2", "Go, Go, Go" ], [ "1", "Green" ], [ "3", "Terrified" ], [ "1", "Total Junk" ] ]
- Klik
projects.instances.databases.updateDdl
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Untuk Isi permintaan, gunakan yang berikut:
{ "statements": [ "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)" ] }
Klik Jalankan. Proses ini mungkin memerlukan waktu beberapa menit untuk diselesaikan, bahkan setelah panggilan REST menampilkan respons. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
- Klik
projects.instances.databases.sessions.read
. Untuk session, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan yang berikut:
{ "table": "Albums", "columns": [ "AlbumId", "AlbumTitle", "MarketingBudget" ], "keySet": { "all": true }, "index": "AlbumsByAlbumTitle2" }
Klik Jalankan. Sebagai bagian dari respons, Anda akan melihat baris berikut:
"rows": [ [ "2", "Forever Hold Your Peace", "500000" ], [ "2", "Go, Go, Go", null ], [ "1", "Green", null ], [ "3", "Terrified", null ], [ "1", "Total Junk", "100000" ] ]
- Klik
projects.instances.databases.sessions.beginTransaction
. Untuk session, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Untuk Isi Permintaan, gunakan yang berikut:
{ "options": { "readOnly": {} } }
Klik Jalankan.
Respons menunjukkan ID transaksi yang Anda buat.
- Klik
projects.instances.databases.sessions.executeSql
. Untuk session, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan yang berikut:
{ "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums", "transaction": { "id": "[TRANSACTION_ID]" } }
Klik Jalankan. Anda akan melihat baris yang mirip dengan berikut dalam respons:
"rows": [ [ "2", "2", "Forever Hold Your Peace" ], [ "1", "2", "Go, Go, Go" ], [ "2", "1", "Green" ], [ "2", "3", "Terrified" ], [ "1", "1", "Total Junk" ] ]
- Klik
projects.instances.databases.sessions.read
. Untuk session, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan yang berikut:
{ "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "keySet": { "all": true }, "transaction": { "id": "[TRANSACTION_ID]" } }
Klik Jalankan. Anda akan melihat baris yang mirip dengan berikut dalam respons:
"rows": [ [ "1", "1", "Total Junk" ], [ "1", "2", "Go, Go, Go" ], [ "2", "1", "Green" ], [ "2", "2", "Forever Hold Your Peace" ], [ "2", "3", "Terrified" ] ]
- Klik
projects.instances.databases.dropDatabase
. Untuk name, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Klik Jalankan.
- Klik
projects.instances.delete
. Untuk name, masukkan:
projects/[PROJECT_ID]/instances/test-instance
Klik Jalankan.
Cara membuat panggilan REST
Anda dapat melakukan panggilan REST Spanner menggunakan:
Konvensi yang digunakan di halaman ini
Instance
Saat pertama kali menggunakan Spanner, Anda harus membuat instance, yang merupakan alokasi resource yang digunakan oleh database Spanner. Saat membuat instance, Anda memilih tempat penyimpanan data dan jumlah kapasitas komputasi yang dimiliki instance.
Mencantumkan konfigurasi instance
Saat membuat instance, Anda menentukan konfigurasi instance, yang menentukan penempatan geografis dan replikasi database Anda di instance tersebut. Anda dapat memilih konfigurasi regional, yang menyimpan data di satu region, atau konfigurasi multi-region, yang mendistribusikan data di beberapa region. Pelajari lebih lanjut di Instance.
Gunakan projects.instanceConfigs.list
untuk menentukan konfigurasi yang tersedia untuk project Google Cloud Anda.
Anda menggunakan nilai name
untuk salah satu konfigurasi instance saat membuat
instance.
Membuat instance
Anda dapat mencantumkan instance menggunakan
projects.instances.list
.
Buat database
Buat database bernama example-db
.
Anda dapat mencantumkan database menggunakan
projects.instances.databases.list
.
Membuat skema
Gunakan Data Definition Language (DDL) Spanner untuk membuat, mengubah, atau menghapus tabel, serta membuat atau menghapus indeks.
Skema ini menentukan dua tabel, Singers
dan Albums
, untuk aplikasi musik dasar. Tabel ini digunakan di seluruh halaman ini. Lihat contoh skema jika Anda belum
melakukannya.
Anda dapat mengambil skema menggunakan
projects.instances.databases.getDdl
.
Membuat sesi
Sebelum dapat menambahkan, memperbarui, menghapus, atau membuat kueri data, Anda harus membuat sesi, yang merepresentasikan saluran komunikasi dengan layanan database Spanner. (Anda tidak menggunakan sesi secara langsung jika menggunakan library klien Spanner, karena library klien mengelola sesi atas nama Anda.)
Sesi dimaksudkan untuk berdurasi panjang. Layanan database Spanner dapat menghapus sesi jika sesi tidak aktif selama lebih dari satu jam. Upaya untuk
menggunakan sesi yang dihapus akan menghasilkan NOT_FOUND
. Jika Anda mengalami error ini, buat dan gunakan sesi baru. Anda dapat melihat apakah sesi masih aktif menggunakan
projects.instances.databases.sessions.get
.
Untuk informasi terkait, lihat Mempertahankan sesi tidak aktif tetap aktif.
Langkah berikutnya adalah menulis data ke database Anda.
Menulis data
Anda menulis data menggunakan
jenis Mutation
. Mutation
adalah penampung untuk operasi mutasi. Mutation
mewakili urutan penyisipan, pembaruan, penghapusan, dan tindakan lain yang dapat
diterapkan secara atomik ke baris dan tabel yang berbeda dalam database
Spanner.
Contoh ini menggunakan insertOrUpdate
. Operasi lainnya
untuk Mutations
adalah insert
, update
, replace
, dan delete
.
Untuk mengetahui informasi tentang cara mengenkode jenis data, lihat TypeCode.
Membuat kueri data menggunakan SQL
Membaca data menggunakan read API
Memperbarui skema database
Misalkan Anda perlu menambahkan kolom baru bernama MarketingBudget
ke tabel Albums
, yang memerlukan pembaruan pada skema database Anda. Spanner mendukung pembaruan skema ke database saat database terus melayani traffic. Pembaruan skema tidak memerlukan penonaktifan database dan tidak
mengunci seluruh tabel atau kolom; Anda dapat terus menulis data ke database
selama pembaruan skema.
Menambahkan kolom
Menulis data ke kolom baru
Kode berikut menulis data ke kolom baru. Tindakan ini menetapkan MarketingBudget
ke
100000
untuk baris yang dikunci oleh Albums(1, 1)
dan ke 500000
untuk baris yang dikunci
oleh Albums(2, 2)
.
Anda juga dapat menjalankan kueri SQL atau panggilan baca untuk mengambil nilai yang baru saja Anda tulis.
Berikut cara menjalankan kueri:
Menggunakan indeks sekunder
Misalnya, Anda ingin mengambil semua baris Albums
yang memiliki nilai AlbumTitle
dalam rentang tertentu. Anda dapat membaca semua nilai dari kolom AlbumTitle
menggunakan
pernyataan SQL atau panggilan baca, lalu menghapus baris yang tidak memenuhi
kriteria, tetapi pemindaian tabel lengkap ini mahal, terutama untuk tabel
dengan banyak baris. Sebagai gantinya, Anda dapat mempercepat pengambilan baris saat
mencari menurut kolom non-kunci primer dengan membuat
indeks sekunder pada tabel.
Menambahkan indeks sekunder ke tabel yang ada memerlukan pembaruan skema. Seperti update skema lainnya, Spanner mendukung penambahan indeks saat database terus melayani traffic. Spanner akan otomatis mengisi ulang indeks dengan data yang ada. Pengisian ulang mungkin memerlukan waktu beberapa menit untuk selesai, tetapi Anda tidak perlu menghentikan database atau menghindari penulisan ke tabel atau kolom tertentu selama proses ini. Untuk mengetahui detail selengkapnya, lihat pengisian ulang indeks.
Setelah Anda menambahkan indeks sekunder, Spanner akan otomatis menggunakannya untuk kueri SQL yang kemungkinan akan berjalan lebih cepat dengan indeks tersebut. Jika menggunakan antarmuka baca, Anda harus menentukan indeks yang ingin digunakan.
Menambahkan indeks sekunder
Anda dapat menambahkan indeks menggunakan updateDdl
.
Membuat kueri menggunakan indeks
Membaca menggunakan indeks
Menambahkan indeks dengan klausa STORING
Anda mungkin memperhatikan bahwa contoh baca di atas tidak menyertakan pembacaan kolom
MarketingBudget
. Hal ini karena antarmuka baca Spanner tidak mendukung kemampuan untuk menggabungkan indeks dengan tabel data guna mencari nilai yang tidak disimpan dalam indeks.
Buat definisi alternatif AlbumsByAlbumTitle
yang menyimpan salinan
MarketingBudget
dalam indeks.
Anda dapat menambahkan indeks STORING menggunakan updateDdl
.
Sekarang Anda dapat menjalankan operasi baca yang mengambil semua kolom AlbumId
, AlbumTitle
, dan MarketingBudget
dari indeks AlbumsByAlbumTitle2
:
Mengambil data menggunakan transaksi hanya baca
Misalkan Anda ingin menjalankan lebih dari satu pembacaan pada stempel waktu yang sama. Transaksi hanya baca mengamati awalan yang konsisten dari histori commit transaksi, sehingga aplikasi Anda selalu mendapatkan data yang konsisten.
Membuat transaksi hanya baca
Sekarang Anda dapat menggunakan transaksi hanya baca untuk mengambil data pada stempel waktu yang konsisten, meskipun data telah berubah sejak Anda membuat transaksi hanya baca.
Menjalankan kueri menggunakan transaksi hanya baca
Membaca menggunakan transaksi hanya baca
Spanner juga mendukung transaksi baca-tulis, yang menjalankan serangkaian pembacaan dan penulisan secara atomik pada satu titik waktu logis. Untuk informasi selengkapnya, lihat Transaksi baca-tulis. (Fungsi Coba! tidak cocok untuk mendemonstrasikan transaksi baca-tulis.)
Pembersihan
Agar tidak menimbulkan biaya tambahan pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus database dan hapus instance yang Anda buat.
Menghapus database
Menghapus instance
Langkah berikutnya
- Mengakses Spanner di Instance Virtual Machine: buat instance virtual machine dengan akses ke database Spanner Anda.
- Pelajari lebih lanjut konsep Spanner.