Fungsi jarak jauh dan tutorial Translation API

Tutorial ini menjelaskan cara membuat fungsi jarak jauh BigQuery, memanggil Cloud Translation API, dan melakukan terjemahan konten dari bahasa apa pun ke bahasa Spanyol menggunakan SQL dan Python.

Kasus penggunaan untuk fungsi ini mencakup hal berikut:

  • Menerjemahkan komentar pengguna di situs ke dalam bahasa lokal
  • Menerjemahkan permintaan dukungan dari banyak bahasa ke dalam satu bahasa umum untuk worker kasus dukungan

Tujuan

  • Menetapkan peran yang diperlukan ke akun Anda.
  • Membuat fungsi Cloud Functions.
  • Membuat set data BigQuery.
  • Membuat koneksi BigQuery dan akun layanan.
  • Memberikan izin ke akun layanan BigQuery.
  • Membuat fungsi jarak jauh BigQuery.
  • Memanggil fungsi jarak jauh BigQuery.

Biaya

Dalam dokumen ini, Anda menggunakan komponen Google Cloud yang dapat ditagih berikut:

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga. Pengguna baru Google Cloud mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Sebelum memulai

Sebaiknya Anda membuat project Google Cloud untuk tutorial ini. Selain itu, pastikan Anda memiliki peran yang diperlukan untuk menyelesaikan tutorial ini.

Menyiapkan project Google Cloud

Guna menyiapkan project Google Cloud untuk tutorial ini, selesaikan langkah-langkah berikut:

  1. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

  2. Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

    Buka pemilih project

  3. Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

  4. Enable the BigQuery, BigQuery Connection, Cloud Translation, Cloud Functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin APIs.

    Enable the APIs

    5.

  5. Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

    Buka pemilih project

  6. Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

  7. Enable the BigQuery, BigQuery Connection, Cloud Translation, Cloud Functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin APIs.

    Enable the APIs

    8.

Peran yang diperlukan untuk akun Anda

Untuk mendapatkan izin yang Anda perlukan untuk melakukan tugas dalam tutorial ini, minta administrator Anda untuk memberi Anda peran IAM berikut pada project Anda:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses.

Peran bawaan ini berisi izin yang diperlukan untuk melakukan tugas dalam tutorial ini. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk melakukan tugas dalam tutorial ini:

  • bigquery.datasets.create
  • bigquery.connections.create
  • bigquery.connections.get
  • cloudfunctions.functions.create

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran yang telah ditetapkan sebelumnya.

Peran yang diperlukan untuk akun layanan default Compute Engine

Saat Anda mengaktifkan API untuk Cloud Functions, akun layanan default Compute Engine telah dibuat. Untuk menyelesaikan tutorial ini, Anda harus memberikan peran Cloud Translation API User untuk akun layanan default ini.

  1. Dapatkan ID yang ditetapkan ke project.

  2. Salin akun layanan default Compute Engine Anda. Akun layanan default Anda akan terlihat seperti ini:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Ganti PROJECT_NUMBER dengan project ID Anda.

  3. Di konsol Google Cloud, buka halaman IAM.

    Buka IAM

  4. Pilih project Anda.

  5. Klik Grant access, lalu di kolom New principals, tempel akun layanan default Compute Engine yang Anda salin sebelumnya.

  6. Dalam daftar Assign roles, telusuri dan pilih Cloud Translation API User.

  7. Klik Save.

Membuat fungsi Cloud Functions

Dengan Cloud Functions, buat fungsi yang menerjemahkan teks input ke dalam bahasa Spanyol.

  1. Buat fungsi Cloud Functions dengan spesifikasi berikut:

    • Untuk Environment, pilih 2nd gen.
    • Untuk Function name, masukkan translation-handler.
    • Untuk Region, pilih us-central1.

    • Untuk Maximum number of instances, masukkan 10.

      Setelan ini berada di bagian Runtime, build, koneksi, dan setelan keamanan.

      Dalam tutorial ini, kami menggunakan nilai yang lebih rendah daripada nilai default untuk mengontrol kecepatan permintaan yang dikirim ke Translation.

    • Untuk Runtime, pilih Python 3.10.

    • Untuk Entry point, masukkan handle_translation.

  2. Dalam daftar file, pilih main.py, lalu tempel kode berikut.

    Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Python API.

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

    from __future__ import annotations


import flask
import functions_framework
from google.api_core.retry import Retry
from google.cloud import translate

# Construct a Translation Client object
translate_client = translate.TranslationServiceClient()


# Register an HTTP function with the Functions Framework
@functions_framework.http
def handle_translation(request: flask.Request) -> flask.Response:
    """BigQuery remote function to translate input text.

    Args:
        request: HTTP request from BigQuery
        https://cloud.google.com/bigquery/docs/reference/standard-sql/remote-functions#input_format

    Returns:
        HTTP response to BigQuery
        https://cloud.google.com/bigquery/docs/reference/standard-sql/remote-functions#output_format
    """
    try:
        # Parse request data as JSON
        request_json = request.get_json()
        # Get the project of the query
        caller = request_json["caller"]
        project = extract_project_from_caller(caller)
        if project is None:
            return flask.make_response(
                flask.jsonify(
                    {
                        "errorMessage": (
                            'project can\'t be extracted from "caller":' f" {caller}."
                        )
                    }
                ),
                400,
            )
        # Get the target language code, default is Spanish ("es")
        context = request_json.get("userDefinedContext", {})
        target = context.get("target_language", "es")

        calls = request_json["calls"]
        translated = translate_text([call[0] for call in calls], project, target)

        return flask.jsonify({"replies": translated})
    except Exception as err:
        return flask.make_response(
            flask.jsonify({"errorMessage": f"Unexpected error {type(err)}:{err}"}),
            400,
        )


def extract_project_from_caller(job: str) -> str:
    """Extract project id from full resource name of a BigQuery job.

    Args:
        job: full resource name of a BigQuery job, like
          "//bigquery.googleapi.com/projects/<project>/jobs/<job_id>"

    Returns:
        project id which is contained in the full resource name of the job.
    """
    path = job.split("/")
    return path[4] if len(path) > 4 else None


def translate_text(
    calls: list[str], project: str, target_language_code: str
) -> list[str]:
    """Translates the input text to specified language using Translation API.

    Args:
        calls: a list of input text to translate.
        project: the project where the translate service will be used.
        target_language_code: The ISO-639 language code to use for translation
          of the input text. See
          https://cloud.google.com/translate/docs/advanced/discovering-supported-languages-v3#supported-target
            for the supported language list.

    Returns:
        a list of translated text.
    """
    location = "<your location>"
    parent = f"projects/{project}/locations/{location}"
    # Call the Translation API, passing a list of values and the target language
    response = translate_client.translate_text(
        request={
            "parent": parent,
            "contents": calls,
            "target_language_code": target_language_code,
            "mime_type": "text/plain",
        },
        retry=Retry(),
    )
    # Convert the translated value to a list and return it
    return [translation.translated_text for translation in response.translations]

    Update <your location> dengan us-central1.

  3. Dalam daftar file, pilih requirements.txt, lalu tempel teks berikut:

    Flask==2.2.2
functions-framework==3.5.0
google-cloud-translate==3.11.1
Werkzeug==2.3.7

  4. Klik Deploy dan tunggu hingga fungsi di-deploy.

  5. Klik tab Trigger.

  6. Salin nilai URL Pemicu dan simpan untuk nanti. Anda harus menggunakan URL ini saat membuat fungsi jarak jauh BigQuery.

Membuat set data BigQuery

Buat set data BigQuery yang akan berisi fungsi jarak jauh. Saat Anda membuat set data, sertakan spesifikasi berikut:

  • Untuk ID Set Data, masukkan remote_function_test.
  • Untuk Jenis lokasi, pilih Multi-region.
  • Untuk Multi-region, pilih AS (beberapa region di Amerika Serikat).

Membuat koneksi dan akun layanan BigQuery

Buat koneksi BigQuery sehingga Anda dapat menerapkan fungsi jarak jauh dengan bahasa yang didukung di Cloud Functions dan Cloud Run. Saat Anda membuat koneksi, akun layanan dibuat untuk koneksi tersebut.

  1. Buat koneksi resource Google Cloud dengan spesifikasi berikut:

    • Untuk Jenis koneksi, pilih BigLake dan fungsi jarak jauh (Cloud Resource)
    • Untuk ID Koneksi, masukkan remote-function-connection.
    • Untuk Jenis lokasi, pilih Multi-region.
    • Untuk Multi-region, pilih AS (beberapa region di Amerika Serikat).

  2. Buka daftar Koneksi eksternal dan pilih us.remote-function-connection.

  3. Salin ID akun layanan dan simpan untuk nanti. Anda harus memberikan izin ke ID ini pada langkah berikutnya.

Memberikan izin ke akun layanan BigQuery

Akun layanan yang Anda buat di langkah sebelumnya memerlukan izin untuk menggunakan Cloud Run sehingga fungsi jarak jauh BigQuery dapat menggunakan fungsi Cloud Functions. Untuk memberikan izin ke akun layanan, selesaikan langkah-langkah berikut:

  1. Buka halaman Cloud Run.

    Buka Cloud Run

  2. Pilih project Anda.

  3. Centang kotak di samping translation-handler.

  4. Di panel Permissions, klik Add principal.

  5. Di kolom New principals, masukkan ID akun layanan yang Anda salin sebelumnya.

  6. Dalam daftar Assign roles, telusuri dan pilih Cloud Run Invoker.

  7. Klik Save.

Membuat fungsi jarak jauh BigQuery

Untuk menggunakan fungsi Cloud Functions yang menerjemahkan teks ke bahasa Spanyol dengan fungsi jarak jauh BigQuery, lakukan langkah-langkah berikut.

  1. Di konsol Google Cloud, buka halaman BigQuery.

    Buka BigQuery

  2. Di Query editor, tempel kueri berikut:

    CREATE OR REPLACE FUNCTION `remote_function_test.translate_text`(x STRING)
RETURNS
STRING
    REMOTE WITH CONNECTION `us.remote-function-connection`
OPTIONS (
    endpoint = 'TRIGGER_URL',
    max_batching_rows = 10);

    Ganti TRIGGER_URL dengan URL pemicu yang Anda simpan sebelumnya saat membuat fungsi Cloud Functions.

  3. Klik Run. Pesan yang mirip dengan pesan berikut ini akan ditampilkan:

    This statement created a new function named
your_project.remote_function_test.translate_text.

Memanggil fungsi jarak jauh BigQuery

Setelah membuat fungsi jarak jauh, uji fungsi tersebut untuk memastikan bahwa fungsi tersebut terhubung ke fungsi Cloud Functions dan memberikan hasil yang diharapkan dalam bahasa Spanyol.

  1. Di editor kueri BigQuery, masukkan kueri berikut, lalu klik Run.

    SELECT
  remote_function_test.translate_text('This new feature is fantastic!')
    AS translated_text;

    Hasilnya mirip dengan berikut ini:

    +-------------------------------------------+
| translated_text                           |
+-------------------------------------------+
| ¡Esta nueva característica es fantástica! |
+-------------------------------------------+

  2. Opsional: Untuk menguji fungsi jarak jauh pada set data publik, masukkan kueri berikut, lalu klik Run. Untuk membatasi hasil yang ditampilkan, gunakan klausa LIMIT.

    SELECT
    text,
    remote_function_test.translate_text(text) AS translated_text
FROM
    (SELECT text FROM `bigquery-public-data.hacker_news.full` LIMIT 3);

    Hasilnya mirip dengan berikut ini:

    +---------------------------------------------------------------------------+
| text                            | translated_text                         |
+---------------------------------------------------------------------------+
| These benchmarks look good.     | Estos puntos de referencia se ven bien. |
| Who is using Java?              | ¿Quién está usando Java?                |
| You need more database storage. | Necesitas más almacenamiento.           |
+---------------------------------------------------------------------------+

Menghapus resource

Jika tidak berencana menggunakan fungsi tersebut dalam project ini, Anda dapat menghindari biaya tambahan dengan menghapus project Anda. Tindakan ini akan menghapus semua resource yang terkait dengan project secara permanen.

  1. Di konsol Google Cloud, buka halaman Manage resource.

    Buka Manage resource

  2. Pada daftar project, pilih project yang ingin Anda hapus, lalu klik Delete.
  3. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.

Langkah berikutnya