במדריך הזה נסביר איך לפרוס פונקציה מבוססת-אירועים ב-Cloud Run, ואיך להשתמש ב-Eventarc כדי להפעיל את הפונקציה בתגובה לאירועים ב-Cloud Storage באמצעות Google Cloud CLI.
כשמציינים מסננים לטריגר של Eventarc, אפשר להגדיר את הניתוב של האירועים, כולל מקור האירוע ויעד האירוע. בדוגמה שבמדריך הזה, עדכון של קטגוריה של Cloud Storage מפעיל את האירוע, ובקשה נשלחת לפונקציה שלכם בצורה של בקשת HTTP.
מטרות
במדריך הזה תלמדו:
עלויות
במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:
בעזרת מחשבון העלויות אתם יכולים להעריך את העלויות בהתאם לשימוש הצפוי.
לפני שמתחילים
יכול להיות שאילוצי אבטחה שהוגדרו על ידי הארגון שלכם ימנעו מכם להשלים את השלבים הבאים. למידע על פתרון בעיות, קראו את המאמר פיתוח אפליקציות בסביבה מוגבלת של Google Cloud .
- נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.
-
התקינו את ה-CLI של Google Cloud.
-
אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.
-
כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:
gcloud init -
יוצרים או בוחרים פרויקט ב- Google Cloud .
התפקידים שנדרשים כדי לבחור או ליצור פרויקט
- בחירת פרויקט: כדי לבחור פרויקט לא נדרש תפקיד IAM ספציפי – אתם יכולים לבחור כל פרויקט שקיבלתם בו תפקיד.
-
יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד "יצירת פרויקטים" (
roles/resourcemanager.projectCreator), שכולל את ההרשאהresourcemanager.projects.create. איך מקצים תפקידים?
-
יוצרים פרויקט ב- Google Cloud :
gcloud projects create PROJECT_ID
מחליפים את
PROJECT_IDבשם של הפרויקט ב- Google Cloud שאתם יוצרים. -
בוחרים את הפרויקט שיצרתם ב- Google Cloud :
gcloud config set project PROJECT_ID
מחליפים את
PROJECT_IDבשם הפרויקט ב- Google Cloud .
-
התקינו את ה-CLI של Google Cloud.
-
אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.
-
כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:
gcloud init -
יוצרים או בוחרים פרויקט ב- Google Cloud .
התפקידים שנדרשים כדי לבחור או ליצור פרויקט
- בחירת פרויקט: כדי לבחור פרויקט לא נדרש תפקיד IAM ספציפי – אתם יכולים לבחור כל פרויקט שקיבלתם בו תפקיד.
-
יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד "יצירת פרויקטים" (
roles/resourcemanager.projectCreator), שכולל את ההרשאהresourcemanager.projects.create. איך מקצים תפקידים?
-
יוצרים פרויקט ב- Google Cloud :
gcloud projects create PROJECT_ID
מחליפים את
PROJECT_IDבשם של הפרויקט ב- Google Cloud שאתם יוצרים. -
בוחרים את הפרויקט שיצרתם ב- Google Cloud :
gcloud config set project PROJECT_ID
מחליפים את
PROJECT_IDבשם הפרויקט ב- Google Cloud .
- אם אתם לא משתמשים ב-Cloud Shell, עדכנו את הרכיבים של Google Cloud CLI והתחברו באמצעות החשבון שלכם:
gcloud components update gcloud auth login
- מפעילים את ממשקי ה-API:
gcloud services enable artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ storage.googleapis.com
- מגדירים את משתני התצורה שבהם משתמשים במדריך הזה:
export REGION=us-central1 gcloud config set run/region ${REGION} gcloud config set run/platform managed gcloud config set eventarc/location ${REGION}
אם אתם כפופים לכלל מדיניות של הארגון של הגבלה לפי דומיין שמגבילה הפעלות לא מאומתות לפרויקט, תצטרכו לגשת לשירות שנפרס כמו שמתואר בקטע בדיקת שירותים פרטיים.
הגדרת התפקידים הנדרשים
אתם או האדמין שלכם צריכים להקצות את תפקידי ה-IAM הבאים לחשבון הפריסה, לזהות של הטריגר, ולסוכני השירות של Pub/Sub ו-Cloud Storage (אופציונלי).
התפקידים הנדרשים לחשבון הפריסה
-
אם אתם יוצרי הפרויקט, אתם מקבלים את התפקיד הבסיסי "בעלים" (
roles/owner). כברירת מחדל, תפקיד ה-IAM הזה כולל את ההרשאות שנדרשות לגישה מלאה לרוב המשאבים של Google Cloud, ואתם יכולים לדלג על השלב הזה.אם אתם לא יוצרי הפרויקט, צריך לתת את ההרשאות הנדרשות בפרויקט לחשבון המשתמש המתאים. לדוגמה, חשבון משתמש יכול להיות חשבון Google (למשתמשי קצה) או חשבון שירות (לאפליקציות ולעומסי עבודה ממוחשבים). מידע נוסף זמין בדף תפקידים והרשאות של יעד האירוע.
כדי לקבל את ההרשאות שדרושות להשלמת המדריך, בקשו מהאדמין להקצות לכם את התפקידים הבאים ב-IAM בפרויקט:
- מפתח מקורות ב-Cloud Run (
roles/run.sourceDeveloper) - גישה לתצוגת יומנים (
roles/logging.viewAccessor) - אדמין IAM בפרויקט (
roles/resourcemanager.projectIamAdmin) - אדמין בחשבון שירות (
roles/iam.serviceAccountAdmin) - משתמש בחשבון שירות (
roles/iam.serviceAccountUser) - אדמין ב-Service Usage (
roles/serviceusage.serviceUsageAdmin)
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.
שימו לב שכברירת מחדל, ההרשאות של Cloud Build כוללות הרשאות להעלאה ולהורדה של פריטי מידע שנוצרו ב-Artifact Registry.
- מפתח מקורות ב-Cloud Run (
התפקידים הנדרשים לזהות הטריגר
שימו לב לחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine, כי תצטרכו לצרף אותו לטריגר של Eventarc כדי לייצג את הזהות של הטריגר לצורכי בדיקה. חשבון השירות הזה נוצר באופן אוטומטי אחרי שמפעילים שירות של Google Cloud שמשתמש ב-Compute Engine, או משתמשים בשירות כזה. כתובת האימייל שלו היא בפורמט הבא:
PROJECT_NUMBER-compute@developer.gserviceaccount.com
מחליפים את
PROJECT_NUMBERבמספר הפרויקט ב- Google Cloud. אפשר לראות את מספר הפרויקט בדף Welcome במסוף Google Cloud , או להריץ את הפקודה הבאה:gcloud projects describe PROJECT_ID --format='value(projectNumber)'
בסביבות ייצור, מומלץ מאוד ליצור חשבון שירות חדש ולהקצות לו תפקיד אחד או יותר ב-IAM, שמכילים את ההרשאות המינימליות הנדרשות ופועלים לפי העיקרון של הרשאות מינימליות.
- כברירת מחדל, רק בעלי פרויקטים, עורכי פרויקטים, אדמינים של Cloud Run ומפעילים של Cloud Run יכולים להפעיל שירותי Cloud Run.
אתם יכולים לשלוט בגישה לכל שירות בנפרד, אבל למטרות בדיקה, כדאי לתת לחשבון השירות של Compute Engine את התפקיד "מפעיל Cloud Run" (
run.invoker) בפרויקט Google Cloud . כך מקצים את התפקיד בכל השירותים והמשימות של Cloud Run בפרויקט.gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \ --role=roles/run.invoker
שימו לב שאם יוצרים טריגר לשירות Cloud Run מאומת בלי להקצות את התפקיד Cloud Run Invoker, הטריגר נוצר בהצלחה והוא פעיל. עם זאת, הטריגר לא יפעל כמו שצריך ותופיע הודעה דומה לזו ביומנים:
The request was not authenticated. Either allow public access or set the proper Authorization header. - מקצים את התפקיד "מקבל אירועים ב-Eventarc" (
roles/eventarc.eventReceiver) בפרויקט לחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine, כדי שהטריגר של Eventarc יוכל לקבל אירועים מספקי אירועים.gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \ --role=roles/eventarc.eventReceiver
תפקיד אופציונלי לסוכן השירות של Cloud Storage
- לפני שיוצרים טריגר לאירועים ישירים מ-Cloud Storage, צריך לתת לסוכן השירות של Cloud Storage את התפקיד "פרסום הודעות ב-Pub/Sub" (
roles/pubsub.publisher):SERVICE_ACCOUNT="$(gcloud storage service-agent --project=PROJECT_ID)" gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:${SERVICE_ACCOUNT}" \ --role='roles/pubsub.publisher'
תפקיד אופציונלי לסוכן השירות של Pub/Sub
- אם הפעלתם את סוכן השירות של Cloud Pub/Sub ב-8 באפריל 2021 או לפני כן, כדי לתמוך בבקשות דחיפה מאומתות של Pub/Sub, צריך להקצות לסוכן השירות את התפקיד "יצירת אסימונים בחשבון שירות" (
roles/iam.serviceAccountTokenCreator). אחרת, התפקיד הזה מוקצה כברירת מחדל:gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \ --role=roles/iam.serviceAccountTokenCreator
יצירת קטגוריה של Cloud Storage
יוצרים קטגוריה של Cloud Storage שתשמש כמקור האירועים:
gcloud storage buckets create -l us-central1 gs://PROJECT_ID-bucket/
כתיבת פונקציה מבוססת-אירועים
כדי לכתוב פונקציה מבוססת-אירועים:
Node.js
יוצרים ספרייה חדשה בשם
helloGCSועוברים אליה:mkdir helloGCS cd helloGCSיוצרים קובץ
package.jsonבספרייהhelloGCSכדי לציין את יחסי התלות של Node.js:יוצרים קובץ
index.jsבספרייהhelloGCSעם הקוד הבא לדוגמה ב-Node.js:
Python
יוצרים ספרייה חדשה בשם
helloGCSועוברים אליה:mkdir helloGCS cd helloGCSיוצרים קובץ
requirements.txtבספרייהhelloGCSכדי לציין את יחסי התלות של Python:הפעולה הזו מוסיפה חבילות שנדרשות לדוגמה.
יוצרים קובץ
main.pyבספרייהhelloGCSעם הקוד הבא ב-Python:
פריסת פונקציה מבוססת-אירועים
כדי לפרוס את הפונקציה helloworld-events, מריצים את הפקודה הבאה בספרייה שמכילה את הקוד לדוגמה:
Node.js
gcloud run deploy helloworld-events \
--source . \
--function helloGCS \
--base-image BASE_IMAGE \
--region us-central1
מחליפים את BASE_IMAGE בסביבת קובץ האימג' הבסיסי של הפונקציה, לדוגמה nodejs24. למידע נוסף על קובצי אימג' בסיסיים ועל החבילות שכלולות בכל קובץ אימג', קראו את המאמר סביבות זמן ריצה של שפות נתמכות וקובצי אימג' בסיסיים.
Python
gcloud run deploy helloworld-events \
--source . \
--function hello_gcs \
--base-image BASE_IMAGE \
--region us-central1
מחליפים את BASE_IMAGE בסביבת קובץ האימג' הבסיסי של הפונקציה, לדוגמה python314. למידע נוסף על קובצי אימג' בסיסיים ועל החבילות שכלולות בכל קובץ אימג', קראו את המאמר סביבות זמן ריצה של שפות נתמכות וקובצי אימג' בסיסיים.
בסיום הפריסה, ב-Google Cloud CLI תוצג כתובת ה-URL שבה השירות פועל.
יצירת טריגר של Eventarc
הטריגר של Eventarc שולח אירועים מהקטגוריה של Cloud Storage לשירות helloworld-events ב-Cloud Run.
יוצרים טריגר שמסנן אירועים של Cloud Storage:
gcloud eventarc triggers create TRIGGER_NAME \ --location=${REGION} \ --destination-run-service=helloworld-events \ --destination-run-region=${REGION} \ --event-filters="type=google.cloud.storage.object.v1.finalized" \ --event-filters="bucket=PROJECT_ID-bucket" \ --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com
מחליפים את:
- TRIGGER_NAME בשם של הטריגר.
- PROJECT_ID במזהה הפרויקט ב- Google Cloud .
- PROJECT_NUMBER במספר הפרויקט ב- Google Cloud .
שימו לב: כשיוצרים טריגר של Eventarc בפעם הראשונה בפרויקט ב- Google Cloud , יכול להיות עיכוב בהקצאה של סוכן השירות של Eventarc. בדרך כלל אפשר לפתור את הבעיה הזו אם מנסים ליצור את הטריגר שוב. מידע נוסף זמין במאמר שגיאות של דחיית הרשאה.
מוודאים שהטריגר נוצר בהצלחה. שימו לב: למרות שהטריגר נוצר באופן מיידי, יכול להיות שיעברו עד שתי דקות עד שהוא יפעל באופן מלא.
gcloud eventarc triggers list --location=${REGION}
הפלט אמור להיראות כך:
NAME: helloworld-events TYPE: google.cloud.storage.object.v1.finalized DESTINATION: Cloud Run service: helloworld-events ACTIVE: Yes LOCATION: us-central1
יצירה וצפייה באירוע
מעלים קובץ טקסט לקטגוריה של Cloud Storage כדי ליצור אירוע שמנותב לפונקציה. פונקציית Cloud Run מתעדת את האירוע ביומני השירות.
מעלים קובץ טקסט ל-Cloud Storage כדי ליצור אירוע:
echo "Hello World" > random.txt gcloud storage cp random.txt gs://PROJECT_ID-bucket/random.txt
ההעלאה יוצרת אירוע, ופונקציית Cloud Run מתעדת ביומן את ההודעה של האירוע.
כדי לראות את הרשומה ביומן:
מסננים את רשומות היומן ומחזירים את הפלט בפורמט JSON:
gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json
מחפשים רשומה ביומן שדומה לזו:
[ { .... "resource": { "labels": { .... "location": "us-central1", ..... "service_name": "helloworld-events" }, }, "textPayload": "File: random.txt", ..... } ]יכול להיות שייקח ליומנים כמה דקות להופיע. אם אתם לא רואים אותם מיד, נסו שוב אחרי דקה.
אחרי שמופיעה הרשומה ביומן, זה אומר שפרסתם בהצלחה פונקציה מבוססת-אירועים שהופעלה כשקובץ טקסט הועלה ל-Cloud Storage.
הסרת המשאבים
אם יצרתם פרויקט חדש בשביל המדריך הזה, מחקו את הפרויקט. אם השתמשתם בפרויקט קיים ואתם רוצים לשמור אותו בלי השינויים שנוספו במדריך הזה, מחקו את המשאבים שנוצרו בשביל המדריך.
מחיקת הפרויקט
הדרך הקלה ביותר לבטל את החיוב היא למחוק את הפרויקט שיצרתם בשביל המדריך הזה.
כדי למחוק את הפרויקט:
- במסוף Google Cloud , נכנסים לדף Manage resources.
- ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
- כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.
מחיקת משאבי המדריך
מוחקים את השירות ב-Cloud Run שפרסתם במדריך הזה:
gcloud run services delete SERVICE_NAME
כאשר
SERVICE_NAMEהוא שם השירות שבחרתם.אפשר גם למחוק שירותי Cloud Run ממסוףGoogle Cloud .
מסירים את כל הגדרות ברירת המחדל של ה-CLI של gcloud שהוספתם במהלך ההגדרה של המדריך.
לדוגמה:
gcloud config unset run/regionאו
gcloud config unset projectמוחקים משאבים אחרים של Google Cloud שנוצרו במדריך הזה:
- מוחקים את הטריגר של Eventarc:
מחליפים אתgcloud eventarc triggers delete TRIGGER_NAME
TRIGGER_NAMEבשם הטריגר.
- מוחקים את הטריגר של Eventarc: