שימוש ב-Common Expression Language

‫Common Expression Language (CEL) היא שפה לא שלמה של טיורינג בקוד פתוח, שאפשר להשתמש בה כדי להעריך ביטויים. כל הרשמה ל-Eventarc Advanced כוללת ביטוי של תנאי שנכתב ב-CEL ומשמש להערכה ולסינון של הודעות. ב-Eventarc Advanced, אפשר גם להשתמש ב-CEL כדי:

  • שליטה בגישת הפרסום על ידי החלת ביטוי תנאי CEL על מאפיין של הקשר של אירוע

  • לשנות את התוכן של נתוני האירועים באמצעות כתיבת ביטויי שינוי באמצעות CEL

באופן כללי, ביטוי של תנאי מורכב מהצהרה או הצהרות שמחוברות על ידי אופרטורים לוגיים (&&, || או !). כל הצהרה מבטאת כלל שמבוסס על מאפיינים ומוחל על הנתונים. בדרך כלל משתמשים באופרטורים כדי להשוות בין הערך של המשתנה לליטרל.

לדוגמה, אם הערך של message.type הוא google.cloud.dataflow.job.v1beta3.statusChanged, הביטוי message.type == "google.cloud.dataflow.job.v1beta3.statusChanged" יהיה שווה ל-True.

למידע נוסף, קראו את המאמרים הבאים:

מאפיינים זמינים

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

שימו לב לנקודות הבאות:

  • אירועים יכולים לכלול כל מספר של מאפיינים מותאמים אישית נוספים של CloudEvents עם שמות שונים (שנקראים גם מאפייני הרחבה), והרשמות יכולות להשתמש בהם. עם זאת, הם מיוצגים כסוגים String בביטויי CEL, ללא קשר לפורמט בפועל. אפשר להשתמש בביטוי CEL כדי להמיר את הערכים שלהם לסוגים אחרים.

  • אי אפשר להעריך הרשמות או לשלוט בגישת הפרסום על סמך תוכן מטען הייעודי (payload) של האירוע. המשתנים message.data ו-message.data_base64 הם משתנים שמורים ואי אפשר להשתמש בהם בביטויים. עם זאת, CEL נתמכת כשמשנים נתוני אירועים, וכך אפשר לשנות את תוכן מטען הייעודי (payload) של האירוע (לדוגמה, כדי לעמוד בדרישות של חוזה ה-API ליעד ספציפי).

אפשר לגשת למאפיינים הבאים כשמעריכים ביטויי תנאים:

מאפיין סוג מאפיין תיאור
message.datacontenttype String סוג התוכן של הערך data
message.dataschema URI מזהה את הסכימה ש-data תואם לה
message.id String מזהה את האירוע. המפיקים צריכים לוודא שהערך source + id הוא ייחודי לכל אירוע נפרד
message.source URI-reference מזהה את ההקשר שבו התרחש אירוע
message.specversion String הגרסה של מפרט CloudEvents שבה נעשה שימוש באירוע
message.subject String תיאור הנושא של האירוע בהקשר של יוצר האירוע (מזוהה על ידי source)
message.time Timestamp חותמת הזמן של מועד ההתרחשות. יכול להיות שיוצר CloudEvents יגדיר זמן אחר (למשל, הזמן הנוכחי), אבל כל היוצרים של אותו source צריכים להיות עקביים
message.type String תיאור של סוג האירוע שקשור להתרחשות המקורית. אפשר לעיין בסוגי האירועים של Google שנתמכים על ידי Eventarc

אופרטורים ופונקציות

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

אופרטורים לוגיים, כמו &&, || ו-!, מאפשרים לבדוק כמה משתנים בביטוי תנאי. לדוגמה: הביטוי message.time.getFullYear() < 2020 && message.type == "google.cloud.dataflow.job.v1beta3.statusChanged" מצרף שתי הצהרות, והוא יהיה שווה True אם שתי ההצהרות מתקיימות.True

אופרטורים לטיפול במחרוזות, כמו x.contains('y'), מתאימים למחרוזות או למחרוזות משנה שאתם מגדירים, ומאפשרים לכם לפתח כללים להתאמת הודעות בלי שתצטרכו לפרט כל שילוב אפשרי.

‫Eventarc Advanced תומך גם בפונקציות של תוספים, כמו merge ו-flatten, שאפשר להשתמש בהן כדי לשנות נתונים ולפשט את השינוי של אירועים שמתקבלים מאפיקוס.

אפשר לעיין ברשימה של אופרטורים ופונקציות מוגדרים מראש ב-CEL וברשימה של פקודות מאקרו מוגדרות מראש ב-CEL.

אופרטורים לוגיים

בטבלה הבאה מתוארים האופרטורים הלוגיים שנתמכים ב-Eventarc Advanced.

ביטוי תיאור
x == "my_string" הפונקציה מחזירה את הערך True אם x שווה לארגומנט הקבוע מסוג מחרוזת מילולית.
x == R"my_string\n" הפונקציה מחזירה את הערך True אם x שווה למחרוזת המילולית הגולמית שצוינה, שלא מפרשת רצפי escape. מחרוזות גולמיות נוחות לביטוי מחרוזות שצריך להשתמש בהן ברצפי escape, כמו ביטויים רגולריים או טקסט של תוכנית.
x == y הפונקציה מחזירה את הערך True אם x שווה ל-y.
x != y הפונקציה מחזירה את הערך True אם x לא שווה ל-y.
x && y הפונקציה מחזירה את הערך True אם גם x וגם y הם True.
x || y הפונקציה מחזירה True אם x,‏ y או שניהם הם True.
!x הפונקציה מחזירה True אם הערך הבוליאני x הוא False, או מחזירה False אם הערך הבוליאני x הוא True.
m['k'] אם המפתח k קיים, הפונקציה מחזירה את הערך במפתח k במפה של מחרוזת למחרוזת m. אם המפתח k לא קיים, הפונקציה מחזירה שגיאה שגורמת לכך שהכלל שנבדק לא תואם.

אופרטורים של מניפולציה של מחרוזות

בטבלה הבאה מתוארים האופרטורים לטיפול במחרוזות שנתמכים ב-Eventarc Advanced.

ביטוי תיאור
double(x) הפונקציה ממירה את תוצאת המחרוזת של x לסוג double. אפשר להשתמש בערך שהומר כדי להשוות בין מספרים עם נקודה צפה (floating-point) באמצעות אופרטורים אריתמטיים רגילים כמו > ו-<=. האפשרות הזו פועלת רק עבור ערכים שיכולים להיות מספרים עם נקודה צפה (floating-point).
int(x) הפונקציה ממירה את תוצאת המחרוזת של x לסוג int. אפשר להשתמש בערך שהומר כדי להשוות בין מספרים שלמים באמצעות אופרטורים אריתמטיים רגילים כמו > ו-<=. האפשרות הזו פועלת רק עם ערכים שיכולים להיות מספרים שלמים.
x + y הפונקציה מחזירה את המחרוזת המשורשרת xy.
x.contains(y) הפונקציה מחזירה את הערך True אם המחרוזת x מכילה את מחרוזת המשנה y.
x.endsWith(y) הפונקציה מחזירה את הערך True אם המחרוזת x מסתיימת במחרוזת המשנה y.
x.join() מחזירה מחרוזת חדשה שבה האלמנטים של רשימת מחרוזות מחוברים. הפונקציה מקבלת מפריד אופציונלי שמוצב בין הרכיבים במחרוזת שמתקבלת. לדוגמה, הביטוי הבא מחזיר 'hello world':

['hello', 'world'].join(' ')
x.lowerAscii() הפונקציה מחזירה מחרוזת חדשה שבה כל תווי ה-ASCII הם באותיות קטנות.
x.matches(y)

הפונקציה מחזירה את הערך True אם המחרוזת x תואמת לדפוס y של RE2 שצוין:

התבנית RE2 עוברת קומפילציה באמצעות האפשרות RE2::Latin1 שמשביתה את התכונות של Unicode.
x.replace(y,z) הפונקציה מחזירה מחרוזת חדשה שבה המופעים של מחרוזת המשנה y מוחלפים במחרוזת המשנה z. מקבלת ארגומנט אופציונלי שמגביל את מספר ההחלפות שיתבצעו. לדוגמה, הביטוי הבא מחזיר 'wello hello':

'hello hello'.replace('he', 'we', 1)
x.split(y) מחזירה רשימה של מחרוזות שפוצלו מהקלט לפי המפריד y. מקבל ארגומנט אופציונלי שמגביל את מספר מחרוזות המשנה שיוחזרו. לדוגמה, הביטוי הבא מחזיר את הערך ['hello', 'hello hello']:

'hello hello hello'.split(' ', 2)
x.startsWith(y) הפונקציה מחזירה את הערך True אם המחרוזת x מתחילה במחרוזת המשנה y.
x.upperAscii() הפונקציה מחזירה מחרוזת חדשה שבה כל תווי ה-ASCII הם באותיות רישיות.

פונקציות של ביטויים רגולריים

בטבלה הבאה מתוארות הפונקציות של הביטויים הרגולריים שנתמכות ב-Eventarc Advanced.

ביטוי תיאור
re.capture(target,regex)

הפונקציה משתמשת ב-regex כדי ללכוד את הערך של הקבוצה הראשונה ללא שם או עם שם במחרוזת target, ומחזירה מחרוזת. לדוגמה, הביטוי הבא מחזיר "o":

re.capture("hello", R"hell(o)")
re.captureN(target,regex) הפונקציה משתמשת ב-regex כדי ללכוד את שם הקבוצה והמחרוזת (לקבוצות עם שם) ואת האינדקס והמחרוזת של הקבוצה (לקבוצות ללא שם) מהמחרוזת target, ומחזירה מיפוי של זוגות של מפתח וערך. לדוגמה, הביטוי הבא מחזיר את הערך {"1": "user", "Username": "testuser", "Domain": "testdomain"}:

re.captureN("The user testuser belongs to testdomain", R"The (user|domain) (?P.*) belongs to (?P.*)")

re.extract(target,regex,rewrite) הפונקציה regex משמשת לחילוץ ערכים של קבוצות תואמות מהמחרוזת target, ומחזירה מחרוזת של הערכים שחולצו, שעוצבה על סמך הארגומנט rewrite. לדוגמה, הביטוי הבא מחזיר "example.com":

re.extract("alex@example.com", "(^.*@)(.*)", "\\2")
x.matches(regex)

הפונקציה מחזירה את הערך True אם המחרוזת x תואמת לדפוס regex של RE2 שצוין:

התבנית RE2 עוברת קומפילציה באמצעות האפשרות RE2::Latin1 שמשביתה את התכונות של Unicode.

הביטויים הרגולריים פועלים לפי התחביר של RE2. שימו לב שהתו R לפני הביטויים הרגולריים מציין מחרוזת גולמית שלא צריך לבצע בה escape.

פונקציות של תוספים

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

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