Fungsi jarak jauh Spanner

Pratinjau — Remote Functions in Spanner

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Fungsi jarak jauh Spanner memungkinkan Anda menerapkan fungsi dalam bahasa selain SQL. Fungsi harus dihosting di Cloud Run Functions atau Cloud Run. Menghosting fungsi dengan cara ini memungkinkan logika bisnis yang kompleks dibagi menjadi fungsi jarak jauh yang terpisah.

Deployment fungsi jarak jauh yang umum memiliki langkah-langkah berikut:

1. Buat endpoint HTTPS di Cloud Run Functions atau Cloud Run.

   • Jika Anda baru menggunakan fungsi jarak jauh, sebaiknya gunakan fungsi Cloud Run.

2. Buat fungsi jarak jauh di Spanner yang mengarah ke endpoint HTTPS tersebut.

3. Gunakan fungsi jarak jauh dalam kueri.

Peran yang diperlukan

Untuk memastikan bahwa akun layanan agen Spanner Anda ([e-mail]) memiliki izin yang diperlukan untuk menggunakan fungsi jarak jauh Spanner, minta administrator untuk memberikan peran IAM Spanner API Service Agent (roles/spanner.serviceAgent) kepada akun layanan agen Spanner Anda ([e-mail]) di project.iam.gserviceaccount.com

Penting: Anda harus memberikan peran ini ke akun layanan agen Spanner Anda ([e-mail]), bukan ke akun pengguna Anda. Jika peran tidak diberikan kepada akun utama yang benar, error izin mungkin terjadi.

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

Administrator Anda juga dapat memberikan akun layanan agen Spanner Anda ([e-mail]) izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Jenis yang didukung

Fungsi jarak jauh mendukung jenis data berikut sebagai jenis argumen atau jenis nilai yang ditampilkan:

• ARRAY (dari salah satu jenis yang didukung berikut)
• BOOLEAN
• BYTES
• DATE
• JSON
• INTEGER
• NUMERIC
• STRING
• TIMESTAMP

Batasan

• Anda tidak dapat membuat fungsi jarak jauh bernilai tabel.

• Fungsi jarak jauh tidak didukung dalam ekspresi kolom yang dihasilkan.

• Anda mungkin melihat permintaan berulang dengan data yang sama ke endpoint, terkadang bahkan setelah respons berhasil, karena error jaringan sementara atau memulai ulang internal Spanner.

• Menjalankan fungsi jarak jauh di instance Spanner fraksional tidak didukung.

• Fungsi jarak jauh tidak didukung untuk fungsi Cloud Run di balik domain kustom.

• Fungsi jarak jauh tidak didukung dalam dialek PostgreSQL.

Membuat endpoint

Logika bisnis harus diimplementasikan sebagai fungsi Cloud Run atau Cloud Run. Endpoint harus dapat memproses batch baris dalam satu permintaan POST HTTPS dan menampilkan hasil untuk batch tersebut sebagai respons HTTPS.

Jika telah membuat fungsi jarak jauh untuk BigQuery, Anda dapat menggunakannya kembali untuk Spanner.

Lihat tutorial Cloud Run Functions dan dokumentasi Cloud Run Functions lainnya tentang cara menulis, men-deploy, menguji, dan mengelola Cloud Run Function.

Lihat Panduan memulai Cloud Run dan dokumentasi Cloud Run lainnya tentang cara menulis, men-deploy, menguji, dan mengelola layanan Cloud Run.

Sebaiknya pertahankan autentikasi default untuk fungsi Cloud Run atau layanan Cloud Run Anda. Hindari mengonfigurasi layanan untuk mengizinkan pemanggilan yang tidak diautentikasi.

Format input

Spanner mengirim permintaan POST HTTPS dengan isi JSON dalam format berikut:

Nama kolom	Deskripsi	Jenis kolom
requestId	ID permintaan. Bersifat unik dari beberapa permintaan yang dikirim ke endpoint dalam kueri GoogleSQL.	Selalu tersedia. String.
calls	Batch data input.	Selalu tersedia. Array JSON. Setiap elemen adalah array JSON yang merepresentasikan daftar argumen yang dienkode JSON untuk satu panggilan fungsi jarak jauh.

Contoh permintaan:

// Sample request to a Cloud Run functions to calculate sum of two numbers. This request
// has two calls batched together into a single request.
{
 "requestId": "124ab1c",
 "calls": [
  [1, 2],
  [3, 4]
 ]
}

Format output

Spanner mengharapkan endpoint menampilkan respons HTTPS dalam format berikut. Jika tidak, Spanner tidak dapat menggunakan respons dan kueri gagal memanggil fungsi jarak jauh.

Nama kolom	Deskripsi	Rentang Nilai
replies	Batch nilai yang ditampilkan.	Array JSON. Setiap elemen sesuai dengan nilai yang ditampilkan fungsi eksternal yang dienkode JSON. Ukuran array harus cocok dengan ukuran array calls JSON dalam permintaan HTTPS. Misalnya, jika array JSON di calls memiliki 4 elemen, array JSON ini juga harus memiliki 4 elemen. Diperlukan agar respons berhasil.
errorMessage	Pesan error saat kode respons HTTPS selain 200 ditampilkan. Untuk error yang tidak dapat dicoba lagi, Spanner akan menampilkan pesan error ini kepada pengguna. Diperlukan dalam respons yang gagal. Biasanya kurang dari 1 KB.	String.

Contoh respons yang berhasil:

// Sample response from the Cloud Run functions which has the sum of the two numbers. Note
// that the order of the values within `replies` field matches the `calls` field from
// the request.
{
  "replies": [
    3,  // 1 + 2 = 3
    7   // 3 + 4 = 7
  ]
}

Contoh respons yang gagal:

{
  // The error message returned by your Cloud Run functions to indicate an error.
  // In this sample, the error message states that an overflow occurred when summing two numbers.
  "errorMessage": "Overflow detected when calculating sum of two numbers."
}

Kode respons HTTPS

Endpoint Anda menampilkan kode HTTPS 200 untuk respons yang berhasil. Saat Spanner menerima nilai lain, Spanner menganggap respons tersebut gagal, dan mencoba lagi saat kode respons HTTPS adalah 408, 429, 500, 503, atau 504 hingga batas internal tercapai.

Kode contoh

Fungsi Cloud Run

Contoh kode Python berikut mengimplementasikan penambahan semua argumen bilangan bulat fungsi jarak jauh. Fungsi ini menangani permintaan dengan argumen untuk pemanggilan batch dan menampilkan semua hasilnya sebagai respons.

"""
Python script which uses Flask framework to spin up a HTTP server to take
integers and return their sum. In case of overflow, it returns the error
as part of the response.
"""
import functions_framework

from flask import jsonify

# Max INT64 value encoded as a number in JSON by TO_JSON_STRING. Larger values are encoded as
# strings.
_MAX_LOSSLESS=9007199254740992

@functions_framework.http
def batch_add(request):
  try:
    return_value = []
    request_json = request.get_json()
    calls = request_json['calls']
    for call in calls:
      return_value.append(sum([int(x) if isinstance(x, str) else x for x in call if x is not None]))
    replies = [str(x) if x > _MAX_LOSSLESS or x < -_MAX_LOSSLESS else x for x in return_value]
    return_json = jsonify( { "replies":  replies } )
    return return_json
  except Exception as e:
    return jsonify( { "errorMessage": str(e) } ), 400

Dengan asumsi bahwa fungsi di-deploy dalam project PROJECT_ID di region us-east1 sebagai nama fungsi remote_add, fungsi tersebut dapat diakses menggunakan endpoint https://us-east1-PROJECT_ID.cloudfunctions.net/remote_add.

Cloud Run

Contoh kode Python berikut mengimplementasikan layanan web, yang dapat dibuat dan di-deploy ke Cloud Run untuk fungsi yang sama.

"""
Python script which uses Flask framework to spin up a HTTP server to take
integers and return their sum. In case of overflow, it returns the error
as part of the response.
"""
import os

from flask import Flask, request, jsonify

# Max INT64 value encoded as a number in JSON by TO_JSON_STRING. Larger values are encoded as
# strings.
_MAX_LOSSLESS=9007199254740992

app = Flask(__name__)

@app.route("/", methods=['POST'])
def batch_add():
  try:
    return_value = []
    request_json = request.get_json()
    calls = request_json['calls']
    for call in calls:
      return_value.append(sum([int(x) if isinstance(x, str) else x for x in call if x is not None]))
    replies = [str(x) if x > _MAX_LOSSLESS or x < -_MAX_LOSSLESS else x for x in return_value]
    return jsonify( { "replies" :  replies } )
  except Exception as e:
    return jsonify( { "errorMessage": str(e) } ), 400

if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

Untuk mem-build dan men-deploy kode, lihat Panduan memulai: Membangun dan men-deploy aplikasi web Python (Flask) ke Cloud Run.

Dengan asumsi bahwa layanan Cloud Run di-deploy dalam project PROJECT_ID di region us-east1 sebagai nama layanan remote_add, layanan tersebut dapat diakses menggunakan endpoint https://remote_add-<project_id_hash>-ue.a.run.app.

Membuat fungsi jarak jauh

Untuk membuat fungsi jarak jauh:

SQL

Jalankan pernyataan CREATE FUNCTION berikut di Spanner:

CREATE FUNCTION REMOTE_FUNCTION_NAME(x INT64, y INT64) RETURNS INT64 NOT DETERMINISTIC LANGUAGE REMOTE OPTIONS (
  endpoint = `ENDPOINT_URL`,
  max_batching_rows = MAX_BATCHING_ROWS
);

Ganti kode berikut:

• REMOTE_FUNCTION_NAME: nama fungsi jarak jauh Anda. Contoh, sum_func.
• ENDPOINT_URL: endpoint Cloud Run Functions atau Cloud Run yang dibuat pada langkah sebelumnya.
• MAX_BATCHING_ROWS (opsional): jumlah maksimum baris yang akan dikirim sebagai bagian dari permintaan. Jika tidak ditentukan, Spanner akan menentukan ukuran batch secara otomatis.

Menggunakan fungsi jarak jauh dalam kueri

Untuk memanggil fungsi jarak jauh dari langkah sebelumnya dalam kueri, gunakan contoh berikut:

SELECT REMOTE_FUNCTION_NAME(1, 2); -- 1 + 2 = 3

Harga

• Harga Spanner standar berlaku.

• Spanner menagih byte yang dikirim ke dan diterima dari Cloud Run Functions atau Cloud Run.

• Fitur ini dapat menimbulkan biaya dari Cloud Run Functions dan Cloud Run. Tinjau halaman harga Cloud Run Functions dan Cloud Run untuk mengetahui detailnya.