Auf dieser Seite wird erläutert, wie Pub/Sub-Abos mit Filtern erstellt werden.
Wenn Sie Nachrichten aus einem Abo mit einem Filter erhalten, erhalten Sie nur die Nachrichten, die dem Filter entsprechen. Der Pub/Sub-Dienst bestätigt automatisch die Nachrichten, die nicht mit dem Filter übereinstimmen. Sie können Nachrichten nach ihren Attributen, aber nicht nach den Daten in der Nachricht filtern.
Sie können mehrere Abos mit einem Thema verknüpfen und jedes Abo kann einen anderen Filter haben.
Wenn Sie beispielsweise zu einem Thema Nachrichten aus verschiedenen Teilen der Welt haben, können Sie ein Abo so konfigurieren, dass nur Nachrichten aus einer bestimmten Region herausgefiltert werden. Für diese Konfiguration musst du darauf achten, dass eines der Nachrichtenattribute des Themas die Region der Nachrichtenpublikation übergibt.
Wenn Sie Nachrichten von einem Abo mit einem Filter erhalten, fallen keine Gebühren für ausgehende Nachrichten für die Nachrichten an, die Pub/Sub automatisch bestätigt. Für diese Nachrichten fallen Gebühren für die Nachrichtenzustellung und suchbezogene Speichergebühren an.
Abo mit einem Filter erstellen
Pull- und Push-Abos können Filter enthalten. Alle Abonnenten können Nachrichten von Abos mit Filtern erhalten, einschließlich Abonnenten, die die StreamingPull API verwenden.
Abos mit einem Filter können über die Google Cloud Console, die Google Cloud CLI, die Clientbibliotheken oder die Pub/Sub API erstellt werden.
Console
So erstellen Sie ein Pull-Abo mit einem Filter:
Öffnen Sie in der Google Cloud Console die Seite Abos.
Klicken Sie auf Abo erstellen.
Geben Sie die Abo-ID ein.
Wählen Sie im Drop-down-Menü ein Thema aus oder erstellen Sie ein Thema. Das Abo erhält Nachrichten aus dem Thema.
Geben Sie im Abschnitt Abo-Filter den Filterausdruck ein.
Klicken Sie auf Erstellen.
So erstellen Sie ein Push-Abo mit einem Filter:
Öffnen Sie in der Google Cloud Console die Seite Abos.
Klicken Sie auf Abo erstellen.
Geben Sie die Abo-ID ein.
Wählen Sie im Drop-down-Menü ein Thema aus oder erstellen Sie ein Thema. Das Abo erhält Nachrichten aus dem Thema.
Klicken Sie im Bereich Zustellungstyp auf Push.
Geben Sie im Feld Endpunkt-URL die URL des Push-Endpunkts ein.
Geben Sie im Abschnitt Abo-Filter den Filterausdruck ein.
Klicken Sie auf Erstellen.
gcloud
Verwenden Sie zum Erstellen eines Pull-Abos mit einem Filter den Befehl gcloud pubsub subscriptions create
mit dem Flag --message-filter
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --message-filter='FILTER'
Ersetzen Sie Folgendes:
- SUBSCRIPTION_ID: Die ID des zu erstellenden Abos
- TOPIC_ID: Die ID des Themas, das an das Abo angehängt werden soll
- FILTER: Ein Ausdruck in der Filtersyntax
Verwenden Sie zum Erstellen eines Push-Abos mit einem Filter den Befehl gcloud pubsub subscriptions create
mit den Flags --push-endpoint
und --message-filter
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --push-endpoint=PUSH_ENDPOINT \ --message-filter='FILTER'
Ersetzen Sie Folgendes:
- SUBSCRIPTION_ID: Die ID des zu erstellenden Abos
- TOPIC_ID: Die ID des Themas, das an das Abo angehängt werden soll
- PUSH_ENDPOINT: Die URL des Servers, auf dem der Push-Abonnent ausgeführt wird
- FILTER: Ein Ausdruck in der Filtersyntax
REST
Wenn Sie ein Abo mit einem Filter erstellen möchten, verwenden Sie die Methode projects.subscriptions.create
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
Ersetzen Sie Folgendes:
- PROJECT_ID: die Projekt-ID des Projekts, in dem das Abo erstellt werden soll
- SUBSCRIPTION_ID: Die ID des zu erstellenden Abos
Wenn Sie ein Pull-Abo mit einem Filter erstellen möchten, geben Sie den Filter im Anfragetext an:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "filter": "FILTER" }
Ersetzen Sie Folgendes:
- PROJECT_ID: Die Projekt-ID des Projekts mit dem Thema
- TOPIC_ID: Die ID des Themas, das an das Abo angehängt werden soll
- FILTER: Ein Ausdruck in der Filtersyntax
Um ein Push-Abo mit einem Filter zu erstellen, geben Sie den Push-Endpunkt und den Filter im Anfragetext an:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "pushConfig": { "pushEndpoint": "PUSH_ENDPOINT" }, "filter": "FILTER" }
Ersetzen Sie Folgendes:
- PROJECT_ID: Die Projekt-ID des Projekts mit dem Thema
- TOPIC_ID: Die ID des Themas, das an das Abo angehängt werden soll
- PUSH_ENDPOINT: Die URL des Servers, auf dem der Push-Abonnent ausgeführt wird
- FILTER: Ein Ausdruck in der Filtersyntax
C++
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für C++ in der Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub C++ API.
C#
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für C# in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub C# API.
Einfach loslegen (Go)
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Go in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Go API.
Java
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Java in der Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Java API.
Node.js
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für PHP in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Node.js API.
Node.js
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für PHP in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Node.js API.
PHP
Folgen Sie der Einrichtungsanleitung für PHP unter Schnellstart: Clientbibliotheken verwenden, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub PHP API.
Python
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Python in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Python API.
Ruby
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Ruby in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Ruby API.
Die maximale Länge eines Filters beträgt 256 Byte. Der Filter ist eine unveränderliche Eigenschaft eines Abos. Nachdem Sie ein Abo erstellt haben, können Sie es nicht mehr aktualisieren, um den Filter zu ändern.
So wirken sich Filter auf Rückstandsmesswerte aus
Informationen zum Überwachen des soeben erstellten Abos finden Sie unter Abos mit Filtern überwachen.
Wenn Sie die Filterung aktiviert haben, enthalten die Rückstandsmesswerte nur Daten aus Nachrichten, die dem Filter entsprechen. Im Folgenden finden Sie eine Liste der Backlog-Messwerte:
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
Weitere Informationen zu diesen Messwerten finden Sie in der Liste der Pub/Sub-Messwerte.
Filter für ein Abo aktualisieren
Sie können den Filter für ein vorhandenes Abo nicht aktualisieren. Folgen Sie stattdessen dieser Problemumgehung.
Erstellen Sie einen Snapshot des Abos, für das Sie den Filter ändern möchten.
Weitere Informationen zum Erstellen eines Snapshots mit der Console finden Sie unter Snapshot erstellen.
Erstellen Sie ein neues Abo mit dem neuen Filter.
Weitere Informationen zum Erstellen eines Abos mit einem Filter findest du unter Abo mit einem Filter erstellen.
Rufen Sie in der Google Cloud Console die Seite Pub/Sub-Abos auf.
Klicken Sie auf das Abo, das Sie gerade erstellt haben.
Klicken Sie auf der Seite mit den Abodetails auf Nachrichten wiedergeben.
Klicken Sie unter Suchen auf Zu einem Snapshot.
Wählen Sie den Snapshot aus, den Sie in Schritt 1 für das ursprüngliche Abo erstellt haben, und klicken Sie dann auf Suchen.
Während der Umstellung gehen keine Nachrichten verloren.
Ändere bei allen Abonnenten das neue Abo.
Anschließend kannst du das ursprüngliche Abo löschen.
Syntax zum Erstellen eines Filters
Schreiben Sie zum Filtern von Nachrichten einen Ausdruck, der Attribute verwendet. Sie können einen Ausdruck schreiben, der mit dem Schlüssel oder Wert der Attribute übereinstimmt. Die Kennzeichnung attributes
wählt die Attribute in der Nachricht aus.
Wählen Sie beispielsweise die Filter name
in der folgenden Tabelle aus:
Filter | Beschreibung |
---|---|
attributes:name |
Nachrichten mit dem Attribut name |
NOT attributes:name |
Nachrichten ohne das Attribut name |
attributes.name = "com" |
Nachrichten mit dem Attribut name und dem Wert com |
attributes.name != "com" |
Nachrichten ohne das Attribut name und den Wert von com |
hasPrefix(attributes.name, "co") |
Nachrichten mit dem Attribut name und einem Wert, der mit co beginnt |
NOT hasPrefix(attributes.name, "co") |
Nachrichten ohne das Attribut name und einem Wert, der mit co beginnt |
Vergleichsoperatoren für den Filterausdruck
Sie können Attribute mit den folgenden Vergleichsoperatoren filtern:
:
=
!=
Der Operator :
entspricht einem Schlüssel in einer Liste von Attributen.
attributes:KEY
Die Gleichheitsoperatoren stimmen mit Schlüsseln und Werten überein. Der Wert muss ein Stringliteral sein.
attributes.KEY = "VALUE"
Ein Ausdruck mit einem Gleichheitsoperator muss mit einem Schlüssel beginnen und der Gleichheitsoperator muss einen Schlüssel mit einem Wert vergleichen.
Gültig: Der Filter vergleicht einen Schlüssel mit einem Wert
attributes.name = "com"
Ungültig: Die linke Seite des Filters ist ein Wert.
"com" = attributes.name
Ungültig: Der Filter vergleicht zwei Schlüssel
attributes.name = attributes.website
Bei Schlüssel und Wert wird zwischen Groß- und Kleinschreibung unterschieden und sie müssen genau mit dem Attribut übereinstimmen. Wenn ein Schlüssel andere Zeichen als Bindestriche, Unterstriche oder alphanumerische Zeichen enthält, verwenden Sie ein String-Literal.
attributes."iana.org/language_tag" = "en"
Wenn Sie in einem Filter Backslash, Anführungszeichen und nicht druckbare Zeichen verwenden möchten, müssen Sie die Zeichen in einem Stringliteral mit Escapezeichen versehen. Sie können auch Unicode-, Hexadezimal- und Oktal-Escapesequenzen innerhalb eines Stringliterals verwenden.
Valid: Der Filter maskiert Zeichen in einem String-Literal
attributes:"\u307F\u3093\u306A"
Ungültig: Der Filter maskiert Zeichen ohne Stringliteral
attributes:\u307F\u3093\u306A
Boolesche Operatoren für den Filterausdruck
Sie können in einem Filter die booleschen Operatoren AND
, NOT
und OR
verwenden. Die Operatoren müssen in Großbuchstaben angegeben werden. Der folgende Filter gilt beispielsweise für Nachrichten mit dem Attribut iana.org/language_tag
, aber ohne das Attribut name
und den Wert com
.
attributes:"iana.org/language_tag" AND NOT attributes.name = "com"
Der Operator NOT
hat die höchste Priorität. Wenn Sie die Operatoren AND
und OR
kombinieren möchten, verwenden Sie Klammern und vollständige Ausdrücke.
Valid: Die Operatoren
AND
undOR
mit Klammernattributes:"iana.org/language_tag" AND (attributes.name = "net" OR attributes.name = "org")
Ungültig:
AND
- undOR
- Operatoren ohne Klammernattributes:"iana.org/language_tag" AND attributes.name = "net" OR attributes.name = "org"
Ungültig: Die Operatoren
AND
undOR
kombinieren unvollständige Ausdrückeattributes.name = "com" AND ("net" OR "org")
Sie können auch den unären Minusoperator anstelle des NOT
-Operators verwenden.
attributes.name = "com" AND -attributes:"iana.org/language_tag"
Funktionen für den Filterausdruck
Mit der Funktion hasPrefix
können Sie nach Attributen filtern, deren Werte mit einem Teilstring beginnen. hasPrefix
ist die einzige unterstützte Funktion in einem Filter.
Während der Präfixabgleich mit der hasPrefix
-Funktion unterstützt wird, werden allgemeine reguläre Ausdrücke nicht unterstützt.
hasPrefix(attributes.KEY, "SUBSTRING")
Ersetzen Sie Folgendes:
- KEY: der Name des Attributs
- SUBSTRING: ein Teilstring des Werts