Memulai Spanner menggunakan REST

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 Google Cloud project ID. Ganti project IDGoogle Cloud 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 menggunakan test-instance.

• Contoh membuat dan menggunakan ID database example-db. Ganti ID database Anda jika Anda tidak menggunakan example-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 mana yang tersedia untuk project Google Cloud Anda.

1. Klik projects.instanceConfigs.list.

2. Untuk parent, masukkan:

   projects/[PROJECT_ID]
   

3. 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

1. Klik projects.instances.create.

2. Untuk parent, masukkan:

   projects/[PROJECT_ID]
   

3. Klik Tambahkan parameter isi permintaan, lalu pilih instance.

4. Klik balon petunjuk untuk instance guna melihat kemungkinan kolom. Tambahkan nilai untuk kolom berikut:

   1. nodeCount: Masukkan 1.
   2. config: Masukkan nilai name dari salah satu konfigurasi instance regional yang ditampilkan saat Anda mencantumkan konfigurasi instance.
   3. displayName: Masukkan Test Instance.

5. Klik balon petunjuk yang mengikuti tanda kurung tutup untuk instance dan pilih instanceId.

6. Untuk instanceId, masukkan test-instance.
   Halaman pembuatan instance Coba Anda sekarang akan terlihat seperti ini:

   

7. 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.

1. Klik projects.instances.databases.create.

2. Untuk parent, masukkan:

   projects/[PROJECT_ID]/instances/test-instance
   

3. Klik Tambahkan parameter isi permintaan, lalu pilih createStatement.

4. Untuk createStatement, masukkan:

   CREATE DATABASE `example-db`
   

   (Nama database, example-db, berisi tanda hubung, sehingga harus diapit dalam tanda petik terbalik (`).
   

5. 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.

1. Klik projects.instances.databases.updateDdl.

2. Untuk database, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db
   

3. 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.

4. Klik Jalankan. Respons menampilkan operasi yang berjalan lama yang dapat Anda buat kuerinya 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.)

1. Klik projects.instances.databases.sessions.create.

2. Untuk database, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db
   

3. Klik Jalankan.

4. 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.

1. Klik projects.instances.databases.sessions.commit.

2. Untuk session, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
   

   (Anda menerima nilai ini saat membuat sesi.)

3. 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"
             ]
           ]
         }
       }
     ]
   }
   

4. 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

1. Klik projects.instances.databases.sessions.executeSql.

2. Untuk session, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
   

   (Anda menerima nilai ini saat membuat sesi.)

3. Untuk Isi permintaan, gunakan kode berikut:

   {
     "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums"
   }
   

4. Klik Jalankan. Responsnya akan menampilkan hasil kueri.

Membaca data menggunakan read API

1. Klik projects.instances.databases.sessions.read.

2. Untuk session, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
   

   (Anda menerima nilai ini saat membuat sesi.)

3. Untuk Isi permintaan, gunakan kode berikut:

   {
     "table": "Albums",
     "columns": [
       "SingerId",
       "AlbumId",
       "AlbumTitle"
     ],
     "keySet": {
       "all": true
     }
   }
   

4. Klik Jalankan. Responsnya 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

1. Klik projects.instances.databases.updateDdl.

2. Untuk database, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db
   

3. Untuk Isi permintaan, gunakan kode berikut:

   {
     "statements": [
       "ALTER TABLE Albums ADD COLUMN MarketingBudget INT64"
     ]
   }
   

   Array statements berisi pernyataan DDL yang menentukan skema.

4. 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. 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).

1. Klik projects.instances.databases.sessions.commit.

2. Untuk session, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
   

   (Anda menerima nilai ini saat membuat sesi.)

3. Untuk Isi permintaan, gunakan kode berikut:

   {
     "singleUseTransaction": {
       "readWrite": {}
     },
     "mutations": [
       {
         "update": {
           "table": "Albums",
           "columns": [
             "SingerId",
             "AlbumId",
             "MarketingBudget"
           ],
           "values": [
             [
               "1",
               "1",
               "100000"
             ],
             [
               "2",
               "2",
               "500000"
             ]
           ]
         }
       }
     ]
   }
   

4. 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:

1. Klik projects.instances.databases.sessions.executeSql.

2. Untuk session, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
   

   (Anda menerima nilai ini saat membuat sesi.)

3. Untuk Isi permintaan, gunakan kode berikut:

   {
     "sql": "SELECT SingerId, AlbumId, MarketingBudget FROM Albums"
   }
   

4. 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 diselesaikan, 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.

1. Klik projects.instances.databases.updateDdl.

2. Untuk database, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db
   

3. Untuk Isi permintaan, gunakan kode berikut:

   {
     "statements": [
       "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)"
     ]
   }
   

4. Klik Jalankan. Mungkin perlu waktu beberapa menit untuk menyelesaikannya, bahkan setelah panggilan REST menampilkan respons. Respons menampilkan operasi yang berjalan lama yang dapat Anda buat kuerinya untuk memeriksa statusnya.

Membuat kueri menggunakan indeks

1. Klik projects.instances.databases.sessions.executeSql.

2. Untuk session, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
   

   (Anda menerima nilai ini saat membuat sesi.)

3. Untuk Isi permintaan, gunakan kode berikut:

   {
     "sql": "SELECT AlbumId, AlbumTitle, MarketingBudget FROM Albums WHERE AlbumTitle >= 'Aardvark' AND AlbumTitle < 'Goo'"
   }
   

4. 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

1. Klik projects.instances.databases.sessions.read.

2. Untuk session, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
   

   (Anda menerima nilai ini saat membuat sesi.)

3. Untuk Isi permintaan, gunakan kode berikut:

   {
     "table": "Albums",
     "columns": [
       "AlbumId",
       "AlbumTitle"
     ],
     "keySet": {
       "all": true
     },
     "index": "AlbumsByAlbumTitle"
   }
   

4. 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.

1. Klik projects.instances.databases.updateDdl.

2. Untuk database, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db
   

3. Untuk Isi permintaan, gunakan kode berikut:

   {
     "statements": [
       "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)"
     ]
   }
   

4. 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:

1. Klik projects.instances.databases.sessions.read.

2. Untuk session, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
   

   (Anda menerima nilai ini saat membuat sesi.)

3. Untuk Isi permintaan, gunakan kode berikut:

   {
     "table": "Albums",
     "columns": [
       "AlbumId",
       "AlbumTitle",
       "MarketingBudget"
     ],
     "keySet": {
       "all": true
     },
     "index": "AlbumsByAlbumTitle2"
   }
   

4. 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 histori commit transaksi yang konsisten, sehingga aplikasi Anda selalu mendapatkan data yang konsisten.

Membuat transaksi hanya baca

1. Klik projects.instances.databases.sessions.beginTransaction.

2. Untuk session, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
   

3. Untuk Isi Permintaan, gunakan kode berikut:

   {
     "options": {
       "readOnly": {}
     }
   }
   

4. Klik Jalankan.

5. 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

1. Klik projects.instances.databases.sessions.executeSql.

2. Untuk session, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
   

   (Anda menerima nilai ini saat membuat sesi.)

3. Untuk Isi permintaan, gunakan kode berikut:

   {
     "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums",
     "transaction": {
       "id": "[TRANSACTION_ID]"
     }
   }
   

4. 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

1. Klik projects.instances.databases.sessions.read.

2. Untuk session, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
   

   (Anda menerima nilai ini saat membuat sesi.)

3. Untuk Isi permintaan, gunakan kode berikut:

   {
     "table": "Albums",
     "columns": [
       "SingerId",
       "AlbumId",
       "AlbumTitle"
     ],
     "keySet": {
       "all": true
     },
     "transaction": {
       "id": "[TRANSACTION_ID]"
     }
   }
   

4. Klik Jalankan. Anda akan melihat baris yang mirip dengan berikut ini 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 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

1. Klik projects.instances.databases.dropDatabase.

2. Untuk name, masukkan:

   projects/[PROJECT_ID]/instances/test-instance/databases/example-db
   

3. Klik Jalankan.

Menghapus instance

1. Klik projects.instances.delete.

2. Untuk name, masukkan:

   projects/[PROJECT_ID]/instances/test-instance
   

3. Klik Jalankan.