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 Run.
  • 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. Aktifkan API BigQuery, BigQuery Connection, Cloud Translation, Cloud Run functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin.

    Mengaktifkan API

  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. Aktifkan API BigQuery, BigQuery Connection, Cloud Translation, Cloud Run functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin.

    Mengaktifkan API

Peran yang diperlukan untuk akun Anda

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

Untuk mengetahui informasi selengkapnya tentang cara memberikan 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, luaskan 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 fungsi Cloud Run, Akun layanan default Compute Engine 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@
    

    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 Simpan.

Membuat fungsi Cloud Run

Menggunakan fungsi Cloud Run, buat fungsi yang menerjemahkan teks input menjadi 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 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.16.0
    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 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 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 US (multiple regions in United States).
  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 agar 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 yang menerjemahkan teks ke dalam bahasa Spanyol dengan fungsi jarak jauh BigQuery, selesaikan 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 Run.

  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 fungsi terhubung 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 mirip dengan yang 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 yang 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