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

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

סדרת ה-codelabs הזו (הדרכות מעשיות בקצב אישי) נועדה לעזור למפתחים להבין את האפשרויות השונות שיש להם כשמפיצים את האפליקציות שלהם. ב-codelab הזה תלמדו איך להשתמש ב-Google Cloud Translation API עם Python, ולהפעיל אותו באופן מקומי או לפרוס אותו בפלטפורמת מחשוב ללא שרת (serverless) ב-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)

ה-Codelab הזה מתמקד בפריסת האפליקציה בפלטפורמות המובלטות שלמעלה.

מה תלמדו

מה תצטרכו

  • פרויקט בענן עם חשבון לחיוב ב-Cloud
  • ‫Flask מותקן להרצה מקומית, או פלטפורמת מחשוב ללא שרת בענן שמופעלת לפריסות מבוססות-ענן
  • מיומנויות בסיסיות ב-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 כדי להשתמש במשאבי Cloud או בממשקי API. העלות של התרגול הזה לא אמורה להיות גבוהה, ואולי אפילו לא תצטרכו לשלם בכלל. כדי לכבות את המשאבים ולא לחייב אתכם מעבר למה שמוסבר במדריך הזה, צריך לפעול לפי ההוראות לניקוי שמופיעות בסוף ה-Codelab. משתמשים חדשים ב-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.

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

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 Console

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

fb0f1d315f122d4a.png

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

2275786a24f8f204.png

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

2556f923b628e31.png

עלות

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

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

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

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

סיכום

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

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

למרות שהמכסה החודשית שלו לא מופיעה בדף הסיכום של התוכנית הכוללת 'תמיד בחינם', בדף התמחור של 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, את מזהה פרויקט בענן, את הלקוח של 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. היא משתנה בהתאם לאזור שבחרתם ולמזהה פרויקט בענן.

518f1c3165f2096d.png

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

539b52bd25377888.png

7. סיכום

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

הסרת המשאבים

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

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

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

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

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

מחקר נוסף

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

  1. כדי להריץ באופן מקומי או לפרוס בפלטפורמות מחשוב ללא שרת של Google Cloud, צריך להשלים את כל המהדורות האחרות של ה-codelab הזה (ראו repo 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 שמותנה בייחוס 2.0 Generic, בעוד שקוד המקור במאגר מורשה לשימוש במסגרת Apache 2.