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
- 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.
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.
- 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.
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 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.
- 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" } ] }- 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.
- 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`- Klik Jalankan. Respons menampilkan operasi yang berjalan lama. Kueri operasi ini untuk memeriksa statusnya.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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 ] ]- 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.
- 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" ] ]- 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" ] ]- 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.
- 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" ] ]- 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.
- 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" ] ]- 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" ] ]- Klik
projects.instances.databases.dropDatabase. Untuk name, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instance/databases/example-dbKlik Jalankan.
- Klik
projects.instances.delete. Untuk name, masukkan:
projects/<var>PROJECT_ID</var>/instances/test-instanceKlik Jalankan.
Cara membuat panggilan REST
Anda dapat melakukan panggilan REST Spanner menggunakan:
Konvensi yang digunakan di halaman ini
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.
Anda menggunakan nilai name untuk salah satu konfigurasi instance saat membuat
instance.
Membuat instance
Mencantumkan instance menggunakan
projects.instances.list.
Buat database
Buat database bernama example-db.
Nama database, example-db, berisi tanda hubung, jadi sertakan dalam
tanda petik terbalik (`).
Mencantumkan database Anda 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. 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.)
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.
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
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
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).
Jalankan kueri SQL atau panggilan baca untuk mengambil nilai yang baru saja Anda tulis.
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 akan 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 tersebut. Jika Anda menggunakan antarmuka baca, tentukan indeks yang ingin Anda gunakan.
Menambahkan indeks sekunder
Tambahkan indeks menggunakan updateDdl.
Membuat kueri menggunakan indeks
Membaca menggunakan indeks
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.
Sekarang, jalankan pembacaan yang mengambil semua kolom AlbumId, AlbumTitle, dan MarketingBudget dari indeks AlbumsByAlbumTitle2:
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
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
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 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
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.