이 페이지에서는 필터를 사용하여 Pub/Sub 구독을 만드는 방법을 설명합니다.
필터를 사용하여 구독에서 메시지를 수신할 때는 필터와 일치하는 메시지만 수신됩니다. Pub/Sub 서비스는 필터와 일치하지 않는 메시지를 자동으로 확인합니다. 메시지의 데이터가 아닌 속성에 따라 메시지를 필터링할 수 있습니다.
주제에 여러 구독을 연결할 수 있고 각 구독은 서로 다른 필터를 포함할 수 있습니다.
예를 들어 전 세계 여러 지역에서 뉴스를 수신하는 주제가 있으면 특정 리전에서만 게시되는 뉴스를 필터링하도록 구독을 구성할 수 있습니다. 이 구성의 경우 주제 메시지 속성 중 하나가 뉴스 게시 리전을 전달하는지 확인해야 합니다.
필터가 포함된 구독에서 메시지를 받으면 Pub/Sub가 자동으로 확인하는 메시지에 대한 아웃바운드 메시지 요금이 발생하지 않습니다. 이러한 메시지에는 메시지 전송 요금 및 탐색 관련 스토리지 요금이 부과됩니다.
필터로 구독 만들기
Pull 및 Push 구독은 필터를 포함할 수 있습니다. 모든 구독자는 StreamingPull API를 사용하는 구독자를 포함하여 필터를 사용하여 구독에서 메시지를 수신할 수 있습니다.
Google Cloud 콘솔, Google Cloud CLI, 클라이언트 라이브러리 또는 Pub/Sub API를 사용하여 필터로 구독을 만들 수 있습니다.
콘솔
필터로 Pull 구독을 만들려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 구독 페이지로 이동합니다.
구독 만들기를 클릭합니다.
구독 ID를 입력합니다.
드롭다운 메뉴에서 하나의 주제를 선택하거나 만듭니다. 구독은 주제에서 메시지를 수신합니다.
구독 필터 섹션에서 필터 표현식을 입력합니다.
만들기를 클릭합니다.
필터로 Push 구독을 만들려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 구독 페이지로 이동합니다.
구독 만들기를 클릭합니다.
구독 ID를 입력합니다.
드롭다운 메뉴에서 하나의 주제를 선택하거나 만듭니다. 구독은 주제에서 메시지를 수신합니다.
전송 유형 섹션에서 Push를 클릭합니다.
엔드포인트 URL 필드에서 Push 엔드포인트의 URL을 입력합니다.
구독 필터 섹션에서 필터 표현식을 입력합니다.
만들기를 클릭합니다.
gcloud
필터로 Pull 구독을 만들려면 gcloud pubsub subscriptions create
명령어를 --message-filter
플래그와 함께 사용합니다.
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --message-filter='FILTER'
다음을 바꿉니다.
- SUBSCRIPTION_ID: 생성할 구독의 ID
- TOPIC_ID: 구독에 연결할 주제의 ID
- FILTER: 필터링 구문의 표현식
필터로 Push 구독을 만들려면 gcloud pubsub subscriptions create
명령어를 --push-endpoint
및 --message-filter
플래그와 함께 사용합니다.
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --push-endpoint=PUSH_ENDPOINT \ --message-filter='FILTER'
다음을 바꿉니다.
- SUBSCRIPTION_ID: 생성할 구독의 ID
- TOPIC_ID: 구독에 연결할 주제의 ID
- PUSH_ENDPOINT: 푸시 구독자가 실행되는 서버의 URL
- FILTER: 필터링 구문의 표현식
REST
필터로 구독을 만들려면 projects.subscriptions.create
메서드를 사용합니다.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
다음을 바꿉니다.
- PROJECT_ID: 구독을 만들려는 프로젝트의 프로젝트 ID
- SUBSCRIPTION_ID: 생성할 구독의 ID
필터로 Pull 구독을 만들려면 요청 본문에 필터를 지정합니다.
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "filter": "FILTER" }
다음을 바꿉니다.
- PROJECT_ID: 주제가 있는 프로젝트의 프로젝트 ID
- TOPIC_ID: 구독에 연결할 주제의 ID
- FILTER: 필터링 구문의 표현식
필터로 Push 구독을 만들려면 Push 엔드포인트 및 필터를 요청 본문에 지정합니다.
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "pushConfig": { "pushEndpoint": "PUSH_ENDPOINT" }, "filter": "FILTER" }
다음을 바꿉니다.
- PROJECT_ID: 주제가 있는 프로젝트의 프로젝트 ID
- TOPIC_ID: 구독에 연결할 주제의 ID
- PUSH_ENDPOINT: 푸시 구독자가 실행되는 서버의 URL
- FILTER: 필터링 구문의 표현식
C++
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 C++ 설정 안내를 따르세요. 자세한 내용은 Pub/Sub C++ API 참고 문서를 확인하세요.
C#
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 Pub/Sub C# API 참조 문서를 확인하세요.
Go
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Go API 참고 문서를 참조하세요.
자바
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 Pub/Sub 자바 API 참조 문서를 참조하세요.
Node.js
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Node.js API 참조 문서를 참조하세요.
Node.js
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Node.js API 참조 문서를 참조하세요.
PHP
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 PHP 설정 안내를 따르세요. 자세한 내용은 Pub/Sub PHP API 참조 문서를 참조하세요.
Python
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Python API 참조 문서를 참조하세요.
Ruby
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Ruby 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Ruby API 참고 문서를 참조하세요.
필터의 최대 길이는 256바이트입니다. 필터는 변경할 수 없는 구독 속성입니다. 구독을 만든 후에는 필터를 수정하기 위해 구독을 업데이트할 수 없습니다.
필터가 백로그 측정항목에 미치는 영향
방금 만든 구독을 모니터링하려면 필터를 사용한 구독 모니터링을 참조하세요.
필터링을 사용 설정한 경우 백로그 측정항목에는 필터와 일치하는 메시지의 데이터만 포함됩니다. 다음은 백로그 측정항목 목록입니다.
subscription/backlog_bytes
subscription/unacked_bytes_by_region
subscription/num_undelivered_messages
subscription/num_unacked_messages_by_region
subscription/oldest_unacked_message_age
subscription/oldest_unacked_message_age_by_region
topic/unacked_bytes_by_region
topic/num_unacked_messages_by_region
topic/oldest_unacked_messages_age_by_region
이러한 측정항목에 대해 자세히 알아보려면 Pub/Sub 측정항목 목록을 참조하세요.
구독 필터 업데이트
기존 구독의 필터는 업데이트할 수 없습니다. 대신 이 해결 방법을 따르세요.
필터를 변경할 구독의 스냅샷을 만듭니다.
콘솔을 사용하여 스냅샷을 만드는 방법에 대한 자세한 내용은 스냅샷 만들기를 참조하세요.
새 필터로 새 구독을 만듭니다.
필터로 구독을 만드는 방법에 대한 자세한 내용은 필터로 구독 만들기를 참조하세요.
Google Cloud 콘솔에서 Pub/Sub 구독 페이지로 이동합니다.
방금 만든 구독을 클릭합니다.
구독 세부정보 페이지에서 메시지 다시보기를 클릭합니다.
탐색에서 스냅샷까지를 클릭합니다.
1단계에서 원래 구독에 대해 만든 스냅샷을 선택한 후 탐색을 클릭합니다.
전환 중에 메시지가 손실되지 않습니다.
새 구독을 사용하도록 구독자를 변경합니다.
이 절차를 완료한 후에는 원래 구독을 삭제할 수 있습니다.
필터를 만드는 구문
메시지를 필터링하려면 속성으로 작동하는 표현식을 작성합니다. 속성의 키 또는 값과 일치하는 표현식을 작성할 수 있습니다. attributes
식별자는 메시지의 속성을 선택합니다.
예를 들어 다음 테이블의 필터는 name
속성을 선택합니다.
필터 | 설명 |
---|---|
attributes:name |
name 속성이 있는 메시지 |
NOT attributes:name |
name 속성이 없는 메시지 |
attributes.name = "com" |
name 속성 및 com 값이 있는 메시지 |
attributes.name != "com" |
name 속성 및 com 값이 없는 메시지 |
hasPrefix(attributes.name, "co") |
name 속성 및 co 로 시작하는 값이 있는 메시지 |
NOT hasPrefix(attributes.name, "co") |
name 속성이 없고 co 로 시작하는 값이 있는 메시지 |
필터 표현식의 비교 연산자
다음 비교 연산자를 사용하여 속성을 필터링할 수 있습니다.
:
=
!=
:
연산자는 속성 목록에서 일치하는 키를 찾습니다.
attributes:KEY
등호 연산자는 일치하는 키와 값을 찾습니다. 값은 문자열 리터럴이어야 합니다.
attributes.KEY = "VALUE"
등호 연산자가 있는 표현식은 키로 시작해야 하며 등호 연산자는 키와 값을 비교해야 합니다.
유효: 필터가 키와 값을 비교합니다.
attributes.name = "com"
유효하지 않음: 필터의 왼쪽 측면이 값입니다.
"com" = attributes.name
유효하지 않음: 필터가 두 키를 비교합니다.
attributes.name = attributes.website
키와 값은 대소문자를 구분하며 속성과 정확하게 일치해야 합니다. 키에 하이픈, 밑줄, 영숫자 문자 이외의 문자가 포함된 경우 문자열 리터럴을 사용합니다.
attributes."iana.org/language_tag" = "en"
필터에 백슬래시, 따옴표, 인쇄되지 않는 문자를 사용하려면 문자열 리터럴 내에서 문자를 이스케이프합니다. 문자열 리터럴 내에서 유니코드, 16진수, 8진수 이스케이프 시퀀스를 사용할 수도 있습니다.
유효: 필터가 문자열 리터럴 내의 문자를 이스케이프합니다.
attributes:"\u307F\u3093\u306A"
유효하지 않음: 필터가 문자열 리터럴 없이 문자를 이스케이프합니다.
attributes:\u307F\u3093\u306A
필터 표현식의 불리언 연산자
필터에 부울 연산자 AND
, NOT
, OR
를 사용할 수 있습니다. 연산자는 대문자여야 합니다. 예를 들어 다음 필터는 iana.org/language_tag
속성이 있고 name
속성과 com
값이 없는 메시지에 사용됩니다.
attributes:"iana.org/language_tag" AND NOT attributes.name = "com"
NOT
연산자의 우선순위가 가장 높습니다. AND
및 OR
연산자를 결합하려면 괄호와 완전한 표현식을 사용합니다.
유효:
AND
및OR
연산자(괄호 포함)attributes:"iana.org/language_tag" AND (attributes.name = "net" OR attributes.name = "org")
유효하지 않음: 괄호 없는
AND
및OR
연산자attributes:"iana.org/language_tag" AND attributes.name = "net" OR attributes.name = "org"
유효하지 않음:
AND
연산자와OR
연산자가 불완전한 표현식을 결합함attributes.name = "com" AND ("net" OR "org")
NOT
연산자 대신 단항 뺄셈 연산자를 사용할 수도 있습니다.
attributes.name = "com" AND -attributes:"iana.org/language_tag"
필터 표현식의 함수
hasPrefix
함수를 사용하여 하위 문자열로 시작하는 값이 있는 속성을 필터링할 수 있습니다. hasPrefix
는 필터에서 지원되는 유일한 함수입니다.
hasPrefix
함수에서는 프리픽스 일치가 지원되지만 일반 정규 표현식이 지원되지 않습니다.
hasPrefix(attributes.KEY, "SUBSTRING")
다음을 바꿉니다.
- KEY: 속성의 이름
- SUBSTRING: 값의 하위 문자열