このドキュメントは、Cloud Monitoring API の projects.alertPolicies、projects.notificationChannels、projects.uptimeCheckConfigs のリファレンス ドキュメントを補足するものです。
API で使用する場合の filter パラメータと orderBy パラメータの構文の詳細を示します。
次の API メソッドは、filter パラメータと orderBy パラメータをサポートします。
次の API メソッドは、filter パラメータのみをサポートしています。
並べ替えとフィルタリングの基本
list オペレーションでの並べ替えとフィルタリングのサポートは、リスト リクエストの本文に filter と orderBy の文字列フィールドが存在することで示されます（リクエストの本文にこれらのフィールドがあるかを確認するには、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 :=
# 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 XXXX」に一致するすべてのエントリを返すには:
display_name=monitoring.regex.full_match('Temp \\d{4}')
正式な仕様
フィルタ式の構文の概要は次のとおりです。
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_]*
サポートされるフィールド
filter フィールドまたは orderBy フィールドで参照されるフィールドは、リストされているオブジェクトの種類によって異なります。
AlertPolicy
AlertPolicy オブジェクトを列挙するときに、次のフィールドは filter と orderBy で参照できます。
- name
- display_name
- documentation.content
- documentation.mime_type
- user_labels
- conditions.size
- combiner
- 有効
- notification_channels
NotificationChannel
NotificationChannel オブジェクトを列挙するときに、次のフィールドは filter と orderBy で参照できます。
- name
- 型
- display_name
- 説明
- ラベル
- 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
高度なトピック
フィールド ケーシング
フィールド名は 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 を使用すると、通知するチャネル数でアラート ポリシーを並べ替えることができます。
バイナリ比較で使用する
さまざまなバイナリ演算子の 1 つを使用してリスト値フィールドをリテラルと比較すると、要素ごとの比較の適用後に結果の 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」に等しいキーが含まれているかどうかを判断できます。
キーによる値の参照
マップエントリは、ドット（.）表記とインデックス（[]）表記の 2 つの表記のうちの 1 つを使用して参照できます。たとえば、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} より大きく {} になります。