이 문서는 Cloud Monitoring API의 projects.alertPolicies, projects.notificationChannels, projects.uptimeCheckConfigs에 대한 참조 문서를 보완하며,
API가 사용할 때 filter 및 orderBy 매개변수에 대한 구문 세부정보를 제공합니다.
다음 API 메서드는 filter 및 orderBy 매개변수를 지원합니다.
다음 API 메서드는 filter 매개변수만 지원합니다.
정렬 및 필터링 기본
list 작업에서 정렬 및 필터링 지원은 list 요청 본문에서 filter 및 orderBy 문자열 필드가 있음으로 나타냅니다(요청 본문에 이러한 필드가 있는지 확인하려면 API 참조 문서를 참조하세요). 두 필드 모두 저장 또는 필터링되는 객체의 필드를 참조하는 데 단순한 언어를 사용합니다.
정렬 순서 구문
orderBy 필드는 쉼표로 구분된 필드 경로 목록으로 구성되며 선택적으로 순서를 바꾸기 위해 빼기 기호가 붙습니다.
예를 들어 user_label.team,display_name은 팀 이름을 기준으로 오름차순으로 정렬한 다음 동일한 팀의 항목을 표시 이름별로 오름차순으로 정렬합니다. 쉼표로 구분된 필드 앞에 빼기 기호를 추가하면 해당 필드가 내림차순으로 정렬됩니다. 예를 들어 제목의 세부정보 수준을 줄이려는 경우 -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_]*
필터 구문
필터 구문은 필터링되는 객체의 하나 이상의 필드에서 조건자를 구성하기 위한 간단한 표현식 언어로 구성됩니다. 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이 모두 지원됩니다.
문자열
기본 제공 속성
문자열 값 필드에는 문자열의 유니코드 문자 수를 계산하는 size 속성이 자동으로 생성됩니다. 예를 들어 display_name.size > 3 AND display_name.size < 10과 같은 필터를 사용할 수 있습니다.
문자열에는 size 외에도 부울 empty 속성이 있습니다.
정렬 순서
orderBy에 문자열을 나열할 때 문자열은 UTF-8 표현의 바이트별 사전순으로 비교됩니다. 문자열은 유니코드 콜레이션 순서에 따라 정렬되지 않습니다.
암시적 Bool 변환
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로 간주됩니다. != 연산자의 경우, 특히 요소별 비교는 ORed가 아니라 ANDed입니다. 즉, !=의 경우 일치하는 요소가 없습니다. 또는 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"을 사용하여 첫 번째 요소만 테스트할 수 있습니다. 범위를 벗어난 색인의 경우 기본값(빈 값, 0 등)이 생성됩니다.
부울로 암시적 변환
필터를 바이너리 비교 없이 지정하면 목록이 암시적으로 부울로 변환됩니다. 이 변환은 목록이 비어 있지 않은지 테스트하는 것과 다릅니다. a_list와 NOT a_list.empty는 {false, false, false} 또는 모든 값이 부울 값 false이거나 부울 값 false로 암시적으로 변환되는 다른 비어있지 않은 목록에 대해 다른 결과를 반환합니다.
지도
기본 제공 속성
지도 값 필드에는 해당 지도의 요소 수를 계산하는 size 속성이 자동으로 생성됩니다. 예를 들어 orderBy에서 user_labels.size를 사용하여 정의된 사용자 라벨 수에 따라 정렬할 수 있습니다.
마찬가지로 부울 값 empty 속성도 자동 생성됩니다.
키 존재 여부 테스트
지원되는 다양한 바이너리 연산자를 사용하여 지도를 리터럴 값과 비교할 수 있습니다. 해석은 지도의 키를 추출한 다음 비교를 실행하여 지도를 목록에 투영하는 것과 논리적으로 동일합니다.
예를 들어 user_labels="phase"를 사용하여 user_labels 지도에 값이 '단계'와 같은 키가 포함되어 있는지 확인할 수 있습니다.
키로 값 참조
지도 항목은 점(.) 표기법과 색인([]) 표기법 중 하나를 사용하여 참조할 수 있습니다. 예를 들어 user_labels.team 또는 user_labels['team']를 사용하여 user_labels 필드의 키 'team'에 해당하는 값을 참조할 수 있습니다. metric.labels. 및 resource.labels. 대신 metric.label. 및 resource.label. 프리픽스를 사용하는 측정항목 API와의 일관성을 위해 지도 필드는 이름의 단수형(예: user_label.team은 허용됨)을 사용하여 참조될 수 있습니다.
size 또는 empty라는 키에는 색인 표기법을 사용해야 합니다. 점 표기법을 사용하면 기본 제공 지도 속성이 참조됩니다.
부울로 암시적 변환
부울로 암시적 변환에서 지도가 비어 있지 않고 하나 이상의 지도 *값이 암시적으로 true로 변환되는 경우 true로 간주됩니다. 이는 지도가 비어 있지 않은지 테스트하는 것과는 다릅니다.
복합 유형으로 정렬
필터에서 참조할 수 있는 모든 필드는 order_by에서도 참조될 수 있습니다. 이는 복잡한 복합 유형에도 적용됩니다. 이러한 유형의 정렬 순서는 반드시 직관적이지는 않지만 안정적이며 명확하게 정의되어 있습니다. 따라서 이 사용은 권장되지는 않지만 허용됩니다.
목록
목록은 요소별 사전형 비교를 통해 비교되며 공통 요소가 동일한 경우 작은 목록이 먼저 표시됩니다.
예를 들어 {0, 1}은 {0, 2}보다 작지만 {0}보다 큽니다.
지도
지도는 키의 합집합에 해당하는 지도 값을 요소별로 수행하며 비교합니다. 한 지도에서는 정의되지만 다른 지도에서는 정의되지 않은 키의 경우 기본값(비어 있음, 0 등)이 비교에 사용됩니다.
예를 들어 {"x":0, "y":0}은 {"x":1, "y":1}보다 작지만 {"a":-1}보다 크고 {}와 같습니다.