מדריך בנושא פונקציות מרוחקות ו-Translation API

במדריך הזה מוסבר איך ליצור פונקציה מרוחקת של BigQuery, להפעיל את Cloud Translation API ולתרגם תוכן מכל שפה לספרדית באמצעות SQL ו-Python.

תרחישי שימוש בפונקציה הזו כוללים את הדוגמאות הבאות:

  • תרגום תגובות של משתמשים באתר לשפה מקומית
  • לתרגם בקשות תמיכה משפות רבות לשפה משותפת אחת עבור עובדי התמיכה

מטרות

  • מקצים לחשבון את התפקידים הנדרשים.
  • יוצרים פונקציה של Cloud Run Functions.
  • יוצרים מערך נתונים ב-BigQuery.
  • יוצרים חיבור ל-BigQuery וחשבון שירות.
  • מעניקים הרשאות לחשבון השירות ב-BigQuery.
  • יוצרים פונקציה מרוחקת ב-BigQuery.
  • קוראים לפונקציה המרוחקת של BigQuery.

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

כדי להעריך את ההוצאות בהתאם לתחזית השימוש שלכם, אתם יכולים להיעזר במחשבון העלויות.

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

לפני שמתחילים

מומלץ ליצור Google Cloud פרויקט לצורך המדריך הזה. בנוסף, חשוב לוודא שיש לכם את התפקידים הנדרשים כדי להשלים את המדריך הזה.

הגדרת Google Cloud פרויקט

כדי להגדיר Google Cloud פרויקט בשביל המדריך הזה, מבצעים את השלבים הבאים:

  1. נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud 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

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

    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

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud 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

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

    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

    8.

התפקידים הנדרשים בחשבון

כדי לקבל את ההרשאות שדרושות לביצוע המשימות במדריך הזה, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

התפקידים המוגדרים מראש האלה כ��ללים את ה��רשאות ש��דרשות לביצוע המשימות במדריך הזה. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:

ההרשאות הנדרשות

כדי לבצע את המשימות במדריך הזה, נדרשות ההרשאות הבאות:

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

יכול להיות שתקבלו את ההרשאות האלה באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.

תפקידים נדרשים לחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine

כשמפעילים את ה-API לפונקציות Cloud Run, נוצר חשבון שירות שמוגדר כברירת מחדל ב-Compute Engine. כדי להשלים את המדריך הזה, צריך לתת לחשבון השירות הזה שמוגדר כברירת מחדל את התפקיד Cloud Translation API User.

  1. איך מאתרים את המזהה שהוקצה לפרויקט

  2. מעתיקים את חשבון השירות שמוגדר כברירת מחדל ב-Compute Engine. חשבון השירות שמוגדר כברירת מחדל נראה כך:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    מחליפים את PROJECT_NUMBER במזהה הפרויקט.

  3. נכנסים לדף IAM במסוף Google Cloud .

    כניסה לדף IAM

  4. בוחרים את הפרויקט הרצוי.

  5. לוחצים על Grant access (מתן גישה), ובשדה New principals (מנהלים חדשים), מדביקים את חשבון השירות שמוגדר כברירת מחדל של Compute Engine שהעתקתם קודם.

  6. ברשימה Assign roles, מחפשים את התפקיד Cloud Translation API User ובוחרים אותו.

  7. לוחצים על Save.

יצירת פונקציה של Cloud Run Functions

באמצעות פונקציות Cloud Run, יוצרים פונקציה שמתרגמת טקסט קלט לספרדית.

  1. יוצרים פונקציה של Cloud Run Functions עם המפרטים הבאים:

    • ��שדה סביבה, בוחרים באפשרות דור שני.
    • בשדה Function name (שם הפונקציה), מזינים translation-handler.
    • בשדה Region, בוחרים us-central1.

    • בשדה מספר מופעים מקסימלי, מזינים 10.

      ההגדרה הזו נמצאת בקטע Runtime, build, connections and security settings (הגדרות של זמן ריצה, build, חיבורים ואבטחה).

      במדריך הזה אנחנו משתמשים בערך נמוך יותר מערך ברירת המחדל כדי לשלוט בקצב הבקשות שנשלחות לתרגום.

    • בקטע Runtime (זמן ריצה), בוחרים באפשרות Python 3.10.

    • בשדה Entry point (נקודת כניסה), מזינים handle_translation.

  2. ברשימת הקבצים, בוחרים באפשרות main.py ומדביקים את הקוד הבא.

    לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Python API.

    כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח. 

    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]

    עדכון של <your location> באמצעות us-central1.

  3. ברשימת הקבצים, בוחרים באפשרות requirements.txt ומדביקים את הטקסט הבא:

    Flask==3.1.3; python_version >= '3.9'
functions-framework==3.9.2
google-cloud-translate==3.18.0
Werkzeug==3.1.8; python_version >= '3.9'

  4. לוחצים על Deploy (פריסה) ומחכים שהפונקציה תיפרס.

  5. לוחצים על הכרטיסייה טריגר.

  6. מעתיקים את הערך של כתובת ה-URL של הטריגר ושומרים אותו לשימוש מאוחר יותר. צריך להשתמש בכתובת ה-URL הזו כשיוצרים פונקציה מרוחקת ב-BigQuery.

יצירת מערך נתונים ב-BigQuery

יוצרים מערך נתונים ב-BigQuery שיכיל את הפונקציה המרוחקת. כשיוצרים את קבוצת הנתונים, צריך לכלול את המפרטים הבאים:

  • בשדה Dataset ID (מזהה מערך הנתונים), מזינים remote_function_test.
  • בשדה Location type, בוחרים באפשרות Multi-region.
  • בקטע Multi-region, בוחרים באפשרות US (multiple regions in United States).

יצירת חיבור ל-BigQuery וחשבון שירות

יוצרים חיבור ל-BigQuery כדי להטמיע פונקציה מרוחקת בכל אחת מהשפות הנתמכות בפונקציות Cloud Run וב-Cloud Run. כשיוצרים חיבור, נוצר חשבון שירות עבור החיבור הזה.

  1. יוצרים Google Cloud חיבור למשאב עם המפרט הבא:

    • בשדה סוג החיבור, בוחרים באפשרות BigLake ופונקציות מרוחקות (משאב בענן).
    • בשדה מזהה החיבור, מזינים את הערך remote-function-connection.
    • בקטע Location type, בוחרים באפשרות Multi-region.
    • בקטע Multi-region, בוחרים באפשרות US (multiple regions in United States).

  2. פותחים את רשימת החיבורים ובוחרים באפשרות us.remote-function-connection.

  3. מעתיקים את המזהה של חשבון השירות ושומרים אותו לשימוש בהמשך. בשלב הבא, צריך להעניק הרשאות למזהה הזה.

מתן הרשאות לחשבון השירות ב-BigQuery

לחשבון השירות שיצרתם בשלב הקודם צריכה להיות הרשאה להשתמש ב-Cloud Run, כדי שהפונקציה המרוחקת של BigQuery תוכל להשתמש בפונקציה של Cloud Run Functions. כדי לתת הרשאות לחשבון השירות, מבצעים את השלבים הבאים:

  1. נכנסים לדף Cloud Run.

    כניסה ל-Cloud Run

  2. בוחרים את הפרויקט הרצוי.

  3. מסמנים את התיבה לצד translation-handler.

  4. בחלונית Permissions, לוחצים על Add principal.

  5. בשדה New principals, מזינים את מזהה חשבון השירות שהעתקתם קודם.

  6. ברשימה Assign roles, מחפשים את התפקיד Cloud Run Invoker ובוחרים אותו.

  7. לוחצים על Save.

יצירת פונקציה מרוחקת ב-BigQuery

כדי להשתמש בפונקציה של Cloud Run Functions שמתרגמת טקסט לספרדית באמצעות פונקציה מרוחקת של BigQuery, מבצעים את השלבים הבאים.

  1. במסוף Google Cloud , עוברים לדף BigQuery.

    כניסה ל-BigQuery

  2. מזינים את השאילתה הבאה בעורך השאילתות:

    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);

    מחליפים את TRIGGER_URL בכתובת ה-URL של הטריגר ששמ��תם קודם כשייצרתם פונקציה של Cloud Run Functions.

  3. לוחצים על Run. מוצגת הודעה דומה לזו שבהמשך:

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

קריאה לפונקציה מרוחקת של BigQuery

אחרי שיוצרים את הפונקציה המרוחקת, בודקים אותה כדי לוודא שהיא מקושרת לפונקציה של פונקציות Cloud Run ומפיקה את התוצאות הרצויות בספרדית.

  1. בעורך השאילתות של BigQuery, מזינים את השאילתה הבאה ולוחצים על הפעלה.

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

    התוצאות אמורות להיראות כך:

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

  2. אופציונלי: כדי לבדוק את הפונקציה המרוחקת במערך נתונים ציבורי, מזינים את השאילתה הבאה ולוחצים על הפעלה. כדי להגביל את התוצאות שמוחזרות, משתמשים בסעיף LIMIT.

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

    התוצאות אמורות להיראות כך:

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

מחיקת המשאבים

אם אתם לא מתכננים להשתמש בפונקציות האלה בפרויקט הזה, אתם יכולים למחוק את הפרויקט כדי להימנע מעלויות נוספות. כל המשאבים שמשויכים לפרויקט יימחקו באופן סופי.

  1. במסוף Google Cloud , נכנסים לדף Manage resources.

    כניסה לדף Manage resources

  2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
  3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

המאמרים הבאים