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

במדריך הזה מוסבר איך ליצור טריגרים לשירותים ולפונקציות של 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 כמו שמתואר בדף ההגדרה.
מפעילים את Artifact Registry,‏ Cloud Build,‏ Cloud Run Admin API,‏ Eventarc,‏ Firestore Cloud Logging ו-Pub/Sub APIs:

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

התפקידים הנדרשים

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

התפקידים הנדרשים לחשבון הפריסה

כדי לקבל את ההרשאות שדרושות להפעלת פונקציות מאירועים ב-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)
אדמין בשימוש בשירותים (roles/serviceusage.serviceUsageAdmin)

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

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

שימו לב: כברירת מחדל, ההרשאות של Cloud Build כוללות הרשאות להעלאה ולהורדה של ארטיפקטים של Artifact Registry.

התפקידים הנדרשים לזהות של הטריגר

חשוב לשים לב לחשבון השירות שמוגדר כברירת מחדל ב-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 שמכילים את ההרשאות המינימליות הנדרשות, ולפעול לפי העיקרון של הרשאות מינימליות.

הערה:
iam.automaticIamGrantsForDefaultServiceAccounts אילוץ מדיניות הארגון iam.automaticIamGrantsForDefaultServiceAccounts מונע מחשבונות שירות שמוגדרים כברירת מחדל לקבל את התפקיד 'עריכה' באופן אוטומטי. אם יצרתם את הארגון אחרי 3 במאי 2024, האילוץ הזה נאכף כברירת מחדל.

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

אם לחשבון השירות שמוגדר כברירת מחדל כבר יש הרשאת עריכה, מומלץ להחליף את הרשאת העריכה בהרשאות עם פחות גישה.כדי לשנות את התפקידים בחשבון השירות בצורה בטוחה, כדאי להשתמש בסימולטור המדיניות כדי לראות את ההשפעה של השינוי, ואז לתת ולבטל את התפקידים המתאימים.
כברירת מחדל, רק בעלי פרויקטים, עורכי פרויקטים, אדמינים ומפעילים של Cloud Run יכולים להפעיל שירותים של Cloud Run. אפשר לשלוט בגישה לכל שירות בנפרד, אבל למטרות בדיקה, כדאי להעניק את התפקיד 'הפעלת Cloud Run' (run.invoker) בפרויקט Google Cloud לחשבון השירות של Compute Engine. ההרשאה הזו ניתנת לתפקיד בכל השירותים והמשימות של 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 unauthenticated invocations 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
```

תפקיד אופציונלי לסוכן השירות של Pub/Sub

אם הפעלתם את סוכן השירות של Cloud Pub/Sub ב-8 באפריל 2021 או לפני כן, כדי לתמוך בבקשות push מאומתות של 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
```

הגדרת מסד נתונים ב-Firestore

לפני שמפעילים את השירות, צריך ליצור מסד נתונים של Firestore:

עוברים אל הדף 'נתונים ב-Firestore'.
בוחרים באפשרות יצירת מסד נתונים.
לוחצים על מצב מקורי ואז על המשך.
בשדה Name your database (מתן שם למסד הנתונים), מזינים מזהה מסד נתונים, כמו firestore-db.
בקטע Location type, בוחרים באפשרות Region ובוחרים את האזור שבו רוצים למקם את מסד הנתונים. הבחירה הזו היא סופית.
לא משנים את ההגדרות בקטע כללים מאובטחים.
לוחצים על יצירת מסד נתונים.

מודל הנתונים של Firestore מורכב מאוספים שמכילים מסמכים. מסמך מכיל קבוצה של צמדי מפתח/ערך.