Auf dieser Seite wird gezeigt, wie Sie Suchvorgänge für Lite-Abos initiieren und verfolgen.
Mit der Suchfunktion von Pub/Sub Lite können Sie Nachrichten wiedergeben und dauerhaft löschen. Es gibt dieselben Anwendungsfälle wie die Pub/Sub-Suche. Im Gegensatz zu Pub/Sub müssen Sie keine Lite-Themen oder -Abos für Suchvorgänge konfigurieren und es entstehen keine zusätzlichen Kosten für die Nutzung.
Die Weitergabe der Suche an Abonnenten kann mit einem lang andauernden Vorgang verfolgt werden. Dies ist ein API-Muster, das von Google Cloud-Produkten verwendet wird, um den Fortschritt von lang andauernden Aufgaben zu verfolgen.
Suchvorgang initiieren
Pub/Sub Lite-Suchvorgänge werden „Out-of-Band“ initiiert, d. h. über die Google Cloud CLI oder eine separate Pub/Sub Lite API, und an Abonnenten weitergegeben. Online-Abonnenten werden über die Suche benachrichtigt und reagieren, während sie aktiv sind. Offline-Abonnenten reagieren auf die Suche, sobald sie online sind.
Sie müssen einen Zielspeicherort für die Suche angeben. Dies kann einer der folgenden sein:
- Anfang des Nachrichtenrückstands: Gibt alle aufbewahrten Nachrichten noch einmal aus. Der Umfang des verfügbaren Rückstands hängt von der Aufbewahrungsdauer und der Speicherkapazität des Lite-Themas ab.
- Ende des Nachrichtenrückstands: Löscht Nachrichten dauerhaft, indem alle aktuell veröffentlichten Nachrichten übersprungen werden.
- Veröffentlichungszeitstempel: Sucht bis zur ersten Nachricht mit einem (servergenerierten) Veröffentlichungszeitstempel, der größer oder gleich dem angegebenen Zeitstempel ist. Wenn keine solche Nachricht gefunden werden kann, wird bis zum Ende des Nachrichtenrückstands gesucht. Nachfolgende Nachrichten haben garantiert einen Veröffentlichungszeitstempel, der größer oder gleich dem angegebenen Zeitstempel ist, mit Ausnahme von angegebenen Zeitstempeln, die in der Zukunft liegen.
- Ereigniszeitstempel: Sucht bis zur ersten Nachricht mit einem (benutzerdefinierten) Ereigniszeitstempel, der größer oder gleich dem angegebenen Zeitstempel ist. Wenn keine solche Nachricht gefunden werden kann, wird bis zum Ende des Nachrichtenrückstands gesucht. Da Ereigniszeitstempel vom Nutzer angegeben werden, können nachfolgende Nachrichten Ereigniszeitstempel haben, die kürzer als die angegebene Ereigniszeit sind, und sollten vom Client bei Bedarf gefiltert werden. Wenn für Nachrichten kein Ereigniszeitstempel festgelegt ist, werden ihre Veröffentlichungszeitstempel als Fallback verwendet.
Sie können eine Suche nach einem Lite-Abo mit der Google Cloud CLI oder der Pub/Sub Lite API initiieren.
gcloud
Verwenden Sie den Befehl gcloud pubsub lite-subscriptions seek
, um ein Lite-Abo zu suchen:
gcloud pubsub lite-subscriptions seek SUBSCRIPTION_ID \ --location=LITE_LOCATION \ (--publish-time=PUBLISH_TIME | --event-time=EVENT_TIME | \ --starting-offset=STARTING_OFFSET) \ [--async]
Dabei gilt:
SUBSCRIPTION_ID: die ID des Lite-Abos
LITE_LOCATION: der Standort des Lite-Abos
PUBLISH_TIME: der Veröffentlichungszeitstempel, zu dem gesucht werden soll
EVENT_TIME: der Ereigniszeitstempel, zu dem gesucht werden soll
STARTING_OFFSET:
beginning
oderend
Weitere Informationen zu Zeitformaten finden Sie unter gcloud topic datetimes
.
Wenn Sie das Flag --async
angeben und die Anfrage erfolgreich ist, wird in der Befehlszeile die ID des Suchvorgangs angezeigt:
Check operation [projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID] for status.
Verwenden Sie den Befehl gcloud pubsub lite-operations describe
, um den Vorgangsstatus abzurufen.
REST
Senden Sie zum Suchen eines Lite-Abos eine POST
-Anfrage wie die folgende:
POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID:seek Authorization: Bearer $(gcloud auth print-access-token)
Ersetzen Sie Folgendes:
REGION: die Region, in der sich das Lite-Abo befindet
PROJECT_NUMBER: die Projektnummer des Projekts mit dem Lite-Abo
LITE_LOCATION: der Standort des Lite-Abos
SUBSCRIPTION_ID: die ID des Lite-Abos
Legen Sie die folgenden Felder im Anfragetext fest, um zum Anfang oder Ende des Nachrichtenrückstands zu suchen:
{ "namedTarget": NAMED_TARGET }
Dabei gilt:
- NAMED_TARGET:
TAIL
für den Beginn oderHEAD
für das Ende des Nachrichtenrückstands.
Um nach einem Veröffentlichungszeitstempel zu suchen, legen Sie die folgenden Felder im Anfragetext fest:
{ "timeTarget": { "publishTime": TIMESTAMP } }
Geben Sie "eventTime"
an, um zu einem Ereigniszeitstempel zu suchen.
Dabei gilt:
- TIMESTAMP: Ein Zeitstempel im Format RFC 3339 UTC mit einer Auflösung im Nanosekundenbereich und bis zu neun Nachkommastellen. Beispiele:
"2014-10-02T15:01:23Z"
und"2014-10-02T15:01:23.045123456Z"
.
Wenn die Anfrage erfolgreich ist, ist die Antwort ein Vorgang mit langer Ausführungszeit im JSON-Format:
{ "name": projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID, ... }
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 zu Pub/Sub Go API.
Java
Bevor Sie dieses Beispiel ausführen, folgen Sie den Schritten zur Einrichtung von Java in Pub/Sub Lite-Clientbibliotheken.
Python
Bevor Sie dieses Beispiel ausführen, folgen Sie den Schritten zur Einrichtung von Java in Pub/Sub Lite-Clientbibliotheken.
Wenn die Suchanfrage erfolgreich ist, ist die Antwort eine Vorgangs-ID mit langer Ausführungszeit. Lesen Sie die Informationen zum Thema Such-Weitergabe verfolgen weiter unten, wenn Sie wissen möchten, wann Abonnenten auf die Suche reagiert haben.
Unterstützte Clients
Für Such-Vorgänge sind Abonnenten erforderlich, die die folgenden Pub/Sub Lite-Clientbibliotheken und Mindestversionen verwenden:
- java-pubsublite: Version 0.15.0.
- java-pubsublite-kafka: Version 0.6.0. Nutzer müssen außerdem Autocommit aktiviert haben.
- python-pubsublite: Version 0.6.0.
- google-cloud-go: pubsublite Version 0.10.0.
Suchvorgänge funktionieren nicht, wenn Pub/Sub Lite mit Apache Beam oder Apache Spark verwendet wird, da diese Systeme selbst Offsets innerhalb von Partitionen verfolgen. Um dieses Problem zu umgehen, leeren Sie die Workflows, suchen und starten Sie diese neu.
Der Pub/Sub Lite-Dienst kann einen Abonnentenclient erkennen, der keine Suchvorgänge unterstützt (z. B. eine alte Version einer Clientbibliothek oder ein nicht unterstütztes Framework) und den Suchvorgang mit einem FAILED_PRECONDITION
Fehlerstatus abbrechen.
Such-Weitergabe verfolgen
Wenn für die erste Suchanfrage eine ID für einen Vorgang mit langer Ausführungszeit zurückgegeben wird, wurde die Suche erfolgreich im Pub/Sub Lite-Dienst registriert und wird letztendlich an die Abonnenten weitergegeben, sofern der Client unterstützt wird (siehe oben). Der Vorgang verfolgt diese Weitergabe und wird abgeschlossen, sobald bei allen Partitionen Abonnenten auf den Suchvorgang reagiert haben.
Wenn Abonnenten online sind, kann es bis zu 30 Sekunden dauern, bis sie die Suchbenachrichtigung erhalten. Suchbenachrichtigungen werden für jede Partition unabhängig gesendet, sodass Partitionen nicht gleichzeitig auf die Suche reagieren. Wenn Abonnenten offline sind, wird der Suchvorgang abgeschlossen, sobald sie online sind.
Wenn ein vorheriger Suchaufruf noch nicht vollständig an Abonnenten weitergegeben wurde, wird er abgebrochen und durch den neuen Suchvorgang ersetzt. Die Metadaten des Suchvorgangs laufen nach 30 Tagen ab, wodurch unvollständige Suchvorgänge abgebrochen werden.
Status des Suchvorgangs
Sie können den Status eines Suchvorgangs mit der Google Cloud CLI oder der Pub/Sub Lite API abrufen.
gcloud
Mit dem Befehl gcloud pubsub lite-operations describe
können Sie Details zu einem Lite-Vorgang abrufen:
gcloud pubsub lite-operations describe OPERATION_ID \ --location=LITE_LOCATION
Dabei gilt:
OPERATION_ID: die ID des Lite-Vorgangs
LITE_LOCATION: der Standort des Lite-Vorgangs
Wenn die Anfrage erfolgreich ist, zeigt die Befehlszeile Metadaten zum Lite-Vorgang an:
metadata: '@type': type.googleapis.com/google.cloud.pubsublite.v1.OperationMetadata createTime: '2021-01-02T03:04:05Z' target: projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID verb: seek name: projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID
REST
Wenn Sie Details zu einem Lite-Vorgang abrufen möchten, senden Sie eine GET
-Anfrage wie die folgende:
GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID Authorization: Bearer $(gcloud auth print-access-token)
Ersetzen Sie Folgendes:
REGION: die Region, in der sich der Lite-Vorgang befindet
PROJECT_NUMBER: die Projektnummer des Projekts mit dem Lite-Vorgang
LITE_LOCATION: der Standort des Lite-Vorgangs
OPERATION_ID: die ID des Lite-Vorgangs
Wenn die Anfrage erfolgreich ist, ist die Antwort ein Vorgang mit langer Ausführungszeit im JSON-Format:
{ "name": projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID, ... }
Suchvorgänge auflisten
Abgeschlossene und aktive Suchvorgänge können mit der Google Cloud CLI oder der Pub/Sub Lite API aufgelistet werden.
gcloud
Verwenden Sie den Befehl gcloud pubsub lite-operations list
, um Lite-Vorgänge in einem Projekt aufzulisten:
gcloud pubsub lite-operations list \
--location=LITE_LOCATION \
[--subscription=SUBSCRIPTION] \
[--done=DONE] \
[--limit=LIMIT]
Ersetzen Sie Folgendes:
LITE_LOCATION: den Standort, an dem sich die Lite-Vorgänge befinden
SUBSCRIPTION: Vorgänge nach Lite-Abo filtern
DONE:
true
, um nur vollständige Vorgänge einzubeziehen,false
, um nur aktive Vorgänge einzuschließenLIMIT: eine Ganzzahl, um die Anzahl der zurückgegebenen Vorgänge zu begrenzen
Wenn die Anfrage erfolgreich ist, wird in der Befehlszeile eine Zusammenfassung der Lite-Vorgänge angezeigt:
OPERATION_ID TARGET CREATE_TIME DONE ERROR_CODE MESSAGE operation2 projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID 2021-05-06T07:08:00Z True operation1 projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID 2021-01-02T03:04:00Z True
REST
Senden Sie eine GET
-Anfrage wie die folgende, um Lite-Vorgänge in einem Projekt aufzulisten:
GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations Authorization: Bearer $(gcloud auth print-access-token)
Ersetzen Sie Folgendes:
REGION: die Region, in der sich die Lite-Vorgänge befinden
PROJECT_NUMBER: die Projektnummer des Projekts mit den Lite-Vorgängen
LITE_LOCATION: den Standort, an dem sich die Lite-Vorgänge befinden
Wenn die Anfrage erfolgreich ist, ist die Antwort eine Liste von Lite-Vorgängen im JSON-Format:
{ "operations": [ { "name": "projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID", ... }, { "name": "projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID", ... } ] }