שימוש ב-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 תומך בפונקציות מסוימות של תוספים שאפשר להשתמש בהן כדי לבצע טרנספורמציה של נתוני האירועים שמתקבלים דרך האוטובוס. מידע נוסף ודוגמאות זמינים במאמר בנושא שינוי אירועים שהתקבלו.

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