このドキュメントでは、該当する Cloud Monitoring API コマンドの結果を並べ替え、フィルタする方法について説明します。並べ替えでは、結果リスト内の要素の順序を指定できます。フィルタを使用すると、結果のリストに含まれる要素のプロパティを定義できます。orderBy フィールドと filter フィールドを使用して、API レスポンスを並べ替え、フィルタします。
次の表に、並べ替えまたはフィルタをサポートする Cloud Monitoring API メソッドを示します。
| メソッド | 並べ替えをサポート | フィルタをサポート |
|---|---|---|
projects.alertPolicies.list |
はい | はい |
projects.notificationChannels.list |
はい | はい |
projects.snoozes.list |
いいえ | ○ |
projects.uptimeCheckConfig.list |
いいえ | はい |
並べ替えとフィルタの基本
リスト リクエストの本文に orderBy と filter の文字列フィールドがある場合は、list オペレーションで並べ替えとフィルタがサポートされています。リクエスト本文にこれらのフィールドが含まれているかどうかを確認するには、API リファレンス ドキュメントをご覧ください。
並べ替えの構文
orderBy フィールドは、フィールドのパスのカンマ区切りリストで構成されています。先頭にマイナス記号を付けると、順序が逆になります。
たとえば、user_label.team,display_name はチーム名の昇順で並べ替えます。同じチームのエントリは表示名の昇順で並べ替えます。1 つのカンマ区切りのフィールドの前にマイナス記号を追加すると、そのフィールドは降順で並べ替えられます。たとえば、タイトルの冗長さを減らす場合、-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_]*
フィルタの構文
フィルタの構文は、フィルタリングされるオブジェクトの 1 つ以上のフィールドから述語を生成するための式言語で構成されます。否定、結合、分離は、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
次のフィールドは、AlertPolicy オブジェクトを列挙するときに filter と orderBy で参照できます。
- name
- display_name
- documentation.content
- documentation.mime_type
- user_labels
- conditions.size
- combiner
- enabled
- notification_channels
NotificationChannel
次のフィールドは、NotificationChannel オブジェクトを列挙するときに filter と orderBy で参照できます。
- name
- type
- display_name
- description
- labels
- user_labels
UptimeCheckConfig
次のフィールドは、UptimeCheckConfig オブジェクトを列挙するときに filter で参照できます。
- 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
次のフィールドは、Snoozes オブジェクトを列挙するときに filter で参照できます。
- interval.start_time
- interval.end_time
高度なトピック
このセクションでは、API の結果の並べ替えとフィルタについて詳しく説明します。
フィールド ケーシング
フィールド名は lower_case_with_underscores と camelCase の両方の形式で表すことができます。つまり、display_name と displayName の両方がサポートされます。
文字列
組み込みプロパティ
文字列値フィールドには、文字列の Unicode 文字数を計算する size プロパティが自動的に生成されます。これにより、たとえば 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 プロパティが自動的に生成されます。たとえば、orderBy で notification_channels.size を使用すると、通知するチャンネル数でアラート ポリシーを並べ替えることができます。
バイナリ比較で使用する
さまざまなバイナリ演算子の一つを使用してリスト値フィールドをリテラルと比較すると、要素ごとの比較の適用後に結果の OR を計算することで、比較が行われます。たとえば、フィルタ notification_channels:"123" は、いずれかの通知チャンネルの部分文字列が「123」の場合に true と評価します。!= 演算子の場合は特に、要素ごとの比較は OR ではなく AND で行われます。つまり、!= の場合、どの要素も一致しません。言い換えると、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" を使用して最初の要素のみをテストできます。範囲外のインデックスの場合、デフォルト（空、ゼロなど）が生成されます。
ブール値への暗黙的な変換
バイナリ比較を使用せずにフィルタで指定すると、リストは暗黙的にブール値に変換されます。この変換は、リストが空でないことを確認するテストとは異なります。a_list と NOT a_list.empty は、{false, false, false} や、すべての値が暗黙的にブール値 false に変換される空でないリストに対して異なる結果を返します。
マップ
組み込みプロパティ
マップ値フィールドには、マップ内の要素数を算出する size プロパティが自動的に生成されます。たとえば、orderBy で user_labels.size を使用すると、定義したユーザーラベル数で並べ替えることができます。同様に、ブール値の empty プロパティも自動生成されます。
キーの存在のテスト
サポートされているさまざまなバイナリ演算子を使用して、マップをリテラル値と比較できます。この解釈は、マップのキーを抽出して比較を実行することにより、マップをリストに投影することと論理的に同等です。たとえば、user_labels="phase" を使用して、user_labels マップに値が「phase」に等しいキーが含まれているかどうかを確認できます。
キーによる値の参照
マップエントリは、ドット（.）表記とインデックス（[]）表記のいずれかの表記を使用して参照できます。たとえば、user_labels.team または user_labels['team'] を使用して、user_labels フィールドのキー「team」に対応する値を参照できます。metric.labels. と resource.labels. ではなく metric.label. と resource.label. の接頭辞を使用する指標の API との整合性を保つため、マップ フィールドは単一形式の名前でも参照できます（つまり user_label.team も許可されます）。size または empty という名前のキーでは、インデックス表記を使用する必要があります。ドット表記を使用すると、組み込みのマップ プロパティが参照されます。
ブール値への暗黙的な変換
ブール値への暗黙的な変換では、マップが空白でなく、少なくとも 1 つのマップ値が暗黙的に true に変換される場合、マップは true と見なされます。これは、マップが空白でないことを確認するテストと異なります。
混合タイプによる並べ替え
フィルタで参照できるすべてのフィールドは、order_by でも参照できます。これは複合タイプと混合タイプにも適用されます。これらのタイプの並べ替え順序は安定しており、明確に定義されていますが、必ずしも直感的ではありません、これらは使用可能ですが、おすすめしません。
リスト
リストは、要素ごとに辞書順で比較が行われます。共通要素が等しい場合は、小さいほうのリストが先になります。
たとえば、{0, 1} は {0, 2} 未満ですが、{0} よりは大きくなります。
マップ
マップの比較では、キーの結合に対応するマップ値の要素ごとに比較されます。一方のマップで定義されているが、他のマップでは定義されていないキーの場合、比較にデフォルト（空、ゼロなど）が使用されます。たとえば、{"x":0, "y":0} は {"x":1, "y":1} より小さく、{"a":-1} より大きく、{} に等しくなります。