Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Filtrare i messaggi di una sottoscrizione

In questa pagina viene spiegato come creare sottoscrizioni Pub/Sub con filtri.

Quando ricevi i messaggi da una sottoscrizione con un filtro, riceverai solo quelli che corrispondono a un filtro. Il servizio Pub/Sub riconosce automaticamente i messaggi che non corrispondono al filtro. Puoi filtrare i messaggi in base ai rispettivi attributi, ma non in base ai dati contenuti nel messaggio.

Puoi collegare più sottoscrizioni a un argomento e ogni sottoscrizione può avere un filtro diverso.

Ad esempio, se hai un argomento che riceve notizie da diverse parti del mondo, puoi configurare una sottoscrizione per filtrare le notizie pubblicate solo da una regione specifica. Per questa configurazione, devi assicurarti che uno degli attributi dei messaggi dell'argomento trasmetta la regione di pubblicazione delle notizie.

Quando ricevi i messaggi da una sottoscrizione con un filtro, non ti vengono addebitati costi per i messaggi in uscita per i messaggi che Pub/Sub riconosce automaticamente. Per questi messaggi sono previsti costi di consegna dei messaggi e tariffe per l'archiviazione correlate alla ricerca .

Creare una sottoscrizione con un filtro

Le sottoscrizioni pull e push possono avere filtri. Tutti i sottoscrittori possono ricevere messaggi da sottoscrizioni con filtri, inclusi i sottoscrittori che utilizzano l'API StreamingPull.

Puoi creare una sottoscrizione con un filtro utilizzando la Google Cloud console, Google Cloud CLI, le librerie client o l'API Pub/Sub.

Console

Per creare una sottoscrizione pull con un filtro:

Nella Google Cloud console, vai alla pagina Sottoscrizioni.

Vai alla pagina degli abbonamenti
Fai clic su Crea sottoscrizione.
Inserisci l'ID sottoscrizione.
Scegli o crea un argomento dal menu a discesa. La sottoscrizione riceve i messaggi dall'argomento.
Nella sezione Filtro sottoscrizione, inserisci l' espressione di filtro.
Fai clic su Crea.

Per creare una sottoscrizione push con un filtro:

Nella Google Cloud console, vai alla pagina Sottoscrizioni.

Vai alla pagina degli abbonamenti
Fai clic su Crea sottoscrizione.
Inserisci l'ID sottoscrizione.
Scegli o crea un argomento dal menu a discesa. La sottoscrizione riceve i messaggi dall'argomento.
Nella sezione Tipo di consegna, fai clic su Push.
Nel campo URL endpoint, inserisci l'URL dell'endpoint push.
Nella sezione Filtro sottoscrizione, inserisci l' espressione di filtro.
Fai clic su Crea.

gcloud

Per creare una sottoscrizione pull con un filtro, utilizza il gcloud pubsub subscriptions create comando con il --message-filter flag:

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

Sostituisci quanto segue:

SUBSCRIPTION_ID: l'ID della sottoscrizione da creare
TOPIC_ID: l'ID dell'argomento da collegare alla sottoscrizione
FILTER: un'espressione nella sintassi di filtro

Per creare una sottoscrizione push con un filtro, utilizza il gcloud pubsub subscriptions create comando con i flag --push-endpoint e --message-filter:

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

Sostituisci quanto segue:

SUBSCRIPTION_ID: l'ID della sottoscrizione da creare
TOPIC_ID: l'ID dell'argomento da collegare alla sottoscrizione
PUSH_ENDPOINT: l'URL del server su cui viene eseguito il sottoscrittore push
FILTER: un'espressione nella sintassi di filtro

REST

Per creare una sottoscrizione con un filtro, utilizza il projects.subscriptions.create metodo.

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

Sostituisci quanto segue:

PROJECT_ID: l'ID progetto del progetto in cui creare la sottoscrizione
SUBSCRIPTION_ID: l'ID della sottoscrizione da creare

Per creare una sottoscrizione pull con un filtro, specifica il filtro nel corpo della richiesta:

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

Sostituisci quanto segue:

PROJECT_ID: l'ID progetto del progetto con l'argomento
TOPIC_ID: l'ID dell'argomento da collegare alla sottoscrizione
FILTER: un'espressione nella sintassi di filtro

Per creare una sottoscrizione push con un filtro, specifica l'endpoint push e il filtro nel corpo della richiesta:

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

Sostituisci quanto segue:

PROJECT_ID: l'ID progetto del progetto con l'argomento
TOPIC_ID: l'ID dell'argomento da collegare alla sottoscrizione
PUSH_ENDPOINT: l'URL del server su cui viene eseguito il sottoscrittore push
FILTER: un'espressione nella sintassi di filtro

C++

Prima di provare questo esempio, segui le istruzioni di configurazione di C++ in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub C++ .

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#

Prima di provare questo esempio, segui le istruzioni di configurazione di C# in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub C# .


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;
    }
}

Vai

L'esempio seguente utilizza la versione principale della libreria client Go Pub/Sub (v2). Se utilizzi ancora la libreria v1, consulta la guida alla migrazione alla v2. Per visualizzare un elenco di esempi di codice della versione 1, consulta gli esempi di codice deprecati.

Prima di provare questo esempio, segui le istruzioni di configurazione di Go in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Go.

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Java in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Java.

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js in guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.

/**
 * 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

/**
 * 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

Prima di provare questo esempio, segui le istruzioni di configurazione di PHP in guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub PHP.

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.

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

L'esempio seguente utilizza la libreria client Ruby Pub/Sub v3. Se utilizzi ancora la libreria v2, consulta la guida alla migrazione alla v3. Per visualizzare un elenco di esempi di codice Ruby v2, consulta gli esempi di codice deprecati.

Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Ruby.

# 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}"

La lunghezza massima di un'espressione di filtro è di 256 byte. Se hai bisogno di un filtro più grande, valuta la possibilità di creare una singola trasformazione dei messaggi (SMT) per filtrare i messaggi.

Il filtro è una proprietà immutabile di una sottoscrizione. Dopo aver creato una sottoscrizione, non puoi aggiornarla per modificare il filtro.

In che modo i filtri influiscono sulle metriche del backlog

Per monitorare la sottoscrizione appena creata, consulta Monitorare le sottoscrizioni con filtri.

Se il filtro è abilitato, le metriche del backlog includono solo i dati dei messaggi che corrispondono al filtro. Di seguito è riportato un elenco delle metriche del 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

Per saperne di più su queste metriche, consulta l'elenco delle metriche Pub/Sub.

Aggiornare il filtro per una sottoscrizione

Non puoi aggiornare il filtro per una sottoscrizione esistente. Segui invece questa soluzione alternativa.

Scatta uno snapshot della sottoscrizione per cui vuoi modificare il filtro.

Per saperne di più su come scattare uno snapshot utilizzando la console, consulta Creare uno snapshot.
Crea una nuova sottoscrizione con il nuovo filtro.

Per saperne di più su come creare una sottoscrizione con un filtro, consulta Creare una sottoscrizione con un filtro.
Nella Google Cloud console, vai alla pagina Sottoscrizioni Pub/Sub.

Vai alle sottoscrizioni
Fai clic sulla sottoscrizione che hai appena creato.
Nella pagina dei dettagli della sottoscrizione, fai clic su Riproduci messaggi.
In Ricerca, fai clic su A uno snapshot.
Seleziona lo snapshot che hai creato per la sottoscrizione originale nel passaggio 1 e fai clic su Ricerca.

Non perderai alcun messaggio durante la transizione.
Modifica i sottoscrittori in modo che utilizzino la nuova sottoscrizione.

Una volta completata questa procedura, puoi eliminare la sottoscrizione originale.

Sintassi per creare un filtro

Per filtrare i messaggi, scrivi un' espressione che opera sugli attributi. Puoi scrivere un'espressione che corrisponda alla chiave o al valore degli attributi. L'identificatore attributes seleziona gli attributi nel messaggio.

Ad esempio, i filtri nella tabella seguente selezionano l'attributo name:

Filtro	Descrizione
`attributes:name`	Messaggi con l'attributo `name`
`NOT attributes:name`	Messaggi senza l'attributo `name`
`attributes.name = "com"`	Messaggi con l'attributo `name` e il valore `com`
`attributes.name != "com"`	Messaggi senza l'attributo `name` e il valore `com`
`hasPrefix(attributes.name, "co")`	Messaggi con l'attributo `name` e un valore che inizia con `co`
`NOT hasPrefix(attributes.name, "co")`	Messaggi senza l'attributo `name` e un valore che inizia con `co`

Operatori di confronto per l'espressione di filtro

Puoi filtrare gli attributi con i seguenti operatori di confronto:

:
=
!=

L'operatore : corrisponde a una chiave in un elenco di attributi.

attributes:KEY

Gli operatori di uguaglianza corrispondono a chiavi e valori. Il valore deve essere un valore letterale stringa.

attributes.KEY = "VALUE"

Un'espressione con un operatore di uguaglianza deve iniziare con una chiave e l'operatore di uguaglianza deve confrontare una chiave e un valore.

Valido: il filtro confronta una chiave e un valore
```
attributes.name = "com"
```
Non valido: il lato sinistro del filtro è un valore
```
"com" = attributes.name
```
Non valido: il filtro confronta due chiavi
```
attributes.name = attributes.website
```

La chiave e il valore sono sensibili alle maiuscole e devono corrispondere esattamente all'attributo. Se una chiave contiene caratteri diversi da trattini, trattini bassi o caratteri alfanumerici, utilizza un valore letterale stringa.

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

Per utilizzare barre rovesciate, virgolette e caratteri non stampabili in un filtro, esegui l'escape dei caratteri all'interno di un valore letterale stringa. Puoi anche utilizzare sequenze di escape Unicode, esadecimali e ottali all'interno di un valore letterale stringa.

Valido: il filtro esegue l'escape dei caratteri all'interno di un valore letterale stringa
```
attributes:"\u307F\u3093\u306A"
```
Non valido: il filtro esegue l'escape dei caratteri senza un valore letterale stringa
```
attributes:\u307F\u3093\u306A
```

Operatori booleani per l'espressione di filtro

Puoi utilizzare gli operatori booleani AND, NOT e OR in un filtro. Gli operatori devono essere in lettere maiuscole. Ad esempio, il seguente filtro è per i messaggi con l'attributo iana.org/language_tag, ma senza l'attributo name e il valore com.

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

L'operatore NOT ha la precedenza più alta. Per combinare gli operatori AND e OR, utilizza le parentesi e le espressioni complete.

Valido: operatori AND e OR con parentesi

attributes:"iana.org/language_tag" AND (attributes.name = "net" OR attributes.name = "org")

Non valido: operatori AND e OR senza parentesi

attributes:"iana.org/language_tag" AND attributes.name = "net" OR attributes.name = "org"

Non valido: AND e OR operatori combinano espressioni incomplete
```
attributes.name = "com" AND ("net" OR "org")
```

Puoi anche utilizzare l'operatore meno unario anziché l'operatore NOT.

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

Funzioni per l'espressione di filtro

Puoi utilizzare la funzione hasPrefix per filtrare gli attributi con valori che iniziano con una sottostringa. hasPrefix è l'unica funzione supportata in un filtro.

Sebbene la corrispondenza dei prefissi sia supportata con la funzione hasPrefix, le espressioni regolari generali non sono supportate.

hasPrefix(attributes.KEY, "SUBSTRING")

Sostituisci quanto segue:

KEY: il nome dell'attributo
SUBSTRING: una sottostringa del valore

Filtrare i messaggi di una sottoscrizione Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Creare una sottoscrizione con un filtro

Console

gcloud

REST

C++

C#

Vai

Java

Node.js

Node.js

PHP

Python

Ruby

In che modo i filtri influiscono sulle metriche del backlog

Aggiornare il filtro per una sottoscrizione

Sintassi per creare un filtro

Operatori di confronto per l'espressione di filtro

Operatori booleani per l'espressione di filtro

Funzioni per l'espressione di filtro

Filtrare i messaggi di una sottoscrizione