Tujuan
Tutorial ini memandu Anda melalui langkah-langkah berikut menggunakan Cloud Spanner API dengan REST:
- Membuat instance dan database Spanner.
- Menulis, membaca, dan mengeksekusi kueri SQL pada data di database.
- Perbarui skema database.
- Tambahkan indeks sekunder ke database.
- Gunakan indeks untuk membaca dan menjalankan kueri SQL pada data.
- Ambil 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 komponen Google Cloud yang 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.
Cara melakukan panggilan REST
Anda dapat melakukan panggilan REST Spanner menggunakan:
- Fitur Coba yang ditemukan 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 REST HTTP.
Konvensi yang digunakan di halaman ini
Contoh menggunakan
[PROJECT_ID]
sebagai project ID Google Cloud. Ganti[PROJECT_ID]
dengan project ID Google Cloud Anda. 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 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 ini 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 secara interaktif ke permintaan.
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 data disimpan dan jumlah kapasitas komputasi yang dimiliki instance.
Membuat daftar konfigurasi instance
Saat membuat instance, Anda menentukan konfigurasi instance, yang menentukan penempatan geografis dan replikasi database Anda dalam 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.
- 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" } ] }
Anda menggunakan nilai name
untuk salah satu konfigurasi instance saat membuat
instance.
Membuat instance
- 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 tutup 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.
Anda dapat mencantumkan instance menggunakan projects.instances.list
.
Buat database
Buat database bernama example-db
.
- 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, sehingga harus diapit dalam tanda petik terbalik (`
).Klik Jalankan. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
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.
- Klik
projects.instances.databases.updateDdl
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Untuk Isi permintaan, gunakan kode 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.
Skema 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 mewakili 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.)
- Klik
projects.instances.databases.sessions.create
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Klik Jalankan.
Respons menunjukkan sesi yang Anda buat, dalam bentuk
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Anda akan menggunakan sesi ini saat membaca atau menulis ke database.
Sesi dimaksudkan untuk digunakan dalam jangka waktu lama. Layanan database Spanner dapat menghapus sesi saat sesi tidak ada aktivitas selama lebih dari satu jam. Mencoba
menggunakan hasil sesi yang dihapus di 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 yang tidak ada aktivitas.
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 lainnya yang dapat
diterapkan secara atomik ke berbagai baris dan tabel dalam database
Spanner.
- 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 kode 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 menunjukkan stempel waktu commit.
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
- 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 kode berikut:
{ "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums" }
Klik Jalankan. Responsnya akan menampilkan hasil kueri.
Membaca data menggunakan read API
- 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 kode berikut:
{ "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "keySet": { "all": true } }
Klik Jalankan. Respons akan menampilkan hasil pembacaan.
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 menyalurkan
traffic. Pembaruan skema tidak memerlukan database offline dan tidak
mengunci seluruh tabel atau kolom; Anda dapat terus menulis data ke database
selama pembaruan skema.
Menambahkan kolom
- Klik
projects.instances.databases.updateDdl
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Untuk Isi permintaan, gunakan kode berikut:
{ "statements": [ "ALTER TABLE Albums ADD COLUMN MarketingBudget INT64" ] }
Array
statements
berisi pernyataan DDL yang menentukan skema.Klik Jalankan. Mungkin perlu waktu beberapa menit untuk menyelesaikannya, bahkan setelah panggilan REST menampilkan respons. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
Menulis data ke kolom baru
Kode berikut menulis data ke kolom baru. Fungsi ini menetapkan MarketingBudget
ke
100000
untuk baris yang diberi kunci oleh Albums(1, 1)
dan ke 500000
untuk baris yang diberi kunci
oleh Albums(2, 2)
.
- 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 kode berikut:
{ "singleUseTransaction": { "readWrite": {} }, "mutations": [ { "update": { "table": "Albums", "columns": [ "SingerId", "AlbumId", "MarketingBudget" ], "values": [ [ "1", "1", "100000" ], [ "2", "2", "500000" ] ] } } ] }
Klik Jalankan. Respons menunjukkan stempel waktu commit.
Anda juga dapat menjalankan kueri SQL atau panggilan baca untuk mengambil nilai yang baru saja Anda tulis.
Berikut cara menjalankan kueri:
- 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 kode 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 ] ]
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 melakukan pemindaian tabel lengkap ini mahal, terutama untuk tabel
dengan banyak baris. Sebagai gantinya, Anda dapat mempercepat pengambilan baris saat
menelusuri menurut kolom kunci non-utama 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 menyalurkan traffic. Spanner otomatis mengisi ulang indeks dengan data yang ada. Pengisian ulang mungkin memerlukan waktu beberapa menit untuk selesai, tetapi Anda tidak perlu membuat database offline 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 cenderung berjalan lebih cepat dengan indeks. Jika menggunakan antarmuka baca, Anda harus menentukan indeks yang ingin digunakan.
Menambahkan indeks sekunder
Anda dapat menambahkan indeks menggunakan updateDdl
.
- Klik
projects.instances.databases.updateDdl
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Untuk Isi permintaan, gunakan kode berikut:
{ "statements": [ "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)" ] }
Klik Jalankan. Mungkin perlu waktu beberapa menit untuk menyelesaikannya, bahkan setelah panggilan REST menampilkan respons. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
Membuat kueri menggunakan indeks
- 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 kode 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" ] ]
Membaca menggunakan indeks
- 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 kode 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" ] ]
Menambahkan indeks dengan klausa STORING
Anda mungkin telah 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 untuk mencari nilai
yang tidak disimpan dalam indeks.
Buat definisi alternatif AlbumsByAlbumTitle
yang menyimpan salinan
MarketingBudget
dalam indeks.
Anda dapat menambahkan indeks STORING menggunakan updateDdl
.
- Klik
projects.instances.databases.updateDdl
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Untuk Isi permintaan, gunakan kode berikut:
{ "statements": [ "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)" ] }
Klik Jalankan. Mungkin perlu waktu beberapa menit untuk menyelesaikannya, bahkan setelah panggilan REST menampilkan respons. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
Sekarang Anda dapat menjalankan operasi baca yang mengambil semua kolom AlbumId
, AlbumTitle
, dan
MarketingBudget
dari indeks AlbumsByAlbumTitle2
:
- 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 kode 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" ] ]
Mengambil data menggunakan transaksi hanya baca
Misalkan Anda ingin menjalankan lebih dari satu operasi baca pada stempel waktu yang sama. Transaksi hanya baca mengamati awalan konsisten dari histori commit transaksi, sehingga aplikasi Anda selalu mendapatkan data yang konsisten.
Membuat transaksi hanya baca
- Klik
projects.instances.databases.sessions.beginTransaction
. Untuk session, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Untuk Isi Permintaan, gunakan kode berikut:
{ "options": { "readOnly": {} } }
Klik Jalankan.
Respons menunjukkan ID transaksi yang Anda buat.
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
- 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 kode 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" ] ]
Membaca menggunakan transaksi hanya baca
- 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 kode 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" ] ]
Spanner juga mendukung transaksi baca-tulis, yang mengeksekusi kumpulan pembacaan dan penulisan secara atomik pada satu titik waktu logis. Untuk informasi selengkapnya, lihat Transaksi baca-tulis. (Fungsi Coba! tidak cocok untuk menunjukkan 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
- Klik
projects.instances.databases.dropDatabase
. Untuk name, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Klik Jalankan.
Menghapus instance
- Klik
projects.instances.delete
. Untuk name, masukkan:
projects/[PROJECT_ID]/instances/test-instance
Klik Jalankan.
Langkah selanjutnya
- Mengakses Spanner di Instance Virtual Machine: membuat instance virtual machine dengan akses ke database Spanner Anda.
- Pelajari konsep Spanner lebih lanjut.