סינון הודעות ממינוי

בדף הזה מוסבר איך ליצור מינויים ל-Pub/Sub עם מסננים.

כשמקבלים הודעות מרשימת תפוצה עם מסנן, מקבלים רק את ההודעות שתואמות למסנן. שירות Pub/Sub מאשר באופן אוטומטי את ההודעות שלא תואמות למסנן. אפשר לסנן הודעות לפי המאפיינים שלהן, אבל לא לפי הנתונים בהודעה.

אפשר להוסיף כמה מינויים לנושא, ולכל מינוי יכול להיות פילטר שונה.

לדוגמה, אם יש לכם נושא שמקבל חדשות מחלקים שונים בעולם, אתם יכולים להגדיר מינוי לסינון חדשות שפורסמו רק מאזור מסוים. בהגדרה הזו, צריך לוודא שאחד ממאפייני ההודעה בנושא מציין את האזור שבו מתפרסמת הידיעה.

כשמקבלים הודעות ממינוי עם מסנן, לא חלים תשלומים על הודעות יוצאות על ההודעות שהמערכת של Pub/Sub מאשרת באופן אוטומטי. תחויבו בדמי מסירת הודעות ובדמי אחסון שקשורים לחיפוש עבור ההודעות האלה.

יצירת מינוי עם מסנן

אפשר להוסיף מסננים למינויים מסוג 'שליפה' ו'דחיפה'. כל המנויים יכולים לקבל הודעות ממינויים עם מסננים, כולל מנויים שמשתמשים ב-StreamingPull API.

אפשר ליצור מינוי עם מסנן באמצעות מסוף Google Cloud , Google Cloud CLI, ספריות הלקוח או Pub/Sub API.

המסוף

כדי ליצור מינוי שליפה עם מסנן:

1. נכנסים לדף Subscriptions במסוף Google Cloud .

   כניסה לדף 'מינויים'

2. לוחצים על יצירת מינוי.

3. מזינים את מזהה המינוי.

4. בוחרים נושא מהתפריט הנפתח או יוצרים נושא חדש. המינוי מקבל הודעות מהנושא.

5. בקטע Subscription filter, מזינים את ביטוי הסינון.

6. לוחצים על יצירה.

כדי ליצור מינוי דחיפה עם מסנן:

1. נכנסים לדף Subscriptions במסוף Google Cloud .

   כניסה לדף 'מינויים'

2. לוחצים על יצירת מינוי.

3. מזינים את מזהה המינוי.

4. בוחרים נושא מהתפריט הנפתח או יוצרים נושא חדש. המינוי מקבל הודעות מהנושא.

5. בקטע סוג המסירה, לוחצים על דחיפה.

6. בשדה כתובת URL של נקודת קצה, מזינים את כתובת ה-URL של נקודת הקצה של ה-push.

7. בקטע Subscription filter, מזינים את ביטוי הסינון.

8. לוחצים על יצירה.

gcloud

כדי ליצור מינוי מסוג pull עם מסנן, משתמשים בפקודה gcloud pubsub subscriptions create עם הדגל --message-filter:

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=TOPIC_ID \
  --message-filter='FILTER'

מחליפים את מה שכתוב בשדות הבאים:

• ‫SUBSCRIPTION_ID: המזהה של המינוי שרוצים ליצור
• ‫TOPIC_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: המזהה של המינוי שרוצים ליצור
• ‫TOPIC_ID: המזהה של הנושא לצירוף למינוי
• ‫PUSH_ENDPOINT: כתובת ה-URL של השרת שבו פועל המנוי לקבלת עדכונים
• ‫FILTER: ביטוי בתחביר הסינון

REST

כדי ליצור מינוי עם מסנן, משתמשים ב-method‏ projects.subscriptions.create.

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer $(gcloud auth print-access-token)

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט שבו רוצים ליצור את המינוי
• ‫SUBSCRIPTION_ID: המזהה של המינוי שרוצים ליצור

כדי ליצור מינוי שליפה עם מסנן, מציינים את המסנן בגוף הבקשה:

{
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  "filter": "FILTER"
}

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט של הפרויקט עם הנושא
• ‫TOPIC_ID: המזהה של הנושא לצירוף למינוי
• ‫FILTER: ביטוי בתחביר הסינון

כדי ליצור מינוי דחיפה עם מסנן, מציינים את נקודת הקצה של הדחיפה ואת המסנן בגוף הבקשה:

{
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  "pushConfig": {
    "pushEndpoint": "PUSH_ENDPOINT"
  },
  "filter": "FILTER"
}

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט של הפרויקט עם הנושא
• ‫TOPIC_ID: המזהה של הנושא לצירוף למינוי
• ‫PUSH_ENDPOINT: כתובת ה-URL של השרת שבו פועל המנוי לקבלת עדכונים
• ‫FILTER: ביטוי בתחביר הסינון

C++‎

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של C++‎ במאמר תחילת העבודה המהירה: שימוש בספריות לקוח. מידע נוסף זמין במאמרי העזרה של Pub/Sub C++ API.

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string topic_id,
   std::string subscription_id) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, std::move(subscription_id))
          .FullName());
  request.set_topic(
      pubsub::Topic(project_id, std::move(topic_id)).FullName());
  request.set_filter(R"""(attributes.is-even = "false")""");
  auto sub = client.CreateSubscription(request);
  if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
    std::cout << "The subscription already exists\n";
    return;
  }
  if (!sub) throw std::move(sub).status();

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

C#‎

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של C# ‎ במאמר הפעלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub C# API.

using Google.Cloud.PubSub.V1;
using Grpc.Core;

public class CreateSubscriptionWithFilteringSample
{
    public Subscription CreateSubscriptionWithFiltering(string projectId, string topicId, string subscriptionId, string filter)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);
        Subscription subscription = null;

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            Filter = filter
        };

        try
        {
            subscription = subscriber.CreateSubscription(subscriptionRequest);
        }
        catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
        {
            // Already exists.  That's fine.
        }
        return subscription;
    }
}

המשך

בדוגמה הבאה נעשה שימוש בגרסה הראשית של ספריית הלקוח Go Pub/Sub ‏ (v2). אם אתם עדיין משתמשים בספרייה v1, כדאי לעיין במדריך להעברה לגרסה v2. כדי לראות רשימה של דוגמאות קוד מגרסה 1, אפשר לעיין ב דוגמאות הקוד שהוצאו משימוש.

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Go במאמר מדריך למתחילים: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Go API.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

func createWithFilter(w io.Writer, projectID, topic, subscription, filter string) error {
	// Receive messages with attribute key "author" and value "unknown".
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// filter := "attributes.author=\"unknown\""
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:   subscription,
		Topic:  topic,
		Filter: filter,
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created subscription with filter: %v\n", sub)
	return nil
}

Java

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Java במאמר התחלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Java API.

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateSubscriptionWithFiltering {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String filter = "attributes.author=\"unknown\"";

    createSubscriptionWithFilteringExample(projectId, topicId, subscriptionId, filter);
  }

  public static void createSubscriptionWithFilteringExample(
      String projectId, String topicId, String subscriptionId, String filter) throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  // Receive messages with attribute key "author" and value "unknown".
                  .setFilter(filter)
                  .build());

      System.out.println(
          "Created a subscription with filtering enabled: " + subscription.getAllFields());
    }
  }
}

Node.js

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Node.js במאמר הפעלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Node.js API.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const filterString = 'YOUR_FILTER_STRING';   // e.g. 'attributes.author="unknown"'

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createSubscriptionWithFilter(
  topicNameOrId,
  subscriptionNameOrId,
  filterString,
) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, {
      filter: filterString,
    });
  console.log(
    `Created subscription ${subscriptionNameOrId} with filter ${filterString}.`,
  );
}

Node.js

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Node.js במאמר הפעלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Node.js API.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const filterString = 'YOUR_FILTER_STRING';   // e.g. 'attributes.author="unknown"'

// Imports the Google Cloud client library
import {PubSub} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createSubscriptionWithFilter(
  topicNameOrId: string,
  subscriptionNameOrId: string,
  filterString: string,
) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, {
      filter: filterString,
    });
  console.log(
    `Created subscription ${subscriptionNameOrId} with filter ${filterString}.`,
  );
}

PHP

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של PHP במאמר התחלה מהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub PHP API.

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $filter  The Pub/Sub subscription filter.
 */
function create_subscription_with_filter(
    string $projectId,
    string $topicName,
    string $subscriptionName,
    string $filter
): void {
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);

    $subscription->create(['filter' => $filter]);

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
    printf('Subscription info: %s' . PHP_EOL, json_encode($subscription->info()));
}

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Python במאמר תחילת העבודה המהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של ה-API בשפת Python של Pub/Sub.

from google.cloud import pubsub_v1

# TODO(developer): Choose an existing topic.
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# filter = "attributes.author=\"unknown\""

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

with subscriber:
    subscription = subscriber.create_subscription(
        request={"name": subscription_path, "topic": topic_path, "filter": filter}
    )
    print(f"Created subscription with filtering enabled: {subscription}")

Ruby

בדוגמה הבאה נעשה שימוש בספריית הלקוח של Ruby Pub/Sub בגרסה 3. אם אתם עדיין משתמשים בספרייה v2, כדאי לעיין במדריך להעברה לגרסה v3. כדי לראות רשימה של דוגמאות קוד של Ruby v2, אפשר לעיין ב דוגמאות הקוד שהוצאו משימוש.

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Ruby במאמר תחילת העבודה המהירה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Ruby API.

# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# filter = "attributes.author=\"unknown\""

pubsub = Google::Cloud::PubSub.new project_id: project_id
subscription_admin = pubsub.subscription_admin

subscription = subscription_admin.create_subscription \
  name: pubsub.subscription_path(subscription_id),
  topic: pubsub.topic_path(topic_id),
  filter: filter

puts "Created subscription with filtering enabled: #{subscription_id}"

האורך המקסימלי של מסנן הוא 256 בייטים. המסנן הוא מאפיין קבוע של מינוי. אחרי שיוצרים מינוי, אי אפשר לעדכן אותו כדי לשנות את המסנן.

איך מסננים משפיעים על מדדי ה-backlog

כדי לעקוב אחרי המינוי שיצרתם, אפשר לקרוא את המאמר מעקב אחרי מינויים באמצעות מסננים.

אם הפעלתם סינון, מדדי העומס בעבודה יכללו רק נתונים מהודעות שתואמות למסנן. ריכזנו כאן רשימה של מדדי ה-backlog:

• 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.

עדכון המסנן למינוי

אי אפשר לעדכן את המסנן של מינוי קיים. במקום זאת, אפשר לנסות את הפתרון העקיף הזה.

1. מצלמים צילום מסך של המינוי שרוצים לשנות את המסנן שלו.

   מידע נוסף על יצירת snapshot באמצעות המסוף זמין במאמר יצירת snapshot.

2. יוצרים מינוי חדש עם המסנן החדש.

   מידע נוסף על יצירת מינוי עם מסנן זמין במאמר יצירת מינוי עם מסנן.

3. נכנסים לדף Pub/Sub subscriptions במסוף Google Cloud .

   לדף המינויים

4. לוחצים על המינוי שיצרתם.

5. בדף פרטי המינוי, לוחצים על הפעלת הודעות מחדש.

6. כדי לדלג, לוחצים על לתמונת מצב.

7. בוחרים את התמונה שנוצרה למינוי המקורי בשלב 1 ולוחצים על חיפוש.

   לא תאבדו אף הודעה במהלך המעבר.

8. מעבירים את המנויים למינוי החדש.

אחרי שמסיימים את התהליך הזה, אפשר למחוק את המינוי המקורי.

תחביר ליצירת מסנן

כדי לסנן הודעות, צריך לכתוב ביטוי שפועל על מאפיינים. אפשר לכתוב ביטוי שתואם למפתח או לערך של המאפיינים. המזהה 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"

כדי להשתמש בקו נטוי הפוך, במירכאות ובתווים שאינם מודפסים במסנן, צריך להשתמש בתו בריחה לתווים בתוך מחרוזת מילולית. אפשר גם להשתמש ברצפי בריחה מסוג Unicode, הקסדצימלי ואוקטלי בתוך מחרוזת מילולית.

• תקין: סינון תווים מיוחדים בתוך מחרוזת מילולית

  attributes:"\u307F\u3093\u306A"
  

• לא תקין: המסנן מבצע escape לתווים בלי מחרוזת מילולית

  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: מחרוזת משנה של הערך