דף זה תורגם על ידי Cloud Translation API.

הפעלת עיבוד אירועים מ-Cloud Storage באמצעות Eventarc ו-Cloud Functions (דור שני)

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

בשיעור ה-Lab הזה תלמדו איך להשתמש באירועי קטגוריה של Cloud Storage וב-Eventarc כדי להפעיל עיבוד אירועים. תשתמשו ב-Cloud Functions (דור שני) כדי לנתח נתונים ולעבד תמונות. הפונקציה תשתמש ב-Google Vision API ותשמור את התמונה שתתקבל בקטגוריה של Cloud Storage.

מה תלמדו

איך לפתח צינור עיבוד תמונות

הגדרת קטגוריות אחסון
יצירת פונקציה של Cloud Functions לקריאה ולכתיבה של אובייקטים ב-Cloud Storage
צריך לשלב את Vision API כדי לזהות תמונות של מנות אוכל
פריסת פונקציה של Cloud Functions
פריסת טריגר של Eventarc
בדיקה ואימות של הפתרון מקצה לקצה

דרישות מוקדמות

שיעור ה-Lab הזה מבוסס על היכרות עם הסביבות של Cloud Console והמעטפת.
ניסיון קודם ב-Cloud Storage, ב-Cloud Functions או ב-Vision API מועיל אבל לא נדרש.

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

הגדרת פרויקט ב-Cloud

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

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

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

הפעלת Cloud Shell

לוחצים על הסמל שמופיע מימין לסרגל החיפוש כדי להפעיל את Cloud Shell.

הגדרת סביבה

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

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NAME=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export REGION=us-east1 
export UPLOAD_BUCKET=gs://menu-item-uploads-$PROJECT_ID
export BUCKET_THUMBNAILS=gs://menu-item-thumbnails-$PROJECT_ID
export MENU_SERVICE_NAME=menu-service
export USER_EMAIL=$(gcloud config list account --format "value(core.account)")

הפעלת ממשקי ה-API הנדרשים לשיעור ה-Lab

gcloud services enable \
    vision.googleapis.com \
    cloudfunctions.googleapis.com \
    pubsub.googleapis.com \
    cloudbuild.googleapis.com \
    logging.googleapis.com \
    eventarc.googleapis.com \
    artifactregistry.googleapis.com \
    run.googleapis.com \
    --quiet

הפעלת ממשקי ה-API הנדרשים לשיעור ה-Lab. (שלב ספציפי ב-Qwiklabs)

gcloud services disable cloudfunctions.googleapis.com
gcloud services enable cloudfunctions.googleapis.com

שכפול המאגר

git clone https://github.com/GoogleCloudPlatform/cymbal-eats.git && cd cymbal-eats/cloud-functions

3. הגדרת קטגוריות של Cloud Storage

יצירת קטגוריות אחסון

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

משתמשים בפקודה gsutil mb ובשם ייחודי כדי ליצור שתי קטגוריות:

העלאת הקטגוריה שאליה התמונות יועלו קודם
קטגוריית תמונות ממוזערות לאחסון תמונות ממוזערות שנוצרו

יוצרים קטגוריה כדי להעלות תמונות חדשות:

gsutil mb -p $PROJECT_ID -l $REGION $UPLOAD_BUCKET

פלט לדוגמה:

Creating gs://menu-item-uploads-cymbal-eats-8399-3119/...

יצירת קטגוריה לאחסון תמונות ממוזערות שנוצרו:

gsutil mb -p $PROJECT_ID -l $REGION $BUCKET_THUMBNAILS

פלט לדוגמה:

Creating gs://menu-item-thumbnails-cymbal-eats-8399-3119/...

עדכון הרשאות של קטגוריה

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

משתמשים בפקודה gsutil iam ch כדי לתת הרשאה לקרוא ולכתוב אובייקטים בקטגוריה:

gsutil iam ch allUsers:objectViewer $UPLOAD_BUCKET
gsutil iam ch allUsers:objectViewer $BUCKET_THUMBNAILS

פלט לדוגמה

Updated IAM policy for project [cymbal-eats-8399-3119].
[...]

4. הגדרה של חשבונות שירות

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

export CF_SERVICE_ACCOUNT=thumbnail-service-sa
gcloud iam service-accounts create ${CF_SERVICE_ACCOUNT}

מקצים את התפקיד artifactregistry.reader כדי לאפשר פעולות קריאה מ-Artifact Registry:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/artifactregistry.reader"

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

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/storage.objectCreator"

מקצים את התפקיד run.invoker כדי לאפשר הפעלה של שירות Cloud Run:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/run.invoker"

כדי לאפשר קבלת אירועים מהספקים, צריך להקצות את התפקיד eventarc.eventReceiver:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/eventarc.eventReceiver"

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

GCS_SERVICE_ACCOUNT=$(gsutil kms serviceaccount -p $PROJECT_NUMBER)

gcloud projects add-iam-policy-binding $PROJECT_NUMBER \
    --member "serviceAccount:$GCS_SERVICE_ACCOUNT" \
    --role "roles/pubsub.publisher"

5. סקירה כללית של הפונקציה של עיבוד תמונות

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

הפעלת פונקציה

הפונקציות של Cloud Storage מבוססות על התראות Pub/Sub מ-Cloud Storage ותומכות בסוגים דומים של אירועים:

בשיעור ה-Lab הזה תפרסו ותפעילו פונקציה כשאובייקט יהיה מוכן ב-Cloud Storage.

השלמת אובייקטים

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

6. שילוב Cloud Storage

Cloud Storage הוא שירות לאחסון אובייקטים ב-Google Cloud. אובייקט הוא חלק של נתונים שלא ניתנים לשינוי, שמורכב מקובץ בכל סוג של פורמט. האובייקטים מאוחסנים בקונטיינרים שנקראים קטגוריות. כל הקטגוריות משויכות לפרויקט, ואפשר לקבץ את הפרויקטים בארגון. ספריות לקוח וממשקי API משתלבים עם Cloud Storage

בשיעור ה-Lab הזה תשתמשו בספריית הלקוח כדי לקרוא ולכתוב אובייקטים ב-Cloud Storage.

התקנה של ספריית הלקוח

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

שימוש בספריית הלקוח

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

package.json

{
    "name": "thumbnail-service",
    "version": "0.1.0",
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0",
      "@google-cloud/storage": "^5.18.2",
      "@google-cloud/vision": "^2.4.2",
        ...
    }
  }

רישום קריאה חוזרת (callback) ב-CloudEvent

רישום קריאה חוזרת (callback) של CloudEvent ב-Functions Framework, שתופעל על ידי Cloud Storage כשתעלו תמונה חדשה לקטגוריה.

index.js

functions.cloudEvent('process-thumbnails', async (cloudEvent) => {
    console.log(`Event ID: ${cloudEvent.id}`);
    console.log(`Event Type: ${cloudEvent.type}`);
    ...

יצירת אובייקט עזר לאחסון

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

index.js

const storage = new Storage();
const bucket = storage.bucket(file.bucket);
const thumbBucket = storage.bucket(process.env.BUCKET_THUMBNAILS);

הורדת אובייקטים של Cloud Storage

index.js

await bucket.file(file.name).download({
            destination: originalFile
        });

העלאת אובייקטים ל-Cloud Storage

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

הקוד שבהמשך מעלה תמונה לאחסון בענן באמצעות העלאה בבקשה אחת.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. שילוב Vision API

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

התקנה של ספריית הלקוח

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

יצירת לקוח של הכלי להוספת הערות לתמונות

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

index.js

const client = new vision.ImageAnnotatorClient();

יצירת בקשה של Vision API

Vision API יכול לבצע זיהוי תכונות בקובץ תמונה על ידי שליחת התוכן של קובץ התמונה כמחרוזת בקידוד base64 בגוף הבקשה.

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

נתוני התמונה בקידוד base64
רשימה של תכונות שהיית רוצה להוסיף להן הערות לגבי התמונה הזו.

index.js

        const client = new vision.ImageAnnotatorClient();
        const visionRequest = {
            image: { source: { imageUri: `gs://${file.bucket}/${file.name}` } },
            features: [
                { type: 'LABEL_DETECTION' },
            ]
        };
        const visionPromise = client.annotateImage(visionRequest);

8. פריסת הפונקציה של Cloud Functions

השירות הזה לשינוי גודל התמונה הוא חלק מהמערכת הגדולה של Cymbal Eats. בסעיף הזה, תפרסו רק את הרכיבים הקשורים לתכונת עיבוד התמונות. ההתקנה המלאה משלבת ממשק משתמש להעלאת התמונה ובקשת downstream לאחסון המטא-נתונים שמתקבלים. היכולות האלה לא מותקנות כחלק משיעור ה-Lab הזה.

הרכיבים הבאים ייווצרו במהלך פריסת הפונקציה:

Cloud Function
שירות Cloud Run
טריגר Eventarc
נושא Pub/Sub ומינוי

בטרמינל של Cloudshell, מריצים את הפקודה הבאה כדי לפרוס את הפונקציה של Cloud Functions עם קטגוריית טריגר ב-menu-item-uploads-$PROJECT_ID:

gcloud functions deploy process-thumbnails \
  --gen2 \
  --runtime=nodejs16 \
  --source=thumbnail \
  --region=$REGION \
  --project=$PROJECT_ID \
  --entry-point=process-thumbnails \
  --trigger-bucket=$UPLOAD_BUCKET \
  --service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --set-env-vars=BUCKET_THUMBNAILS=$BUCKET_THUMBNAILS,MENU_SERVICE_URL=$MENU_SERVICE_URL \
  --max-instances=1 \
  --quiet

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

פלט לדוגמה

Deploying function (may take a while - up to 2 minutes)...done.
[...]

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

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

במסוף Cloud, בודקים את הטריגר Eventarc שנוצר לפונקציה:

במסוף Cloud, בודקים את ה-Topics וה-Subscription של Pub/Sub שנוצרו עבור הטריגר של Eventarc:

9. בדיקה ואימות של הפתרון מקצה לקצה

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

העלאת תמונה מתאימה

שומרים את התמונה הזאת במחשב המקומי
משנים את שם הקובץ 1.jpg.
פתיחת מסוף Cloud Storage
לוחצים על הקטגוריה menu-item-uploads-...
לוחצים על העלאת קבצים.
מעלים את הקובץ 1.jpg לקטגוריית האחסון
במסוף Cloud, עוברים אל Cloud Functions.
לוחצים על תמונה ממוזערת.
לוחצים על הכרטיסייה LOGS.

עוברים לקטגוריה menu-item-thumbnails-$PROJECT_ID Cloud Storage
איך מוודאים שהתמונה הממוזערת נוצרה בקטגוריית התמונות הממוזערות

העלאת תמונה שלא מיועדת למאכל

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

שומרים את התמונה הזאת במחשב המקומי
משנים את שם הקובץ 2.jpg.
פתיחת מסוף Cloud Storage
לוחצים על הקטגוריה menu-item-uploads-...
לוחצים על העלאת קבצים
מעלים 2.jpg לקטגוריית האחסון
במסוף Cloud, עוברים אל Cloud Functions.
לוחצים על תמונה ממוזערת.
לוחצים על הכרטיסייה LOGS.

10. מעולה!

כל הכבוד, סיימת את שיעור ה-Lab!

השלב הבא:

בקישורים הבאים תוכלו למצוא עוד מעבדי קוד Labs של Cymbal Eats:

הסרת המשאבים

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

מחיקת הפרויקט

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