Pub/Sub Lite-Nachrichten nach Pub/Sub exportieren

In diesem Dokument wird beschrieben, wie Sie den automatischen Export von Pub/Sub Lite-Nachrichten nach Pub/Sub einrichten.

Hier sind einige Szenarien, in denen Sie diese Funktion verwenden könnten:

• Arbeiten Sie zwischen Arbeitslasten zusammen, die eine Mischung aus Pub/Sub Lite und Pub/Sub verwenden.
• Pub/Sub Lite-Arbeitslast zu Pub/Sub migrieren
• Erweiterte Pub/Sub-Features wie Push-Abos und Filter aus einer vorhandenen Anwendung verwenden, die auf Pub/Sub Lite basiert.
• Konsolidieren Sie mehrere Datenpipelines.

Überblick

Wenn Sie Nachrichten von Pub/Sub Lite nach Pub/Sub exportieren möchten, erstellen Sie einen speziellen Abotyp, der als Exportabo bezeichnet wird. Ein Exportabo empfängt Nachrichten von einem Lite-Thema, konvertiert sie in Pub/Sub-Nachrichten und sendet die konvertierten Nachrichten an ein Pub/Sub-Zielthema.

Ein Lite-Thema kann eine Kombination aus Exportabos und Standardabos enthalten. Die beiden Abotypen sind in Bezug auf Kontingentnutzung und Reservierungsdurchsatz identisch. Ein Exportabo verbraucht die Durchsatzkapazität für Lite-Abos und wird für den Pub/Sub-Veröffentlichungsdurchsatz in Rechnung gestellt.

Ein Exportabo verbindet ein Lite-Thema mit genau einem Pub/Sub-Thema. Ein Lite-Thema kann jedoch mehrere Exportabos haben, die mit verschiedenen Pub/Sub-Themen (Fan-Out-Architektur) verbunden sind. Sie können auch aus mehreren Lite-Themen in dasselbe Pub/Sub-Thema (Fan-In-Architektur) exportieren.

Authentifizierung

Ein Exportabo greift sowohl auf Pub/Sub Lite- als auch auf Pub/Sub-Ressourcen zu. Zum Erstellen eines Exportabos benötigen Sie die folgenden Berechtigungen:

• pubsublite.subscriptions.create. Diese Berechtigung ist in folgenden vordefinierten Rollen enthalten:

  • roles/pubsublite.admin
  • roles/pubsublite.editor

  Siehe Zugriffssteuerung für Pub/Sub Lite.

• pubsub.topics.get. Diese Berechtigung ist in folgenden vordefinierten Rollen enthalten:

  • roles/pubsub.admin
  • roles/pubsub.editor
  • roles/pubsub.viewer

  Siehe Zugriffssteuerung für Pub/Sub.

Dienst-Agents

Ein Exportabo wird in Ihrem Namen in einem Pub/Sub-Thema veröffentlicht. Dazu wird ein von Google verwaltetes Dienstkonto verwendet.

Wenn Sie das erste Exportabo in einem Projekt erstellen, wird automatisch ein von Google verwalteter Pub/Sub Lite-Dienst-Agent erstellt. Wenn Sie im selben Projekt zusätzliche Exportabos erstellen, verwenden diese denselben Dienst-Agent. Der Dienst-Agent hat das folgende Benennungsschema: service-<your_project_number>@gcp-sa-pubsublite.iam.gserviceaccount.com.

Der Dienst-Agent wird mit der Berechtigung zum Veröffentlichen in allen Pub/Sub- und Pub/Sub Lite-Themen im selben Projekt wie das Exportabo erstellt. Wenn sich Ihr Pub/Sub-Zielthema in einem anderen Projekt als das Exportabo befindet, müssen Sie dem Dienst-Agent zusätzliche Berechtigungen gewähren. Fügen Sie dazu die Rolle Pub/Sub-Publisher (roles/pubsub.publisher) hinzu. Sie können Berechtigungen für ein ganzes Projekt oder ein einzelnes Thema erteilen. Wir empfehlen, Berechtigungen auf Themenebene gemäß dem Prinzip der geringsten Berechtigung zu gewähren.

Weitere Informationen finden Sie unter Zugriff über die Google Cloud Console steuern. Sie können auch den Befehl gcloud projects add-iam-policy-binding verwenden, um IAM-Rollen hinzuzufügen:

gcloud pubsub topics add-iam-policy-binding TOPIC_NAME \
 --member=serviceAccount:[e-mail]
 --role=roles/pubsub.publisher

Ersetzen Sie Folgendes:

• TOPIC_NAME: Der Name des Pub/Sub-Zielthemas, dem die IAM-Richtlinienbindung hinzugefügt werden soll.
• PROJECT_NUMBER: Die Projektnummer des Projekts des Pub/Sub Lite-Exportabos.

Exportabo erstellen

Sie können ein Lite-Exportabo mit der Google Cloud Console, der Google Cloud CLI oder der Pub/Sub Lite API erstellen.

Ein Lite-Exportabo muss sich im selben Projekt und am selben Standort wie das Lite-Thema befinden, mit dem es verknüpft ist. Informationen zum Erstellen des Lite-Themas finden Sie unter Lite-Themen erstellen und verwalten.

Achten Sie beim Hinzufügen eines Exportabos an ein Lite-Thema darauf, dass alle im Lite-Thema veröffentlichten Nachrichten mit Pub/Sub kompatibel sind. Weitere Informationen finden Sie unter Nachrichtenkompatibilität.

Sobald es erstellt wurde, kann ein Exportabo nicht mehr in ein Standardabo geändert werden oder umgekehrt.

Console

1. Rufen Sie die Seite Lite-Abos auf.

   Zu Lite-Abos

2. Klicken Sie auf Lite-Abo erstellen.

3. Geben Sie eine Lite-Abo-ID ein.

4. Wählen Sie ein Lite-Thema aus, von dem Nachrichten empfangen werden sollen.

5. Wählen Sie Nachrichten sofort zustellen oder Nachrichten nach dem Speichern zustellen aus.

6. Wählen Sie den Typ Anfangsversatz aus.

7. Wählen Sie In Pub/Sub-Thema exportieren aus.

8. Wählen Sie in der Liste Zielthema ein Pub/Sub-Thema aus, das die exportierten Lite-Nachrichten erhalten soll.

9. Optional. Geben Sie ein Thema für unzustellbare Nachrichten an.

   1. Klicken Sie das Kästchen Unzustellbare Nachrichten aktivieren an.
   2. Wählen Sie ein Lite-Thema aus, das als Thema für unzustellbare Nachrichten verwendet werden soll, oder klicken Sie auf Lite-Thema erstellen, um ein neues Thema für unzustellbare Nachrichten zu erstellen. Das Thema für unzustellbare Nachrichten muss sich am selben Standort (Zone oder Region) und im selben Projekt wie das Exportabo befinden.

10. Klicken Sie auf Erstellen.

gcloud

Verwenden Sie den Befehl gcloud pubsub lite-subscriptions create, um ein Exportabo zu erstellen:

gcloud pubsub lite-subscriptions create SUBSCRIPTION_ID \
  --location=LOCATION \
  --topic=TOPIC_ID \
  --export-pubsub-topic=PUBSUB_TOPIC_NAME \
  --export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \
  --export-desired-state=DESIRED_STATE

Ersetzen Sie Folgendes:

• SUBSCRIPTION_ID: Die ID des zu erstellenden Lite-Abos.
• LOCATION: Der Standort des Lite-Abos.
• TOPIC_ID: Die ID des Lite-Themas, das mit dem Lite-Abo verknüpft werden soll.
• PUBSUB_TOPIC_NAME: Der Name des Pub/Sub-Themas, in das exportiert werden soll. Geben Sie den vollständigen Namen an, wenn sich das Thema in einem anderen Projekt befindet: projects/my-project-id/topics/my-topic-id.
• DEAD_LETTER_TOPIC_ID: Optional. Die ID eines Lite-Themas, das als Thema für unzustellbare Nachrichten verwendet werden soll. Das Thema für unzustellbare Nachrichten muss sich am selben Standort (Zone oder Region) und im selben Projekt wie das Exportabo befinden.
• DESIRED_STATE: Optional. Der Startstatus des Abos. Folgende Werte werden unterstützt:
  • active: Das Abo exportiert Lite-Nachrichten in Pub/Sub. (Standardeinstellung.)
  • paused: Der Export von Lite-Nachrichten wurde gesperrt.

Wenn die Anfrage erfolgreich ist, wird in der Befehlszeile eine Bestätigung angezeigt:

Created [SUBSCRIPTION_ID].

Protokoll

Senden Sie eine POST-Anfrage wie die folgende, um ein Lite-Exportabo zu erstellen:

POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer $(gcloud auth print-access-token)

Ersetzen Sie Folgendes:

• REGION: Die Region, in der das Lite-Abo gespeichert wird.
• PROJECT_NUMBER: Die Projektnummer des Projekts, in dem das Lite-Abo erstellt werden soll.
• LOCATION: Der Name eines Standorts, den Pub/Sub Lite unterstützt.
• SUBSCRIPTION_ID: Die ID des Lite-Abos.

Geben Sie im Anfragetext die folgenden Felder an:

{
  "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      }
  }
}

Ersetzen Sie Folgendes:

• DELIVERY_REQUIREMENT: Die Zustellungsanforderung, entweder DELIVER_AFTER_STORED oder DELIVER_IMMEDIATELY.
• DESIRED_STATE: Der Startstatus für das Abo. Folgende Werte werden unterstützt:
  • ACTIVE: Das Abo exportiert Lite-Nachrichten in Pub/Sub.
  • PAUSED: Der Export von Lite-Nachrichten wurde gesperrt.
• DEAD_LETTER_TOPIC_ID: Die ID eines vorhandenen Lite-Themas, das als Thema mit unzustellbaren Nachrichten verwendet werden soll. Das Thema muss sich am selben Standort (Zone oder Region) und im selben Projekt wie das Exportabo selbst befinden.
• PUBSUB_TOPIC_NAME: Der Name des Pub/Sub-Themas, in das exportiert werden soll. Beispielformat: projects/my-project-id/topics/my-topic-id.

Wenn die Anfrage erfolgreich ist, ist die Antwort das Lite-Abo im JSON-Format:

{
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      },
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID",
  "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
}

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.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsublite"
)

func createPubsubExportSubscription(w io.Writer, projectID, region, location, topicID, subID, pubsubTopicID string) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// NOTE: location can be either a region ("us-central1") or a zone ("us-central1-a")
	// For a list of valid locations, see https://cloud.google.com/pubsub/lite/docs/locations.
	// location := "us-central1"
	// NOTE: topic and subscription must be in the same region/zone (e.g. "us-central1-a")
	// topicID := "my-topic"
	// subID := "my-subscription"
	// pubsubTopicID := "destination-topic-id"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %w", err)
	}
	defer client.Close()

	// Initialize the subscription to the oldest retained messages for each
	// partition.
	targetLocation := pubsublite.AtTargetLocation(pubsublite.Beginning)

	sub, err := client.CreateSubscription(ctx, pubsublite.SubscriptionConfig{
		Name:                fmt.Sprintf("projects/%s/locations/%s/subscriptions/%s", projectID, location, subID),
		Topic:               fmt.Sprintf("projects/%s/locations/%s/topics/%s", projectID, location, topicID),
		DeliveryRequirement: pubsublite.DeliverImmediately, // Can also be DeliverAfterStored.
		// Configures an export subscription that writes messages to a Pub/Sub topic.
		ExportConfig: &pubsublite.ExportConfig{
			DesiredState: pubsublite.ExportActive, // Can also be ExportPaused.
			Destination: &pubsublite.PubSubDestinationConfig{
				Topic: fmt.Sprintf("projects/%s/topics/%s", projectID, pubsubTopicID),
			},
		},
	}, targetLocation)
	if err != nil {
		return fmt.Errorf("client.CreateSubscription got err: %w", err)
	}
	fmt.Fprintf(w, "Created export subscription: %s\n", sub.Name)
	return nil
}

Java

Folgen Sie der Einrichtungsanleitung für Java unter Pub/Sub Lite-Clientbibliotheken, bevor Sie dieses Beispiel ausführen.

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.BacklogLocation;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudRegionOrZone;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.SeekTarget;
import com.google.cloud.pubsublite.SubscriptionName;
import com.google.cloud.pubsublite.SubscriptionPath;
import com.google.cloud.pubsublite.TopicName;
import com.google.cloud.pubsublite.TopicPath;
import com.google.cloud.pubsublite.proto.ExportConfig;
import com.google.cloud.pubsublite.proto.ExportConfig.PubSubConfig;
import com.google.cloud.pubsublite.proto.ExportConfig.State;
import com.google.cloud.pubsublite.proto.Subscription;
import com.google.cloud.pubsublite.proto.Subscription.DeliveryConfig;
import com.google.cloud.pubsublite.proto.Subscription.DeliveryConfig.DeliveryRequirement;
import java.util.concurrent.ExecutionException;

public class CreatePubsubExportSubscriptionExample {

  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String cloudRegion = "your-cloud-region";
    char zoneId = 'b';
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String pubsubTopicId = "destination-topic-id";
    long projectNumber = Long.parseLong("123456789");
    // True if using a regional location. False if using a zonal location.
    // https://cloud.google.com/pubsub/lite/docs/topics
    boolean regional = false;

    createPubsubExportSubscriptionExample(
        cloudRegion, zoneId, projectNumber, topicId, subscriptionId, pubsubTopicId, regional);
  }

  public static void createPubsubExportSubscriptionExample(
      String cloudRegion,
      char zoneId,
      long projectNumber,
      String topicId,
      String subscriptionId,
      String pubsubTopicId,
      boolean regional)
      throws Exception {

    CloudRegionOrZone location;
    if (regional) {
      location = CloudRegionOrZone.of(CloudRegion.of(cloudRegion));
    } else {
      location = CloudRegionOrZone.of(CloudZone.of(CloudRegion.of(cloudRegion), zoneId));
    }

    TopicPath topicPath =
        TopicPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(location)
            .setName(TopicName.of(topicId))
            .build();

    SubscriptionPath subscriptionPath =
        SubscriptionPath.newBuilder()
            .setLocation(location)
            .setProject(ProjectNumber.of(projectNumber))
            .setName(SubscriptionName.of(subscriptionId))
            .build();

    com.google.pubsub.v1.TopicName pubsubTopicName =
        com.google.pubsub.v1.TopicName.of(String.valueOf(projectNumber), pubsubTopicId);

    Subscription subscription =
        Subscription.newBuilder()
            .setDeliveryConfig(
                // Possible values for DeliveryRequirement:
                // - `DELIVER_IMMEDIATELY`
                // - `DELIVER_AFTER_STORED`
                // You may choose whether to wait for a published message to be successfully written
                // to storage before the server delivers it to subscribers. `DELIVER_IMMEDIATELY` is
                // suitable for applications that need higher throughput.
                DeliveryConfig.newBuilder()
                    .setDeliveryRequirement(DeliveryRequirement.DELIVER_IMMEDIATELY))
            .setExportConfig(
                // Configures an export subscription that writes messages to a Pub/Sub topic.
                ExportConfig.newBuilder()
                    // Possible values for State:
                    // - `ACTIVE`: enable message processing.
                    // - `PAUSED`: suspend message processing.
                    .setDesiredState(State.ACTIVE)
                    .setPubsubConfig(
                        PubSubConfig.newBuilder().setTopic(pubsubTopicName.toString())))
            .setName(subscriptionPath.toString())
            .setTopic(topicPath.toString())
            .build();

    // Target location within the message backlog that the subscription should be initialized to.
    SeekTarget initialLocation = SeekTarget.of(BacklogLocation.BEGINNING);

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(location.extractRegion()).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources, or
    // use "try-with-close" statement to do this automatically.
    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      Subscription response = adminClient.createSubscription(subscription, initialLocation).get();
      System.out.println(response.getAllFields() + " created successfully.");
    } catch (ExecutionException e) {
      try {
        throw e.getCause();
      } catch (AlreadyExistsException alreadyExists) {
        System.out.println("This subscription already exists.");
      } catch (Throwable throwable) {
        throwable.printStackTrace();
      }
    }
  }
}

Python

Folgen Sie der Einrichtungsanleitung für Python unter Pub/Sub Lite-Clientbibliotheken, bevor Sie dieses Beispiel ausführen.

from google.api_core.exceptions import AlreadyExists
from google.cloud.pubsub_v1 import PublisherClient
from google.cloud.pubsublite import AdminClient, Subscription, ExportConfig
from google.cloud.pubsublite.types import (
    BacklogLocation,
    CloudRegion,
    CloudZone,
    SubscriptionPath,
    TopicPath,
)

def create_lite_pubsub_export_subscription(
    project_number,
    cloud_region="us-central1",
    zone_id="a",
    topic_id="my-topic-id",
    subscription_id="my-subscription-id",
    pubsub_topic_id="destination-topic-id",
    regional=True,
    target_location=BacklogLocation.BEGINNING,
):
    if regional:
        location = CloudRegion(cloud_region)
    else:
        location = CloudZone(CloudRegion(cloud_region), zone_id)

    topic_path = TopicPath(project_number, location, topic_id)
    subscription_path = SubscriptionPath(project_number, location, subscription_id)
    destination_topic_path = PublisherClient.topic_path(project_number, pubsub_topic_id)

    subscription = Subscription(
        name=str(subscription_path),
        topic=str(topic_path),
        delivery_config=Subscription.DeliveryConfig(
            # Possible values for delivery_requirement:
            # - `DELIVER_IMMEDIATELY`
            # - `DELIVER_AFTER_STORED`
            # You may choose whether to wait for a published message to be successfully written
            # to storage before the server delivers it to subscribers. `DELIVER_IMMEDIATELY` is
            # suitable for applications that need higher throughput.
            delivery_requirement=Subscription.DeliveryConfig.DeliveryRequirement.DELIVER_IMMEDIATELY,
        ),
        # Configures an export subscription that writes messages to a Pub/Sub topic.
        export_config=ExportConfig(
            # Possible values for desired_state:
            # - `ACTIVE`: enable message processing.
            # - `PAUSED`: suspend message processing.
            desired_state=ExportConfig.State.ACTIVE,
            pubsub_config=ExportConfig.PubSubConfig(
                topic=destination_topic_path,
            ),
        ),
    )

    # Initialize client that will be used to send requests across threads. This
    # client only needs to be created once, and can be reused for multiple requests.
    client = AdminClient(cloud_region)
    try:
        response = client.create_subscription(subscription, target_location)
        print(f"{response.name} created successfully.")
    except AlreadyExists:
        print(f"{subscription_path} already exists.")

Exportabo aktualisieren

Sie können Lite-Abos mit der Google Cloud Console, der Google Cloud CLI oder der Pub/Sub Lite API aktualisieren. Es kann bis zu 30 Sekunden dauern, bis die neuen Einstellungen angewendet werden.

Console

1. Rufen Sie die Seite Lite-Abos auf.

   Zu Lite-Abos

2. Klicken Sie auf die Lite-Abo-ID.

3. Klicken Sie auf der Seite Lite-Abonnementdetails auf Bearbeiten.

gCloud

Verwenden Sie zum Aktualisieren eines Lite-Abos den Befehl gcloud pubsub lite-subscriptions update:

gcloud pubsub lite-subscriptions update SUBSCRIPTION_ID \
--location=LOCATION \
--delivery-requirement=DELIVERY_REQUIREMENT \
--export-pubsub-topic=PUBSUB_TOPIC_NAME \
--export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \
--export-desired-state=DESIRED_STATE

Ersetzen Sie Folgendes:

• SUBSCRIPTION_ID: Die ID des Lite-Abos
• LOCATION: Der Standort des Lite-Abos.
• DELIVERY_REQUIREMENT: Optional. Die Zustellungsanforderung, entweder deliver-after-stored oder deliver-immediately.
• PUBSUB_TOPIC_NAME: Optional. Der Name des Pub/Sub-Themas, in das exportiert werden soll. Geben Sie den vollständigen Namen an, wenn sich das Thema in einem anderen Projekt befindet: projects/my-project-id/topics/my-topic-id.
• DEAD_LETTER_TOPIC_ID: Die ID eines vorhandenen Lite-Themas, das als Thema mit unzustellbaren Nachrichten verwendet werden soll. Das Thema muss sich am selben Standort (Zone oder Region) und im selben Projekt wie das Exportabo selbst befinden.
• DESIRED_STATE: Optional. Der gewünschte Status des Abos. Folgende Werte werden unterstützt:
  • active: Das Abo exportiert Lite-Nachrichten in Pub/Sub. (Standardeinstellung.)
  • paused: Der Export von Lite-Nachrichten wurde gesperrt.

Wenn die Anfrage erfolgreich ist, wird in der Befehlszeile das Lite-Abo angezeigt:

Updated subscription [SUBSCRIPTION_ID].
deliveryConfig:
deliveryRequirement: DELIVERY_REQUIREMENT
exportConfig:
currentState: DESIRED_STATE
deadLetterTopic: projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID
desiredState: DESIRED_STATE
pubsubConfig:
  topic: PUBSUB_TOPIC_NAME
name: projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID
topic: projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID

Protokoll

Um ein Lite-Abo zu aktualisieren, senden Sie eine PATCH-Anfrage wie die folgende:

PATCH https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID?updateMask=deliveryConfig.deliveryRequirement,exportConfig
Authorization: Bearer $(gcloud auth print-access-token)

Ersetzen Sie Folgendes:

• REGION: Die Region, in der das Lite-Abo erstellt wurde.
• PROJECT_NUMBER: Die Projektnummer des Projekts, in dem das Lite-Abo erstellt wurde.
• LOCATION: Der Standort, an dem das Lite-Abo erstellt wurde.
• SUBSCRIPTION_ID: Die ID des Lite-Abos.

Geben Sie im Anfragetext die folgenden Felder an:

{
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      }
  }
}

Ersetzen Sie Folgendes:

• DELIVERY_REQUIREMENT: Die Zustellungsanforderung, entweder DELIVER_AFTER_STORED oder DELIVER_IMMEDIATELY.
• DESIRED_STATE: Der gewünschte Status für das Abo. Folgende Werte werden unterstützt:
  • ACTIVE: Das Abo exportiert Lite-Nachrichten in Pub/Sub.
  • PAUSED: Der Export von Lite-Nachrichten wurde gesperrt.
• DEAD_LETTER_TOPIC_ID: Die ID eines vorhandenen Lite-Themas, das als Thema mit unzustellbaren Nachrichten verwendet werden soll. Das Thema muss sich am selben Standort (Zone oder Region) und im selben Projekt wie das Exportabo selbst befinden.
• PUBSUB_TOPIC_NAME: Der Name des Pub/Sub-Zielthemas. Beispielformat: projects/my-project-id/topics/my-topic-id.

Wenn die Anfrage erfolgreich ist, ist die Antwort das Lite-Abo im JSON-Format:

{
"deliveryConfig": {
  "deliveryRequirement": "DELIVERY_REQUIREMENT",
},
"exportConfig": {
  "desiredState": "DESIRED_STATE",
  "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
  "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" }
},
"name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
}

Exportabo pausieren oder starten

Exportabos haben die Einstellung gewünschter Status mit einem von zwei Werten:

• Aktiv: Das Abo exportiert Lite-Nachrichten in Pub/Sub.
• Pausiert: Der Export von Lite-Nachrichten wird ausgesetzt.

So ändern Sie den gewünschten Status in der Google Cloud Console:

1. Rufen Sie die Seite Lite-Abos auf.

   Zu Lite-Abos

2. Klicken Sie auf die Lite-Abo-ID.

3. Klicken Sie auf der Seite Lite-Abodetails auf Pausieren oder Starten.

Sie können den gewünschten Status auch mithilfe der Google Cloud CLI oder der Pub/Sub Lite API aktualisieren. Siehe Exportabo aktualisieren.

Best Practices

In diesem Abschnitt werden einige Best Practices für die Verwendung von Exportabos beschrieben.

Reservierungen

Wir empfehlen, ein Exportabo mit einer Reservierung zu verwenden, anstatt die Durchsatzkapazität des Abos explizit festzulegen.

Nachrichtenkompatibilität

Wenn eine Pub/Sub Lite-Nachricht nicht mit Pub/Sub kompatibel ist, wird die Nachricht vom Exportabo nicht in Pub/Sub veröffentlicht. Stattdessen wird die Nachricht in das Thema für unzustellbare Nachrichten verschoben, wenn ein Thema zugewiesen wurde. Wenn kein Thema für unzustellbare Nachrichten zugewiesen wurde, werden inkompatible Nachrichten einfach gelöscht.

Beachten Sie beim Veröffentlichen von Nachrichten im Lite-Thema die folgenden Kompatibilitätsprobleme:

• Schlüssel: Pub/Sub Lite-Schlüssel haben den Typ bytes, Pub/Sub-Sortierschlüssel den Typ string. Der Pub/Sub Lite-Schlüssel darf nur UTF-8-Zeichen enthalten, um kompatibel zu sein.

• Attribute: Für Nachrichtenattribute gelten die folgenden Anforderungen:

  • Alle Pub/Sub Lite-Nachrichtenattribute müssen einen einzigen Wert haben, um kompatibel zu sein. Pub/Sub Lite unterstützt Nachrichtenattribute mit mehreren Werten, Pub/Sub unterstützt jedoch nur Attribute mit einem Wert.
  • Die Nachrichtenattribute dürfen die Limits für Pub/Sub-Nachrichten, einschließlich der maximalen Anzahl von Attributen pro Nachricht und der maximalen Schlüssel- und Wertgröße pro Attribut, nicht überschreiten.

Thema für unzustellbare Nachrichten

Um inkompatible Nachrichten aufzubewahren und zu verarbeiten, empfehlen wir die Verwendung eines Themas für unzustellbare Nachrichten. Sie können beim Erstellen des Exportabos ein Thema für unzustellbare Nachrichten zuweisen oder ein vorhandenes Exportabo so aktualisieren, dass ein Thema für unzustellbare Nachrichten verwendet wird. Wenn das Abo eine Nachricht erhält, die mit Pub/Sub nicht kompatibel ist, wird die Nachricht im Thema für unzustellbare Nachrichten veröffentlicht.

Ein Thema für unzustellbare Nachrichten ist ein reguläres Pub/Sub Lite-Thema. Es muss sich am selben Speicherort und Projekt wie das Exportabo befinden und sich vom Quellthema unterscheiden.

In der Regel hat ein Thema für unzustellbare Nachrichten eine niedrige Durchsatzauslastung. Daher empfehlen wir, dem Thema für unzustellbare Nachrichten eine Reservierung zuzuweisen, anstatt dem Thema einen Durchsatz zuzuweisen.

Übermittlungsfehler

Ein Exportabo versucht, alle kompatiblen Nachrichten an das Pub/Sub-Zielthema zu senden. Wenn die Nachrichtenübermittlung fehlschlägt, wird das Exportabo gesperrt. Die Fehlerkategorie finden Sie im Messwert subscription/export_status. Die folgenden Werte geben einen Fehler an:

• PERMISSION_DENIED: Unzureichende Berechtigungen zum Exportieren von Nachrichten.
• NOT_FOUND: Eine oder mehrere Ressourcen wurden nicht gefunden. Das Zielthema ist beispielsweise nicht vorhanden.

Weitere Informationen zur Fehlerbehebung finden Sie unter Fehler beim Export von Abos beheben.

Nachdem Sie den Fehler behoben haben, wird das Exportabo nach regelmäßigen Wiederholungsversuchen automatisch neu gestartet.

Preise

Die vom Exportabo genutzten Pub/Sub Lite- und Pub/Sub-Ressourcen werden Ihnen in Rechnung gestellt. Insbesondere werden Ihnen der zugewiesene Abodurchsatz und der zugewiesene Speicher für das Pub/Sub Lite-Abo in Rechnung gestellt, die für das Pub/Sub Lite-Thema konfiguriert sind. Außerdem wird Ihnen die Veröffentlichung im Pub/Sub-Zielthema in Rechnung gestellt. Siehe Pub/Sub-Preise.

Für die Nutzung der Exportfunktion fallen keine zusätzlichen Gebühren an. Außerdem gibt es keine Preisunterschiede zwischen Pub/Sub Lite-Exportabos und Standardabos.

Fehler beim Export von Abos beheben

In diesem Abschnitt finden Sie einige Tipps zur Fehlerbehebung beim Export von Abos.

Das Exportabo ist pausiert

Wenn das Abo pausiert ist, werden keine Nachrichten exportiert.

So erkennen Sie dieses Problem:

• Google Cloud Console: Rufen Sie die Abodetails auf. Wenn das Abo pausiert ist, sind Gewünschter Status und Aktueller Status Paused.

• Messwerte: Der Messwert subscription/export_status ist PAUSED.

Starten Sie das Abo, um dieses Problem zu beheben.

Das Zielthema oder Thema für unzustellbare Nachrichten wurde gelöscht

Wenn Sie das mit einem Exportabo verknüpfte Pub/Sub-Thema oder das Thema für unzustellbare Nachrichten löschen, tritt ein Fehler auf.

So erkennen Sie dieses Problem:

• Google Cloud Console: Rufen Sie die Abodetails auf. Wenn das Thema gelöscht wurde, ist der aktuelle Status Not found.

• Messwerte: Der Messwert subscription/export_status. Wenn das Thema gelöscht wurde, lautet der Wert NOT_FOUND.

Prüfen Sie das Pub/Sub-Zielthema und das Thema für unzustellbare Nachrichten (falls konfiguriert), um dieses Problem zu beheben.

Wenn das Ziel-Pub/Sub gelöscht wurde, erstellen Sie das Thema mit demselben Namen neu. Die Veröffentlichung des Exportabos setzt die Veröffentlichung fort, sofern sich die Berechtigungen nicht geändert haben.

Wenn das Thema für unzustellbare Nachrichten gelöscht wurde, erstellen Sie ein neues Thema für unzustellbare Nachrichten und aktualisieren Sie das Exportabo, um darauf zu verweisen.

Inkompatible Nachrichten

Wenn Nachrichten mit Pub/Sub nicht kompatibel sind, werden sie nicht exportiert.

So erkennen Sie dieses Problem:

• Messwerte: Der Messwert subscription/unexportable_message_count gibt die Anzahl der inkompatiblen Nachrichten an, die nicht exportiert werden konnten.

Verwenden Sie zur Behebung dieses Problems ein Thema für unzustellbare Nachrichten, um die inkompatiblen Nachrichten aufzubewahren. Prüfen Sie die Meldungen, um die Ursache zu ermitteln, transformieren Sie sie und veröffentlichen Sie sie gegebenenfalls neu. Siehe Nachrichtenkompatibilität.

Export ist gedrosselt

So erkennen Sie dieses Problem:

• Messwerte: Der Messwert subscription/flow_control_status zeigt den Grund für die Ablaufsteuerung von NO_CLIENT_TOKENS an. Dieser gibt an, dass das Limit für ausstehende Byte oder Nachrichten pro Partition erreicht wurde. Bis das Problem behoben ist, erhöht sich der Rückstand für die zugehörigen Exportabos.

Dieser Fehler hat mehrere mögliche Ursachen. Die meisten möglichen Ursachen treten im Back-End auf. Überprüfen Sie jedoch Folgendes:

• Achten Sie darauf, dass Sie Lite-Nachrichten mit demselben Schlüssel mit einer Rate von weniger als 1 MiB/s pro Schlüssel veröffentlichen. Das Exportabo schreibt Lite-Nachrichtenschlüssel als Pub/Sub-Sortierschlüssel. In Pub/Sub hat jeder Sortierschlüssel ein Limit von 1 MiB/s. Das Überschreiten dieses Limits kann zu einer Drosselung führen.

Der Nutzer ist nicht zum Ausführen dieser Aktion berechtigt

Der Pub/Sub Lite-Dienst-Agent muss Berechtigungen zum Veröffentlichen im Pub/Sub-Zielthema haben.

So erkennen Sie dieses Problem:

• Google Cloud Console: Rufen Sie die Abodetails auf. Wenn Berechtigungsfehler vorliegen, lautet der Aktueller Status Permission denied.

• Messwerte: Der Messwert subscription/export_status ist PERMISSON_DENIED.

Dieser Fehler kann beispielsweise in den folgenden Situationen auftreten:

• Dem Pub/Sub Lite-Dienst-Agent fehlt die richtige Berechtigung oder Rolle zum Veröffentlichen von Nachrichten im Pub/Sub-Zielthema in einem anderen Projekt.
• Der Dienst-Agent wurde aus der IAM-Richtlinie des übergeordneten Projekts des Exportabos entfernt.
• Der Pub/Sub Lite-Dienst-Agent wird noch eingerichtet. Ein Dienst-Agent wird automatisch erstellt, wenn Sie das erste Exportabo in einem Projekt erstellen. Der Berechtigungsfehler sollte innerhalb von 10 Minuten automatisch behoben sein.

Prüfen Sie, ob dem Dienst-Agent die richtige Berechtigung oder Rolle gewährt wurde, um das Problem zu beheben. Siehe Dienst-Agents.

Nächste Schritte

Wählen Sie zwischen Pub/Sub oder Pub/Sub Lite aus.