Tujuan
Tutorial ini memandu Anda melakukan 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
- Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify 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.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Cara melakukan panggilan REST
Anda dapat melakukan panggilan REST Spanner menggunakan:
- Fitur Coba! yang ada di dokumentasi referensi Spanner API.
- Google APIs Explorer, yang berisi Cloud Spanner API dan Google API lainnya.
- Alat atau framework lain yang mendukung panggilan HTTP REST.
Konvensi yang digunakan di halaman ini
Contoh menggunakan
<var>PROJECT_ID</var>sebagai ID project Google Cloud . Ganti Google Cloud project ID Anda dengan<var>PROJECT_ID</var>.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
<var>SESSION</var>sebagai bagian dari nama sesi. Ganti nilai yang Anda terima saat membuat sesi untuk<var>SESSION</var>.Contoh ini menggunakan ID transaksi
<var>TRANSACTION_ID</var>. Ganti nilai yang Anda terima saat membuat transaksi untuk<var>TRANSACTION_ID</var>.Fungsi Coba! mendukung penambahan setiap kolom permintaan HTTP secara interaktif. Sebagian besar contoh dalam dokumen ini memberikan seluruh permintaan, bukan menjelaskan cara menambahkan setiap kolom ke permintaan secara interaktif.
Instance
Saat pertama kali menggunakan Spanner, buat instance. Instance mengalokasikan resource yang digunakan oleh database Spanner. Saat membuat instance, Anda memilih lokasi 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. Pilih konfigurasi regional untuk menyimpan data di satu region, atau konfigurasi multi-region untuk 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. Respons menunjukkan konfigurasi instance yang tersedia. Berikut adalah contoh respons (project Anda mungkin memiliki konfigurasi instance yang berbeda):
{ "instanceConfigs": [ { "name": "projects/<var>PROJECT_ID</var>/instanceConfigs/regional-asia-south1", "displayName": "asia-south1" }, { "name": "projects/<var>PROJECT_ID</var>/instanceConfigs/regional-asia-east1", "displayName": "asia-east1" }, { "name": "projects/<var>PROJECT_ID</var>/instanceConfigs/regional-asia-northeast1", "displayName": "asia-northeast1" }, { "name": "projects/<var>PROJECT_ID</var>/instanceConfigs/regional-europe-west1", "displayName": "europe-west1" }, { "name": "projects/<var>PROJECT_ID</var>/instanceConfigs/regional-us-east4", "displayName": "us-east4" }, { "name": "projects/<var>PROJECT_ID</var>/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/<var>PROJECT_ID</var>Klik Add request body parameters, lalu pilih
instance.Klik balon petunjuk untuk instance guna melihat kemungkinan kolom. Tambahkan nilai untuk kolom berikut:
nodeCount: Masukkan1.config: Masukkan nilainamedari 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. Kueri operasi ini untuk memeriksa statusnya.
Mencantumkan instance menggunakan
projects.instances.list.
Buat database
Buat database bernama example-db.
- Klik
projects.instances.databases.create. Untuk parent, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instanceKlik Add request body parameters, lalu pilih
createStatement.Untuk
createStatement, masukkan:CREATE DATABASE `example-db`
Nama database, example-db, berisi tanda hubung, jadi sertakan dalam
tanda petik terbalik (`).
- Klik Jalankan. Respons menampilkan operasi yang berjalan lama. Kueri operasi ini untuk memeriksa statusnya.
Mencantumkan database Anda menggunakan
projects.instances.databases.list.
Membuat skema
Gunakan Data Definition Language (DDL) Spanner untuk membuat, mengubah, atau menghapus tabel, dan untuk membuat atau menghapus indeks.
- Klik
projects.instances.databases.updateDdl. Untuk database, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instance/databases/example-dbUntuk 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
statementsberisi pernyataan DDL yang menentukan skema.Klik Jalankan. Respons menampilkan operasi yang berjalan lama. Buat kueri operasi ini untuk memeriksa statusnya.
Skema ini menentukan dua tabel, Singers dan Albums, untuk aplikasi musik dasar. Dokumen ini menggunakan tabel tersebut. Tinjau contoh skema.
Ambil skema Anda menggunakan
projects.instances.databases.getDdl.
Membuat sesi
Sebelum Anda menambahkan, memperbarui, menghapus, atau membuat kueri data, buat sesi. Sesi 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/<var>PROJECT_ID</var>/instances/test-instance/databases/example-dbKlik Jalankan.
Respons menampilkan sesi yang Anda buat, dalam formulir
projects/<var>PROJECT_ID</var>/instances/test-instance/databases/example-db/sessions/<var>SESSION</var>Gunakan sesi ini saat Anda membaca atau menulis ke database.
Sesi dimaksudkan untuk berdurasi panjang. Layanan database Spanner
menghapus sesi saat 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. Lihat apakah sesi masih aktif menggunakan
projects.instances.databases.sessions.get.
Untuk informasi terkait, lihat Mempertahankan sesi tidak aktif tetap aktif.
Sesi adalah konsep lanjutan. Untuk mengetahui detail dan praktik terbaik selengkapnya, lihat Sesi.
Selanjutnya, tulis 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
diterapkan secara atomik ke baris dan tabel yang berbeda dalam database
Spanner.
- Klik
projects.instances.databases.sessions.commit. Untuk session, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instance/databases/example-db/sessions/<var>SESSION</var>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.
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/<var>PROJECT_ID</var>/instances/test-instance/databases/example-db/sessions/<var>SESSION</var>Untuk Isi permintaan, gunakan yang berikut:
{ "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums" }Klik Jalankan. Respons akan menampilkan hasil kueri.
Membaca data menggunakan read API
- Klik
projects.instances.databases.sessions.read. Untuk session, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instance/databases/example-db/sessions/<var>SESSION</var>Untuk Isi permintaan, gunakan yang berikut:
{ "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "keySet": { "all": true } }Klik Jalankan. Respons akan menampilkan hasil baca.
Memperbarui skema database
Tambahkan kolom baru bernama MarketingBudget ke tabel Albums. Tindakan ini memerlukan pembaruan pada skema database Anda. Spanner mendukung pembaruan skema ke database saat database terus melayani traffic. Pembaruan skema tidak memerlukan penghentian database 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/<var>PROJECT_ID</var>/instances/test-instance/databases/example-dbUntuk Isi permintaan, gunakan yang berikut:
{ "statements": [ "ALTER TABLE Albums ADD COLUMN MarketingBudget INT64" ] } ``` The `statements` array contains the DDL statements that define the schema.Klik Jalankan. Proses ini mungkin memerlukan waktu beberapa menit untuk diselesaikan, bahkan setelah panggilan REST menampilkan respons. Respons menampilkan operasi yang berjalan lama. Kueri operasi ini untuk memeriksa statusnya.
Menulis data ke kolom baru
Kode ini 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).
- Klik
projects.instances.databases.sessions.commit. Untuk session, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instance/databases/example-db/sessions/<var>SESSION</var>(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.
Jalankan kueri SQL atau panggilan baca untuk mengambil nilai yang baru saja Anda tulis.
- Klik
projects.instances.databases.sessions.executeSql. Untuk session, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instance/databases/example-db/sessions/<var>SESSION</var>Untuk Isi permintaan, gunakan yang berikut:
{ "sql": "SELECT SingerId, AlbumId, MarketingBudget FROM Albums" }Klik Jalankan. Respons menampilkan dua baris yang berisi nilai
MarketingBudgetyang diperbarui:"rows": [ [ "1", "1", "100000" ], [ "1", "2", null ], [ "2", "1", null ], [ "2", "2", "500000" ], [ "2", "3", null ] ]
Menggunakan indeks sekunder
Untuk mengambil semua baris Albums yang memiliki nilai AlbumTitle
dalam rentang tertentu, baca semua nilai dari kolom AlbumTitle menggunakan
pernyataan SQL atau panggilan baca, lalu buang baris yang tidak memenuhi
kriteria. Namun, pemindaian tabel penuh ini mahal, terutama untuk tabel dengan banyak baris. Untuk mempercepat pengambilan baris saat melakukan penelusuran berdasarkan kolom kunci non-primer, buat
indeks sekunder pada tabel.
Menambahkan indeks sekunder ke tabel yang ada memerlukan pembaruan skema. Mirip dengan pembaruan skema lainnya, Spanner mendukung penambahan indeks saat database terus melayani traffic. Spanner otomatis mengisi ulang indeks dengan data yang ada. Pengisian ulang mungkin memerlukan waktu beberapa menit untuk diselesaikan, tetapi Anda tidak perlu menghentikan database atau menghindari penulisan ke tabel atau kolom tertentu selama proses ini. Untuk mengetahui informasi selengkapnya, lihat pengisian ulang indeks.
Setelah Anda menambahkan indeks sekunder, Spanner akan otomatis menggunakannya untuk kueri SQL yang berjalan lebih cepat dengan indeks. Jika Anda menggunakan antarmuka baca, tentukan indeks yang ingin Anda gunakan.
Menambahkan indeks sekunder
Tambahkan indeks menggunakan updateDdl.
- Klik
projects.instances.databases.updateDdl. Untuk database, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instance/databases/example-dbUntuk 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. Kueri operasi ini untuk memeriksa statusnya.
Membuat kueri menggunakan indeks
- Klik
projects.instances.databases.sessions.executeSql. Untuk session, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instance/databases/example-db/sessions/<var>SESSION</var>Untuk Isi permintaan, gunakan yang berikut:
{ "sql": "SELECT AlbumId, AlbumTitle, MarketingBudget FROM Albums WHERE AlbumTitle >= 'Aardvark' AND AlbumTitle < 'Goo'" }Klik Jalankan. Respons menampilkan 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/<var>PROJECT_ID</var>/instances/test-instance/databases/example-db/sessions/<var>SESSION</var>Untuk Isi permintaan, gunakan yang berikut:
{ "table": "Albums", "columns": [ "AlbumId", "AlbumTitle" ], "keySet": { "all": true }, "index": "AlbumsByAlbumTitle" }Klik Jalankan. Respons menampilkan baris berikut:
"rows": [ [ "2", "Forever Hold Your Peace" ], [ "2", "Go, Go, Go" ], [ "1", "Green" ], [ "3", "Terrified" ], [ "1", "Total Junk" ] ]
Menambahkan indeks dengan klausa STORING
Contoh pembacaan sebelumnya tidak menyertakan kolom MarketingBudget. Hal ini terjadi karena antarmuka baca Spanner tidak mendukung penggabungan indeks dengan tabel data untuk mencari nilai yang tidak disimpan dalam indeks.
Buat definisi alternatif AlbumsByAlbumTitle yang menyimpan salinan
MarketingBudget di indeks.
Tambahkan indeks STORING menggunakan updateDdl.
- Klik
projects.instances.databases.updateDdl. Untuk database, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instance/databases/example-dbUntuk 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. Kueri operasi ini untuk memeriksa statusnya.
Sekarang, jalankan pembacaan yang mengambil semua kolom AlbumId, AlbumTitle, dan MarketingBudget dari indeks AlbumsByAlbumTitle2:
- Klik
projects.instances.databases.sessions.read. Untuk session, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instance/databases/example-db/sessions/<var>SESSION</var>Untuk Isi permintaan, gunakan yang berikut:
{ "table": "Albums", "columns": [ "AlbumId", "AlbumTitle", "MarketingBudget" ], "keySet": { "all": true }, "index": "AlbumsByAlbumTitle2" }Klik Jalankan. Respons menampilkan 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
Untuk menjalankan lebih dari satu pembacaan pada stempel waktu yang sama, gunakan Transaksi hanya baca. Transaksi ini mengamati awalan yang 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/<var>PROJECT_ID</var>/instances/test-instance/databases/example-db/sessions/<var>SESSION</var>Untuk Isi Permintaan, gunakan yang berikut:
{ "options": { "readOnly": {} } }Klik Jalankan.
Respons menunjukkan ID transaksi yang Anda buat.
Gunakan transaksi hanya baca untuk mengambil data pada stempel waktu yang konsisten, meskipun data berubah setelah Anda membuat transaksi hanya baca.
Menjalankan kueri menggunakan transaksi hanya baca
- Klik
projects.instances.databases.sessions.executeSql. Untuk session, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instance/databases/example-db/sessions/<var>SESSION</var>Untuk Isi permintaan, gunakan yang berikut:
{ "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums", "transaction": { "id": "<var>TRANSACTION_ID</var>" } }Klik Jalankan. Respons menampilkan baris yang mirip dengan berikut ini:
"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/<var>PROJECT_ID</var>/instances/test-instance/databases/example-db/sessions/<var>SESSION</var>Untuk Isi permintaan, gunakan yang berikut:
{ "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "keySet": { "all": true }, "transaction": { "id": "<var>TRANSACTION_ID</var>" } }Klik Jalankan. Respons menampilkan baris yang mirip dengan berikut ini:
"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 menjalankan serangkaian pembacaan dan penulisan secara atomik pada satu titik waktu logis. Untuk mengetahui 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
- Klik
projects.instances.databases.dropDatabase. Untuk name, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instance/databases/example-dbKlik Jalankan.
Menghapus instance
- Klik
projects.instances.delete. Untuk name, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instanceKlik Jalankan.
Langkah berikutnya
- Mengakses Spanner di Instance Mesin Virtual: buat instance mesin virtual dengan akses ke database Spanner Anda.
- Pelajari lebih lanjut konsep Spanner.