במדריך הזה מוסבר איך ליצור טריגרים לשירותים ולפונקציות של Cloud Run מאירועים ב-Firestore.
אתם יכולים להגדיר את שירותי Cloud Run כך שיופעלו על ידי אירועים במסד נתונים של Firestore. כשמופעלים אירועים, השירות קורא ומעדכן מסד נתונים של Firestore בתגובה לאירועים האלה באמצעות ממשקי ה-API וספריות הלקוח של Firestore.
במחזור חיים רגיל, זה מה שקורה כשאירועים ב-Firestore מפעילים שירות Cloud Run:
השירות ממתין לשינויים במסמך מסוים.
כשמתרחש שינוי, השירות מופעל ומבצע את המשימות שלו.
השירות מקבל אובייקט נתונים עם תמונת מצב של המסמך הרלוונטי. באירועים מסוג
writeאוupdate, אובייקט הנתונים מכיל תמונות מצב שמייצגות את מצב המסמך לפני ואחרי האירוע שהפעיל את המעקב.
סוגי אירועים
Firestore תומך באירועים create, update, delete ו-write. האירוע write כולל את כל השינויים במסמך.
| סוג אירוע | הטריגר |
|---|---|
google.cloud.firestore.document.v1.created (ברירת מחדל) |
מופעל כשמסמך נכתב בפעם הראשונה. |
google.cloud.firestore.document.v1.updated |
מופעל כשמסמך כבר קיים וערך כלשהו בו משתנה. |
google.cloud.firestore.document.v1.deleted |
מופעל כשמסמך עם נתונים נמחק. |
google.cloud.firestore.document.v1.written |
מופעל כשמסמך נוצר, מתעדכן או נמחק. |
תווים כלליים לחיפוש נכתבים בטריגרים באמצעות סוגריים מסולסלים, לדוגמה:
projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}
ציון נתיב המסמך
כדי להפעיל את השירות, מציינים נתיב של מסמך להאזנה. נתיב המסמך צריך להיות באותו Google Cloud פרויקט כמו השירות.
אלו כמה דוגמאות לנתיבי מסמכים תקינים:
users/marie: טריגר תקין. עוקב אחרי מסמך יחיד,/users/marie.
users/{username}: טריגר תקין. מעקב אחרי כל המסמכים של המשתמשים. תווים כלליים משמשים למעקב אחרי כל המסמכים באוסף.users/{username}/addresses: טריגר לא חוקי. ההפניה היא לאוסף המשנהaddresses, ולא למסמך.
users/{username}/addresses/home: טריגר תקין. מנטר את המסמך עם כתובת המגורים של כל המשתמשים.
users/{username}/addresses/{addressId}: טריגר תקין. עוקב אחרי כל מסמכי הכתובות.
users/{user=**}: טריגר תקין. הכלי עוקב אחרי כל המסמכים של המשתמשים וכל המסמכים בתתי-אוספים מתחת לכל מסמך משתמש, כמו/users/userID/address/homeאו/users/userID/phone/work.
תווים כלליים לחיפוש ופרמטרים
אם אתם לא יודעים מהו המסמך הספציפי שאתם רוצים לעקוב אחריו, אתם יכולים להשתמש ב-{wildcard}
במקום במזהה המסמך:
-
users/{username}מאזין לשינויים בכל מסמכי המשתמשים.
בדוגמה הזו, כשמשנים שדה כלשהו במסמך כלשהו ב-users, הוא תואם לתו כל כללי שנקרא {username}.
אם במסמך ב-users יש אוספי משנה, ושדה באחד מהמסמכים של אוספי המשנה האלה משתנה, התו הכללי {username} לא מופעל. אם רוצים להגיב לאירועים גם בקולקציות משנה, צריך להשתמש בתו הכללי {username=**} של כמה מקטעים.
התאמות של תווים כלליים לחיפוש מחולצות מנתיבי מסמכים. אפשר להגדיר כמה תווים כלליים שרוצים במקום מזהים מפורשים של אוספים או מסמכים. אפשר להשתמש בתו כללי אחד לחיפוש של כמה פלחים, כמו {username=**}.
מבנים של אירועים
הטריגר הזה מפעיל את השירות שלכם עם אירוע שדומה ל:
{ "oldValue": { // Update and Delete operations only A Document object containing a pre-operation document snapshot }, "updateMask": { // Update operations only A DocumentMask object that lists changed fields. }, "value": { // A Document object containing a post-operation document snapshot } }
כל אובייקט Document מכיל אובייקט Value אחד או יותר. למידע על הפניות לסוגים, אפשר לעיין בValueמסמכים.
לפני שמתחילים
- חשוב לוודא שהגדרתם פרויקט חדש ל-Cloud Run כמו שמתואר בדף ההגדרה.
מפעילים את ממשקי ה-API של Artifact Registry, Cloud Build, Cloud Run Admin, Eventarc, Cloud Logging של Firestore ו-Pub/Sub:
התפקידים הנדרשים לחשבון הפריסה
כדי לקבל את ההרשאות שדרושות להפעלת פונקציות מאירועים ב-Firestore, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:
- עריכה ב-Cloud Build (
roles/cloudbuild.builds.editor) - אדמין ב-Cloud Run (
roles/run.admin) - בעלים של Datastore (
roles/datastore.owner) - אדמין ב-Eventarc (
roles/eventarc.admin) - בעל הרשאת גישה לתצוגת יומנים (
roles/logging.viewAccessor) - אדמין IAM בפרויקט (
roles/resourcemanager.projectIamAdmin) - אדמין בחשבון שירות (
roles/iam.serviceAccountAdmin) - משתמש בחשבון שירות (
roles/iam.serviceAccountUser) - אדמין Service Usage (
roles/serviceusage.serviceUsageAdmin)
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.
שימו לב: כברירת מחדל, ההרשאות של Cloud Build כוללות הרשאות להעלאה ולהורדה של ארטיפקטים של Artifact Registry.
הגדרת מסד נתונים ב-Firestore
לפני שמפעילים את השירות, צריך ליצור מסד נתונים של Firestore:
עוברים אל הדף 'נתונים ב-Firestore'.
בוחרים באפשרות יצירת מסד נתונים.
לוחצים על מצב מקורי ואז על המשך.
בשדה Name your database (מתן שם למסד הנתונים), מזינים מזהה מסד נתונים, כמו
firestore-db.בקטע Location type, בוחרים באפשרות Region ובוחרים את האזור שבו רוצים שהמסד הנתונים יהיה ממוקם. הבחירה הזו היא קבועה.
לא משנים את הקטע כללים מאובטחים.
לוחצים על יצירת מסד נתונים.
מודל הנתונים של Firestore מורכב מאוספים שמכילים מסמכים. מסמך מכיל קבוצה של צמדי מפתח/ערך.
יצירת טריגרים
בהתאם לסוג השירות שאתם פורסים, אתם יכולים:
יצירת טריגר לשירותים
אחרי פריסת שירות, אפשר להגדיר טריגר באמצעות מסוף Google Cloud , Google Cloud CLI או Terraform.
המסוף
פורסים את שירות Cloud Run באמצעות קונטיינרים או ממקור.
במסוף Google Cloud , עוברים אל Cloud Run:
ברשימת השירותים, לוחצים על שירות קיים.
בדף פרטי השירות, עוברים לכרטיסייה Triggers (טריגרים).
לוחצים על Add trigger (הוספת טריגר) ובוחרים באפשרות Firestore trigger (טריגר של Firestore).
בחלונית Eventarc trigger משנים את פרטי הטריגר באופן הבא:
בשדה Trigger name, מזינים שם לטריגר או משתמשים בשם ברירת המחדל.
בוחרים סוג טריגר מהרשימה כדי לציין אחד מסוגי הטריגרים הבאים:
מקורות Google כדי לציין טריגרים ל-Pub/Sub, ל-Cloud Storage, ל-Firestore ולספקי אירועים אחרים של Google.
צד שלישי כדי לבצע שילוב עם ספקים שאינם של Google שמציעים מקור Eventarc. מידע נוסף זמין במאמר בנושא אירועים של צד שלישי ב-Eventarc.
בוחרים באפשרות Firestore מתוך רשימת ספקי האירועים, כדי לבחור מוצר שמספק את סוג האירוע להפעלת השירות. רשימת ספקי האירועים מופיעה במאמר ספקי אירועים ויעדים.
ברשימה Event type (סוג האירוע), בוחרים באפשרות type=google.cloud.firestore.document.v1.created. הגדרת הטריגר משתנה בהתאם לסוג האירוע הנתמך. מידע נוסף זמין במאמר בנושא סוגי אירועים.
בקטע Filters (מסננים), בוחרים מסד נתונים, פעולה וערכי מאפיינים, או משתמשים בבחירות ברירת המחדל.
אם השדה אזור מופעל, בוחרים מיקום לטריגר Eventarc. באופן כללי, המיקום של טריגר Eventarc צריך להיות זהה למיקום של Google Cloud המשאב שרוצים לעקוב אחרי האירועים שלו. ברוב התרחישים, מומלץ גם לפרוס את השירות באותו אזור. מידע נוסף על מיקומי טריגרים של Eventarc זמין במאמר הסבר על מיקומי Eventarc.
בשדה Service account, בוחרים חשבון שירות. טריגרים של Eventarc מקושרים לחשבונות שירות כדי לשמש כזהות כשמפעילים את השירות. לחשבון השירות של טריגר Eventarc צריכה להיות הרשאה להפעלת השירות. כברירת מחדל, Cloud Run משתמש בחשבון השירות של Compute Engine שמוגדר כברירת מחדל.
אפשר לציין את נתיב כתובת ה-URL של השירות כדי לשלוח את הבקשה הנכנסת. זהו הנתיב היחסי בשירות היעד שאליו יישלחו האירועים של הטריגר. לדוגמה:
/,/route,routeו-route/subroute.אפשרות נוספת: כדי להפעיל ניסיונות חוזרים אם ניסיון המסירה נכשל, מסמנים את תיבת הסימון הפעלת ניסיון חוזר במקרה של כשל. אחרת, התנהגות ברירת המחדל היא ניסיון מסירה יחיד ללא ניסיונות חוזרים. מידע נוסף זמין במאמר בנושא ניסיון חוזר לשליחת אירועים.
אחרי שממלאים את שדות החובה, לוחצים על שמירת הטריגר.
אחרי שיוצרים את הטריגר, מוודאים שהוא תקין. הסימן לכך הוא סימן וי check_circle בכרטיסייה Triggers.
gcloud
פורסים את שירות Cloud Run באמצעות קונטיינרים או ממקור.
מריצים את הפקודה הבאה כדי ליצור טריגר שמסנן אירועים ומנתב אותם:
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" \ --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.comמחליפים את מה שכתוב בשדות הבאים:
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 של השיטה מצליחה. בפעולות ארוכות טווח, האירוע נוצר רק בסוף הפעולה, ורק אם הפעולה בוצעה בהצלחה. רשימה של סוגי האירועים הנתמכים מופיעה במאמר בנושא סוגי אירועים של Google שנתמכים על ידי Eventarc. -
SERVICE_ACCOUNT_NAME: השם של חשבון השירות שמנוהל על ידי המשתמש. -
PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
הערות:
- אחרי שיוצרים טריגר, אי אפשר לשנות את סוג המסנן של האירועים. כדי להגדיר סוג אירוע אחר, צריך ליצור טריגר חדש.
--event-filters=type=google.cloud.firestore.document.v1.writtenמציין שהפונקציה מופעלת כשמסמך נוצר, מתעדכן או נמחק, בהתאם לסוג האירוע.-
--event-filters=database='(default)'מציין את מסד הנתונים של Firebase. לשם מסד הנתונים שמוגדר כברירת מחדל, משתמשים ב-(default). --event-filters-path-pattern=document='users/{username}'מציין את תבנית הנתיב של המסמכים שצריך לעקוב אחריהם כדי לזהות שינויים רלוונטיים. תבנית הנתיב הזו מציינת שצריך לעקוב אחרי כל המסמכים באוסףusers. מידע נוסף זמין במאמר הסבר על דפוסי נתיבים.- אפשר גם לציין ניסיון אחד למסירת אירוע ללא ניסיונות חוזרים באמצעות הדגל
--max-retry-attempts. הערך החוקי היחיד הוא1. אם לא מציינים את הדגל, המערכת תנסה שוב לבצע את הפעולה לפי ההתנהגות הרגילה. מידע נוסף זמין במאמר בנושא ניסיון חוזר לשליחת אירועים. - יש דגלים אחרים. מידע נוסף זמין במאמר
gcloud eventarc triggers create.
Terraform
כדי ליצור טריגר Eventarc לשירות Cloud Run, ראו יצירת טריגר באמצעות Terraform.
יצירת טריגר לפונקציות
אחרי פריסת הפונקציה, אפשר להגדיר טריגר באמצעות מסוף Google Cloud , Google Cloud CLI או Terraform.
המסוף
כשמשתמשים במסוף Google Cloud כדי ליצור פונקציה, אפשר גם להוסיף טריגר לפונקציה. כדי ליצור טריגר לפונקציה:
נכנסים ל-Cloud Run במסוף Google Cloud :
לוחצים על Write a function (כתיבת פונקציה) ומזינים את פרטי הפונקציה. מידע נוסף על הגדרת פונקציות במהלך הפריסה זמין במאמר פריסת פונקציות.
בקטע Trigger (טריגר), לוחצים על Add trigger (הוספת טריגר).
בוחרים באפשרות Firestore trigger (טריגר של Firestore).
בחלונית Eventarc trigger משנים את פרטי הטריגר באופן הבא:
מזינים שם לטריגר בשדה Trigger name או משתמשים בשם ברירת המחדל.
בוחרים סוג טריגר מהרשימה:
מקורות Google כדי לציין טריגרים ל-Pub/Sub, ל-Cloud Storage, ל-Firestore ולספקי אירועים אחרים של Google.
צד שלישי כדי לבצע שילוב עם ספקים שאינם של Google שמציעים מקור Eventarc. מידע נוסף זמין במאמר בנושא אירועים של צד שלישי ב-Eventarc.
בוחרים באפשרות Firestore מתוך רשימת ספקי האירועים, כדי לבחור מוצר שמספק את סוג האירוע להפעלת הפונקציה. רשימת ספקי האירועים מופיעה במאמר ספקי אירועים ויעדים.
ברשימה Event type (סוג האירוע), בוחרים באפשרות type=google.cloud.firestore.document.v1.created. הגדרת הטריגר משתנה בהתאם לסוג האירוע הנתמך. מידע נוסף זמין במאמר בנושא סוגי אירועים.
בקטע Filters (מסננים), בוחרים מסד נתונים, פעולה וערכי מאפיינים, או משתמשים בבחירות ברירת המחדל.
אם השדה Region מופעל, בוחרים מיקום לטריגר Eventarc. באופן כללי, המיקום של טריגר Eventarc צריך להיות זהה למיקום שלGoogle Cloud המשאב שרוצים לעקוב אחרי האירועים שלו. ברוב התרחישים, כדאי גם לפרוס את הפונקציה באותו אזור. מידע נוסף על מיקומי טריגרים של Eventarc זמין במאמר הסבר על מיקומי Eventarc.
בשדה Service account, בוחרים חשבון שירות. טריגרים של Eventarc מקושרים לחשבונות שירות כדי לשמש כזהות כשמפעילים את הפונקציה. לחשבון השירות של טריגר Eventarc צריך להיות הרשאה להפעיל את הפונקציה. כברירת מחדל, Cloud Run משתמש בחשבון השירות של Compute Engine שמוגדר כברירת מחדל.
אפשר לציין את נתיב כתובת ה-URL של השירות כדי לשלוח את הבקשה הנכנסת. זהו הנתיב היחסי בשירות היעד שאליו יישלחו האירועים של הטריגר. לדוגמה:
/,/route,routeו-route/subroute.אפשרות נוספת: כדי להפעיל ניסיונות חוזרים אם ניסיון המסירה נכשל, מסמנים את תיבת הסימון הפעלת ניסיון חוזר במקרה של כשל. אחרת, התנהגות ברירת המחדל היא ניסיון מסירה יחיד ללא ניסיונות חוזרים. מידע נוסף זמין במאמר בנושא ניסיון חוזר לשליחת אירועים.
אחרי שממלאים את שדות החובה, לוחצים על שמירת הטריגר.
לוחצים על יצירה.
בכרטיסייה מקור, עורכים את קוד המקור אם צריך, ואז לוחצים על שמירה ופריסה מחדש.
gcloud
כשיוצרים פונקציה באמצעות ה-CLI של gcloud, קודם צריך לפרוס את הפונקציה ואז ליצור טריגר. כדי ליצור טריגר לפונקציה:
מריצים את הפקודה הבאה בספרייה שמכילה את הקוד לדוגמה כדי לפרוס את הפונקציה:
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.
מריצים את הפקודה הבאה כדי ליצור טריגר שמסנן אירועים ומנתב אותם:
gcloud eventarc triggers create TRIGGER_NAME \ --location=LOCATION \ --destination-run-service=FUNCTION \ --destination-run-region=DESTINATION_RUN_REGION \ --event-filters="type=EVENT_FILTER_TYPE" \ --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.comמחליפים את מה שכתוב בשדות הבאים:
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 של השיטה מצליחה. בפעולות ארוכות טווח, האירוע נוצר רק בסוף הפעולה, ורק אם הפעולה בוצעה בהצלחה. רשימה של סוגי האירועים הנתמכים מופיעה במאמר בנושא סוגי אירועים של Google שנתמכים על ידי Eventarc. -
SERVICE_ACCOUNT_NAME: השם של חשבון השירות שמנוהל על ידי המשתמש. -
PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
הערות:
- אחרי שיוצרים טריגר, אי אפשר לשנות את סוג המסנן של האירועים. כדי להגדיר סוג אירוע אחר, צריך ליצור טריגר חדש.
--event-filters=type=google.cloud.firestore.document.v1.writtenמציין שהפונקציה מופעלת כשמסמך נוצר, מתעדכן או נמחק, בהתאם לסוג האירוע.-
--event-filters=database='(default)'מציין את מסד הנתונים של Firebase. לשם מסד הנתונים שמוגדר כברירת מחדל, משתמשים ב-(default). --event-filters-path-pattern=document='users/{username}'מציין את תבנית הנתיב של המסמכים שצריך לעקוב אחריהם כדי לזהות שינויים רלוונטיים. תבנית הנתיב הזו מציינת שצריך לעקוב אחרי כל המסמכים באוסףusers. מידע נוסף זמין במאמר הסבר על דפוסי נתיבים.- אפשר גם לציין ניסיון אחד למסירת אירוע ללא ניסיונות חוזרים באמצעות הדגל
--max-retry-attempts. הערך החוקי היחיד הוא1. אם לא מציינים את הדגל, המערכת תנסה שוב לבצע את הפעולה לפי ההתנהגות הרגילה. מידע נוסף זמין במאמר בנושא ניסיון חוזר לשליחת אירועים. - יש דגלים אחרים. מידע נוסף זמין במאמר
gcloud eventarc triggers create.
Terraform
כדי ליצור טריגר Eventarc לפונקציית Cloud Run, אפשר לעיין במאמר יצירת טריגר באמצעות Terraform.
מידע נוסף זמין במאמר הרחבת Firestore באמצעות טריגרים לאירועים באמצעות פונקציות Cloud Run.
המאמרים הבאים
- דוגמאות לפונקציות שמופעלות כשמבצעים שינויים במסמך בתוך אוסף מוגדר.