יצירת טריגרים באמצעות Eventarc

בדף הזה מוסבר איך ליצור טריגר של Eventarc כדי ששירות Cloud Run יוכל לקבל אירועים משירות Google Cloud אחר.

‫Eventarc הוא שירות של Google Cloudשמאפשר ליצור ארכיטקטורות מבוססות-אירועים בלי להטמיע, להתאים אישית או לתחזק את התשתית הבסיסית.

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

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

מיקום הטריגר

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

זהות הטריגר

כשיוצרים טריגר של Eventarc, מציינים בשבילו חשבון שירות לניהול זהויות והרשאות גישה (IAM). הטריגר משתמש בחשבון השירות הזה כזהות ברירת המחדל שלו. מומלץ לציין חשבון שירות בניהול המשתמשים ולהקצות לו את ההרשאות המינימליות הנדרשות.

לפני שמתחילים

  1. הגדרת הסביבה של Cloud Run.

  2. מפעילים את ממשקי ה-API הבאים: Artifact Registry,‏ Cloud Build,‏ Cloud Run Admin API ו-Eventarc:

    הפעלת ממשקי ה-API

  3. מקצים את התפקידים וההרשאות הנדרשים ב-IAM.

יצירת טריגר לשירותים

אחרי שפורסים שירות, אפשר להגדיר טריגר באמצעות מסוף Google Cloud ,‏ Google Cloud CLI או Terraform.

המסוף

  1. פורסים את שירות Cloud Run באמצעות קונטיינרים או מקוד המקור.

  2. נכנסים לדף Cloud Run במסוף Google Cloud :

    כניסה ל-Cloud Run

  3. ברשימת השירותים, לוחצים על שירות קיים.

  4. בדף פרטי השירות, עוברים לכרטיסייה Triggers.

  5. לוחצים על הוספת טריגר ובוחרים אפשרות.

  6. בחלונית Eventarc trigger, משנים את פרטי הטריגר באופן הבא:

    1. בשדה Trigger name, מזינים שם לטריגר או משתמשים בשם ברירת המחדל.

    2. בוחרים באפשרות Trigger type מהרשימה כדי לציין אחד מסוגי הטריגרים הבאים:

      • מקורות של Google כדי לציין טריגרים ל-Pub/Sub, ל-Cloud Storage, ל-Firestore ולספקי אירועים אחרים של Google.

      • צד שלישי כדי לשלב עם ספקים שאינם של Google שמציעים מקור Eventarc. מידע נוסף זמין במאמר אירועים של צד שלישי ב-Eventarc.

    3. בוחרים ספק אירועים מהרשימה Event provider כדי לבחור מוצר שמספק את סוג האירוע להפעלת השירות. רשימת ספקי האירועים מופיעה במאמר ספקים ויעדים של אירועים.

    4. בוחרים סוג אירוע מהרשימה סוג אירוע. הגדרת הטריגר משתנה בהתאם לסוג האירוע הנתמך. מידע נוסף מופיע במאמר סוגי אירועים.

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

    6. בשדה Service account, בוחרים חשבון שירות. טריגרים של Eventarc מקושרים לחשבונות שירות כדי להשתמש בהם כזהות כשמפעילים את השירות. לחשבון השירות של הטריגר ב-Eventarc צריכה להיות הרשאה להפעיל את השירות. כברירת מחדל, Cloud Run משתמש בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine.

    7. אם רוצים, מציינים את נתיב כתובת ה-URL של השירות שאליו תישלח הבקשה הנכנסת. זהו הנתיב היחסי בשירות היעד שאליו צריך לשלוח את האירועים של הטריגר. לדוגמה: /, /route, route ו-route/subroute.

    8. אם רוצים לאפשר ניסיונות חוזרים במקרה של כישלון, מסמנים את התיבה Enable retry on failure. אחרת, פעולת ברירת המחדל היא ניסיון שליחה אחד ללא ניסיונות חוזרים. מידע נוסף זמין במאמר ניסיון חוזר של אירועים.

    9. אחרי שממלאים את שדות החובה, לוחצים על שמירת הטריגר.

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

gcloud

  1. פורסים את שירות Cloud Run באמצעות קונטיינרים או מקוד המקור.

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

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE  \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --max-retry-attempts=1 \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫TRIGGER_NAME: המזהה של הטריגר או מזהה מלא.
    • ‫LOCATION: המיקום של הטריגר של Eventarc. לחלופין, אפשר להגדיר את המאפיין eventarc/location, לדוגמה gcloud config set eventarc/location us-central1.

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

    • ‫DESTINATION_RUN_SERVICE: השם של שירות Cloud Run שמקבל את האירועים של הטריגר. השירות יכול להיות בכל אחד מהמיקומים שנתמכים ב-Cloud Run, ולא חייב להיות באותו מיקום של הטריגר. עם זאת, השירות חייב להיות באותו פרויקט כמו הטריגר, והוא יקבל אירועים כבקשות HTTP POST שנשלחות לנתיב כתובת ה-URL הבסיסית שלו (/) בכל פעם שהאירוע נוצר.
    • ‫DESTINATION_RUN_REGION: (אופציונלי) המיקום ב-Cloud Run שבו נמצא שירות היעד של Cloud Run. אם לא מציינים אזור, ההנחה היא שהשירות נמצא באותו אזור של הטריגר.
    • ‫EVENT_FILTER_TYPE: המזהה של האירוע. אירוע נוצר כשקריאה ל-API של ה-method מצליחה. בפעולות שנמשכות זמן רב, האירוע נוצר רק בסוף הפעולה, ורק אם הפעולה בוצעה בהצלחה. כאן תוכלו למצוא רשימה של סוגי האירועים של Google שנתמכים ב-Eventarc.
    • ‫SERVICE_ACCOUNT_NAME: השם של חשבון השירות שמנוהל על ידי המשתמש.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

    הערות:

    • חובה להשתמש בדגל --event-filters="type=EVENT_FILTER_TYPE". אם לא מוגדר מסנן אירועים אחר, מתבצעת התאמה של אירועים לכל המשאבים.
    • אי אפשר לשנות את EVENT_FILTER_TYPE אחרי שיוצרים את המרחב. כדי לשנות את EVENT_FILTER_TYPE, צריך ליצור טריגר חדש ולמחוק את הישן.
    • לכל טריגר יכולים להיות כמה מסנני אירועים, מופרדים בפסיקים בדגל אחד --event-filters=[ATTRIBUTE=VALUE,...] , או שאפשר לחזור על הדגל כדי להוסיף עוד מסננים. רק אירועים שתואמים לכל המסננים נשלחים ליעד. אין תמיכה בתווים כלליים לחיפוש ובביטויים רגולריים, אבל כשמשתמשים בדגל --event-filters-path-pattern, אפשר להגדיר תבנית נתיב של משאב.
    • אם רוצים לציין ניסיון אחד לשליחת אירוע בלי ניסיונות חוזרים, משתמשים בדגל --max-retry-attempts. הערך התקין היחיד הוא 1. אם לא מציינים את הדגל, חלה התנהגות ברירת המחדל של ניסיון חוזר. מידע נוסף זמין במאמר ניסיון חוזר של אירועים.
    • יש עוד דגלים שאפשר להשתמש בהם. מידע נוסף זמין במאמר gcloud eventarc triggers create.

Terraform

כדי ליצור טריגר של Eventarc לשירות Cloud Run, קראו את המאמר יצירת טריגר באמצעות Terraform.

יצירת טריגר לפונקציות

אחרי שפורסים פונקציה, אפשר להגדיר טריגר באמצעות מסוף Google Cloud , Google Cloud CLI או Terraform.

המסוף

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

  1. נכנסים ל-Cloud Run במסוף Google Cloud :

    כניסה ל-Cloud Run

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

  3. בקטע Trigger (טריגר), לוחצים על Add trigger (הוספת טריגר).

  4. אפשר לבחור באחת מהאפשרויות.

  5. בחלונית Eventarc trigger, משנים את פרטי הטריגר באופן הבא:

    1. בשדה Trigger name, מזינים שם לטריגר או משתמשים בשם ברירת המחדל.

    2. בוחרים סוג טריגר מהרשימה:

      • מקורות של Google כדי לציין טריגרים ל-Pub/Sub, ל-Cloud Storage, ל-Firestore ולספקי אירועים אחרים של Google.

      • צד שלישי כדי לשלב עם ספקים שאינם של Google שמציעים מקור Eventarc. מידע נוסף זמין במאמר אירועים של צד שלישי ב-Eventarc.

    3. בוחרים ספק אירועים מהרשימה Event provider כדי לבחור מוצר שמספק את סוג האירוע להפעלת הפונקציה. רשימת ספקי האירועים מופיעה במאמר ספקים ויעדים של אירועים.

    4. בוחרים סוג אירוע מהרשימה סוג אירוע. הגדרת הטריגר משתנה בהתאם לסוג האירוע הנתמך. מידע נוסף מופיע במאמר סוגי אירועים.

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

    6. בשדה Service account, בוחרים חשבון שירות. הטריגרים של Eventarc מקושרים לחשבונות שירות כדי להשתמש בהם כזהות כשמפעילים את הפונקציה. לחשבון השירות של הטריגר ב-Eventarc צריכה להיות הרשאה להפעיל את הפונקציה. כברירת מחדל, Cloud Run משתמש בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine.

    7. אם רוצים, מציינים את נתיב כתובת ה-URL של השירות שאליו תישלח הבקשה הנכנסת. זהו הנתיב היחסי בשירות היעד שאליו צריך לשלוח את האירועים של הטריגר. לדוגמה: /, /route, route ו-route/subroute.

    8. אם רוצים לאפשר ניסיונות חוזרים במקרה של כישלון, מסמנים את התיבה Enable retry on failure. אחרת, פעולת ברירת המחדל היא ניסיון שליחה אחד ללא ניסיונות חוזרים. מידע נוסף זמין במאמר ניסיון חוזר של אירועים.

  6. אחרי שממלאים את שדות החובה, לוחצים על שמירת הטריגר.

  7. לוחצים על יצירה.

  8. בכרטיסייה Source, עורכים את קוד המקור לפי הצורך ולוחצים על Save and redeploy.

gcloud

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

  1. מריצים את הפקודה הבאה בספרייה שמכילה את הקוד לדוגמה כדי לפרוס את הפונקציה:

    gcloud run deploy FUNCTION \
    --source . \
    --function FUNCTION_ENTRYPOINT \
    --base-image BASE_IMAGE_ID \
    --region REGION

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫FUNCTION: שם הפונקציה שאתם פורסים. אפשר להשמיט את הפרמטר הזה לגמרי, אבל אם תשמיטו אותו תתבקשו להזין את השם.

    • ‫FUNCTION_ENTRYPOINT: נקודת הכניסה לפונקציה בקוד המקור. זה הקוד ש-Cloud Run מריץ כשהפונקציה פועלת. הערך של הדגל הזה חייב להיות שם של פונקציה או שם מלא של מחלקה שקיימים בקוד המקור.

    • ‫BASE_IMAGE_ID: סביבת קובץ האימג' הבסיסי של הפונקציה. לפרטים נוספים על קובצי אימג' בסיסיים ועל החבילות שכלולות בכל קובץ אימג', ראו קובצי אימג' בסיסיים של סביבות זמן ריצה.

    • ‫REGION: האזור Google Cloudשבו רוצים לפרוס את הפונקציה. לדוגמה, europe-west1.

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

    gcloud eventarc triggers create TRIGGER_NAME \
    --location=LOCATION \
    --destination-run-service=FUNCTION \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --max-retry-attempts=1 \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫TRIGGER_NAME: המזהה של הטריגר או מזהה מלא.
    • ‫LOCATION: המיקום של הטריגר של Eventarc. לחלופין, אפשר להגדיר את המאפיין eventarc/location, לדוגמה gcloud config set eventarc/location us-central1.

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

    • ‫FUNCTION: השם של פונקציית Cloud Run שנפרסה ומקבלת את האירועים של הטריגר.
    • ‫DESTINATION_RUN_REGION: (אופציונלי) המיקום ב-Cloud Run שבו נמצאת פונקציית היעד של Cloud Run. אם לא מציינים אזור, ההנחה היא שהפונקציה נמצאת באותו אזור של הטריגר.
    • ‫EVENT_FILTER_TYPE: המזהה של האירוע. אירוע נוצר כשקריאה ל-API של ה-method מצליחה. בפעולות שנמשכות זמן רב, האירוע נוצר רק בסוף הפעולה, ורק אם הפעולה בוצעה בהצלחה. כאן תוכלו למצוא רשימה של סוגי האירועים של Google שנתמכים ב-Eventarc.
    • ‫SERVICE_ACCOUNT_NAME: השם של חשבון השירות שמנוהל על ידי המשתמש.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

    הערות:

    • חובה להשתמש בדגל --event-filters="type=EVENT_FILTER_TYPE". אם לא מוגדר מסנן אירועים אחר, מתבצעת התאמה של אירועים לכל המשאבים.
    • אי אפשר לשנות את EVENT_FILTER_TYPE אחרי שיוצרים את המרחב. כדי לשנות את EVENT_FILTER_TYPE, צריך ליצור טריגר חדש ולמחוק את הישן.
    • לכל טריגר יכולים להיות כמה מסנני אירועים, מופרדים בפסיקים בדגל אחד --event-filters=[ATTRIBUTE=VALUE,...] , או שאפשר לחזור על הדגל כדי להוסיף עוד מסננים. רק אירועים שתואמים לכל המסננים נשלחים ליעד. אין תמיכה בתווים כלליים לחיפוש ובביטויים רגולריים, אבל כשמשתמשים בדגל --event-filters-path-pattern, אפשר להגדיר תבנית נתיב של משאב.
    • אם רוצים לציין ניסיון אחד לשליחת אירוע בלי ניסיונות חוזרים, משתמשים בדגל --max-retry-attempts. הערך התקין היחיד הוא 1. אם לא מציינים את הדגל, חלה התנהגות ברירת המחדל של ניסיון חוזר. מידע נוסף זמין במאמר ניסיון חוזר של אירועים.
    • יש עוד דגלים שאפשר להשתמש בהם. מידע נוסף זמין במאמר gcloud eventarc triggers create.

Terraform

כדי ליצור טריגר של Eventarc לפונקציית Cloud Run, קראו את המאמר יצירת טריגר באמצעות Terraform.

הגדרת המועד האחרון לאישור ב-Pub/Sub

פונקציות Cloud Run מבוססות-אירועים מיושמות באמצעות Eventarc בשילוב עם מינוי ל-Pub/Sub. כברירת מחדל, המועד האחרון לאישור (ack) של המינוי הזה ל-Pub/Sub הוא 10 שניות. ההגדרה הזו לא מספיקה לפונקציות רבות, והיא עלולה לגרום להפעלות כפולות לא רצויות.

אם אתם מפעילים את השירות או הפונקציה ישירות באמצעות מינוי דחיפה של Pub/Sub בלי Eventarc, מינויי דחיפה ישירים חולקים את אותו מועד אחרון לאישור של 10 שניות כברירת מחדל ו-600 שניות (10 דקות) לכל היותר, שמגביל את זמן הקצוב לתפוגה של הבקשה.

מומלץ להגדיר את המועד האחרון של ack לשירות או לפונקציה לערך המקסימלי של 600 שניות, באופן הבא:

המסוף

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

  1. נכנסים לדף Cloud Run במסוף Google Cloud :

    כניסה ל-Cloud Run

  2. ברשימה Services, מאתרים את הפונקציה שרוצים לעדכן ולוחצים עליה כדי לפתוח את הפרטים שלה.

  3. פותחים את הכרטיסייה טריגרים.

  4. לוחצים על שם הטריגר כדי לפתוח את פרטי הטריגר.

  5. לוחצים על הקישור נושא כדי לפתוח את חלונית העריכה של הנושא.

  6. לוחצים על השם של Subscription ID כדי לעבור לחלונית המינוי, ואז לוחצים על Edit בחלק העליון של הדף.

  7. מגדירים את הערך של Acknowledgement Deadline ל-600 ולוחצים על Update כדי לשמור את השינוי.

gcloud

מעדכנים את המועד האחרון של ack לכל טריגר לערך המקסימלי של 600 שניות. שימו לב שהפקודות הבאות מפנות למשתנים (TRIGGER_NAME ו-LOCATION) שהערכים שלהם הוגדרו בשלבים הקודמים.

## Per Cloud Run function:

# Update Ack Deadline to max (600s)
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$TRIGGER_NAME" --location $LOCATION --format json | jq -r '.transport.pubsub.subscription')
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600

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

### Match all Cloud Run service triggers and update all deadlines to 600s (max timeout)
### This will change ALL Cloud Run services and Cloud Run functions
TRIGGER_NAMES=($(gcloud eventarc triggers list | awk '/Cloud Run service/ {print $1}'))

if [ ${#TRIGGER_NAMES[@]} -eq 0 ]; then
  echo "No matching triggers found"
fi

for trigger in "${TRIGGER_NAMES[@]}"; do
echo "Updating ack deadline for trigger: $trigger"
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$trigger" --location $LOCATION --format json | jq -r '.transport.pubsub.subscription')

if [ -z "$SUBSCRIPTION_ID" ]; then
    echo "Error: Could not retrieve subscription ID for trigger: $trigger"
    continue # Skip to the next trigger
fi
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600
echo "Ack deadline updated for subscription: $SUBSCRIPTION_ID"
done

הצגת המזהה והמקור של CloudEvent

כדי לראות את המזהה והמקור של CloudEvent שהפעילו את השירות, אתם יכולים לעיין במשאבים הבאים ביומני השירות של Cloud Run:

  • LogEntry.labels.run.googleapis.com/cloud_event_id
  • LogEntry.labels.run.googleapis.com/cloud_event_source

המאמרים הבאים