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 {}
.