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

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

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

מה תלמדו

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

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

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

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

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

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

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

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

שימו לב: מזהה הפרויקט הוא ייחודי גלובלי, ואף אחד אחר לא יוכל להשתמש בו אחרי שתבחרו בו. אתם היחידים שמשתמשים במזהה הזה. גם אם מוחקים פרויקט, אי אפשר להשתמש שוב במזהה שלו

הערה: אם אתם משתמשים בחשבון Gmail, אתם יכולים להשאיר את מיקום ברירת המחדל כפי שהוא – ללא ארגון. אם אתם משתמשים בחשבון Google Workspace, בחרו מיקום שמתאים לארגון שלכם.

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

הפעלת Cloud Shell

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

הגדרת הסביבה

1. כדי ליצור משתני סביבה שקשורים לפרויקט ולמשאבים, מריצים את הפקודות הבאות במסוף 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)")

2. הפעלת ממשקי ה-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

3. שכפול המאגר

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

3. הגדרת קטגוריות ב-Cloud Storage

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

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

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

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

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

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

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

פלט לדוגמה

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

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

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

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"

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

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 ותומכות בסוגי אירועים דומים:

• finalize
• מחיקה
• archive
• עדכון מטא-נתונים

בשיעור ה-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",
        ...
    }
  }

הקובץ package.json מציין את ‎google-cloud/storage כאחד מיחסי התלות של האפליקציות.

התלות ב-google-cloud/functions-framework משמשת לרישום קריאה חוזרת (callback) של CloudEvent ב-Functions Framework, שתופעל על ידי אירועים ב-Cloud Storage.

יחסי התלות של ‎google-cloud/vision ישמשו לקריאה ל-Vision API כדי לקבל הערות לגבי התמונות שהועלו, כדי לקבוע אם מדובר בפריט מזון או לא.

רישום קריאה חוזרת (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}`);
    ...

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

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

index.js

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

הקוד שלמעלה יוצר לקוח אחסון שנקרא 'storage' ושני הפניות לקטגוריות אחסון, שיופנו באמצעות המשתנים 'bucket' ו-'thumbBucket'.

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

index.js

const client = new vision.ImageAnnotatorClient();

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

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

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

כדי ליצור בקשה באמצעות המשאב images כדי להוסיף הערות לתמונה. בקשה ל-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 Functions.

העלאת תמונה

הערה: התמונה של Tom Dillon ב-Unsplash זמינה לשימוש חופשי בכפוף לרישיון Unsplash.

1. שומרים את התמונה הזו במחשב המקומי.
2. משנים את שם הקובץ ל-1.jpg.
3. פותחים את מסוף Cloud Storage.
4. לוחצים על הקטגוריה menu-item-uploads-....
5. לוחצים על העלאת קבצים.
6. מעלים את הקובץ 1.jpg לקטגוריית האחסון
7. נכנסים לדף Cloud Run במסוף Cloud.
8. לוחצים על process-thumbails.
9. לוחצים על הכרטיסייה LOGS.

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

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

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

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

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

הערה: התמונה של Insung Yoon ב-Unsplash זמינה לשימוש חופשי בכפוף לרישיון Unsplash.

1. שומרים את התמונה הזו במחשב המקומי.
2. משנים את שם הקובץ ל-2.jpg
3. פותחים את מסוף Cloud Storage.
4. לוחצים על הקטגוריה menu-item-uploads-....
5. לוחצים על העלאת קבצים.
6. מעלים את הקובץ 2.jpg לקטגוריית האחסון
7. נכנסים לדף Cloud Run במסוף Cloud.
8. לוחצים על process-thumbails.
9. לוחצים על הכרטיסייה LOGS.

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

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

10. מעולה!

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

השלב הבא:

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

• הפעלת תהליכי עבודה ב-Cloud באמצעות Eventarc
• התחברות ל-CloudSQL פרטי מ-Cloud Run
• חיבור למסדי נתונים מנוהלים מ-Cloud Run
• אבטחה של אפליקציה ללא שרת באמצעות שרת proxy לאימות זהויות (IAP)
• הפעלת משימות Cloud Run באמצעות Cloud Scheduler
• פריסה מאובטחת ב-Cloud Run
• אבטחת תעבורת הנתונים הנכנסת (ingress) ב-Cloud Run
• התחברות ל-AlloyDB פרטי מ-GKE Autopilot

הסרת המשאבים

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

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

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