메시지 필터링

이 페이지에서는 필터를 사용하여 구독을 만드는 방법을 설명합니다.

필터를 사용하여 구독에서 메시지를 수신할 때는 필터와 일치하는 메시지만 수신됩니다. Pub/Sub 서비스는 필터와 일치하지 않는 메시지를 자동으로 확인합니다. 속성으로 메시지를 필터링할 수 있습니다.

필터가 포함된 구독에서 메시지를 받으면 Pub/Sub가 자동으로 확인하는 메시지에 대한 이그레스 요금이 발생하지 않습니다. 이러한 메시지에는 메시지 전송 요금 및 탐색 관련 스토리지 요금이 부과됩니다.

필터로 구독 만들기

Pull 및 Push 구독은 필터를 포함할 수 있습니다. 모든 구독자는 StreamingPull API를 사용하는 구독자를 포함하여 필터를 사용하여 구독에서 메시지를 수신할 수 있습니다.

Cloud Console, gcloud 명령줄 도구 또는 Pub/Sub API를 사용하여 필터로 구독을 만들 수 있습니다.

Console

필터로 Pull 구독을 만들려면 다음 단계를 따르세요.

  1. Cloud Console에서 구독 페이지로 이동합니다.

    구독 페이지로 이동

  2. 구독 만들기를 클릭합니다.

  3. 구독 ID를 입력합니다.

  4. 드롭다운 메뉴에서 하나의 주제를 선택하거나 만듭니다. 구독은 주제에서 메시지를 수신합니다.

  5. 구독 필터 섹션에서 필터 표현식을 입력합니다.

  6. 만들기를 클릭합니다.

필터로 Push 구독을 만들려면 다음 단계를 따르세요.

  1. Cloud Console에서 구독 페이지로 이동합니다.

    구독 페이지로 이동

  2. 구독 만들기를 클릭합니다.

  3. 구독 ID를 입력합니다.

  4. 드롭다운 메뉴에서 하나의 주제를 선택하거나 만듭니다. 구독은 주제에서 메시지를 수신합니다.

  5. 전송 유형 섹션에서 Push를 클릭합니다.

  6. 엔드포인트 URL 필드에서 Push 엔드포인트의 URL을 입력합니다.

  7. 구독 필터 섹션에서 필터 표현식을 입력합니다.

  8. 만들기를 클릭합니다.

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: 필터링 구문의 표현식

필터의 최대 길이는 256바이트입니다. 구독을 만든 후에는 필터를 수정할 수 없습니다. 백로그 측정항목에는 필터와 일치하지 않는 메시지가 포함될 수 있습니다.

필터링 구문

메시지를 필터링하려면 속성으로 작동하는 표현식을 작성합니다. 속성의 키 또는 값과 일치하는 표현식을 작성할 수 있습니다. attributes 식별자는 메시지의 속성을 선택합니다.

예를 들어 다음 테이블의 필터는 domain 속성을 선택합니다.

필터 설명
attributes:domain domain 속성이 있는 메시지
NOT attributes:domain domain 속성이 없는 메시지
attributes.domain = "com" domain 속성 및 com 값이 있는 메시지
attributes.domain != "com" domain 속성 및 com 값이 없는 메시지
hasPrefix(attributes.domain, "co") domain 속성 및 co로 시작하는 값이 있는 메시지
NOT hasPrefix(attributes.domain, "co") domain 속성이 없고 co로 시작하는 값이 있는 메시지

비교 연산자

다음 비교 연산자를 사용하여 속성을 필터링할 수 있습니다.

  • :
  • =
  • !=

: 연산자는 속성 목록에서 일치하는 키를 찾습니다.

attributes:KEY

등호 연산자는 일치하는 키와 값을 찾습니다. 값은 문자열 리터럴이어야 합니다.

attributes.KEY = "VALUE"

등호 연산자가 있는 표현식은 키로 시작해야 하며 등호 연산자는 키와 값을 비교해야 합니다.

  • 유효: 필터가 키와 값을 비교합니다.

    attributes.domain = "com"
    
  • 유효하지 않음: 필터의 왼쪽 측면이 값입니다.

    "com" = attributes.domain
    
  • 유효하지 않음: 필터가 두 키를 비교합니다.

    attributes.domain = attributes.website
    

키와 값은 대소문자를 구분하며 속성과 정확하게 일치해야 합니다. 키에 하이픈, 밑줄, 영숫자 문자 이외의 문자가 포함된 경우 문자열 리터럴을 사용합니다.

attributes."iana.org/language_tag" = "en"

필터에 백슬래시, 따옴표, 인쇄되지 않는 문자를 사용하려면 문자열 리터럴 내에서 문자를 이스케이프합니다. 문자열 리터럴 내에서 유니코드, 16진수, 8진수 이스케이프 시퀀스를 사용할 수도 있습니다.

  • 유효: 필터가 문자열 리터럴 내의 문자를 이스케이프합니다.

    attributes:"\u307F\u3093\u306A"
    
  • 유효하지 않음: 필터가 문자열 리터럴 없이 문자를 이스케이프합니다.

    attributes:\u307F\u3093\u306A
    

부울 연산자

필터에 부울 연산자를 사용할 수 있습니다. 예를 들어 다음 필터는 iana.org/language_tag 속성이 있는 메시지용이지만, domain 속성과 com 값이 없는 메시지에 사용됩니다.

attributes:"iana.org/language_tag" AND NOT attributes.domain = "com"

NOT 연산자의 우선순위가 가장 높습니다. ANDOR 연산자를 결합하려면 괄호와 완전한 표현식을 사용합니다.

  • 유효: ANDOR 연산자(괄호 포함)

    attributes:"iana.org/language_tag" AND (attributes.domain = "net" OR attributes.domain = "org")
    
  • 유효하지 않음: 괄호 없는 ANDOR 연산자

    attributes:"iana.org/language_tag" AND attributes.domain = "net" OR attributes.domain = "org"
    
  • 유효하지 않음: AND 연산자와 OR 연산자가 불완전한 표현식을 결합함

    attributes.domain = "com" AND ("net" OR "org")
    

NOT 연산자 대신 단항 뺄셈 연산자를 사용할 수도 있습니다.

attributes.domain = "com" AND -attributes:"iana.org/language_tag"

함수

hasPrefix 함수는 하위 문자열로 시작하는 값이 있는 속성을 필터링합니다.

hasPrefix(attributes.KEY, "SUBSTRING")

다음을 바꿉니다.

  • KEY: 속성의 이름
  • SUBSTRING: 값의 하위 문자열