העברת אירועים מ-Cloud Firestore אל Workflows

רגילה

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

האירועים מועברים בפורמט CloudEvents באמצעות בקשת HTTP. שירות Workflows ממיר את האירוע לאובייקט JSON (בהתאם למפרט CloudEvents) ומעביר את האירוע להרצת זרימת העבודה כארגומנט של זמן הריצה של זרימת העבודה. צריך לוודא שגודל האירוע לא חורג ממגבלת המשאבים. אירועים שגדולים מהגודל המקסימלי של ארגומנטים ב-Workflows לא יפעילו את הביצוע של תהליך העבודה.

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

בהוראות האלה מוסבר איך להגדיר ניתוב אירועים כך שהרצה של תהליך העבודה תופעל בתגובה לאירועCloud Firestore ישיר. פרטים נוספים זמינים ברשימה של אירועים ישירים נתמכים.

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

הכנות ליצירת טריגר

לפני שיוצרים טריגר Eventarc לזרימת עבודה של יעד, צריך לבצע את המשימות הבאות.

המסוף

1. בדף לבחירת הפרויקט במסוף Google Cloud , בוחרים פרויקט ב- Google Cloud או יוצרים אותו.

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

   כניסה לדף לבחירת הפרויקט

2. מפעילים את ממשקי ה-API‏ Eventarc,‏ Eventarc Publishing,‏ Workflows ו-Workflow Executions.

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

3. אם רלוונטי, מפעילים את ממשק ה-API שקשור לאירועים הישירים. לדוגמה, כדי להשתמש ב Cloud Firestore אירועים, צריך להפעיל את ה-API שלCloud Firestore .

4. אם עדיין אין לכם חשבון שירות בניהול המשתמש, אתם צריכים ליצור כזה חשבון ואז להקצות לו את התפקידים וההרשאות הנדרשים כדי ש-Eventarc יוכל לנהל אירועים עבור זרימת עבודה יעד.

   1. נכנסים לדף Service Accounts במסוף Google Cloud .

      לדף Service accounts

   2. בוחרים את הפרויקט הרצוי.

   3. כותבים שם בשדה Service account name. השדה Service account ID ימולא במסוף Google Cloud בהתאם לשם הזה.

      כותבים תיאור בשדה Service account description. לדוגמה, Service account for event trigger.

   4. לוחצים על Create and continue.

   5. כדי לספק גישה מתאימה, ברשימה Select a role בוחרים את תפקידי ניהול הזהויות והגישה (IAM) שרוצים להקצות לחשבון השירות. מידע נוסף זמין במאמר תפקידים והרשאות ליעדים של כלי Workflows.

      כדי להוסיף עוד תפקידים, לוחצים על Add another role ומוסיפים אותם אחד אחרי השני.

   6. לוחצים על Continue.

   7. כדי לסיים את יצירת החשבון, לוחצים על סיום.

gcloud

1. במסוף Google Cloud , מפעילים את Cloud Shell.

   הפעלת Cloud Shell

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

2. מפעילים את ממשקי ה-API‏ Eventarc,‏ Eventarc Publishing,‏ Workflows ו-Workflow Executions:

   gcloud services enable eventarc.googleapis.com \
       eventarcpublishing.googleapis.com \
       workflows.googleapis.com \
       workflowexecutions.googleapis.com

3. אם רלוונטי, מפעילים את ממשק ה-API שקשור לאירועים הישירים. לדוגמה, כדי להפעיל את האפשרות firestore.googleapis.com לאירועים, צריך להזין את הערך Cloud Firestore events.

4. אם עדיין אין לכם חשבון שירות בניהול המשתמש, אתם צריכים ליצור אותו ולהקצות לו את התפקידים וההרשאות הנדרשים כדי ש-Eventarc יוכל לנהל אירועים עבור זרימת עבודה יעד.

   1. יוצרים את חשבון השירות:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      מחליפים את SERVICE_ACCOUNT_NAME בשם של חשבון השירות. הוא צריך להיות באורך שבין 6 ל-30 תווים, והוא יכול לכלול תווים אלפאנומריים ומקפים. אחרי שיוצרים חשבון שירות, אי אפשר לשנות את השם שלו.

   2. מעניקים את התפקידים או ההרשאות הנדרשים לניהול זהויות והרשאות גישה (IAM). למידע נוסף, אפשר לעיין במאמר בנושא תפקידים והרשאות ליעדים של Workflows.

יצירת טריגר

אפשר ליצור טריגר Eventarc עם תהליך עבודה שפריסתו הושלמה כמקבל האירוע באמצעות Google Cloud CLI ‏ (gcloud או Terraform) או דרך מסוף Google Cloud .

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

המסוף

1. נכנסים לדף Triggers ב-Eventarc במסוף Google Cloud .

   כניסה לדף Triggers

2. לוחצים על Create trigger (יצירת ביטוי להפעלה).
3. מקלידים Trigger name.

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

4. בשדה Trigger type, בוחרים באפשרות Google sources.
5. ברשימה Event provider בוחרים באפשרות Cloud Firestore.

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

6. ברשימה סוג האירוע, מתוך האירועים ישירים, בוחרים סוג אירוע.
7. ברשימה סוג התוכן של נתוני האירועים, בוחרים את הקידוד של מטען הייעודי (payload) של האירוע.

   במקרה של אירועים ישירים מ- Cloud Firestore, הערך צריך להיות application/protobuf ונתוני האירוע הם מערך בייטים. מידע נוסף על הודעות protobuf לאירועים ב-Cloud Firestore זמין במאמר בנושא אירועים נפוצים. שימו לב שאפשר להשתמש בפונקציה של ספרייה רגילה של Workflows כדי לקודד בייטים לטקסט Base64. מידע נוסף זמין במאמר בנושא החזרת בייטים.

8. ברשימה Region, בוחרים את אותו אזור כמוGoogle Cloud השירות שמייצר את האירועים.

   מידע נוסף זמין במאמר בנושא מיקומי Eventarc.

9. אם האפשרות רלוונטית לספק האירועים, לוחצים על הוספת מסנן ומציינים את הפרטים הבאים:
   1. בשדה Attribute 1 (מאפיין 1), בהתאם לאירוע הישיר שבחרתם, בוחרים מזהה משאב שיכול לשמש כמסנן אירועים.
   2. בוחרים אופרטור:
      • שווה
      • תבנית נתיב: רלוונטי למשאבי document (מצב Native) ו-entity (מצב Datastore). אפשר להשתמש בתווים כלליים לחיפוש כדי להגיב לשינויים שתואמים לתבנית. תו כללי * מתאים לפלח אחד, ותו כללי של כמה פלחים * מתאים לאפס פלחים או יותר בדפוס.** אין לציין לוכסן מוביל – לדוגמה:

        users/* או users/{userId}	תואם לכל המסמכים באוסף /users. הערך לא תואם למסמכים באוספי משנה כמו /users/marie/messages/33e2IxYBD9enzS50SJ68
        users/**	התאמה לכל המסמכים באוסף /users ולמסמכים באוספי משנה כמו /users/marie/messages/33e2IxYBD9enzS50SJ68

        מידע נוסף זמין במאמר בנושא הסבר על דפוסי נתיבים.

   3. בשדה ערך מאפיין 1, בהתאם לאופרטור שבחרתם, מקלידים את הערך המדויק או מחילים תבנית נתיב.
   4. אם יש עוד מסנני מאפיינים שרלוונטיים, לוחצים על הוספת מסנן ומציינים את הערכים המתאימים.
10. בוחרים את חשבון השירות שיפעיל את השירות או את תהליך העבודה.

    אפשר גם ליצור חשבון שירות חדש.

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

11. ברשימה Event destination, בוחרים באפשרות Workflows.
12. בוחרים תהליך עבודה.
    

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

    מידע נוסף מופיע במאמר בנושא יצירת טריגר לזרימות עבודה.

13. אפשר גם ללחוץ על הוספת תווית. תוויות הן צמדי מפתח/ערך שעוזרים לכם לארגן אתGoogle Cloud המשאבים. מידע נוסף זמין במאמר מהן תוויות?
14. לוחצים על יצירה.

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

gcloud

כדי ליצור טריגר, מריצים פקודה עם דגלים נדרשים ואופציונליים.gcloud eventarc triggers create

הדגלים שונים בהתאם למצב ההפעלה של Firestore: במצב Native או במצב Datastore. מידע נוסף זמין במאמר בחירה בין מצב Native לבין מצב Datastore.

מצב מותאם

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-workflow=DESTINATION_WORKFLOW  \
    --destination-workflow-location=DESTINATION_WORKFLOW_LOCATION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="document=DOCUMENT" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account="SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

מצב Datastore

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-workflow=DESTINATION_WORKFLOW  \
    --destination-workflow-location=DESTINATION_WORKFLOW_LOCATION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="entity=ENTITY" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account="SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

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

• ‫TRIGGER: המזהה של הטריגר או מזהה מלא.

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

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

• ‫DESTINATION_WORKFLOW: המזהה של תהליך העבודה שנפרס ומקבל את האירועים מהטריגר. תהליך העבודה יכול להיות בכל אחד מהמיקומים שנתמכים ב-Workflows, והוא לא חייב להיות באותו מיקום כמו הטריגר. עם זאת, תהליך העבודה חייב להיות באותו פרויקט כמו הטריגר.
• ‫DESTINATION_WORKFLOW_LOCATION (אופציונלי): המיקום שבו מופעל תהליך העבודה של היעד. אם לא מציינים זאת, ההנחה היא שתהליך העבודה נמצא באותו מיקום כמו הטריגר.
• ‫EVENT_FILTER_TYPE: המזהה של האירוע. אירוע נוצר כשקריאה ל-API של השיטה מצליחה. בפעולות ארוכות טווח, האירוע נוצר רק בסוף הפעולה, ורק אם הפעולה בוצעה בהצלחה. רשימה של סוגי האירועים הנתמכים מופיעה במאמר בנושא סוגי אירועים של Google שנתמכים על ידי Eventarc.

‫Cloud Firestore תומך בסוגי האירועים הבאים במצב Native בלבד.

• ‫google.cloud.firestore.document.v1.created: האירוע נשלח כשמסמך נכתב בפעם הראשונה
• ‫google.cloud.firestore.document.v1.created.withAuthContext: אירוע עם מאפיינים של פרטי אימות נשלח כשמסמך נכתב בפעם הראשונה
• ‫google.cloud.firestore.document.v1.updated: האירוע נשלח כשמסמך כבר קיים וערך כלשהו בו השתנה
• ‫google.cloud.firestore.document.v1.updated.withAuthContext: אירוע עם מאפיינים של פרטי אימות נשלח כשמסמך כבר קיים וערך כלשהו שלו השתנה
• ‫google.cloud.firestore.document.v1.deleted: האירוע נשלח כשמסמך נמחק
• google.cloud.firestore.document.v1.deleted.withAuthContext: אירוע עם מאפיינים של פרטי אימות נשלח כשמסמך נמחק
• ‫google.cloud.firestore.document.v1.written: האירוע נשלח כשמסמך נוצר, מתעדכן או נמחק
• ‫google.cloud.firestore.document.v1.written.withAuthContext: אירוע עם מאפייני מידע לאימות נשלח כשמסמך נוצר, מתעדכן או נמחק.

‫Cloud Firestore תומך בסוגי האירועים הבאים במצב Datastore בלבד. אובייקטים של נתונים ב-Firestore במצב Datastore נקראים ישויות.

• ‫google.cloud.datastore.entity.v1.created: האירוע נשלח כשמתבצעת כתיבה של ישות בפעם הראשונה
• ‫google.cloud.datastore.entity.v1.created.withAuthContext: אירוע עם מאפיינים של פרטי אימות נשלח כשמתבצעת כתיבה לישות בפעם הראשונה
• ‫google.cloud.datastore.entity.v1.updated: האירוע נשלח כשישות כבר קיימת וערך כלשהו שלה השתנה
• ‫google.cloud.datastore.entity.v1.updated.withAuthContext: אירוע עם מאפיינים של פרטי אימות נשלח כשישות כבר קיימת וערך כלשהו שלה משתנה
• ‫google.cloud.datastore.entity.v1.deleted: האירוע נשלח כשמחקתם ישות
• ‫google.cloud.datastore.entity.v1.deleted.withAuthContext: אירוע עם מאפייני פרטי אימות נשלח כשמחקתם ישות
• ‫google.cloud.datastore.entity.v1.written: האירוע נשלח כשיוצרים, מעדכנים או מוחקים ישות
• ‫google.cloud.datastore.entity.v1.written.withAuthContext: אירוע עם מאפיינים של פרטי אימות נשלח כשיוצרים, מעדכנים או מוחקים ישות

• ‫DATABASE: מסד הנתונים של Firestore. לשם מסד הנתונים שמוגדר כברירת מחדל, משתמשים ב-(default).
• ‫NAMESPACE (אופציונלי): מרחב השמות של מסד הנתונים ב-Firestore. במצב Datastore, מרחב השמות שמוגדר כברירת מחדל הוא (default). אם לא מציינים את הפרמטר הזה, מתבצעת התאמה לתווים כלליים לחיפוש (*) לכל המקרים.
• ‫DOCUMENT (אופציונלי): רלוונטי למופעי מסד נתונים שפועלים במצב מקורי בלבד. נתיב מסד הנתונים שממנו רוצים לקבל אירועים כשנתונים נוצרים, מתעדכנים או נמחקים בנתיב הזה. אל תציינו לוכסן מוביל. האופרטור יכול להיות אחד מהערכים הבאים:
  • שווה; לדוגמה, --event-filters="document=DOCUMENT"
  • דפוס נתיב; לדוגמה, --event-filters-path-pattern="document=DOCUMENT".

    שימוש בתווים כלליים לחיפוש כדי להגיב לשינויים במסמכים שתואמים לתבנית. תו כללי לחיפוש * מתאים לפלח יחיד, ותו כללי לחיפוש של כמה פלחים ** מתאים לאפס פלחים או יותר בדפוס – לדוגמה:

    users/* או users/{userId}	תואם לכל המסמכים באוסף /users. הערך שונה מהערכים שמופיעים במסמכים בקולקציות משנה, כמו /users/marie/messages/33e2IxYBD9enzS50SJ68
    users/**	התאמה לכל המסמכים באוסף /users ולמסמכים באוספי משנה כמו /users/marie/messages/33e2IxYBD9enzS50SJ68

    מידע נוסף זמין במאמר הסבר על דפוסי נתיבים.
• ‫ENTITY (אופציונלי): רלוונטי למופעי מסד נתונים שפועלים במצב Datastore בלבד. נתיב מסד הנתונים שממנו רוצים לקבל אירועים כשנתונים נוצרים, מתעדכנים או נמחקים בנתיב הזה. אל תציינו לוכסן מוביל. האופרטור יכול להיות אחד מהאפשרויות הבאות:
  • שווה; לדוגמה, --event-filters="document=ENTITY"
  • דפוס נתיב; לדוגמה, --event-filters-path-pattern="ENTITY=ENTITY"

    מידע נוסף זמין במאמר הסבר על דפוסי נתיבים.

    הערה: יכול להיות שתצטרכו להשתמש בתו בריחה (escape) במזהי סוגים ובמזהי ישויות. הוספת תו בריחה מאפשרת למסנן האירועים לפרש את המזהה בצורה נכונה. מידע נוסף מופיע במאמר בנושא הסרת תווי escape.

• ‫EVENT_DATA_CONTENT_TYPE: הקידוד של מטען הייעודי (payload) של האירוע. במקרה של אירועים ישירים מ-Firestore, הערך צריך להיות application/protobuf ונתוני האירוע הם מערך בייטים. מידע נוסף על הודעות protobuf לאירועים ב-Cloud Firestore זמין במאמר אירועים נפוצים. שימו לב שאפשר להשתמש בפונקציה של ספרייה רגילה של Workflows כדי לקודד בייטים לטקסט Base64. מידע נוסף זמין במאמר בנושא החזרת בייטים.
• ‫SERVICE_ACCOUNT_NAME: השם של חשבון השירות שמנוהל על ידי המשתמש.
• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud

הערות:

• באירועים ישירים מ- Cloud Firestore, הקידוד של מטען הייעודי (payload) של האירוע הוא application/protobuf.
• חובה להשתמש בדגל --event-filters="type=EVENT_FILTER_TYPE". אם לא מוגדר מסנן אירועים אחר, המערכת מתאימה אירועים לכל המשאבים.
• EVENT_FILTER_TYPE אי אפשר לשנות את ההגדרה הזו אחרי שהמרחב נוצר. כדי לשנות את EVENT_FILTER_TYPE, צריך ליצור טריגר חדש ולמחוק את הטריגר הישן.
• לכל טריגר יכולים להיות כמה מסנני אירועים, מופרדים בפסיקים בדגל אחד --event-filters=[ATTRIBUTE=VALUE,...] או שאפשר לחזור על הדגל כדי להוסיף עוד מסננים. רק אירועים שתואמים לכל המסננים נשלחים ליעד. אין תמיכה בתווים כלליים לחיפוש ובביטויים רגולריים. עם זאת, כשמשתמשים בדגל --event-filters-path-pattern, אפשר להגדיר דפוס נתיב של משאב.
• הדגל --service-account משמש לציון כתובת האימייל בחשבון השירות בניהול זהויות והרשאות גישה (IAM) שמשויך לטריגר.

דוגמה:

gcloud eventarc triggers create helloworld-trigger \
    --location=us-east1 \
    --destination-workflow=my-workflow \
    --destination-workflow-location=us-east1 \
    --event-filters="type=google.cloud.firestore.document.v1.updated" \
    --event-filters="database=my-database" \
    --event-filters-path-pattern="document=users/my-document-*" \
    --event-data-content-type="application/protobuf" \
    --service-account="${TRIGGER_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

הפקודה הזו יוצרת טריגר בשם helloworld-trigger לאירוע שמזוהה כ-google.cloud.firestore.document.v1.updated במופע של מסד הנתונים my-database שפועל במצב Native, ומסננת אירועים עבור נתיבי document שתואמים ל-users/my-document-.

Terraform

אפשר ליצור טריגר לתהליך עבודה באמצעות Terraform. פרטים נוספים מופיעים במאמר בנושא הפעלת תהליך עבודה באמצעות Eventarc ו-Terraform.

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

הצגת טריגר

אפשר לאשר את יצירת הטריגר באמצעות רשימת הטריגרים של Eventarc ב-Google Cloud CLI או במסוף Google Cloud .

המסוף

1. נכנסים לדף Triggers ב-Eventarc במסוף Google Cloud .

   כניסה לדף Triggers

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

2. כדי לסנן את הטריגרים:

   1. לוחצים על Filter (מסנן) או על השדה Filter triggers (טריגרים של מסנן).
   2. ברשימה Properties, בוחרים אפשרות לסינון הטריגרים.

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

3. כדי למיין את הטריגרים, לוחצים על מיון לצד כותרת של עמודה נתמכת.

gcloud

מריצים את הפקודה הבאה כדי להציג את הטריגרים:

gcloud eventarc triggers list --location=-

הפקודה הזו מציגה רשימה של הטריגרים בכל המיקומים, וכוללת פרטים כמו שמות, סוגים, יעדים וסטטוסים.

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

• מידע נוסף על שימוש ב-Eventarc וב-Cloud Firestore
• הפעלת תהליך עבודה באמצעות Eventarc ו-Terraform.
• מידע נוסף על Eventarc
• איך מנהלים טריגרים