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

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

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

כאן מוסבר איך

מה צריך להכין

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

סקר

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

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

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

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

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

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

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

הגדרת סביבה בקצב עצמאי

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

96a9c957bc475304.png

b9a10ebdf5b5a448.png

a1e3c01a38fa61c2.png

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

3. הפעלת Translation API

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

מבוא

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

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

אומנם התהליך של הפעלת ממשקי API ממסוף Cloud הוא נפוץ יותר, אבל יש מפתחים שמעדיפים לעשות הכול משורת הפקודה. לשם כך, צריך לחפש את 'שם השירות' של 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 ללא עמלות, צריך להשתמש במוצרי Google Cloud ממשקי API לא זמינים בחינם. כשמפעילים את Cloud APIs, יכול להיות שתתבקשו ליצור חשבון פעיל לחיוב. עם זאת, חשוב לציין שבחלק ממוצרי Google Cloud יש תכונת "חינם תמיד" tier (יומי/חודשי), שעליך לחרוג ממנו כדי לצבור חיובים בגין חיוב; אחרת, לא נחייב את כרטיס האשראי שלך (או את אמצעי החיוב שצוין).

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

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

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

סיכום

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

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

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

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

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

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, את 'נתיב המיקום' ההורה עבור קריאות ל-Translate 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 שולח ב-אובייקט Falask Request משלו, וכל שאר האובייקטים (שפועלים באופן מקומי או נפרסים ב-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. במקרה של חריגה מהתנאים האלה, תצברו חיובים. אם אתם מתכננים להמשיך ל-Codelab הבא, אין צורך להשבית את האפליקציה.

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

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

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

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

מחקר נוסף

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

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

מידע נוסף

Google App Engine

פונקציות Google Cloud

Google Cloud Run

Google Cloud Buildpacks, Container Registry, Artifact Registry

תרגום של Google Cloud וערכת למידת מכונה של Google

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

Python ו-Flask

רישיון

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