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

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

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

מה תלמדו

איך יוצרים צינור לעיבוד תמונות.

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

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

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

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

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

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

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

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

הפעלת 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_NAME=menu-item-uploads-$PROJECT_ID
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

שכפול המאגר

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

יצירת לקוח של Image Annotator

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

index.js

const client = new vision.ImageAnnotatorClient();

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

‫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 Run

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

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

פונקציות Cloud Run
טריגר Eventarc
נושא ומינוי ב-Pub/Sub

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

כדי לפרוס פונקציות Cloud Run ישירות ב-Cloud Run, קודם פורסים את הפונקציה ואז יוצרים בשבילה טריגר.

פורסים את הפונקציות של Cloud Run:

gcloud beta run deploy process-thumbnails \
      --source=thumbnail \
      --function process-thumbnails \
      --region $REGION \
      --base-image google-22-full/nodejs20 \
      --no-allow-unauthenticated \
      --project=$PROJECT_ID \
--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

פלט לדוגמה:

Done.                                                                                                                                                                                    
Service [process-thumbnails] revision [process-thumbnails-00001-abc] has been deployed and is serving 100 percent of traffic.
Service URL: https://process-thumbnails-000000000.us-east1.run.app

יוצרים את הטריגר:

gcloud eventarc triggers create process-thumbnails-trigger \
     --location=$REGION \
     --destination-run-service=process-thumbnails \
    --destination-run-region=$REGION \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=$UPLOAD_BUCKET_NAME" \
     --service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com"

פלט לדוגמה:

Creating trigger [process-thumbnails-trigger] in project [qwiklabs-gcp-02-53f8532696e1], location [us-east1]...done.                                                                     
WARNING: It may take up to 2 minutes for the new trigger to become active.

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

פלט שגיאה לדוגמה:

...If you recently started to use Eventarc, it may take a few minutes before all necessary permissions are propagated to the Service Agent...
[...]

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

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

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

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

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

העלאת תמונה

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

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

העלאת תמונה של מוצר שאינו מזון

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

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

10. מעולה!

כל הכבוד, סיימתם את ה-Lab.

השלב הבא:

כדאי לעיין במדריכי Codelab נוספים של Cymbal Eats:

הסרת המשאבים

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

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

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