פריסת "Google Translate" אפליקציית Express.js ב-App Engine, Cloud Functions ו-Cloud Run

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

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

במדריך הזה ל-JavaScript תשתמשו ב-Node.js באמצעות ה-framework של Express.js. בנוסף, תלמדו איך לגשת אל ממשקי ה-API של Google Cloud מהפלטפורמות שלנו בלי שרת (serverless). כל הגרסאות של האפליקציה הזו מגיעות ממאגר הקוד הפתוח nebulous serverless, שכולל גרסת Python של האפליקציה הזו וסדנאות קוד עצמאיות. במאגר יש גם אפליקציות דומות שמראות למפתחים איך לגשת לממשקי Google API שלא מבוססים על Cloud מהפלטפורמות שלנו בלי שרתים.

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

מה תלמדו

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

מה תצטרכו

פרויקט בענן עם חשבון לחיוב ב-Cloud
מסגרת אינטרנט שמותקנת להפעלה מקומית ( Flask למי שמבצע את המדריך ל-Python או Express למי שמבצע את המדריך ל-JavaScript/Node.js)
לפחות פלטפורמת מחשוב ללא שרתים אחת שמופעלת לפריסות ב-Google Cloud
מיומנויות תכנות בסיסיות (Python או JavaScript/Node.js)
ידע מעשי בפקודות בסיסיות של מערכת ההפעלה

סקר

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

לקרוא ולענות על התרגילים

לקרוא בלבד

איך היית מדרג את חוויית הפיתוח שלך ב-Python או ב-Node.js?

מתחילים

ביניים

מומחים

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

מתחילים

ביניים

מומחים

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

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

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

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

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

‫3. הפעלת Translation API

בקטע הזה מוסבר איך להפעיל Google APIs באופן כללי. באפליקציה לדוגמה שלנו, תפעילו את Cloud Translation API. תצטרכו גם להפעיל את App Engine,‏ Cloud Functions ו/או Cloud Run (בנוסף ל-Cloud Artifact Registry), בהתאם לפלטפורמות שבהן אתם רוצים לפרוס את אפליקציית הדוגמה.

הפעלת Google APIs

מבוא

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

אפשרות 1: `gcloud` ממשק שורת פקודה (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

דוגמה 1: הפעלת Cloud Vision API

gcloud services enable vision.googleapis.com

דוגמה 2: הפעלת Google App Engine

gcloud services enable appengine.googleapis.com

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

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

הפקודה הזו מפעילה את App Engine,‏ Cloud Functions,‏ Cloud Run ו-Cloud Translation API. בנוסף, הוא מאפשר את Cloud Artifact Registry, כי שם מערכת Cloud Build צריכה לרשום קובצי אימג' של קונטיינרים כדי לפרוס אותם ב-Cloud Run.

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

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

מתחילים להזין את השם של ה-API בסרגל החיפוש כדי לראות את התוצאות התואמות:

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

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

עלות

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

משתמשים חדשים ב-GCP זכאים לתקופת ניסיון בחינם, שכוללת כרגע קרדיט בסך 300 $לשימוש ב-90 הימים הראשונים. בדרך כלל לא נדרש תשלום על Codelabs, או שהתשלום נמוך מאוד, ולכן מומלץ לחכות עם תקופת הניסיון בחינם עד שתהיו מוכנים באמת לנסות אותה, במיוחד כי מדובר בהצעה חד-פעמית. המכסות של התוכנית בחינם לא פוקעות והן חלות גם אם משתמשים בתקופת הניסיון בחינם וגם אם לא.

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

‫Google Cloud/GCP – כל מוצר מחויב באופן שונה, ובדרך כלל לפי שימוש. מידע על תוכנית בחינם מופיע למעלה.
‫מפות Google – כולל חבילה של ממשקי API ומציע למשתמשים זיכוי חודשי בסך 200$‎.
‫Google Workspace (לשעבר G Suite) APIs – מספק נתוני שימוש (עד למגבלות מסוימות) שמכוסים על ידי דמי המינוי החודשיים ל-Workspace, כך שאין חיוב ישיר על שימוש בממשקי API לאפליקציות כמו Gmail,‏ Google Drive,‏ יומן Google,‏ Docs,‏ Sheets או Slides.

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

מוודאים שהשירותים הרצויים מופעלים

מוודאים ש-Cloud Translation API מופעל ב-API Manager, כמו שמתואר למעלה. אם לא הפעלתם את הפלטפורמות בלי שרתים משורת הפקודה, תוכלו לעשות זאת ממרכזי הבקרה המתאימים ב-מסוף Cloud: ‏ App Engine,‏ Cloud Functions ו-Cloud Run.

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

$ gcloud services enable appengine.googleapis.com \
cloudfunctions.googleapis.com artifactregistry.googleapis.com \
run.googleapis.com translate.googleapis.com
Operation "operations/acf.p2-xxxxxx035451-704918f2-5470-4436-9bdd-c3b204yyyyyy" finished successfully.

מידע נוסף על עלויות

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

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

הורדת קובץ ZIP או שיבוט של מאגר

מורידים את קובץ ה-ZIP או משכפלים את המאגר באמצעות git clone https://github.com/googlecodelabs/cloud-nebulous-serverless.git
אם אין לכם סביבת פיתוח מקומית ואתם רוצים לבצע את ההדרכה הזו ב-Cloud Shell, אתם יכולים לשכפל את המאגר באמצעות אותה פקודה git clone.
אפשר גם לגשת לקובץ ה-ZIP באמצעות הלחצן הירוק Code, כמו שמוצג בצילום המסך הבא:

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

5. אישור סביבת Node.js

כדי להגדיר את סביבת Node.js, צריך לבצע את הפעולות הבאות:

מוודאים שמותקנות הגרסאות העדכניות של Node ‏(‎>=10) ו-NPM ‏(‎>=6)
עוברים למיקום שבו שיבטתם את המאגר (או ביטלתם את הדחיסה של קובץ ה-ZIP) ואז עוברים לתיקייה cloud/nodejs.
מוודאים שהערך package.json מופיע ואז מריצים את הפקודה npm install

במקרה של #1 למעלה, אפשר לבדוק אילו גרסאות יש לכם בשורת הפקודה:

$ node -v
v17.0.1
$ npm -v
8.1.0

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

אפליקציית הדוגמה היא נגזרת פשוטה של Google Translate, שמבקשת מהמשתמשים להזין טקסט באנגלית ומקבלת את התרגום המקביל של הטקסט הזה בספרדית.

קובץ התצורה package.json מציין אילו חבילות של צד שלישי נדרשות לאפליקציה (שימו לב: יכול להיות שגרסאות החבילות יעודכנו מעבר למה שמופיע כאן):

{
  "name": "cloud-nebulous-serverless-nodejs",
  "version": "0.0.1",
  "description": "Nebulous Serverless sample app",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "mocha test/test_neb.js"
  },
  "author": "Google LLC",
  "license": "Apache-2.0",
  "dependencies": {
    "@google-cloud/translate": "^6.3.1",
    "express": "^4.17.1",
    "nunjucks": "^3.2.3"
  },
  "devDependencies": {
    "mocha": "^9.1.3",
    "supertest": "^6.1.6"
  }
}

עכשיו נפתח את הקובץ index.js כדי לראות איך הוא עובד. אם משמיטים את השורות עם ההערות לגבי הרישיון, הקוד נראה כך בחלק העליון והתחתון:

const express = require('express');
const nunjucks = require('nunjucks');
const {TranslationServiceClient} = require('@google-cloud/translate');

const app = express();
app.use(express.urlencoded({extended: true}));
nunjucks.configure('templates', {autoescape: true, express: app});
const TRANSLATE = new TranslationServiceClient();

const PORT = process.env.PORT || 8080;
const SOURCE = ['en', 'English'];
const TARGET = ['es', 'Spanish'];
let parent;
TRANSLATE.getProjectId().then(result => {
    parent = `projects/${result}`;
});


if (!process.env.FUNCTION_TARGET) {
    app.listen(PORT, () =>
        console.log(`Listening on port ${PORT}`)
    );
}

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

app.all('/', translate);
module.exports = {
    app
};

‫requires מספקות פונקציונליות של מסגרות ותבניות, וגם את ספריית הלקוח של Cloud Translation API.
המשתנים הגלובליים מייצגים את אפליקציית האינטרנט, את מזהה פרויקט בענן, את הלקוח של Translation API, את הנתיב של המיקום הראשי לקריאות של Translation API ואת השפות SOURCE ו-TARGET. בדוגמה הזו, שפת המקור היא אנגלית (en) ושפת היעד היא ספרדית (es), אבל אפשר לשנות את הערכים האלה לקודי שפה אחרים שנתמכים על ידי Cloud Translation API.
הרכיב הראשון בכל צמד (SOURCE ו-TARGET) הוא קוד השפה, והרכיב השני הוא שם השפה (והוא משמש רק למטרות תצוגה, כי הוא לא רלוונטי ל-API).
השורות הבודדות בחלק התחתון נועדו לשלוח את כל בקשות ה-HTTP אל translate() ואז לייצא את אובייקט האפליקציה app.

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

async function translate(req, rsp) {
    let text = null;
    let translated = null;
    if (req.method === 'POST') {
        text = req.body.text.trim();
        if (text) {
            const data = {
                contents: [text],
                parent: parent,
                targetLanguageCode: TARGET[0]
            };
            const [response] = await TRANSLATE.translateText(data);
            translated = response.translations[0].translatedText;
        }
    }
    const context = {
        orig:  {text: text, lc: SOURCE},
        trans: {text: translated, lc: TARGET}
    };
    rsp.render('index.html', context);
}

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

מאפסים את המשתנים הבסיסיים של הטופס. ההגדרה הזו רלוונטית בעיקר לבקשות GET, כי בקשות POST יכללו נתונים שיחליפו את הערכים האלה.
אם זו בקשת POST, צריך לאחזר את הטקסט לתרגום, ואם הוא לא ריק, ליצור מבנה JSON שמייצג את דרישת המטא-נתונים של ה-API. לאחר מכן מפעילים את ה-API של השירות.
לא העברנו את SOURCE[0] אל ה-API למקור ספציפי באנגלית. אם לא מציינים את שפת המקור, מבקשים מה-API לזהות באופן אוטומטי את שפת המקור (ראו sourceLanguageCode במסמכים).
בכל מקרה, צריך לעצב את התוצאות בפועל (POST) או את הנתונים (GET) בהקשר של התבנית ולבצע עיבוד.

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

<!doctype html>
<html><head><title>My Google Translate 1990s</title><body>
<style>
body {
  font-family: Verdana, Helvetica, sans-serif;
  background-color: #DDDDDD;
}
</style>
<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>

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

הפעלת השירות באופן מקומי
פריסה ב-App Engine (סביבה רגילה)
פריסה ל-Cloud Functions
פריסה ב-Cloud Run

7. אפשרות 1: הפעלת השירות באופן מקומי

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

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

יצירה של חשבון שירות
יצירת זוג מפתחות ציבורי/פרטי של חשבון שירות
הורדה של קובץ פרטי הכניסה וצירוף שלו לקוד האפליקציה
הפעלת השירות

מידע על חשבונות שירות

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

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

יצירת צמד מפתחות לחשבון שירות והורדה של קובץ פרטי הכניסה

פועלים לפי ההוראות בדף הזה כדי ליצור חשבון שירות וצמד מפתחות ציבורי/פרטי להפעלה מקומית. כשיוצרים את המפתח של חשבון השירות, תתבקשו לציין את ההרשאות הרצויות. חשוב לבחור באפשרות roles/cloudtranslate.user כדי שתוכלו לגשת ל-API.

אחרי שזוג המפתחות נוצר בהצלחה, תתבקשו להוריד את קובץ המפתח של חשבון השירות. קוראים לה credentials.json ומעבירים אותה לתיקייה ברמה העליונה של האפליקציה. עכשיו צריך להגדיר את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS כך שיצביע על הקובץ הזה, כדי ש-Cloud SDK ישתמש בפרטי הכניסה האלה. מידע נוסף על התהליך הזה זמין גם בדף הזה בנושא השימוש בחשבונות שירות.

הפעלת השירות

כשמוכנים להמשיך, מפעילים את שרת Express באופן מקומי באמצעות הפקודה הבאה:

$ npm start

> cloud-nebulous-serverless-nodejs@0.0.1 start
> node index.js

Listening on port 8080

עוברים לדפדפן האינטרנט כדי להתחבר אליו בכתובת localhost:8080, וצריך לראות משהו כמו הדוגמה הבאה:

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

כשמסיימים, יוצאים מהשרת באמצעות ‎ ^C (Control-C). כל הכבוד שהצלחת להפעיל פריסה מקומית. החדשות הטובות הן שהפריסה בענן הרבה יותר פשוטה.

פתרון בעיות

האם מופיעה שגיאה כזו כשאתם מבקשים תרגום?

node:fs:2486
      handleErrorFromBinding(ctx);
      ^

Error: The file at credentials.json does not exist, or it is not a file. ENOENT: no such file or directory, lstat '/tmp/nodejs/credentials.json'
    . . .

הפתרון: השגיאה הזו מציינת שלא סיימתם ליצור חשבון שירות ולהוריד את קובץ זוג המפתחות הציבורי/פרטי credentials.json. צריך לחזור אל אפשרות 1: הפעלת השירות באופן מקומי, להשלים את התהליך הזה ולהתקין את פרטי הכניסה בתיקייה הראשית לפני שממשיכים.

8. אפשרות 2: פריסה ב-App Engine (סביבה רגילה)

הקטע הזה ב-Codelab מיועד רק לפריסה ב-Node App Engine. אם אתם לא מעוניינים בכך, אפשר לעבור לקטע הבא.

הפריסה הזו משתמשת בקובץ התצורה app.yaml שבו מצוינת סביבת ההרצה שבה App Engine ישתמש, בשורה אחת:

runtime: nodejs16

הקובץ app.yaml לא נמצא בשימוש ב-Cloud Functions או ב-Cloud Run. אם אתם לא מתכננים להשתמש ב-App Engine, אפשר למחוק את הקובץ הזה בבטחה. כשמוכנים לפרוס ל-App Engine, מריצים את הפקודה הבאה:

$ gcloud app deploy

אחרי שבוחרים אזור, הפלט gcloud app deploy יהיה הרבה פחות מפורט ויראה כך:

Services to deploy:

descriptor:                  [/private/tmp/nodejs/app.yaml]
source:                      [/private/tmp/nodejs]
target project:              [PROJECT_ID]
target service:              [default]
target version:              [2021...]
target url:                  [https://PROJECT_ID.REG_ABBR.appspot.com]
target service account:      [App Engine default service account]


Do you want to continue (Y/n)?

Beginning deployment of service [default]...
╔════════════════════════════════════════════════════════════╗
╠═ Uploading 2 files to Google Cloud Storage                          ═╣
╚════════════════════════════════════════════════════════════╝
File upload done.
Updating service [default]...⠏WARNING: *** Improve build performance by generating and committing package-lock.json.

Updating service [default]...done.
Setting traffic split for service [default]...done.
Deployed service [default] to [https://PROJECT_ID.REG_ABBR.appspot.com]

You can stream logs from the command line by running:
  $ gcloud app logs tail -s default

To view your application in the web browser run:
  $ gcloud app browse

To take a quick anonymous survey, run:
  $ gcloud survey

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

אם שולחים בקשה, היא פועלת כמו כל הפריסות האחרות.

9. אפשרות 3: פריסה ב-Cloud Functions

הקטע הזה של ה-codelab מיועד רק לפריסה ב-Node Cloud Functions. אם אתם לא מעוניינים בכך, אפשר לעבור לקטע הבא.

אין קובצי הגדרה ב-Cloud Functions, לכן כשמוכנים לפרוס ל-Cloud Functions, מריצים את הפקודה הבאה:

$ gcloud functions deploy translate \
  --runtime nodejs16 \
  --entry-point app \
  --trigger-http \
  --region REGION \
  --allow-unauthenticated

יכול להיות שלפרויקט GCP שלכם יש REGION ברירת מחדל, אבל אתם יכולים להשתמש בדגל --region כדי לפרוס את הפונקציה לאזור ספציפי. ב-Cloud Functions לא מוצגת הנחיה כמו במוצרי Cloud אחרים. לא משנה איזה אזור תבחרו, הפלט של gcloud functions deploy צריך להיראות כך:

Deploying function (may take a while - up to 2 minutes)...⠛
For Cloud Build Logs, visit: https://console.cloud.google.com/cloud-build/builds;region=REGION/15ac7fc1-731d-4f3b-bc15-8f2614xxxxxx?project=062269xxxxxx
Deploying function (may take a while - up to 2 minutes)...done.
availableMemoryMb: 256
buildId: aaf7e0cd-fbbd-4624-abeb-3e7437xxxxxx
buildName: projects/062269xxxxxx/locations/REGION/builds/aaf7e0cd-fbbd-4624-abeb-3e7437xxxxxx
entryPoint: app
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: nodejs16
serviceAccountEmail: PROJECT_ID@appspot.gserviceaccount.com
sourceUploadUrl: https://storage.googleapis.com/gcf-upload-REGION-01de94c2-6eb4-4c49-aaff-09276cdb7ae9/a1db9f2d-3511-414b-aeeb-de6042xxxxxx.zip
status: ACTIVE
timeout: 60s
updateTime: '2021...'
versionId: '...'

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

10. אפשרות 4: פריסה ב-Cloud Run

הקטע הזה של ה-codelab מיועד רק לפריסה ב-Cloud Run. אם אתם לא מעוניינים בכך, אפשר לעבור לקטע הבא.

אין קובצי תצורה ב-Cloud Run, לכן כשמוכנים לפרוס ל-Cloud Run, צריך לפעול לפי ההוראות שבהמשך.

עכשיו אפשר לפרוס את שירות התרגום ב-Cloud Run על ידי הפעלת הפקודה הבאה:

$ gcloud run deploy translate --source . --allow-unauthenticated --platform managed

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

Please specify a region:
 [1] asia-east1
 [2] asia-east2
. . . (other regions) . . .
 [28] us-west4
 [29] cancel
Please enter your numeric choice:  REGION_CHOICE

To make this the default region, run `gcloud config set run/region REGION`.

Deploying from source requires an Artifact Registry repository to
store build artifacts. A repository named [cloud-run-source-deploy] in
 region [REGION] will be created.

Do you want to continue (Y/n)?

This command is equivalent to running "gcloud builds submit --pack image=[IMAGE] ." and "gcloud run deploy translate --image [IMAGE]"

Building . . . and deploying container to Cloud Run service [translate] in project [PROJECT_ID] region [REGION]
✓ Building and deploying... Done.
  ✓ Creating Container Repository...
  ✓ Uploading sources...
  ✓ Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds/60e1b
  9bb-b991-4b4e-8d8a-HASH?project=PROJECT_NUMBER].
  ✓ Creating Revision...
  ✓ Routing traffic...
  ✓ Setting IAM Policy...
Done.
Service [translate] revision [translate-00001-xyz] has been deployed and is serving 100 percent of traffic.
Service URL: https://SVC_NAME-HASH-REG_ABBR.a.run.app

‫Cloud Buildpacks מאפשרת להעביר את האפליקציות שלכם ל-Cloud Run, בדומה לאופן שבו הייתם עושים זאת אם הייתם מריצים את האפליקציה באופן מקומי. למשתמשי Node.js, הוא מריץ את npm install ו-npm start. ב-Python, הוא מריץ את pip install -r requirements.txt ומתחיל את האפליקציה מההוראות ב-Procfile. (אותו הדבר נכון לגבי כל השפות האחרות שנתמכות ב-Cloud Buildpacks). האפליקציה תהיה מוכנה לשימוש אחרי שתהליך ה-build יסתיים.

האפליקציה שלכם (נפרסת אזורית אבל) זמינה בכל העולם, ואפשר להגיע אליה בכתובת ה-URL שמכילה את מזהה הפרויקט שלכם, כמו שמוצג בפלט הפריסה (בקטע Service URL:‎):

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

11. סיכום

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

הסרת המשאבים

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

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

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

מחקר נוסף

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

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

מידע נוסף

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

קישורים ל-Node.js

רישיון

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