Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Referensi: Menyortir dan memfilter

Dokumen ini menjelaskan cara Anda dapat mengurutkan dan memfilter hasil perintah Cloud Monitoring API yang berlaku. Pengurutan memungkinkan Anda menentukan urutan elemen dalam daftar hasil. Pemfilteran memungkinkan Anda menentukan properti elemen yang disertakan dalam daftar hasil. Anda menggunakan kolom orderBy dan filter untuk mengurutkan dan memfilter respons API.

Tabel berikut mencantumkan metode Cloud Monitoring API yang mendukung pengurutan atau pemfilteran:

Metode	Mendukung pengurutan	Mendukung pemfilteran
`projects.alertPolicies.list`	Ya	Ya
`projects.notificationChannels.list`	Ya	Ya
`projects.snoozes.list`	Tidak	Ya
`projects.uptimeCheckConfig.list`	Tidak	Ya

Dasar-dasar pengurutan dan pemfilteran

Keberadaan kolom string orderBy dan filter di isi permintaan daftar menunjukkan dukungan untuk pengurutan dan pemfilteran dalam operasi list. Lihat dokumentasi referensi API untuk menentukan apakah isi permintaan menyertakan kolom ini.

Sintaksis urutan penyortiran

Kolom orderBy terdiri dari daftar jalur kolom yang dipisahkan koma yang secara opsional diberi awalan tanda minus untuk membalikkan urutan.

Misalnya, user_label.team,display_name mengurutkan menurut nama tim dalam urutan menaik, lalu -- untuk entri dengan tim yang sama -- mengurutkan menurut nama tampilan, juga dalam urutan menaik. Jika Anda menambahkan tanda minus di depan salah satu kolom yang dipisahkan koma, kolom tersebut akan 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 panjang hingga judul yang paling singkat.

Untuk memberikan contoh yang lebih realistis, user_label.team,display_name mengelompokkan hasil terlebih dahulu menurut tim (dalam urutan leksikografis), lalu, dalam setiap pengelompokan tim, mengelola 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 :=
       # 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_]*

Filter sintaksis

Sintaksis filter terdiri dari bahasa ekspresi 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 : (berisi), = (kesetaraan), > (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 yang lebih canggih.

Contoh

Untuk menampilkan semua entri dengan nama tampilan atau deskripsi yang tidak kosong jika kolom user_labels memiliki setelan kunci active (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 XYZ":

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

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

Kolom yang didukung

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

`AlertPolicy`

Kolom berikut dapat dirujuk di filter dan orderBy saat mencantumkan objek AlertPolicy:

nama
display_name
documentation.content
documentation.mime_type
user_labels
conditions.size
penggabung
diaktifkan
notification_channels

`NotificationChannel`

Kolom berikut dapat dirujuk di filter dan orderBy saat mencantumkan objek NotificationChannel:

nama
jenis
display_name
deskripsi
labels
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

`Snoozes`

Kolom berikut dapat direferensikan di filter saat menghitung objek Snoozes:

interval.start_time
interval.end_time

Topik lanjutan

Bagian ini memberikan informasi selengkapnya tentang pengurutan dan pemfilteran hasil API.

Casing kolom

Nama kolom dapat dinyatakan dalam bentuk lower_case_with_underscores dan dalam bentuk 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. Hal ini memungkinkan, misalnya, filter seperti display_name.size > 3 AND display_name.size < 10. Selain size, string juga memiliki properti bool empty.

Urutan pengurutan

Saat mencantumkan string dalam orderBy, string dibandingkan menggunakan urutan leksikografis byte demi byte dalam representasi UTF-8 string; string tidak diurutkan menurut urutan kolasi Unicode.

Konversi bool implisit

String dapat dikonversi secara implisit menjadi bool dalam filter seperti pada user_label.enabled. Perhatikan bahwa konversi ini tidak identik dengan pengujian bahwa string tidak kosong; dalam konversi ini, konten string diuraikan ke bool dan string yang secara jelas diuraikan ke boolean mengambil nilai boolean tersebut; jika string tidak jelas bernilai boolean, maka string yang tidak kosong ditafsirkan sebagai benar dan string kosong ditafsirkan sebagai salah.

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

Daftar

Properti bawaan

Kolom bernilai daftar otomatis memiliki properti size yang dihasilkan yang 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

Saat membandingkan kolom bernilai daftar dengan literal menggunakan salah satu dari berbagai operator biner, perbandingan ditafsirkan sebagai penerapan perbandingan per elemen, lalu menghitung OR dari hasilnya. Misalnya, filter notification_channels:"123" akan dievaluasi sebagai benar jika salah satu channel notifikasi memiliki "123" sebagai substring. Khusus untuk operator !=, perbandingan per elemen di-AND-kan, bukan di-OR-kan; dengan kata lain, untuk !=, tidak ada elemen yang diizinkan untuk cocok. Atau, dengan kata lain, x!=y secara logis setara dengan pseudo-code x[0]!=y AND x[1]!=y AND ... AND x[x.size-1]!=y, sedangkan x=y secara logis setara dengan pseudo-code x[0]=y OR x[1]=y OR ... OR x[x.size-1]=y. Ketidakkonsistenan ini dirancang untuk menangani kemungkinan maksud x!=y dan mencegah kebingungan dengan ekspresi yang menampilkan hasil yang berisi nilai yang difilter.

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

Konversi implisit ke bool

Jika ditentukan dalam filter tanpa perbandingan biner, daftar akan dikonversi secara implisit menjadi 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 semua nilainya adalah atau secara implisit dikonversi menjadi nilai boolean false.

Maps

Properti bawaan

Kolom 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 menurut jumlah label pengguna yang ditentukan. Demikian pula, properti empty bernilai boolean juga dibuat secara otomatis.

Menguji keberadaan kunci

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

Mereferensikan nilai menurut kunci

Entri peta dapat dirujuk 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 kunci "team" di kolom user_labels. Agar konsisten dengan Metrics API yang menggunakan awalan metric.label. dan resource.label., bukan metric.labels. dan resource.labels., kolom peta juga dapat dirujuk menggunakan bentuk tunggal nama (misalnya, user_label.team juga diizinkan). Perhatikan bahwa untuk kunci yang bernama size atau empty, Anda harus menggunakan notasi indeks; menggunakan notasi titik akan merujuk ke properti peta bawaan.

Konversi implisit ke bool

Dalam konversi implisit ke bool, peta dianggap benar jika tidak kosong dan setidaknya satu *nilai peta - dikonversi secara implisit menjadi benar. Hal ini tidak sama dengan menguji bahwa peta tidak kosong.

Mengurutkan menurut jenis gabungan

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

Daftar

Daftar dibandingkan menggunakan perbandingan leksikografis per elemen, dengan daftar yang lebih kecil muncul terlebih dahulu jika elemen umumnya sama. Sebagai contoh, {0, 1} kurang dari {0, 2}, tetapi lebih besar dari {0}.

Maps

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

Referensi: Menyortir dan memfilter Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Dasar-dasar pengurutan dan pemfilteran

Sintaksis urutan penyortiran

Filter sintaksis

Contoh

Spesifikasi formal

Kolom yang didukung

AlertPolicy

NotificationChannel

UptimeCheckConfig

Snoozes

Topik lanjutan

Casing kolom

String

Daftar

Maps

Mengurutkan menurut jenis gabungan

Referensi: Menyortir dan memfilter

`AlertPolicy`

`NotificationChannel`

`UptimeCheckConfig`

`Snoozes`