Referensi: Mengurutkan dan menyaring data

Dokumen ini melengkapi dokumentasi referensi untuk projects.alertPolicies, projects.notificationChannels, dan projects.uptimeCheckConfigs di Cloud Monitoring API. Kode ini memberikan detail sintaksis parameter filter dan orderBy saat digunakan oleh API.

Metode API berikut mendukung parameter filter dan orderBy:

Metode API berikut hanya mendukung parameter filter:

Dasar-dasar pengurutan dan pemfilteran

Dukungan untuk pengurutan dan pemfilteran dalam operasi list ditunjukkan oleh adanya kolom string filter dan orderBy dalam isi permintaan daftar (lihat dokumentasi referensi API untuk mengetahui apakah isi permintaan memiliki kolom ini atau tidak). Kedua kolom menggunakan bahasa yang sederhana untuk merujuk ke kolom dalam objek yang diurutkan atau difilter.

Sintaksis urutan penyortiran

Kolom orderBy terdiri dari daftar jalur kolom yang dipisahkan koma yang secara opsional diawali dengan tanda minus untuk membalik urutan.

Misalnya, user_label.team,display_name mengurutkan berdasarkan nama tim dalam urutan menaik, lalu -- untuk entri dengan tim yang sama -- mengurutkan berdasarkan nama tampilan, juga dalam urutan menaik. Jika Anda menambahkan tanda minus di depan salah satu kolom yang dipisahkan koma, kolom tersebut diurutkan dalam urutan menurun; misalnya, jika Anda mencoba mengurangi panjang judul, Anda dapat menggunakan -display_name.size untuk mengurutkan berdasarkan panjang judul, dengan objek diurutkan dari judul yang paling rumit ke judul yang paling singkat.

Untuk memberikan contoh yang lebih realistis, user_label.team,display_name mengelompokkan hasil terlebih dahulu berdasarkan tim (dalam urutan leksikografis), lalu, dalam setiap pengelompokan tim, mengatur hasil menurut judul (juga dalam urutan leksikografis).

Secara formal, sintaksis dapat dijelaskan sebagai:

   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 :=
       # 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_]*

Filter sintaksis

Sintaksis filter terdiri dari bahasa ekspresi sederhana untuk membuat predikat dari satu atau beberapa kolom objek yang difilter. Negasi, konjungsi, dan disjungsi ditulis menggunakan kata kunci NOT, AND, dan OR. Kolom dapat dibandingkan dengan nilai literal menggunakan operator : (pembatasan), = (setara), > (lebih besar), < (kurang dari), >= (lebih besar dari atau sama dengan), <= (kurang dari atau sama dengan), dan != (ketidaksetaraan). Fungsi bawaan starts_with, ends_with, monitoring.regex.full_match (sintaksis RE2) serta properti bawaan empty dan size memberikan dukungan untuk perbandingan lanjutan.

Contoh

Untuk menampilkan semua entri dengan nama tampilan atau deskripsi yang tidak kosong, dengan kolom user_labels memiliki kunci active yang ditetapkan (dengan nilai apa pun):

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

Untuk menampilkan semua entri yang deskripsinya berisi 'cloud':

description:'cloud'

Untuk menampilkan semua entri yang judulnya cocok dengan "Temp XXXX":

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

Spesifikasi formal

Sintaksis ekspresi filter dapat diringkas sebagai berikut:

   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 :=
       # 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

   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_]*

Kolom yang didukung

Kolom yang dapat direferensikan di kolom filter atau orderBy bergantung pada jenis objek yang dicantumkan.

AlertPolicy

Kolom berikut dapat direferensikan dalam filter dan orderBy saat menghitung objek AlertPolicy:

  • name
  • display_name
  • documentation.content
  • documentation.mime_type
  • user_labels
  • conditions.size
  • penggabung
  • diaktifkan
  • notification_channels

NotificationChannel

Kolom berikut dapat direferensikan dalam filter dan orderBy saat menghitung objek NotificationChannel:

  • name
  • jenis
  • display_name
  • deskripsi
  • label
  • user_labels

UptimeCheckConfig

Kolom berikut dapat direferensikan di filter saat menghitung objek 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

Topik lanjutan

Huruf besar/kecil kolom

Nama kolom dapat dinyatakan dalam bentuk lower_case_with_underscores dan camelCase. Artinya, display_name dan displayName didukung.

String

Properti bawaan

Kolom bernilai string otomatis memiliki properti size yang dihasilkan, yang menghitung jumlah karakter Unicode dalam string. Tindakan ini akan mengaktifkan, sebagai contoh, filter seperti display_name.size > 3 AND display_name.size < 10. Selain size, string juga memiliki properti empty bool.

Urutan urutan

Saat mencantumkan string dalam orderBy, string akan dibandingkan menggunakan pengurutan leksikografis sesuai byte dalam representasi UTF-8 dari string; string tidak diurutkan sesuai dengan urutan kolasi Unicode.

Konversi bool implisit

Anda dapat secara implisit mengonversi string ke bool dalam filter seperti dalam user_label.enabled. Perhatikan bahwa konversi ini tidak sama dengan pengujian bahwa string tidak kosong; dalam konversi ini, konten string diuraikan menjadi bool dan string yang secara jelas diurai ke pengambilan nilai boolean tersebut; jika string tidak bernilai boolean dengan jelas, maka string yang tidak kosong akan ditafsirkan sebagai benar dan string kosong akan ditafsirkan sebagai salah.

String yang tidak peka huruf besar/kecil cocok dengan "false", "f", "no", "n", atau "0" dianggap salah secara jelas; string yang tidak peka huruf besar/kecil cocok dengan "true", "t", "yes", "y", atau "1" dianggap benar tanpa ambigu.

Daftar

Properti bawaan

Kolom dengan nilai daftar otomatis memiliki properti size yang dihasilkan untuk menghitung jumlah elemen dalam daftar tersebut. Misalnya, Anda dapat menggunakan notification_channels.size di orderBy untuk mengurutkan kebijakan pemberitahuan berdasarkan jumlah saluran yang diberi tahu.

Penggunaan dalam perbandingan biner

Ketika membandingkan kolom bernilai daftar dengan literal menggunakan salah satu dari berbagai operator biner, perbandingan akan ditafsirkan sebagai menerapkan perbandingan berbasis elemen, lalu menghitung OR dari hasilnya. Misalnya, filter notification_channels:"123" akan bernilai benar (true) jika salah satu saluran notifikasi memiliki "123" sebagai substring. Khusus untuk operator !=, perbandingan elemen adalah AND, bukan OR, dengan kata lain, untuk !=, tidak ada elemen yang diizinkan untuk cocok. Atau, untuk menyatakan kembali, x!=y secara logis setara dengan kode pseudo x[0]!=y AND x[1]!=y AND ... AND x[x.size-1]!=y, sedangkan x=y secara logis setara dengan kode pseudo x[0]=y OR x[1]=y OR ... OR x[x.size-1]=y. Inkonsistensi ini dirancang untuk mengatasi kemungkinan intent x!=y dan mencegah kebingungan dengan ekspresi tersebut yang menampilkan hasil yang berisi nilai yang dilarang/difilter.

Selain membatasi daftar secara keseluruhan, Anda juga dapat merujuk ke entri daftar tertentu melalui operator pengindeksan ([]). Misalnya, Anda dapat menggunakan notification_channels[0]:"123" untuk menguji elemen pertama saja. Nilai default (kosong, nol, dll.) akan dihasilkan jika indeks di luar batas akan dihasilkan.

Konversi implisit ke bool

Jika ditentukan dalam filter tanpa perbandingan biner, daftar akan secara implisit dikonversi ke boolean. Konversi ini berbeda dengan pengujian bahwa daftar tidak kosong; a_list dan NOT a_list.empty menampilkan hasil yang berbeda untuk {false, false, false} atau daftar tidak kosong lainnya yang nilainya semua atau secara implisit dikonversi ke nilai boolean false.

Maps

Properti bawaan

Kolom yang bernilai peta secara otomatis memiliki properti size yang dihasilkan, yang menghitung jumlah elemen dalam peta tersebut. Misalnya, Anda dapat menggunakan user_labels.size di orderBy untuk mengurutkan berdasarkan jumlah label pengguna yang ditentukan. Demikian pula, properti empty bernilai boolean juga akan dibuat secara otomatis.

Menguji keberadaan kunci

Maps dapat dibandingkan dengan nilai literal menggunakan berbagai operator biner yang didukung. Penafsiran ini secara logis setara dengan memproyeksikan peta ke dalam daftar dengan mengekstrak kunci peta, lalu menjalankan perbandingan. Untuk memberikan contoh, Anda dapat menggunakan user_labels="phase" untuk menentukan apakah peta user_labels berisi kunci yang nilainya sama dengan "fase".

Mereferensikan nilai berdasarkan kunci

Entri peta dapat direferensikan menggunakan salah satu dari dua notasi: notasi titik (.) dan notasi indeks ([]). Misalnya, Anda dapat menggunakan user_labels.team atau user_labels['team'] untuk merujuk ke nilai yang sesuai dengan "tim" kunci di kolom user_labels. Agar konsisten dengan API metrik yang menggunakan awalan metric.label. dan resource.label., bukan metric.labels. dan resource.labels., kolom peta juga dapat direferensikan menggunakan bentuk tunggal namanya (misalnya, user_label.team juga diizinkan). Perhatikan bahwa untuk kunci bernama size atau empty, Anda harus menggunakan notasi indeks; penggunaan notasi titik akan merujuk pada properti peta bawaan.

Konversi implisit ke bool

Dalam konversi implisit ke bool, peta dianggap benar jika tidak kosong dan setidaknya satu *nilai peta - secara implisit dikonversi ke true. Ini tidak sama dengan pengujian bahwa peta tidak kosong.

Mengurutkan berdasarkan jenis gabungan

Semua kolom yang dapat direferensikan dalam filter juga dapat direferensikan di order_by. Hal ini juga berlaku untuk jenis kompleks dan gabungan. Urutan pengurutan untuk jenis ini stabil dan ditentukan dengan baik, meskipun tidak selalu intuitif; oleh karena itu, penggunaan ini tidak disarankan, tetapi diizinkan.

Daftar

Daftar dibandingkan menggunakan perbandingan leksikografis berbasis elemen, dengan daftar yang lebih kecil berada di urutan pertama jika elemen umumnya sama. Sebagai contoh, {0, 1} kurang dari {0, 2} tetapi lebih besar dari {0}.

Peta

Peta dibandingkan dengan melakukan perbandingan berbasis elemen dari nilai peta yang sesuai dengan gabungan kuncinya. Untuk kunci yang ditentukan dalam satu peta, tetapi tidak di peta yang lain, nilai default (kosong, nol, dll.) akan digunakan untuk perbandingan. Sebagai contoh, {"x":0, "y":0} lebih kecil dari {"x":1, "y":1} tetapi lebih besar dari {"a":-1} dan sama dengan {}.