Menggunakan fungsi jarak jauh

Fungsi jarak jauh BigQuery memungkinkan Anda untuk menerapkan fungsi dalam bahasa lain selain SQL dan JavaScript, atau dengan library atau layanan yang tidak diizinkan dalam fungsi yang ditentukan pengguna BigQuery.

Ringkasan

Fungsi jarak jauh BigQuery memungkinkan Anda untuk menggabungkan fungsi GoogleSQL dengan software di luar BigQuery dengan memberikan integrasi langsung dengan fungsi Cloud Run dan Cloud Run. Dengan fungsi jarak jauh BigQuery, Anda dapat men-deploy fungsi di fungsi Cloud Run atau Cloud Run yang diimplementasikan dengan bahasa yang didukung, lalu memanggilnya dari kueri GoogleSQL.

Alur kerja

  1. Buat endpoint HTTP di fungsi Cloud Run atau Cloud Run.
  2. Membuat fungsi jarak jauh di BigQuery.
    1. Membuat koneksi jenis CLOUD_RESOURCE.
    2. Membuat fungsi jarak jauh.
  3. Menggunakan fungsi jarak jauh dalam kueri sama seperti fungsi lainnya yang ditentukan pengguna.

Keterbatasan

  • Fungsi jarak jauh hanya mendukung salah satu jenis data berikut sebagai jenis argumen atau jenis nilai yang ditampilkan:

    • Boolean
    • Byte
    • Angka
    • String
    • Tanggal
    • Datetime
    • Time
    • Stempel waktu
    • JSON

    Fungsi jarak jauh tidak mendukung jenis ARRAY, STRUCT, INTERVAL, atau GEOGRAPHY.

  • Anda tidak dapat membuat fungsi jarak jauh sementara.

  • Anda tidak dapat membuat fungsi jarak jauh bernilai tabel.

  • Anda tidak dapat menggunakan fungsi jarak jauh saat membuat tampilan terwujud.

  • Nilai yang ditampilkan fungsi jarak jauh selalu dianggap sebagai non-deterministik sehingga hasil kueri yang memanggil fungsi jarak jauh tidak di-cache.

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

  • Ketika evaluasi fungsi jarak jauh dilewati untuk beberapa baris karena korsleting, misalnya, dalamekspresi kondisional atau pernyataan MERGE dengan WHEN [NOT] MATCHED, pengelompokan tidak digunakan dengan fungsi jarak jauh. Dalam hal ini, kolom calls di isi permintaan HTTP memiliki tepat satu elemen.

  • Jika set data yang terkait dengan fungsi jarak jauh direplikasi ke region tujuan melalui replikasi set data lintas region, fungsi jarak jauh hanya dapat dikueri di region fungsi tersebut dibuat.

Membuat endpoint

Untuk membuat fungsi jarak jauh yang dapat mengimplementasikan logika bisnis, Anda harus membuat endpoint HTTP menggunakan fungsi Cloud Run atau Cloud Run. Endpoint harus dapat memproses batch baris dalam satu permintaan POST HTTP dan menampilkan hasil untuk batch tersebut sebagai respons HTTP.

Jika Anda membuat fungsi jarak jauh menggunakan BigQuery DataFrames, Anda tidak perlu membuat endpoint HTTP secara manual; layanan tersebut akan melakukannya secara otomatis.

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

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

Sebaiknya Anda tetap melakukan autentikasi default daripada mengizinkan pemanggilan fungsi Cloud Run atau layanan Cloud Run yang tidak diautentikasi.

Format input

BigQuery mengirim permintaan POST HTTP dengan isi JSON dalam format berikut:

Nama kolom Deskripsi Jenis kolom
requestId ID permintaan. Bersifat unik dari beberapa permintaan yang dikirim ke endpoint ini dalam kueri GoogleSQL. Selalu tersedia. String.
caller Nama lengkap resource tugas untuk kueri GoogleSQL yang memanggil fungsi jarak jauh. Selalu tersedia. String.
sessionUser Email pengguna yang menjalankan kueri GoogleSQL. Selalu tersedia. String.
userDefinedContext Konteks yang ditentukan pengguna yang digunakan saat membuat fungsi jarak jauh di BigQuery. Opsional. Objek JSON dengan key-value pair.
calls Batch data input. Selalu tersedia. Array JSON.

Setiap elemen adalah array JSON, yang merupakan daftar argumen yang dienkode JSON dari panggilan fungsi jarak jauh.

Contoh permintaan:

{
 "requestId": "124ab1c",
 "caller": "//bigquery.googleapis.com/projects/myproject/jobs/myproject:US.bquxjob_5b4c112c_17961fafeaf",
 "sessionUser": "test-user@test-company.com",
 "userDefinedContext": {
  "key1": "value1",
  "key2": "v2"
 },
 "calls": [
  [null, 1, "", "abc"],
  ["abc", "9007199254740993", null, null]
 ]
}

Format output

BigQuery memperkirakan endpoint menampilkan respons HTTP dalam format berikut. Jika tidak, BigQuery tidak akan dapat menggunakannya dan akan menggagalkan kueri yang memanggil fungsi jarak jauh.

Nama kolom Deskripsi Rentang Nilai
replies Batch nilai yang ditampilkan. Diperlukan agar respons berhasil. 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 HTTP. Misalnya, jika array JSON di calls memiliki 4 elemen, array JSON ini juga harus memiliki 4 elemen.

errorMessage Pesan error saat kode respons HTTP selain 200 ditampilkan. Untuk error yang tidak dapat dicoba lagi, kami menampilkannya sebagai bagian dari pesan error tugas BigQuery kepada pengguna. Opsional. String. Ukuran harus kurang dari 1 KB.

Contoh respons yang berhasil:

{
  "replies": [
    1,
    0
  ]
}

Contoh respons yang gagal:

{
  "errorMessage": "Received but not expected that the argument 0 be null".
}

Kode respons HTTP

Endpoint Anda harus menampilkan kode respons HTTP 200 agar respons berhasil. Saat BigQuery menerima nilai lain, BigQuery menganggap respons tersebut gagal, dan bisa dicoba lagi saat kode respons HTTP adalah 408, 429, 500, 503, atau 504 hingga mencapai batas internal.

Encoding JSON dari jenis data SQL

Encoding JSON pada permintaan/respons HTTP mengikuti encoding JSON BigQuery yang ada untuk fungsi TO_JSON_STRING.

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

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.
# See https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#json_encodings
_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 my_gcf_project di region us-east1 sebagai nama fungsi remote_add, fungsi tersebut dapat diakses melalui endpoint https://us-east1-my_gcf_project.cloudfunctions.net/remote_add.

Contoh kode Cloud Run

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

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.
# See https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#json_encodings
_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)))

Lihat panduan tentang cara membuat dan men-deploy kode.

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

Membuat fungsi jarak jauh

BigQuery menggunakan koneksi CLOUD_RESOURCE untuk berinteraksi dengan fungsi Cloud Run Anda. Untuk membuat fungsi jarak jauh, Anda harus membuat koneksi CLOUD_RESOURCE. Jika Anda membuat fungsi jarak jauh menggunakan BigQuery DataFrame dan Anda telah diberikan peran Project IAM Admin (roles/resourcemanager.projectIamAdmin), maka Anda tidak perlu membuat koneksi dan memberikan akses secara manual; layanan tersebut akan melakukannya secara otomatis.

Membuat koneksi

Anda harus memiliki koneksi resource Cloud untuk terhubung ke fungsi Cloud Run dan Cloud Run.

Pilih salah satu opsi berikut:

Konsol

  1. Buka halaman BigQuery.

    Buka BigQuery

  2. Untuk membuat koneksi, klik Tambahkan, lalu klik Koneksi ke sumber data eksternal.

  3. Dalam daftar Connection type, pilih Vertex AI remote models, remote functions and BigLake (Cloud Resource).

  4. Di kolom Connection ID, masukkan nama untuk koneksi Anda.

  5. Klik Create connection.

  6. Klik Go to connection.

  7. Di panel Connection info, salin ID akun layanan untuk digunakan di langkah berikutnya.

bq

  1. Di lingkungan command line, buat koneksi:

    bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID

    Parameter --project_id akan mengganti project default.

    Ganti kode berikut:

    • REGION: region koneksi Anda
    • PROJECT_ID: project ID Google Cloud Anda
    • CONNECTION_ID: ID untuk koneksi Anda

    Saat Anda membuat resource koneksi, BigQuery akan membuat akun layanan sistem unik dan mengaitkannya dengan koneksi.

    Pemecahan masalah: Jika Anda mendapatkan error koneksi berikut, update Google Cloud SDK:

    Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...

  2. Ambil dan salin ID akun layanan untuk digunakan di langkah berikutnya:

    bq show --connection PROJECT_ID.REGION.CONNECTION_ID

    Outputnya mirip dengan hal berikut ini:

    name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel."}

Terraform

Gunakan resource google_bigquery_connection.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut membuat koneksi resource Cloud bernama my_cloud_resource_connection di region US:


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Untuk menerapkan konfigurasi Terraform di project Google Cloud, selesaikan langkah-langkah di bagian berikut.

Menyiapkan Cloud Shell

  1. Luncurkan Cloud Shell.

  2. Tetapkan project Google Cloud default tempat Anda ingin menerapkan konfigurasi Terraform.

    Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

Menyiapkan direktori

Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri (juga disebut modul root).

  1. Di Cloud Shell, buat direktori dan file baru di dalam direktori tersebut. Nama file harus memiliki ekstensi .tf—misalnya main.tf. Dalam tutorial ini, file ini disebut sebagai main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Jika mengikuti tutorial, Anda dapat menyalin kode contoh di setiap bagian atau langkah.

    Salin kode contoh ke dalam main.tf yang baru dibuat.

    Atau, salin kode dari GitHub. Tindakan ini direkomendasikan jika cuplikan Terraform adalah bagian dari solusi menyeluruh.

  3. Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
  4. Simpan perubahan Anda.
  5. Lakukan inisialisasi Terraform. Anda hanya perlu melakukan ini sekali per direktori. 
    terraform init

    Secara opsional, untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade: 

    terraform init -upgrade

Menerapkan perubahan

  1. Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan: 
    terraform plan

    Koreksi konfigurasi jika diperlukan.

  2. Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt: 
    terraform apply

    Tunggu hingga Terraform menampilkan pesan "Apply complete!".

  3. Buka project Google Cloud Anda untuk melihat hasilnya. Di Konsol Google Cloud, buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

Menyiapkan akses

Anda harus memberikan koneksi baru akses hanya baca ke fungsi Cloud Run atau layanan Cloud Run. Sebaiknya jangan mengizinkan pemanggilan yang tidak diautentikasi untuk fungsi Cloud Run atau layanan Cloud Run.

Untuk memberikan peran, ikuti langkah-langkah berikut:

  1. Buka halaman IAM & Admin.

    Buka IAM & Admin

  2. Klik Add.

    Dialog Add principals akan terbuka.

  3. Di kolom Akun utama baru, masukkan ID akun layanan yang Anda salin sebelumnya.

  4. Di kolom Pilih peran, pilih salah satu opsi berikut:

    • Jika Anda menggunakan fungsi Cloud Run generasi ke-1, pilih Cloud Function, lalu pilih Peran Invoker Cloud Function.
    • Jika Anda menggunakan fungsi Cloud Run generasi ke-2, pilih Cloud Run, lalu pilih Peran Invoker Cloud Run.
    • Jika Anda menggunakan layanan Cloud Run, pilih Cloud Run, lalu pilih Peran Invoker Cloud Run.

  5. Klik Simpan.

Membuat fungsi jarak jauh

Untuk membuat fungsi jarak jauh:

SQL

Jalankan pernyataan CREATE FUNCTION berikut di BigQuery:

  1. Di Konsol Google Cloud, buka halaman BigQuery.

    Buka BigQuery

  2. Di editor kueri, masukkan pernyataan berikut:

    CREATE FUNCTION PROJECT_ID.DATASET_ID.remote_add(x INT64, y INT64) RETURNS INT64
REMOTE WITH CONNECTION PROJECT_ID.LOCATION.CONNECTION_NAME
OPTIONS (
  endpoint = 'ENDPOINT_URL'
)

    Ganti kode berikut:

    • DATASET_ID: ID set data BigQuery Anda.
    • ENDPOINT_URL: URL fungsi Cloud Run atau endpoint fungsi jarak jauh Cloud Run Anda.

  3. Klik Run.

Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.

DataFrame BigQuery

  1. Aktifkan API yang diperlukan dan pastikan Anda telah diberi peran yang diperlukan, seperti yang dijelaskan di bagian Persyaratan dari Fungsi jarak jauh.

  2. Gunakan dekorator remote_function:

    import bigframes.pandas as bpd

# Set BigQuery DataFrames options
bpd.options.bigquery.project = your_gcp_project_id
bpd.options.bigquery.location = "us"

# BigQuery DataFrames gives you the ability to turn your custom scalar
# functions into a BigQuery remote function. It requires the GCP project to
# be set up appropriately and the user having sufficient privileges to use
# them. One can find more details about the usage and the requirements via
# `help` command.
help(bpd.remote_function)

# Read a table and inspect the column of interest.
df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")
df["body_mass_g"].head(10)

# Define a custom function, and specify the intent to turn it into a remote
# function. It requires a BigQuery connection. If the connection is not
# already created, BigQuery DataFrames will attempt to create one assuming
# the necessary APIs and IAM permissions are setup in the project. In our
# examples we will be letting the default connection `bigframes-default-connection`
# be used. We will also set `reuse=False` to make sure we don't
# step over someone else creating remote function in the same project from
# the exact same source code at the same time. Let's try a `pandas`-like use
# case in which we want to apply a user defined scalar function to every
# value in a `Series`, more specifically bucketize the `body_mass_g` value
# of the penguins, which is a real number, into a category, which is a
# string.
@bpd.remote_function(
    float,
    str,
    reuse=False,
)
def get_bucket(num: float) -> str:
    if not num:
        return "NA"
    boundary = 4000
    return "at_or_above_4000" if num >= boundary else "below_4000"

# Then we can apply the remote function on the `Series`` of interest via
# `apply` API and store the result in a new column in the DataFrame.
df = df.assign(body_mass_bucket=df["body_mass_g"].apply(get_bucket))

# This will add a new column `body_mass_bucket` in the DataFrame. You can
# preview the original value and the bucketized value side by side.
df[["body_mass_g", "body_mass_bucket"]].head(10)

# The above operation was possible by doing all the computation on the
# cloud. For that, there is a google cloud function deployed by serializing
# the user code, and a BigQuery remote function created to call the cloud
# function via the latter's http endpoint on the data in the DataFrame.

# The BigQuery remote function created to support the BigQuery DataFrames
# remote function can be located via a property `bigframes_remote_function`
# set in the remote function object.
print(f"Created BQ remote function: {get_bucket.bigframes_remote_function}")

# The cloud function can be located via another property
# `bigframes_cloud_function` set in the remote function object.
print(f"Created cloud function: {get_bucket.bigframes_cloud_function}")

# Warning: The deployed cloud function may be visible to other users with
# sufficient privilege in the project, so the user should be careful about
# having any sensitive data in the code that will be deployed as a remote
# function.

# Let's continue trying other potential use cases of remote functions. Let's
# say we consider the `species`, `island` and `sex` of the penguins
# sensitive information and want to redact that by replacing with their hash
# code instead. Let's define another scalar custom function and decorate it
# as a remote function. The custom function in this example has external
# package dependency, which can be specified via `packages` parameter.
@bpd.remote_function(
    str,
    str,
    reuse=False,
    packages=["cryptography"],
)
def get_hash(input: str) -> str:
    from cryptography.fernet import Fernet

    # handle missing value
    if input is None:
        input = ""

    key = Fernet.generate_key()
    f = Fernet(key)
    return f.encrypt(input.encode()).decode()

# We can use this remote function in another `pandas`-like API `map` that
# can be applied on a DataFrame
df_redacted = df[["species", "island", "sex"]].map(get_hash)
df_redacted.head(10)

Anda harus memiliki izin bigquery.routines.create di set data tempat Anda membuat fungsi jarak jauh, dan izin bigquery.connections.delegate (tersedia dari peran BigQuery Connection Admin) pada koneksi yang digunakan oleh fungsi jarak jauh.

Memberikan konteks yang ditentukan pengguna

Anda dapat menentukan user_defined_context di OPTIONS sebagai bentuk key-value pair, yang akan menjadi bagian dari setiap permintaan HTTP ke endpoint. Dengan konteks yang ditentukan pengguna, Anda dapat membuat beberapa fungsi jarak jauh, tetapi menggunakan kembali satu endpoint yang memberikan perilaku berbeda berdasarkan konteks yang diteruskan ke sana.

Contoh berikut membuat dua fungsi jarak jauh untuk mengenkripsi dan mendekripsi data BYTES menggunakan endpoint yang sama.

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.encrypt(x BYTES)
RETURNS BYTES
REMOTE WITH CONNECTION `PROJECT_ID.LOCATION.CONNECTION_NAME`
OPTIONS (
  endpoint = 'ENDPOINT_URL',
  user_defined_context = [("mode", "encryption")]
)

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.decrypt(x BYTES)
RETURNS BYTES
REMOTE WITH CONNECTION `PROJECT_ID.LOCATION.CONNECTION_NAME`
OPTIONS (
  endpoint = 'ENDPOINT_URL',
  user_defined_context = [("mode", "decryption")]
)

Membatasi jumlah baris dalam permintaan batch

Anda dapat menentukan max_batching_rows di OPTIONS sebagai jumlah baris maksimum di setiap permintaan HTTP, untuk menghindari waktu tunggu fungsi Cloud Run. Jika tidak ditentukan, BigQuery akan menentukan jumlah baris yang disertakan dalam satu batch.

Menggunakan fungsi jarak jauh dalam kueri

Pastikan Anda telah memberikan izin di fungsi Cloud Run, sehingga dapat diakses oleh akun layanan BigQuery yang terkait dengan koneksi fungsi jarak jauh.

Anda juga harus memiliki izin bigquery.routines.get pada set data di mana fungsi jarak jauh berada, dan izin bigquery.connections.use, yang bisa Anda dapatkan melalui peran BigQuery Connection User, pada koneksi yang digunakan oleh fungsi jarak jauh.

Anda dapat menggunakan fungsi jarak jauh dalam kueri seperti fungsi yang ditentukan pengguna.

Misalnya, Anda dapat menggunakan fungsi remote_add dalam contoh kueri:

SELECT
  val,
  `PROJECT_ID.DATASET_ID`.remote_add(val, 2)
FROM
  UNNEST([NULL,2,3,5,8]) AS val;

Contoh ini menghasilkan output berikut:

+------+-----+
|  val | f0_ |
+------+-----+
| NULL |   2 |
|    2 |   4 |
|    3 |   5 |
|    5 |   7 |
|    8 |  10 |
+------+-----+

Region yang didukung

Ada dua jenis lokasi di BigQuery:

  • Region adalah lokasi geografis spesifik, seperti London.

  • Multi-region adalah wilayah geografis yang luas, seperti Amerika Serikat, yang berisi dua atau lebih tempat geografis.

Satu region

Dalam set data satu region BigQuery, Anda hanya dapat membuat fungsi jarak jauh yang menggunakan fungsi Cloud Run yang di-deploy di region yang sama. Misalnya:

  • Fungsi jarak jauh di satu region us-east4 BigQuery hanya dapat menggunakan fungsi Cloud Run di us-east4.

Jadi untuk satu region, fungsi jarak jauh hanya didukung di region yang mendukung fungsi Cloud Run dan BigQuery.

Multi-region

Dalam set data multi-region BigQuery (US, EU), Anda hanya dapat membuat fungsi jarak jauh yang menggunakan fungsi Cloud Run yang di-deploy di region dalam area geografis yang sama luas (AS, Uni Eropa). Contoh:

  • Fungsi jarak jauh di multi-region US BigQuery hanya dapat menggunakan fungsi Cloud Run yang di-deploy di satu region di area geografis Amerika Serikat, seperti us-central1, us-east4, us-west2, dll.
  • Fungsi jarak jauh di multi-region EU BigQuery hanya dapat menggunakan fungsi Cloud Run yang di-deploy di satu region di negara anggota Uni Eropa, seperti europe-north1, europe-west3, dll.

Untuk mengetahui informasi selengkapnya tentang region dan multi-region BigQuery, lihat halaman Lokasi Set Data. Untuk mengetahui informasi selengkapnya tentang region fungsi Cloud Run, lihat halaman Lokasi fungsi Cloud Run.

Koneksi

Untuk lokasi satu region atau lokasi multi-region, Anda hanya dapat membuat fungsi jarak jauh di lokasi yang sama dengan koneksi yang Anda gunakan. Misalnya, untuk membuat fungsi jarak jauh di multi-region US, gunakan koneksi yang terletak di multi-region US.

Harga

Menggunakan Kontrol Layanan VPC

Kontrol Layanan VPC adalah fitur Google Cloud yang memungkinkan Anda untuk menyiapkan perimeter yang aman untuk mencegah pemindahan data yang tidak sah. Untuk menggunakan Kontrol Layanan VPC dengan fungsi jarak jauh guna memberikan keamanan tambahan, atau menggunakan endpoint dengan setelan masuk internal traffic, ikuti Panduan Kontrol Layanan VPC untuk:

  1. Membuat perimeter layanan.

  2. Menambahkan project BigQuery dari kueri menggunakan fungsi jarak jauh ke perimeter.

  3. Menambahkan project endpoint ke perimeter dan menetapkan Cloud Functions API atau Cloud Run API di layanan yang dibatasi berdasarkan jenis endpoint Anda. Untuk mengetahui detail selengkapnya, lihat Kontrol Layanan VPC fungsi Cloud Run dan Kontrol Layanan VPC Cloud Run.

Praktik terbaik untuk fungsi jarak jauh

  • Filter input Anda terlebih dahulu: Jika input Anda dapat dengan mudah difilter sebelum diteruskan ke fungsi jarak jauh, kueri Anda mungkin akan lebih cepat dan lebih murah.

  • Jaga fungsi Cloud Run Anda tetap skalabel. Skalabilitas adalah fungsi instance minimum, instance maksimum, dan konkurensi.

    • Jika memungkinkan, gunakan nilai default untuk jumlah maksimum instance fungsi Cloud Run Anda.
    • Perlu diperhatikan bahwa tidak ada batas default untuk fungsi Cloud Run HTTP generasi ke-1. Untuk menghindari peristiwa penskalaan tanpa batas dengan fungsi Cloud Run HTTP generasi ke-1 saat pengujian atau dalam produksi, sebaiknya tetapkan batas, misalnya, 3000.

  • Ikuti Tips fungsi Cloud Run lainnya untuk mendapatkan performa yang lebih baik. Kueri fungsi jarak jauh yang berinteraksi dengan fungsi Cloud Run latensi tinggi dapat gagal karena waktu tunggu habis.

  • Terapkan endpoint Anda untuk menampilkan kode respons HTTP dan payload yang tepat untuk respons yang gagal.

    • Untuk meminimalkan upaya coba lagi dari BigQuery, gunakan kode respons HTTP selain 408, 429, 500, 503, dan 504 untuk respons yang gagal, dan pastikan untuk menangkap semua pengecualian dalam kode fungsi Anda. Jika tidak, framework layanan HTTP dapat secara otomatis menampilkan 500 untuk setiap pengecualian yang tidak tertangkap. Anda mungkin masih melihat permintaan HTTP yang dicoba lagi saat BigQuery mencoba lagi kueri atau partisi data yang gagal.

    • Endpoint Anda akan menampilkan payload JSON dalam format yang ditentukan untuk respons yang gagal. Meskipun tidak wajib, fitur ini membantu BigQuery membedakan apakah respons yang gagal berasal dari implementasi fungsi atau infrastruktur fungsi Cloud Run/Cloud Run. Untuk yang terakhir, BigQuery dapat mencoba lagi dengan batas internal yang berbeda.

Kuota

Untuk mengetahui informasi tentang kuota fungsi jarak jauh, lihat Kuota dan batas.