מאמר עזר בנושא שפת ההתאמה ב-CEL

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

מאפיינים

בכל בקשת חיבור, שרת ה-Proxy מחלץ מאפיינים, שהם קבוצה של מידע לפי הקשר. למאפיינים יש סוג קבוע (כמו string או int), והם יכולים להיות קיימים או לא, בהתאם להקשר. המאפיינים נחשפים לסביבת זמן הריצה של CEL במהלך העיבוד של תנאי ההתאמה. כדי להעביר מאפיינים ספציפיים לשירות או לפלאגין של התוסף, משתמשים בשדה forwardAttributes. מידע נוסף זמין במאמר מאפיינים נתמכים.

מאפייני הבקשות

אפשר לחלץ את המאפיינים הבאים מהבקשות:

מאפיין סוג LbEdge LbRoute LbTraffic Authz CdnEdge תיאור
request.headers מפה ✓ ✓ ✓ ✓ ✓ מפה של מחרוזת למחרוזת של כותרות בקשות HTTP, שבה כל המקשים הם באותיות קטנות.
request.method מחרוזת ✓ ✓ ✓ ✓ ✓ ה-method של בקשת ה-HTTP (לדוגמה, GET, POST).
request.host מחרוזת ✓ ✓ ✓ ✓ ✓ נוחות שוות ערך ל-request.headers['host'].
request.path מחרוזת ✓ ✓ ✓ ✓ ✓ נתיב כתובת ה-URL מסוג HTTP שנכלל בבקשה.
request.query מחרוזת ✓ ✓ ✓ ✓ ✓ מחרוזת השאילתה של כתובת ה-URL‏ (name1=value&name2=value2).
request.scheme מחרוזת ✓ ✓ ✓ ✓ ✓ סכמת כתובת ה-URL‏ (http או https).
request.backend_service_name מחרוזת — ✓ ✓ — — השם של השירות לקצה העורפי.
request.backend_service_project_number int — ✓ ✓ — — מספר הפרויקט של שירות הקצה העורפי.

מאפייני החיבור

אפשר לחלץ את המאפיינים הבאים מהחיבורים:

מאפיין סוג LbEdge LbRoute LbTraffic Authz CdnEdge תיאור
source.ip מחרוזת ✓ ✓ ✓ ✓ — כתובת ה-IP של הלקוח.
source.port int ✓ ✓ ✓ ✓ ✓ מספר היציאה של חיבור הלקוח.
source.client_region מחרוזת ✓ — ✓ — ✓ קוד מדינה או אזור של הלקוח, שמורכב משתי אותיות.
connection.sni מחרוזת ✓ — ✓ ✓ ✓ אינדיקציה לשם שרת TLS במורד הזרם.
connection.tls_version מחרוזת ✓ — ✓ ✓ ✓ גרסת TLS במורד הזרם (לדוגמה, TLSv1.2, TLSv1.3).
connection.sha256_peer_certificate_digest מחרוזת ✓ — ✓ ✓ — תקציר SHA-256 של אישור עמית.

אופרטורים

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

אופרטורים של מניפולציה של מחרוזות מתאימים למחרוזות או למחרוזות משנה שאתם מגדירים. לדוגמה, הביטוי request.host.endsWith('.example.com') מקבל את הערך true אם בקשת ה-HTTP נשלחה לסיומת הדומיין example.com.

אופרטורים לוגיים מאפשרים לאמת כמה משתנים בביטוי תנאי. לדוגמה, הביטוי request.method == 'GET' && request.host.matches('.example.com') מצרף שתי הצהרות, והוא יהיה שווה true אם שתי ההצהרות שוות true.

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

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

ביטוי לדוגמה תיאור
x == "foo" הפונקציה מחזירה את הערך true אם x שווה לארגומנט המילולי של המחרוזת הקבועה.
x == R"fo'o" הפונקציה מחזירה את הערך 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 לא קיים, הפונקציה מחזירה שגיאה שגורמת לכך שהכלל שנבדק לא יתאים.
k in m הפונקציה מחזירה את הערך true אם המפתח k נמצא במפה m עם מפתחות מסוג מחרוזת. אחרת, הפונקציה מחזירה false.

אופרטורים לטיפול במחרוזות

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

ביטוי תיאור
x.contains(y) הפונקציה מחזירה true אם המחרוזת x מכילה את מחרוזת המשנה y.
x.startsWith(y) הפונקציה מחזירה את הערך true אם המחרוזת x מתחילה במחרוזת המשנה y.
x.endsWith(y) הפונקציה מחזירה את הערך true אם המחרוזת x מסתיימת במחרוזת המשנה y.
x.matches(y)

הפונקציה מחזירה את הערך true אם המחרוזת x תואמת לתבנית RE2 שצוינה y.

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

בתוספי Edge אפשר להשתמש רק בביטוי רגולרי אחד לכל ביטוי CEL.
x.lower() הפונקציה מחזירה את הערך של המחרוזת x באותיות קטנות.
x.upper() הפונקציה מחזירה את הערך של המחרוזת x באותיות רישיות.
int(x) הפונקציה ממירה את תוצאת המחרוזת של x לסוג int. אפשר להשתמש במחרוזת שהומרה כדי להשוות בין מספרים שלמים באמצעות אופרטורים אריתמטיים רגילים, כמו גדול מ- (>) וקטן מ- או שווה ל- (≤). זה עובד רק עם ערכים שיכולים להיות מספרים שלמים.

ביטויים לדוגמה

התאמה של כל הבקשות למארח example.com עם שירות לקצה העורפי bs1 ב-123 כיעד הסופי:

request.host == "example.com" && request.backend_service_name == "bs1" &&
  request.backend_service_project_number == 123

התאמה של כל הבקשות לנתיב */inventory עם כותרת HTTP‏ Hello. שימו לב ששמות הכותרות לא תלויי-רישיות בהתאמה של CEL:

request.path.endsWith("/inventory") && "Hello" in request.headers

מגבלות

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

  • מספר הביטויים המקסימלי לכל תוסף: 1 לתוספים של Edge ו-5 לתוספים אחרים
  • מספר התווים המקסימלי לכל ביטוי רגולרי: 100
  • מספר התווים המקסימלי לכל ביטוי CEL‏: 500