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.
  • Buat fungsi Cloud Run 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 akan menggunakan komponen Cloud de Confiance by S3NSyang dapat ditagih berikut:

Sebelum memulai

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

Menyiapkan project Cloud de Confiance

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

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

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

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

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 di project Anda:

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

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

Peran yang diperlukan untuk akun layanan default Compute Engine

Saat Anda mengaktifkan API untuk Cloud Run 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.s3ns-system.iam.gserviceaccount.com

    Ganti PROJECT_NUMBER dengan project ID Anda.

  3. Di konsol Cloud de Confiance , 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 Simpan.

Membuat fungsi Cloud Run Functions

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

  1. Buat fungsi Cloud Run 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.

    Sebelum menjalankan contoh kode, tetapkan variabel lingkungan GOOGLE_CLOUD_UNIVERSE_DOMAIN ke s3nsapis.fr. 

    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.9.2
google-cloud-translate==3.18.0
Werkzeug==2.3.8

  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 US (multiple regions in United States).

Membuat koneksi dan akun layanan BigQuery

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

  1. Buat Cloud de Confiance koneksi resource 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 US (multiple regions in United States).

  2. Buka daftar Koneksi 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 Run. 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 Run Functions yang menerjemahkan teks ke bahasa Spanyol dengan fungsi jarak jauh BigQuery, lakukan langkah-langkah berikut.

  1. Di konsol Cloud de Confiance , 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 Run 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 Run 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 akan 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 akan 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 Cloud de Confiance , buka halaman Manage resources.

    Buka Kelola 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