חומר עזר: מיון וסינון

במאמר הזה מוסבר איך אפשר למיין ולסנן את התוצאות של פקודות רלוונטיות ב-Cloud Monitoring API. מיון מאפשר לכם לציין את הסדר של הרכיבים ברשימת התוצאות. סינון מאפשר להגדיר את המאפיינים של הרכיבים שנכללים ברשימת התוצאות. משתמשים בשדות orderBy ו-filter כדי למיין ולסנן את תגובת ה-API.

בטבלה הבאה מפורטות השיטות של Cloud Monitoring API שתומכות במיון או בסינון:

‏Method	תמיכה במיון	תמיכה בסינון
projects.alertPolicies.list	כן	כן
projects.notificationChannels.list	כן	כן
projects.snoozes.list	לא	כן
projects.uptimeCheckConfig.list	לא	כן

פעולות בסיסיות של מיון וסינון

הנוכחות של שדות המחרוזת orderBy ו-filter בגוף בקשת הרשימה מציינת תמיכה במיון ובסינון בפעולה list. כדי לבדוק אם גוף הבקשה כולל את השדות האלה, אפשר לעיין במסמכי התיעוד של הפניה ל-API.

תחביר של סדר מיון

השדה orderBy מכיל רשימה מופרדת בפסיקים של נתיבי שדות. אפשר להוסיף סימן מינוס לפני הנתיבים כדי להפוך את הסדר.

לדוגמה, user_label.team,display_name מיון של הזמנות לפי שם הצוות בסדר עולה, ואז – עבור רשומות עם אותו צוות – מיון לפי השם לתצוגה, גם בסדר עולה. אם מוסיפים סימן מינוס לפני אחד מהשדות המופרדים באמצעות פסיקים, השדה הזה ממוין בסדר יורד. לדוגמה, אם רוצים לקצר את השמות של האובייקטים, אפשר להשתמש ב--display_name.size כדי למיין לפי אורך השם, כך שהאובייקטים יסודרו מהשם הארוך ביותר לשם הקצר ביותר.

כדי לספק דוגמה מציאותית יותר, user_label.team,display_name קבוצות תוצאות קודם לפי צוות (בסדר לקסיקוגרפי) ואז, בתוך כל קבוצת צוות, מארגנת את התוצאות לפי הכותרת (גם בסדר לקסיקוגרפי).

התחביר יכול להיות מוגדר כך:

   ORDER_BY_SPEC :=
      # Comma-separated list of fields.
      ORDERED_FIELD_LIST

   ORDERED_FIELD_LIST :=
      # Single field on which to sort.
      ORDERED_FIELD

      # Sort by the first field and then by the remaining fields.
      | ORDERED_FIELD "," ORDERED_FIELD_LIST

   ORDERED_FIELD :=
      # Sort by the field in ascending order.
      FIELD_REFERENCE

      # Sort by the field in descending order.
      | "-" FIELD_REFERENCE

   FIELD_REFERENCE :=
      # Simple field reference
      FIELD_NAME

      # Map value or list index lookup. For string-valued keys, the
      # supplied key in this notation must be quoted.
      | FIELD_NAME "[" LITERAL "]"

   FIELD_NAME :=
      # Immediate element
      IDENTIFIER

      # Subfield dereference or map element dereference. Note that,
      # in the case of maps, the IDENTIFIER on the left can also
      # be the singular form of the name of the map. That is, it is
      # permitted to use `user_label.mykey` and not just
      # `user_labels.mykey`. This is done for consistency with the
      # metric filters which permit `resource.label.` and `metric.label.`
      # which are in the singular form even though the map is `labels`.
      | IDENTIFIER "." FIELD_NAME

   LITERAL :=
       # Whole or real number.
       [0-9]+(.[0.9]+)?

       # String literal using single quotes. Note that strings must
       # always be quoted. This is to avoid ambiguity with attempting
       # to refer to the value of a field.
       |  '[^']*'

       # String literal using double quotes. Note that strings must
       # always be quoted. This is to avoid ambiguity with attempting
       # to refer to the value of a field.
       |  "[^"]*"

       # Literal boolean true.
       |  true

       # Literal boolean false.
       |  false

   IDENTIFIER :=
       # Non-digit followed by any number of letters or digits.
       [a-zA-Z_]+[a-zA-Z0-9_]*

תחביר של מסננים

תחביר המסנן מורכב משפת ביטויים לבניית תנאי משדה אחד או יותר של האובייקטים שמסננים. שלילה, קשר וניתוק נכתבים באמצעות מילות המפתח NOT, AND ו-OR. אפשר להשוות בין שדות לבין ערכים מילוליים באמצעות האופרטורים : (הכלה), = (שוויון), > (גדול מ-), < (קטן מ-), >= (גדול מ- או שווה ל-), <= (קטן מ- או שווה ל-) ו-!= (אי-שוויון). הפונקציות המובנות starts_with, ‏ ends_with, ‏ monitoring.regex.full_match (תחביר RE2) והמאפיינים המובנים empty ו-size מספקים תמיכה בהשוואות מתקדמות יותר.

דוגמאות

כדי להחזיר את כל הרשומות עם שם מוצג או תיאור לא ריקים, שבהן השדה user_labels מוגדר עם המפתח active (עם ערך כלשהו):

(NOT display_name.empty OR NOT description.empty) AND user_labels='active'

כדי להחזיר את כל הרשומות שהתיאור שלהן מכיל את המילה cloud:

description:'cloud'

כדי להחזיר את כל הרשומות שהכותרת שלהן תואמת ל-Temp XYZ:

display_name=monitoring.regex.full_match('Temp \\d{3}')

מפרט פורמלי

אפשר לסכם את התחביר של ביטוי הסינון באופן הבא:

   FILTER_EXPRESSION :=
         # Negation
         "NOT" FILTER_EXPRESSION

         # Short-circuiting AND
         | FILTER_EXPRESSION "AND" FILTER_EXPRESSION

         # Short-circuiting OR
         | FILTER_EXPRESSION "OR" FILTER_EXPRESSION

         # Implicit short-circuiting AND
         | FILTER_EXPRESSION FILTER_EXPRESSION

         # Parenthesized sub-expression
         | "(" FILTER_EXPRESSION ")"

         # Basic expression
         | SIMPLE_EXPRESSION

   SIMPLE_EXPRESSION :=
         # Field implicitly converted to boolean
         FIELD_REFERENCE

         # Field binary comparison. Note that the right-hand side must
         # be compatible with the type on the left-hand side; one cannot
         # compare a number with a string. Sensible implicit conversions
         # are permitted, however; comparing an integer and double will
         # succeed with appropriate conversion/widening taking place.
         | FIELD_REFERENCE OP LITERAL

         # Function invocation
         | FIELD_REFERENCE "=" FUNCTION_EXPRESSION


   FIELD_REFERENCE :=
         # Simple field reference
         FIELD_NAME

         # Map value or list index lookup. For string-valued keys, the
         # supplied key in this notation must be quoted.
         | FIELD_NAME "[" LITERAL "]"

   FIELD_NAME :=
         # Immediate element
         IDENTIFIER

         # Subfield dereference or map element dereference. Note that,
         # in the case of maps, the IDENTIFIER on the left can also
         # be the singular form of the name of the map. That is, it is
         # permitted to use `user_label.mykey` and not just
         # `user_labels.mykey`. This is done for consistency with the
         # metric filters which permit `resource.label.` and `metric.label.`
         # which are in the singular form even though the map is `labels`.
         | IDENTIFIER "." FIELD_NAME

   OP :=
         # Equality comparison. Should be avoided for double-valued fields.
         "="

         # Less than.
         | "<"

         # Greater than.
         | ">"

         # Less than or equal.
         | "<="

         # Greater than or equal.
         | ">="

         # Containment. This is equivalent to '=' for numeric types.
         | ":"

         # Not equal.
         | "!="

   LITERAL :=
       # Whole or real number.
       [0-9]+(.[0.9]+)?

       # String literal using single quotes. Note that strings must
       # always be quoted. This is to avoid ambiguity with attempting
       # to refer to the value of a field.
       |  '[^']*'

       # String literal using double quotes. Note that strings must
       # always be quoted. This is to avoid ambiguity with attempting
       # to refer to the value of a field.
       |  "[^"]*"

       # Literal boolean true.
       |  true

       # Literal boolean false.
       |  false

       # Date and Time formatted as per RFC-3339 standards using
       # double quotes.
       |  "YYYY-MM-DDT00:00:00-00:00"

   FUNCTION_EXPRESSION :=
       # Starts with.
       "starts_with" "(" LITERAL ")"

       # Ends with.
       |  "ends_with" "(" LITERAL ")"

       # Has substring. Takes an optional second argument that indicates whether
       # the substring matching is case-sensitive (true) or not (false).
       # The default is false, providing case-insensitive matches.
       |  "has_substring" "(" LITERAL [, [true|false]] ")"

       # Regular expression match.
       |  "monitoring.regex.full_match" "(" LITERAL ")"

   IDENTIFIER :=
       # Non-digit followed by any number of letters or digits.
       [a-zA-Z_]+[a-zA-Z0-9_]*

שדות נתמכים

השדות שאפשר להפנות אליהם בשדות filter או orderBy תלויים בסוג האובייקט שמפורט.

AlertPolicy

אפשר להפנות לשדות הבאים ב-filter וב-orderBy כשמבצעים ספירה של אובייקטים מסוג AlertPolicy:

• name
• display_name
• documentation.content
• documentation.mime_type
• user_labels
• conditions.size
• כלי לשילוב
• מופעל
• notification_channels

NotificationChannel

אפשר להפנות לשדות הבאים ב-filter וב-orderBy כשמבצעים ספירה של אובייקטים מסוג NotificationChannel:

• name
• סוג
• display_name
• description
• labels
• user_labels

UptimeCheckConfig

אפשר להפנות לשדות הבאים ב-filter כשמבצעים ספירה של אובייקטים מסוג UptimeCheckConfig:

• display_name
• user_labels
• selected_regions
• http_check.path
• http_check.headers
• http_check.port
• tcp_check.port
• monitored_resource.type
• monitored_resource.labels

Snoozes

אפשר להפנות לשדות הבאים ב-filter כשמבצעים ספירה של אובייקטים מסוג Snoozes:

• interval.start_time
• interval.end_time

נושאים מתקדמים

בקטע הזה מוסבר איך למיין ולסנן תוצאות של API.

חיפוי השדה

אפשר להשתמש בשמות של שדות גם בפורמט lower_case_with_underscores וגם בפורמט camelCase. כלומר, יש תמיכה גם ב-display_name וגם ב-displayName.

מחרוזות

מאפיינים מובנים

לשדות עם ערך מחרוזת נוצרת באופן אוטומטי מאפיין size שמחשב את מספר תווי ה-Unicode במחרוזת. לדוגמה, זה מאפשר להשתמש במסנן כמו display_name.size > 3 AND display_name.size < 10. בנוסף ל-size, למחרוזות יש גם מאפיין בוליאני empty.

סדר המיון

כשמפרטים מחרוזת ב-orderBy, המחרוזות מושוות באמצעות סדר לקסיקוגרפי לפי בייטים בייצוג UTF-8 של המחרוזת. המחרוזות לא ממוינות לפי סדר איסוף Unicode.

המרה מרומזת לערך בוליאני

אפשר להמיר מחרוזת לערך בוליאני במסנן באופן מרומז, כמו בדוגמה user_label.enabled. שימו לב שההמרה הזו לא זהה לבדיקה שהמחרוזת לא ריקה. במסגרת ההמרה הזו, התוכן של המחרוזת מנותח לערך בוליאני, ומחרוזות שאפשר לנתח באופן חד-משמעי לערך בוליאני מקבלות את הערך הבוליאני הזה. אם המחרוזת לא מכילה ערך בוליאני ברור, מחרוזות לא ריקות מפורשות כ-true ומחרוזות ריקות מפורשות כ-false.

מחרוזות שתואמות לערכים 'false',‏ 'f',‏ 'no',‏ 'n' או '0' (בלי הבדל בין אותיות רישיות לאותיות קטנות) נחשבות לערך false חד-משמעי. מחרוזות שתואמות לערכים 'true',‏ 't',‏ 'yes',‏ 'y' או '1' (בלי הבדל בין אותיות רישיות לאותיות קטנות) נחשבות לערך true חד-משמעי.

רשימות

מאפיינים מובנים

בשדות עם ערכי רשימה נוצר באופן אוטומטי מאפיין size שמחשב את מספר הרכיבים ברשימה. לדוגמה, אפשר להשתמש ב-notification_channels.size ב-orderBy כדי למיין את מדיניות ההתראות לפי מספר הערוצים שהן שולחות להם התראות.

שימוש בהשוואות בינאריות

כשמשווים שדה עם ערך רשימה לליטרל באמצעות אחד מהאופרטורים הבינאריים השונים, ההשוואה מתפרשת כהשוואה של כל רכיב בנפרד, ואז חישוב של OR של התוצאות. לדוגמה, המסנן notification_channels:"123" יחזיר את הערך True אם אחד מערוצי ההתראות מכיל את מחרוזת המשנה '123'. באופרטור !=, ההשוואה בין הרכיבים היא AND ולא OR. במילים אחרות, באופרטור !=, אף אחד מהרכיבים לא יכול להיות זהה. במילים אחרות, הביטוי x!=y שקול מבחינה לוגית לקוד פסאודו x[0]!=y AND x[1]!=y AND ... AND x[x.size-1]!=y, ואילו הביטוי x=y שקול מבחינה לוגית לקוד פסאודו x[0]=y OR x[1]=y OR ... OR x[x.size-1]=y. חוסר העקביות הזה נועד לטפל בכוונה הסבירה של x!=y ולמנוע בלבול עם ביטוי כזה שמחזיר תוצאות שמכילות את הערך המסונן.

בנוסף להגבלת הרשימה כולה, אפשר גם להתייחס לרשומות ספציפיות ברשימה באמצעות אופרטור האינדקס ([]). לדוגמה, אפשר להשתמש ב-notification_channels[0]:"123" כדי לבדוק רק את הרכיב הראשון. ערך ברירת מחדל (ריק, אפס וכו') נוצר במקרה של אינדקסים מחוץ לטווח.

המרה מרומזת ל-bool

כשמציינים רשימה במסנן בלי השוואה בינארית, המערכת ממירה אותה באופן מרומז לערך בוליאני. ההמרה הזו שונה מבדיקה אם הרשימה לא ריקה. הפונקציות a_list ו-NOT a_list.empty מחזירות תוצאות שונות עבור {false, false, false} או כל רשימה לא ריקה אחרת שכל הערכים שלה הם הערך הבוליאני false או מומרים אליו באופן מרומז.

מפות

מאפיינים מובנים

בשדות עם ערך של מפה נוצרת באופן אוטומטי מאפיין size שמחשב את מספר הרכיבים במפה הזו. לדוגמה, אפשר להשתמש ב-user_labels.size ב-orderBy כדי למיין לפי מספר התוויות שהוגדרו למשתמש. באופן דומה, נוצר באופן אוטומטי גם מאפיין empty עם ערך בוליאני.

הערה: אם המפה מכילה מפתח בשם size, צריך להשתמש ב-user_labels.size כדי להתייחס למספר הרכיבים במפה, וב-user_labels['size'] כדי להתייחס לערך של מפתח התווית של המשתמש size. אותו עיקרון חל על המאפיין empty.

בדיקה אם קיים מפתח

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

הפניה לערכים לפי מפתח

אפשר להפנות לערכי המיפוי באמצעות אחד משני סוגי סימון: סימון נקודות (.) וסימון אינדקס ([]). לדוגמה, אפשר להשתמש ב-user_labels.team או ב-user_labels['team'] כדי להתייחס לערך שמתאים למפתח team בשדה user_labels. כדי לשמור על עקביות עם Metrics API, שבו נעשה שימוש בקידומות metric.label. ו-resource.label. במקום metric.labels. ו-resource.labels., אפשר גם להפנות לשדות של מפות באמצעות הצורה היחידה של השם (לדוגמה, אפשר גם להשתמש ב-user_label.team). שימו לב: אם המפתחות נקראים size או empty, צריך להשתמש בסימון אינדקס. שימוש בסימון נקודות יתייחס למאפייני המפה המובנים.

המרה מרומזת ל-bool

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

מיון לפי סוגים מורכבים

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

רשימות

ההשוואה בין הרשימות מתבצעת לפי סדר המילים במילון, כשבמקרה של רכיבים משותפים שווים, הרשימה הקטנה יותר מופיעה ראשונה. לדוגמה, {0, 1} קטן מ-{0, 2} אבל גדול מ-{0}.

מפות Google

ההשוואה בין המפות מתבצעת על ידי השוואה בין הערכים של המפות לפי המפתחות המשותפים שלהן. למפתחות שמוגדרים במיפוי אחד אבל לא במיפוי השני, נעשה שימוש בערך ברירת מחדל (ריק, אפס וכו') לצורך ההשוואה. לדוגמה, {"x":0, "y":0} קטן מ-{"x":1, "y":1} אבל גדול מ-{"a":-1} ושווה ל-{}.