פריסת "Google Translate" אפליקציה ב-Python 3 Cloud Functions

1. סקירה כללית

סדרת ה-codelabs הזו (מדריכים מעשיים וברמה עצמאית) נועדה לעזור למפתחים להבין את האפשרויות השונות שעומדות לרשותם בפריסה של האפליקציות שלהם. ב-codelab הזה תלמדו איך להשתמש ב-Google Cloud Translation API עם Python ולהריץ אותו באופן מקומי או לפרוס אותו בפלטפורמת מחשוב ללא שרת ב-Cloud (App Engine,‏ Cloud Functions או Cloud Run). אפשר לפרוס את האפליקציה לדוגמה שנמצאת במאגר של המדריך הזה (לפחות) בשמונה דרכים שונות, עם שינויים קלים בלבד בהגדרות:

  1. שרת Flask מקומי (Python 2)
  2. שרת Flask מקומי (Python 3)
  3. App Engine‏ (Python 2)
  4. App Engine‏ (Python 3)
  5. Cloud Functions‏ (Python 3)
  6. Cloud Run (Python 2 דרך Docker)
  7. Cloud Run (Python 3 דרך Docker)
  8. Cloud Run (Python 3 דרך Cloud Buildpacks)

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

כאן מוסבר איך

מה צריך להכין

  • פרויקט ב-Google Cloud עם חשבון פעיל לחיוב ב-Cloud
  • Flask מותקן להרצה מקומית, או פלטפורמת מחשוב ללא שרת ב-Cloud שמופעלת לפריסות מבוססות-ענן
  • מיומנויות בסיסיות ב-Python
  • ידע מעשי בפקודות בסיסיות של מערכת ההפעלה

סקר

איך תוכלו להשתמש במדריך הזה?

לקרוא אותו ולבצע את התרגילים לקרוא אותו בלבד

איזה דירוג מגיע לדעתך לחוויה שלך עם Python?

מתחילים בינוניים מומחים

מהו הדירוג שלך לגבי חוויית השימוש בשירותי Google Cloud?

מתחילים בינוניים מומחים

2. הגדרה ודרישות

הגדרת סביבה בקצב אישי

  1. נכנסים למסוף Google Cloud ויוצרים פרויקט חדש או משתמשים מחדש בפרויקט קיים. אם עדיין אין לכם חשבון Gmail או חשבון Google Workspace, עליכם ליצור חשבון.

96a9c957bc475304.png

b9a10ebdf5b5a448.png

a1e3c01a38fa61c2.png

  • שם הפרויקט הוא השם המוצג של המשתתפים בפרויקט. זוהי מחרוזת תווים שלא משמשת את Google APIs, ואפשר לעדכן אותה בכל שלב.
  • מזהה הפרויקט צריך להיות ייחודי בכל הפרויקטים ב-Google Cloud, ואי אפשר לשנות אותו אחרי שמגדירים אותו. מסוף Cloud יוצר מחרוזת ייחודית באופן אוטומטי. בדרך כלל לא משנה מה המחרוזת הזו. ברוב סדנאות ה-Codelab, תצטרכו להפנות למזהה הפרויקט (בדרך כלל הוא מזוהה בתור PROJECT_ID). אם המזהה לא מוצא חן בעיניכם, תוכלו ליצור מזהה אקראי אחר או לנסות ליצור מזהה משלכם ולבדוק אם הוא זמין. לאחר מכן, הוא 'מקפיא' אחרי יצירת הפרויקט.
  • יש ערך שלישי, מספר פרויקט, שמשתמשים בו בממשקי API מסוימים. מידע נוסף על כל שלושת הערכים האלה זמין במסמכי העזרה.
  1. בשלב הבא, תצטרכו להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבים או ב-API של Cloud. השלמת הקודלאב הזה לא אמורה לעלות הרבה, אם בכלל. כדי להשבית את המשאבים כדי שלא תחויבו אחרי סיום המדריך, פועלים לפי ההוראות ל'ניקוי' שמופיעות בסוף הקודלאב. משתמשים חדשים ב-Google Cloud זכאים להשתתף בתוכנית תקופת ניסיון בחינם בסך 300$.

3. הפעלת Translation API

בקטע הזה נסביר איך מפעילים את Google APIs באופן כללי. באפליקציית הדוגמה שלנו, מפעילים את Cloud Translation API ואת השירות Cloud Functions.

מבוא

לא משנה באיזה ממשק Google API אתם רוצים להשתמש באפליקציה, צריך להפעיל אותו. בדוגמה הבאה מוצגות שתי דרכים להפעלת Cloud Vision API. אחרי שתראו איך מפעילים ממשק Cloud API אחד, תוכלו להפעיל ממשקי API אחרים כי התהליך דומה.

אפשרות 1: מ-Cloud Shell או מממשק שורת הפקודה

הפעלת ממשקי API מ-Cloud Console היא דרך נפוצה, אבל חלק מהמפתחים מעדיפים לעשות הכל דרך שורת הפקודה. כדי לעשות זאת, צריך לחפש את 'שם השירות' של ה-API. היא נראית כמו כתובת URL: SERVICE_NAME.googleapis.com. אפשר למצוא אותם בטבלה של המוצרים הנתמכים, או לשלוח שאילתות פרוגרמטיות לגביהם באמצעות Google Discovery API.

בעזרת המידע הזה, אפשר להשתמש ב-Cloud Shell (או בסביבת הפיתוח המקומית עם כלי שורת הפקודה gcloud) כדי להפעיל ממשק API באופן הבא:

gcloud services enable SERVICE_NAME.googleapis.com

לדוגמה, הפקודה הבאה מפעילה את Cloud Vision API:

gcloud services enable vision.googleapis.com

הפקודה הזו מפעילה את App Engine:

gcloud services enable appengine.googleapis.com

אפשר גם להפעיל כמה ממשקי API בבקשה אחת. לדוגמה, שורת הפקודה הזו מפעילה את Cloud Run,‏ Cloud Artifact Registry ו-Cloud Translation API:

gcloud services enable artifactregistry.googleapis.com run.googleapis.com translate.googleapis.com

אפשרות 2: דרך מסוף Cloud

אפשר גם להפעיל את Vision API במנהל ה-API. במסוף Cloud, עוברים אל API Manager ובוחרים באפשרות Library.

fb0f1d315f122d4a.png

אם רוצים להפעיל את Cloud Vision API, מתחילים להזין 'vision' בסרגל החיפוש, וכל מה שתזינו עד עכשיו יופיע:

2275786a24f8f204.png

בוחרים את ה-API שרוצים להפעיל ולוחצים על Enable:

2556f923b628e31.png

עלות

אפשר להשתמש בממשקי Google API רבים ללא תשלום, אבל השימוש במוצרים ובממשקי ה-API של Google Cloud לא בחינם. כשמפעילים את Cloud APIs, יכול להיות שתתבקשו להזין חשבון פעיל לחיוב. עם זאת, חשוב לציין שלמוצרים מסוימים ב-Google Cloud יש תוכנית 'תמיד בחינם' (יומית או חודשית), שצריך לחרוג ממנה כדי שנחייב אתכם. אחרת, כרטיס האשראי (או אמצעי החיוב שציינתם) לא יחויב.

לפני שמפעילים ממשק API, חשוב לעיין במידע על התמחור שלו, במיוחד כדי לבדוק אם יש לו שכבה ללא תשלום, ואם כן, מה היא. אם מפעילים את Cloud Vision API, צריך לעיין בדף מידע על התמחור שלו. ל-Cloud Vision יש מכסה בחינם, וכל עוד לא חורגים מהמגבלות הכוללות (בכל חודש), לא אמורים להיות חיובים.

התמחור והרמות החינמיות משתנים בין ממשקי Google API. דוגמאות:

יש הבדלים בחיוב של מוצרים שונים של Google, לכן חשוב לעיין במסמכי התיעוד של ה-API כדי לקבל מידע נוסף.

סיכום

עכשיו, אחרי שלמדת איך להפעיל ממשקי Google API באופן כללי, עליך לעבור אל מנהל ה-API ולהפעיל גם את Cloud Translation API וגם את השירות Cloud Functions (אם עדיין לא עשית זאת). צריך להפעיל את Cloud Functions כי האפליקציה שלנו תשתמש בו, וצריך להפעיל את Cloud Translation API כי אתם פורסים Cloud Function. אם אתם מעדיפים לעשות זאת משורת הפקודה, אפשר להשתמש בפקודה הבאה במקום זאת:

gcloud services enable cloudfunctions.googleapis.com translate.googleapis.com

המכסה החודשית לא מופיעה בדף הסיכום הכללי של רמת Always Free, אבל בדף התמחור של Translation API מצוין שכל המשתמשים מקבלים כמות קבועה של תווים מתורגמים מדי חודש. אם תשתמשו ב-API בלי לחרוג מהסף הזה, לא תחויבו. אם יש חיובים אחרים שקשורים ל-Google Cloud, הם ידונו בסוף המאמר בקטע 'ניקוי'.

4. קבלת הקוד של האפליקציה לדוגמה

משכפלים את הקוד במאגר באופן מקומי או ב-Cloud Shell (באמצעות הפקודה git clone), או מורידים את קובץ ה-ZIP מהלחצן הירוק Code (קוד) כפי שמוצג בצילום המסך הבא:

5cd6110c4414cf65.png

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

5. סיור באפליקציה לדוגמה

האפליקציה לדוגמה היא נגזרת פשוטה של Google Translate שמבקשת מהמשתמשים להזין טקסט באנגלית ולקבל את התרגום המקביל של הטקסט הזה בספרדית. עכשיו פותחים את הקובץ main.py כדי שנוכל לראות איך הוא עובד. אם משמיטים את השורות עם ההערות לגבי הרישוי, הקטע נראה כך בחלק העליון ובחלק התחתון:

from flask import Flask, render_template, request
import google.auth
from google.cloud import translate

app = Flask(__name__)
_, PROJECT_ID = google.auth.default()
TRANSLATE = translate.TranslationServiceClient()
PARENT = 'projects/{}'.format(PROJECT_ID)
SOURCE, TARGET = ('en', 'English'), ('es', 'Spanish')

# . . . [translate() function definition] . . .

if __name__ == '__main__':
    import os
    app.run(debug=True, threaded=True, host='0.0.0.0',
            port=int(os.environ.get('PORT', 8080)))
  1. היבוא כולל את הפונקציונליות של Flask, את המודול google.auth ואת ספריית הלקוח של Cloud Translation API.
  2. המשתנים הגלובליים מייצגים את אפליקציית Flask, את מזהה הפרויקט ב-Cloud, את הלקוח של Translation API, את 'נתיב המיקום' של ההורה לקריאות ל-Translation API ואת שפות המקור והיעד. במקרה הזה, אלה אנגלית (en) וספרדית (es), אבל אתם יכולים לשנות את הערכים האלה לקודי שפות אחרים שתומכים ב-Cloud Translation API.
  3. הבלוק הגדול if בתחתית המסך משמש במדריך להפעלת האפליקציה באופן מקומי – הוא משתמש בשרת הפיתוח של Flask כדי להציג את האפליקציה. הקטע הזה מופיע גם במדריכים לפריסה ב-Cloud Run, למקרה ששרת האינטרנט לא נכלל בחבילה של הקונטיינר. תתבקשו להפעיל את הקיפול של השרת בקונטיינר, אבל אם תתעלמו מכך, קוד האפליקציה יחזור להשתמש בשרת הפיתוח של Flask. (זו לא בעיה ב-App Engine או ב-Cloud Functions כי אלה פלטפורמות שמבוססות על מקורות, כלומר Google Cloud מספק ומפעיל שרת אינטרנט שמוגדר כברירת מחדל).

לבסוף, באמצע main.py נמצא ליבה של האפליקציה, הפונקציה translate():

@app.route('/', methods=['GET', 'POST'])
def translate(gcf_request=None):
    """
    main handler - show form and possibly previous translation
    """

    # Flask Request object passed in for Cloud Functions
    # (use gcf_request for GCF but flask.request otherwise)
    local_request = gcf_request if gcf_request else request

    # reset all variables (GET)
    text = translated = None

    # if there is data to process (POST)
    if local_request.method == 'POST':
        text = local_request.form['text']
        data = {
            'contents': [text],
            'parent': PARENT,
            'target_language_code': TARGET[0],
        }
        # handle older call for backwards-compatibility
        try:
            rsp = TRANSLATE.translate_text(request=data)
        except TypeError:
            rsp = TRANSLATE.translate_text(**data)
        translated = rsp.translations[0].translated_text

    # create context & render template
    context = {
        'orig':  {'text': text, 'lc': SOURCE},
        'trans': {'text': translated, 'lc': TARGET},
    }
    return render_template('index.html', **context)

הפונקציה הראשית מקבלת את הקלט מהמשתמש ומפעילה את Translation API כדי לבצע את העבודה הקשה. בואו נסביר:

  1. בודקים אם הבקשות מגיעות מ-Cloud Functions באמצעות המשתנה local_request. Cloud Functions שולח אובייקט בקשה של Flask משלו, ואילו כל שאר הפלטפורמות (שפועלות באופן מקומי או שנפרסות ב-App Engine או ב-Cloud Run) יקבלו את אובייקט הבקשה ישירות מ-Flask.
  2. איפוס המשתנים הבסיסיים של הטופס. האפשרות הזו מיועדת בעיקר לבקשות GET, כי לבקשות POST יהיו נתונים שיחליפו את הפרמטרים האלה.
  3. אם מדובר בבקשת POST, צריך לבחור את הטקסט לתרגום וליצור מבנה JSON שמייצג את דרישת המטא-נתונים של ה-API. לאחר מכן, קוראים ל-API ומעבירים אותו לגרסה קודמת של ה-API אם המשתמש משתמש בספרייה ישנה יותר.
  4. בכל מקרה, צריך לעצב את התוצאות בפועל (POST) או ללא נתונים (GET) בהקשר התבנית ולבצע עיבוד.

החלק החזותי של האפליקציה נמצא בקובץ התבנית index.html. מוצגות בו תוצאות שכבר תורגמו (אם לא, הוא יהיה ריק), ואחריו הטופס שבו מבקשים לכתוב משהו לתרגום:

<!doctype html>
<html><head><title>My Google Translate 1990s</title><body>
<h2>My Google Translate (1990s edition)</h2>

{% if trans['text'] %}
    <h4>Previous translation</h4>
    <li><b>Original</b>:   {{ orig['text'] }}  (<i>{{ orig['lc'][0] }}</i>)</li>
    <li><b>Translated</b>: {{ trans['text'] }} (<i>{{ trans['lc'][0] }}</i>)</li>
{% endif %}

<h4>Enter <i>{{ orig['lc'][1] }}</i> text to translate to <i>{{ trans['lc'][1] }}</i>:</h4>
<form method="POST"><input name="text"><input type="submit"></form>
</body></html>

6. פריסת השירות

כדי לפרוס את שירות התרגום ב-Cloud Functions (Python 3), מריצים את הפקודה הבאה:

gcloud functions deploy translate --runtime python37 --trigger-http --allow-unauthenticated

הפלט אמור להיראות כך, ולכלול הנחיות לשלבים הבאים:

$ gcloud functions deploy translate --runtime python37 --trigger-http --allow-unauthenticated
Deploying function (may take a while - up to 2 minutes)...⠹
For Cloud Build Stackdriver Logs, visit: https://console.cloud.google.com/logs/viewer?project=PROJECT_ID&advancedFilter=resource.type%3Dbuild%0Aresource.labels.build_id%3D7e32429d-ec36-422c-8a8b-43c4d661a15c%0AlogName%3Dprojects%2FPROJECT_ID%2Flogs%2Fcloudbuild
Deploying function (may take a while - up to 2 minutes)...done.
availableMemoryMb: 256
buildId: 7e32429d-ec36-422c-8a8b-43c4d661a15
entryPoint: translate
httpsTrigger:
  securityLevel: SECURE_OPTIONAL
  url: https://REGION-PROJECT_ID.cloudfunctions.net/translate
ingressSettings: ALLOW_ALL
labels:
  deployment-tool: cli-gcloud
name: projects/PROJECT_ID/locations/REGION/functions/translate
runtime: python37
serviceAccountEmail: PROJECT_ID@appspot.gserviceaccount.com
sourceUploadUrl: https://storage.googleapis.com/gcf-upload-REGION-873f8448-838f-4eb2-beda-3e200a1420d/cb1cbdca-34eb-41d0-88d6-c276d5205fb.zip?GoogleAccessId=service-104690130103@gcf-admin-robot.iam.gserviceaccount.com&Expires=1619139674
status: ACTIVE
timeout: 60s
updateTime: '2021-04-23T00:32:58.065Z'
versionId: '3'

עכשיו, כשהאפליקציה זמינה ברחבי העולם, אמורה להיות לכם אפשרות לגשת אליה בכתובת ה-URL שמכילה את מזהה הפרויקט, כפי שמוצג בפלט הפריסה. כתובת ה-URL אמורה להיראות כך: https://REGION-PROJECT_ID.cloudfunctions.net/translate, והיא משתנה בהתאם לאזור שבחרתם ולמזהה הפרויקט ב-Cloud.

518f1c3165f2096d.png

מתרגמים משהו כדי לראות איך זה עובד.

539b52bd25377888.png

7. סיכום

מעולה! למדתם איך להפעיל את Cloud Translation API, לקבל את פרטי הכניסה הנדרשים ולפרוס אפליקציית אינטרנט פשוטה ב-Cloud Functions. מידע נוסף על הפריסה הזו זמין בטבלה הזו במאגר.

הסרת המשאבים

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

עם זאת, אם אתם עדיין לא מוכנים להמשיך למדריך הבא או שאתם חוששים שהאינטרנט יגלה את האפליקציה שפרסמתם, השביתו את האפליקציה ב-App Engine, מחקו את Cloud Function או השביתו את שירות Cloud Run כדי להימנע מחיובים. כשתהיו מוכנים לעבור לסדנת הקוד הבאה, תוכלו להפעיל אותו מחדש. לעומת זאת, אם אתם לא מתכוונים להמשיך עם האפליקציה הזו או עם Codelabs אחרים ואתם רוצים למחוק את הכל לגמרי, אתם יכולים לסגור את הפרויקט.

בנוסף, פריסה בפלטפורמת מחשוב ללא שרת (serverless) ב-Google Cloud כרוכה בעלות קטנה על פיתוח ואחסון. ל-Cloud Build יש מכסה בחינם משלו, כמו גם ל-Cloud Storage. כדי לשפר את השקיפות, Cloud Build יוצר את קובץ האימג' של האפליקציה, שמאוחסן לאחר מכן ב-Cloud Container Registry או ב-Artifact Registry, הממשיך שלו. אחסון התמונה הזו צורך חלק מהמכסה הזו, וכך גם תעבורת הנתונים היוצאת (egress) ברשת במהלך העברת התמונה לשירות. עם זאת, יכול להיות שאתם גרים באזור שבו אין שכבה חינמית כזו, לכן חשוב לשים לב לשימוש שלכם בנפח האחסון כדי למזער את העלויות האפשריות.

8. מקורות מידע נוספים

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

מחקר נוסף

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

  1. מומלץ להשלים את כל המהדורות האחרות של codelab הזה כדי להריץ את הקוד באופן מקומי או לפרוס אותו בפלטפורמות מחשוב ללא שרת של Google Cloud (ראו README של המאגר).
  2. איך משלימים את המדריך הזה בשפת תכנות אחרת.
  3. לשנות את האפליקציה הזו כך שתתמוך בשפות מקור או יעד שונות.
  4. שדרוג האפליקציה הזו כדי שתוכלו לתרגם טקסט ליותר משפה אחת. שינוי קובץ התבנית כך שיכלול תפריט נפתח של שפות היעד הנתמכות.

מידע נוסף

Google App Engine

Google Cloud Functions

Google Cloud Run

Google Cloud Buildpacks, ‏ Container Registry, ‏ Artifact Registry

Google Cloud Translation ו-Google ML Kit

מוצרים או דפים אחרים של Google Cloud

Python ו-Flask

רישיון

המדריך הזה זמין ברישיון Creative Commons Attribution 2.0 Generic, ואילו קוד המקור במאגר זמין ברישיון Apache 2.