Membuat fungsi Cloud Run yang menampilkan hasil Spanner

Cloud Run Functions memungkinkan Anda membuat layanan tanpa server yang mengkueri dan menayangkan data Spanner melalui HTTP. Dalam tutorial ini, Anda akan menulis dan men-deploy fungsi yang dipicu HTTP yang mengambil rekaman dari database Spanner.

Tujuan

Menulis, men-deploy, dan memicu fungsi HTTP yang mengakses Spanner.

Biaya

Dokumen ini menggunakan Spanner dan Cloud Run, yang merupakan komponen yang dapat ditagih Google Cloud.

• Untuk mengetahui informasi tentang biaya penggunaan Spanner, lihat Harga Spanner.

• Untuk mengetahui informasi tentang biaya penggunaan Cloud Run, termasuk pemanggilan gratis, lihat Harga Cloud Run.

Sebelum memulai

1. Dokumen ini mengasumsikan bahwa Anda memiliki instance Spanner bernama test-instance dan database bernama example-db yang menggunakan skema aplikasi musik. Untuk petunjuk tentang cara membuat instance dan database dengan skema aplikasi musik, lihat Panduan memulai menggunakan konsol atau tutorial Memulai di Node.js, atau Python.

   Catatan: Setelah langkah ini, Anda akan memiliki dua tabel, Singers dan Albums, di database Anda dengan data sampel yang ditentukan dalam skema aplikasi musik.

2. Aktifkan Cloud Run dan Cloud Build API.

   Aktifkan API

3. Instal dan lakukan inisialisasi gcloud CLI.

   Jika Anda sudah menginstal gcloud CLI, update dengan menjalankan perintah berikut:

   gcloud components update
   

4. Siapkan lingkungan pengembangan:

   Node.js

   Lihat panduan penyiapan Node.js.

   Python

   Lihat panduan penyiapan Python.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk men-deploy layanan Cloud Run dari sumber, minta administrator Anda untuk memberi Anda peran IAM berikut:

• Cloud Run Source Developer (roles/run.sourceDeveloper) di project Anda
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) di layanan Cloud Run
• Pengguna Akun Layanan (roles/iam.serviceAccountUser) di identitas layanan
• Spanner Admin (roles/spanner.admin) di instance Spanner

Untuk mengetahui daftar peran dan izin IAM yang terkait dengan Cloud Run, lihat Peran IAM Cloud Run dan Izin IAM Cloud Run. Jika layanan Cloud Run Anda berinteraksi dengan Google Cloud API, seperti Cloud Client Libraries, lihat panduan konfigurasi identitas layanan. Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat izin deployment dan mengelola akses.

Peran untuk akun layanan Cloud Build

Anda atau administrator Anda harus memberikan peran IAM berikut ke akun layanan Cloud Build.

Klik untuk melihat peran yang diperlukan untuk akun layanan Cloud Build

Cloud Build secara otomatis menggunakan akun layanan default Compute Engine sebagai akun layanan Cloud Build default untuk mem-build kode sumber dan resource Cloud Run Anda, kecuali jika Anda mengganti perilaku ini. Agar Cloud Build dapat mem-build sumber Anda, minta administrator Anda untuk memberikan Cloud Run Builder (roles/run.builder) ke akun layanan default Compute Engine di project Anda:

  gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:PROJECT_NUMBER-compute@ \
      --role=roles/run.builder
  

Ganti PROJECT_NUMBER dengan nomor project Anda Google Cloud, dan PROJECT_ID dengan ID project Anda Google Cloud. Untuk mengetahui petunjuk mendetail tentang cara menemukan ID project dan nomor project Anda, lihat Membuat dan mengelola project.

Pemberian peran builder Cloud Run ke akun layanan default Compute Engine memerlukan waktu beberapa menit untuk diterapkan.

Catatan:

Batasan kebijakan organisasi iam.automaticIamGrantsForDefaultServiceAccounts mencegah peran Editor diberikan secara otomatis ke akun layanan default. Jika Anda membuat organisasi setelah 3 Mei 2024, batasan ini diterapkan secara default.

Sebaiknya Anda menerapkan batasan ini untuk menonaktifkan pemberian peran otomatis. Jika Anda menonaktifkan pemberian peran otomatis, Anda harus menentukan peran mana yang akan diberikan ke akun layanan default, lalu memberikan peran tersebut sendiri.

Jika akun layanan default sudah memiliki peran Editor, sebaiknya ganti peran Editor dengan peran yang kurang permisif.

Peran untuk identitas layanan

Anda harus memberikan peran IAM berikut ke identitas layanan yang Anda gunakan untuk layanan Cloud Run.

• Spanner Database Reader (roles/spanner.databaseReader)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Menyiapkan aplikasi

1. Buat clone repositori aplikasi contoh ke komputer lokal Anda:

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   Atau, Anda dapat mendownload contoh sebagai file ZIP dan mengekstraknya.

   Python

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

   Atau, Anda dapat mendownload contoh sebagai file ZIP dan mengekstraknya.

2. Beralihlah ke direktori yang berisi kode contoh Cloud Run Functions untuk mengakses Spanner:

   Node.js

   cd nodejs-docs-samples/functions/spanner

   Python

   cd python-docs-samples/functions/spanner

3. Lihat kode contoh:

   Node.js

   // Imports the Google Cloud client library
   const {Spanner} = require('@google-cloud/spanner');
   
   // Imports the functions framework to register your HTTP function
   const functions = require('@google-cloud/functions-framework');
   
   // Instantiates a client
   const spanner = new Spanner();
   
   // Your Cloud Spanner instance ID
   const instanceId = 'test-instance';
   
   // Your Cloud Spanner database ID
   const databaseId = 'example-db';
   
   /**
    * HTTP Cloud Function.
    *
    * @param {Object} req Cloud Function request context.
    * @param {Object} res Cloud Function response context.
    */
   functions.http('spannerQuickstart', async (req, res) => {
     // Gets a reference to a Cloud Spanner instance and database
     const instance = spanner.instance(instanceId);
     const database = instance.database(databaseId);
   
     // The query to execute
     const query = {
       sql: 'SELECT * FROM Albums',
     };
   
     // Execute the query
     try {
       const results = await database.run(query);
       const rows = results[0].map(row => row.toJSON());
       rows.forEach(row => {
         res.write(
           `SingerId: ${row.SingerId}, ` +
             `AlbumId: ${row.AlbumId}, ` +
             `AlbumTitle: ${row.AlbumTitle}\n`
         );
       });
       res.status(200).end();
     } catch (err) {
       res.status(500).send(`Error querying Spanner: ${err}`);
     }
   });

   Python

   import functions_framework
   from google.cloud import spanner
   
   instance_id = "test-instance"
   database_id = "example-db"
   
   client = spanner.Client()
   instance = client.instance(instance_id)
   database = instance.database(database_id)
   
   
   @functions_framework.http
   def spanner_read_data(request):
       query = "SELECT * FROM Albums"
   
       outputs = []
       with database.snapshot() as snapshot:
           results = snapshot.execute_sql(query)
   
           for row in results:
               output = "SingerId: {}, AlbumId: {}, AlbumTitle: {}".format(*row)
               outputs.append(output)
   
       return "\n".join(outputs)
   
   

   Fungsi ini mengirim kueri SQL untuk mengambil semua data Albums dari database Anda. Fungsi ini dijalankan saat Anda membuat permintaan HTTP ke endpoint fungsi.

Menerapkan fungsi

Untuk men-deploy fungsi dengan pemicu HTTP, jalankan perintah berikut di direktori spanner:

Node.js

gcloud run deploy nodejs-spanner-function \
    --source . \
    --region REGION \
    --function spannerQuickstart \
    --base-image RUNTIME_ID \
    --log-http

Python

gcloud run deploy python-spanner-function \
    --source . \
    --region REGION \
    --function spanner_read_data \
    --base-image RUNTIME_ID \
    --log-http

Ganti:

• REGION dengan nama Google Cloud region tempat Anda ingin men-deploy fungsi (misalnya, us-west1).

• RUNTIME_ID dengan ID runtime yang sesuai (misalnya, nodejs22). Lihat Runtime bahasa dan image dasar yang didukung.

Deployment fungsi mungkin memerlukan waktu hingga dua menit.

Catat nilai url yang ditampilkan saat fungsi Anda selesai di-deploy. Anda akan menggunakannya saat memicu fungsi.

Anda dapat melihat fungsi yang di-deploy di halaman Cloud Run di Google Cloud konsol. Anda juga dapat membuat dan mengedit fungsi di halaman tersebut, serta mendapatkan detail dan diagnostik untuk fungsi Anda.

Memicu fungsi

Buat permintaan HTTP ke fungsi Anda:

curl URL

Ganti URL dengan nilai URL yang ditampilkan saat fungsi Anda selesai di-deploy.

Anda akan melihat output yang menampilkan hasil kueri SQL, dengan asumsi Anda telah menyelesaikan tutorial Memulai dan mengisi database:

SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk

Anda juga dapat membuka URL fungsi di browser untuk melihat hasil kueri SQL.

**Berhasil:** Anda telah membuat fungsi Cloud Run HTTP yang menampilkan hasil Spanner.

Pembersihan

Agar tidak menimbulkan biaya tambahan pada Google Cloud akunAnda untuk resource Spanner dan Cloud Run Functions yang digunakan dalam dokumen ini:

1. Hapus instance:

   gcloud CLI instances delete test-instance
   

2. Hapus layanan Cloud Run yang Anda deploy dalam tutorial ini:

   Node.js

   gcloud run services delete nodejs-spanner-function

   Python

   gcloud run services delete python-spanner-function

Langkah berikutnya

• Pelajari lebih lanjut cara menulis fungsi Cloud Run.
• Pelajari lebih lanjut cara men-deploy fungsi Cloud Run.
• Pelajari lebih lanjut cara memicu fungsi Cloud Run.