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 akan menggunakan komponen Google Cloud yang dapat ditagih berikut:

• BigQuery
• Cloud Run functions
• Cloud Translation

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. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

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

   Enable the APIs

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

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

   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:

• BigQuery Data Owner (roles/bigquery.dataOwner)
• BigQuery Connection Admin (roles/bigquery.connectionAdmin)
• Cloud Functions Developer (roles/cloudfunctions.developer)

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 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:

   [e-mail]
   

   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

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

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

Catatan: Diperlukan waktu hingga satu menit sebelum izin baru berlaku.

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

Catatan: Untuk membatasi jumlah baris yang disertakan dalam permintaan HTTP, opsi max_batching_rows ditetapkan ke 10. Jika Anda tidak menentukan opsi max_batching_rows, BigQuery akan menentukan jumlah baris yang disertakan dalam permintaan HTTP.

Memanggil fungsi jarak jauh BigQuery

Setelah membuat fungsi jarak jauh, uji fungsi tersebut untuk memastikan bahwa fungsi tersebut terhubung ke fungsi Cloud Run 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 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.

Perhatian: Menghapus project memiliki efek berikut:

• Semua hal dalam project akan dihapus. Jika menggunakan project yang sudah ada untuk tugas dalam dokumen ini, saat Anda menghapusnya, pekerjaan lain yang telah Anda lakukan dalam project tersebut juga akan terhapus.
• Project ID kustom hilang. Saat membuat project ini, Anda mungkin telah membuat project ID kustom yang ingin digunakan di masa mendatang. Untuk mempertahankan URL yang menggunakan project ID, seperti URL appspot.com, hapus resource yang dipilih di dalam project, bukan menghapus seluruh project.

Jika Anda berencana mempelajari beberapa arsitektur, tutorial atau panduan memulai, dengan menggunakan kembali project dapat membantu Anda agar tidak melampaui batas kuota project.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Langkah berikutnya

• Pelajari cara menggunakan fungsi jarak jauh di BigQuery.
• Pelajari Translation.
• Pelajari fungsi Cloud Run.
• Pelajari Cloud Run.