Esportare messaggi Pub/Sub Lite in Pub/Sub

Nota: Pub/Sub Lite è deprecato. A partire dal 18 marzo 2026, Pub/Sub Lite verrà disattivato.

• Clienti attuali: Pub/Sub Lite rimarrà funzionante fino al 18 marzo 2026. Se non hai utilizzato Pub/Sub Lite nei 90 giorni precedenti il 24 settembre 2024 (dal 26 giugno al 24 settembre 2024), non potrai accedere a Pub/Sub Lite a partire dal 24 settembre 2024.
• Nuovi clienti: Pub/Sub Lite non sarà più disponibile per i nuovi clienti dopo il 18 settembre 2024.

Questo documento descrive come configurare l'esportazione automatica dei messaggi Pub/Sub Lite in Pub/Sub.

Ecco alcuni scenari in cui è possibile utilizzare questa funzionalità:

• Interoperare tra carichi di lavoro che utilizzano una combinazione di Pub/Sub Lite e Pub/Sub.
• Eseguire la migrazione di un carico di lavoro Pub/Sub Lite in Pub/Sub.
• Utilizza le funzionalità avanzate di Pub/Sub, come le sottoscrizioni push e i filtri, da un'applicazione esistente basata su Pub/Sub Lite.
• Consolidare più pipeline di dati.

Panoramica

Per esportare i messaggi da Pub/Sub Lite a Pub/Sub, devi creare un tipo speciale di sottoscrizione chiamato sottoscrizione di esportazione. Una sottoscrizione di esportazione riceve i messaggi da un argomento Lite, li converte in messaggi Pub/Sub e invia i messaggi convertiti a un argomento Pub/Sub di destinazione.

Un argomento Lite può avere una combinazione di sottoscrizioni di esportazione e sottoscrizioni standard. I due tipi di abbonamento sono identici in termini di utilizzo delle quote e velocità effettiva di prenotazione. Una sottoscrizione di esportazione utilizza la capacità di velocità effettiva della sottoscrizione Lite e viene addebitata la velocità effettiva di pubblicazione di Pub/Sub.

Una sottoscrizione di esportazione collega un argomento Lite a esattamente un argomento Pub/Sub. Tuttavia, un argomento Lite può avere più sottoscrizioni di esportazione che si connettono a diversi argomenti Pub/Sub (architettura fan-out). Puoi anche esportare da più argomenti Lite nello stesso argomento Pub/Sub (architettura fan-in).

Autenticazione

Una sottoscrizione di esportazione accede alle risorse Pub/Sub Lite e Pub/Sub. Per creare una sottoscrizione per l'esportazione, devi disporre delle seguenti autorizzazioni:

• pubsublite.subscriptions.create. I seguenti ruoli predefiniti contengono questa autorizzazione:

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

  Vedi Controllo dell'accesso per Pub/Sub Lite.

• pubsub.topics.get. I seguenti ruoli predefiniti contengono questa autorizzazione:

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

  Vedi Controllo dell'accesso per Pub/Sub.

Agenti di servizio

Una sottoscrizione di esportazione pubblica in un argomento Pub/Sub per tuo conto. Per farlo, utilizza un agente di servizio.

Dopo aver creato la prima sottoscrizione di esportazione in un progetto, viene creato automaticamente un agente di servizio Pub/Sub Lite. Se crei sottoscrizioni di esportazione aggiuntive nello stesso progetto, queste utilizzano lo stesso agente di servizio. L'agente di servizio ha il seguente schema di denominazione: service-<your_project_number>@gcp-sa-pubsublite.iam.gserviceaccount.com.

L'agente di servizio viene creato con le autorizzazioni per pubblicare in tutti gli argomenti Pub/Sub e Pub/Sub Lite all'interno dello stesso progetto della sottoscrizione di esportazione. Se l'argomento Pub/Sub di destinazione si trova in un progetto diverso dalla sottoscrizione di esportazione, devi concedere all'agente di servizio ulteriori autorizzazioni aggiungendo il ruolo Publisher Pub/Sub (roles/pubsub.publisher). Puoi concedere le autorizzazioni per un intero progetto o per un singolo argomento. Ti consigliamo di concedere le autorizzazioni a livello di argomento, secondo il principio del privilegio minimo.

Per ulteriori informazioni, consulta Controllo dell'accesso tramite la console Google Cloud. Puoi anche utilizzare il comando gcloud projects add-iam-policy-binding per aggiungere ruoli IAM:

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

Sostituisci quanto segue:

• TOPIC_NAME: il nome dell'argomento Pub/Sub di destinazione per aggiungere l'associazione dei criteri IAM.
• PROJECT_NUMBER: il numero del progetto della sottoscrizione di esportazione Pub/Sub Lite.

Crea una sottoscrizione per l'esportazione

Puoi creare un abbonamento di esportazione Lite con la console Google Cloud, Google Cloud CLI o l'API Pub/Sub Lite.

Una sottoscrizione di esportazione Lite deve trovarsi nello stesso progetto e nella stessa località dell'argomento Lite a cui è collegata. Per creare l'argomento Lite, consulta Creare e gestire argomenti Lite.

Se colleghi una sottoscrizione di esportazione a un argomento Lite, assicurati che tutti i messaggi pubblicati nell'argomento Lite siano compatibili con Pub/Sub. Per ulteriori informazioni, consulta la sezione Compatibilità dei messaggi.

Una volta creato, non puoi cambiare una sottoscrizione per l'esportazione in un abbonamento standard e viceversa.

Console

1. Vai alla pagina Abbonamenti Lite.

   Vai agli abbonamenti Lite

2. Fai clic su Crea sottoscrizione Lite.

3. Inserisci un ID sottoscrizione Lite.

4. Seleziona un argomento Lite da cui ricevere messaggi.

5. Seleziona Recapita immediatamente i messaggi o Recapita i messaggi dopo l'archiviazione.

6. Scegli un tipo di Offset iniziale.

7. Seleziona Esporta in argomento Pub/Sub.

8. Nell'elenco Argomento di destinazione, scegli un argomento Pub/Sub per ricevere i messaggi Lite esportati.

9. Facoltativo. Specifica un argomento messaggi non recapitabili.

   1. Seleziona la casella di controllo Abilita messaggi non recapitabili.
   2. Seleziona un argomento Lite da utilizzare come argomento messaggi non recapitabili o fai clic su Crea argomento Lite per creare un nuovo argomento messaggi non recapitabili. L'argomento messaggi non recapitabili deve trovarsi nella stessa località (zona o regione) e nello stesso progetto della sottoscrizione di esportazione.

10. Fai clic su Crea.

gcloud

Per creare una sottoscrizione per l'esportazione, utilizza il comando gcloud pubsub lite-subscriptions create:

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

Sostituisci quanto segue:

• SUBSCRIPTION_ID: l'ID della sottoscrizione Lite da creare.
• LOCATION: la località della sottoscrizione Lite.
• TOPIC_ID: l'ID dell'argomento Lite da collegare alla sottoscrizione Lite.
• PUBSUB_TOPIC_NAME: il nome dell'argomento Pub/Sub in cui eseguire l'esportazione. Specifica il nome completo se l'argomento si trova in un altro progetto: projects/my-project-id/topics/my-topic-id.
• DEAD_LETTER_TOPIC_ID: facoltativo. L'ID di un argomento Lite da utilizzare come argomento messaggi non recapitabili. L'argomento messaggi non recapitabili deve trovarsi nella stessa località (zona o regione) e nello stesso progetto della sottoscrizione di esportazione.
• DESIRED_STATE: facoltativo. Lo stato iniziale dell'abbonamento. Sono supportati i seguenti valori:
  • active: la sottoscrizione esporta i messaggi Lite in Pub/Sub. (opzione predefinita).
  • paused: l'esportazione di messaggi Lite è sospesa.

Se la richiesta ha esito positivo, la riga di comando visualizza una conferma:

Created [SUBSCRIPTION_ID].

Protocollo

Per creare una sottoscrizione di esportazione Lite, invia una richiesta POST come la seguente:

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

Sostituisci quanto segue:

• REGION: la regione in cui archiviare la sottoscrizione Lite.
• PROJECT_NUMBER: il numero del progetto in cui creare la sottoscrizione Lite.
• LOCATION: il nome di una località supportata da Pub/Sub Lite.
• SUBSCRIPTION_ID: l'ID della sottoscrizione Lite.

Specifica i seguenti campi nel corpo della richiesta:

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

Sostituisci quanto segue:

• DELIVERY_REQUIREMENT: il requisito di recapito, ovvero DELIVER_AFTER_STORED o DELIVER_IMMEDIATELY.
• DESIRED_STATE: lo stato iniziale dell'abbonamento. Sono supportati i seguenti valori:
  • ACTIVE: la sottoscrizione esporta i messaggi Lite in Pub/Sub.
  • PAUSED: l'esportazione di messaggi Lite è sospesa.
• DEAD_LETTER_TOPIC_ID: l'ID di un argomento Lite esistente da utilizzare come argomento messaggi non recapitabili. L'argomento deve trovarsi nella stessa località (zona o regione) e nello stesso progetto dell'abbonamento di esportazione.
• PUBSUB_TOPIC_NAME: il nome dell'argomento Pub/Sub in cui eseguire l'esportazione. Formato di esempio: projects/my-project-id/topics/my-topic-id.

Se la richiesta ha esito positivo, la risposta è la sottoscrizione Lite in formato JSON:

{
  "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",
}

Go

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

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

Prima di eseguire questo esempio, segui le istruzioni di configurazione di Java nelle librerie client di Pub/Sub Lite.

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

Prima di eseguire questo esempio, segui le istruzioni di configurazione di Python nelle librerie client di Pub/Sub Lite.

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.")

Aggiorna una sottoscrizione per l'esportazione

Puoi aggiornare gli abbonamenti Lite con la console Google Cloud, Google Cloud CLI o l'API Pub/Sub Lite. L'applicazione delle nuove impostazioni può richiedere fino a 30 secondi.

Console

1. Vai alla pagina Abbonamenti Lite.

   Vai agli abbonamenti Lite

2. Fai clic sull'ID sottoscrizione Lite.

3. Nella pagina Dettagli abbonamento Lite, fai clic su Modifica.

gCloud

Per aggiornare una sottoscrizione Lite, utilizza il comando 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

Sostituisci quanto segue:

• SUBSCRIPTION_ID: l'ID della sottoscrizione Lite
• LOCATION: la località della sottoscrizione Lite.
• DELIVERY_REQUIREMENT: facoltativo. Il requisito di recapito, ovvero deliver-after-stored o deliver-immediately.
• PUBSUB_TOPIC_NAME: facoltativo. Il nome dell'argomento Pub/Sub in cui eseguire l'esportazione. Specifica il nome completo se l'argomento si trova in un altro progetto: projects/my-project-id/topics/my-topic-id.
• DEAD_LETTER_TOPIC_ID: l'ID di un argomento Lite esistente da utilizzare come argomento messaggi non recapitabili. L'argomento deve trovarsi nella stessa località (zona o regione) e nello stesso progetto dell'abbonamento di esportazione.
• DESIRED_STATE: facoltativo. Lo stato desiderato della sottoscrizione. Sono supportati i seguenti valori:
  • active: la sottoscrizione esporta i messaggi Lite in Pub/Sub. (opzione predefinita).
  • paused: l'esportazione di messaggi Lite è sospesa.

Se la richiesta ha esito positivo, la riga di comando visualizza la sottoscrizione Lite:

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

Protocollo

Per aggiornare una sottoscrizione Lite, invia una richiesta PATCH come la seguente:

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)

Sostituisci quanto segue:

• REGION: la regione in cui è stata creata la sottoscrizione Lite.
• PROJECT_NUMBER: il numero del progetto in cui è stata creata la sottoscrizione Lite.
• LOCATION: la località in cui è stata creata la sottoscrizione Lite.
• SUBSCRIPTION_ID: l'ID della sottoscrizione Lite.

Specifica i seguenti campi nel corpo della richiesta:

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

Sostituisci quanto segue:

• DELIVERY_REQUIREMENT: il requisito di recapito, ovvero DELIVER_AFTER_STORED o DELIVER_IMMEDIATELY.
• DESIRED_STATE: lo stato desiderato per l'abbonamento. Sono supportati i seguenti valori:
  • ACTIVE: la sottoscrizione esporta i messaggi Lite in Pub/Sub.
  • PAUSED: l'esportazione di messaggi Lite è sospesa.
• DEAD_LETTER_TOPIC_ID: l'ID di un argomento Lite esistente da utilizzare come argomento messaggi non recapitabili. L'argomento deve trovarsi nella stessa località (zona o regione) e nello stesso progetto dell'abbonamento di esportazione.
• PUBSUB_TOPIC_NAME: il nome dell'argomento Pub/Sub di destinazione. Formato di esempio: projects/my-project-id/topics/my-topic-id.

Se la richiesta ha esito positivo, la risposta è la sottoscrizione Lite in formato JSON:

{
"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",
}

Mettere in pausa o avviare una sottoscrizione all'esportazione

Le sottoscrizioni di esportazione hanno un'impostazione denominata stato desiderato, che ha uno di due valori:

• Attivo: la sottoscrizione esporta i messaggi Lite in Pub/Sub.
• In pausa: l'esportazione di messaggi Lite è stata sospesa.

Per modificare lo stato desiderato nella console Google Cloud:

1. Vai alla pagina Abbonamenti Lite.

   Vai agli abbonamenti Lite

2. Fai clic sull'ID sottoscrizione Lite.

3. Nella pagina dei dettagli dell'abbonamento Lite, fai clic su Metti in pausa o Avvia.

Puoi anche aggiornare lo stato desiderato utilizzando Google Cloud CLI o l'API Pub/Sub Lite. Vedi Aggiornare un abbonamento di esportazione.

Best practice

In questa sezione vengono descritte alcune best practice relative all'utilizzo dell'esportazione di abbonamenti.

Prenotazioni

Ti consigliamo di utilizzare una sottoscrizione di esportazione con una prenotazione, anziché impostare esplicitamente la capacità di velocità effettiva dell'abbonamento.

Compatibilità dei messaggi

Se un messaggio Pub/Sub Lite non è compatibile con Pub/Sub, la sottoscrizione di esportazione non pubblica il messaggio in Pub/Sub. Il messaggio viene invece inserito nellargomento messaggi non recapitabili, se assegnato. Se non è stato assegnato alcun argomento messaggi non recapitabili, i messaggi incompatibili vengono semplicemente eliminati.

Quando pubblichi messaggi nell'argomento Lite, tieni presente i seguenti problemi di compatibilità:

• Chiavi. Le chiavi Pub/Sub Lite hanno il tipo bytes, mentre le chiavi di ordinamento Pub/Sub sono di tipo string. Per essere compatibile, la chiave Pub/Sub Lite deve contenere solo caratteri UTF-8.

• Attributi. Gli attributi dei messaggi presentano i seguenti requisiti:

  • Per essere compatibili, tutti gli attributi dei messaggi Pub/Sub Lite devono avere un singolo valore. Pub/Sub Lite supporta gli attributi dei messaggi con più valori, mentre Pub/Sub supporta solo gli attributi a valore singolo.
  • Gli attributi dei messaggi non devono superare i limiti dei messaggi Pub/Sub, inclusi il numero massimo di attributi per messaggio e le dimensioni massime di chiave e valore per attributo.

Argomento messaggi non recapitabili

Per conservare e gestire i messaggi non compatibili, ti consigliamo di utilizzare un argomento relativo ai messaggi non recapitabili. Puoi assegnare un argomento messaggi non recapitabili quando crei la sottoscrizione di esportazione oppure puoi aggiornare una sottoscrizione di esportazione esistente in modo da utilizzare un argomento messaggi non recapitabili. Se la sottoscrizione riceve un messaggio incompatibile con Pub/Sub, lo pubblica nell'argomento messaggi non recapitabili.

Un argomento messaggi non recapitabili è un normale argomento Pub/Sub Lite. Deve trovarsi nella stessa località e nello stesso progetto della sottoscrizione di esportazione e deve essere un argomento diverso da quello di origine.

In genere, un argomento messaggi non recapitabili ha un basso utilizzo della velocità effettiva. Consigliamo quindi di assegnare una prenotazione all'argomento messaggi non recapitabili, anziché di allocare la velocità effettiva all'argomento.

Errori di recapito

Una sottoscrizione di esportazione tenta di consegnare tutti i messaggi compatibili all'argomento Pub/Sub di destinazione. Se il recapito del messaggio non va a buon fine, l'abbonamento per l'esportazione viene sospeso. Per trovare la categoria di errore, controlla la metrica subscription/export_status. I seguenti valori indicano un errore:

• PERMISSION_DENIED: autorizzazioni insufficienti per esportare i messaggi.
• NOT_FOUND: una o più risorse non sono state trovate; ad esempio, l'argomento di destinazione non esiste.

Per maggiori informazioni sulla risoluzione dei problemi, vedi Risolvere i problemi di esportazione degli abbonamenti.

Una volta risolto l'errore, l'abbonamento per l'esportazione viene riavviato automaticamente a causa di nuovi tentativi periodici.

Prezzi

Ti vengono addebitate le risorse Pub/Sub Lite e Pub/Sub utilizzate dalla sottoscrizione di esportazione. In particolare, ti vengono addebitate la velocità effettiva di sottoscrizione allocata e lo spazio di archiviazione nella sottoscrizione Pub/Sub Lite, configurata per l'argomento Pub/Sub Lite. Ti viene inoltre addebitata la pubblicazione nell'argomento Pub/Sub di destinazione. Vedi Prezzi di Pub/Sub.

Non sono previsti costi aggiuntivi per l'utilizzo della funzionalità di esportazione e non esiste alcuna differenza di prezzo tra le sottoscrizioni di esportazione di Pub/Sub Lite e le sottoscrizioni standard.

Risoluzione dei problemi di esportazione delle sottoscrizioni

In questa sezione vengono descritti alcuni suggerimenti per la risoluzione dei problemi relativi all'esportazione delle iscrizioni.

La sottoscrizione all'esportazione è in pausa

Se la sottoscrizione viene sospesa, non verrà esportato nessun messaggio.

Per rilevare questo problema:

• Console Google Cloud: visualizza i dettagli dell'abbonamento. Se l'abbonamento è in pausa, lo Stato desiderato e lo Stato attuale sono Paused.

• Metriche: la metrica subscription/export_status è PAUSED.

Per risolvere il problema, attiva l'abbonamento.

L'argomento di destinazione o l'argomento messaggi non recapitabili è stato eliminato

Se elimini l'argomento Pub/Sub collegato a una sottoscrizione di esportazione o l'argomento messaggi non recapitabili, si verifica un errore.

Per rilevare questo problema:

• Console Google Cloud: visualizza i dettagli dell'abbonamento. Se l'argomento è stato eliminato, lo stato attuale è Not found.

• Metriche: la metrica subscription/export_status. Se l'argomento è stato eliminato, il valore è NOT_FOUND.

Per risolvere il problema, controlla l'argomento Pub/Sub di destinazione e l'argomento messaggi non recapitabili (se configurato).

Se Pub/Sub di destinazione è stato eliminato, ricrea l'argomento con lo stesso nome. La pubblicazione dell'abbonamento di esportazione riprende, supponendo che le autorizzazioni non siano state modificate.

Se l'argomento messaggi non recapitabili è stato eliminato, crea un nuovo argomento messaggi non recapitabili e aggiorna la sottoscrizione di esportazione per farvi riferimento.

Messaggi incompatibili

Se i messaggi non sono compatibili con Pub/Sub, non vengono esportati.

Per rilevare questo problema:

• Metriche: la metrica subscription/unexportable_message_count mostra il numero di messaggi incompatibili che non è stato possibile esportare.

Per risolvere il problema, utilizza un argomento messaggi non recapitabili per conservare i messaggi non compatibili. Esamina i messaggi per determinarne la causa, quindi trasformali e ripubblicali, se necessario. Consulta Compatibilità dei messaggi.

L'esportazione è limitata

Per rilevare questo problema:

• Metriche: la metrica subscription/flow_control_status mostra un motivo del controllo del flusso di NO_CLIENT_TOKENS, che indica che è stato raggiunto il limite per partizione di byte o messaggi in sospeso. Finché il problema non verrà risolto, il backlog aumenterà per le sottoscrizioni di esportazione associate.

Questo errore ha diverse possibili cause principali. La maggior parte delle possibili cause si verifica sul backend, ma verifica quanto segue:

• Assicurati di pubblicare messaggi Lite che condividono la stessa chiave a una velocità inferiore a 1 MiB/s per chiave. La sottoscrizione di esportazione scrive le chiavi dei messaggi Lite come chiavi di ordinamento Pub/Sub e Pub/Sub ha un limite di 1 MiB/s per ogni chiave di ordinamento. Il superamento di questo limite può causare una limitazione.

Utente non autorizzato a eseguire questa azione

L'agente di servizio Pub/Sub Lite deve disporre delle autorizzazioni per pubblicare nell'argomento Pub/Sub di destinazione.

Per rilevare questo problema:

• Console Google Cloud: visualizza i dettagli dell'abbonamento. Se sono presenti errori di autorizzazione, lo stato attuale è Permission denied.

• Metriche: la metrica subscription/export_status è PERMISSON_DENIED.

Ad esempio, le seguenti situazioni possono causare questo errore:

• L'agente di servizio Pub/Sub Lite non dispone dell'autorizzazione o del ruolo corretti per pubblicare messaggi nell'argomento Pub/Sub di destinazione di un altro progetto.
• L'agente di servizio è stato rimosso dal criterio IAM del progetto principale della sottoscrizione di esportazione.
• L'agente di servizio Pub/Sub Lite è ancora in fase di configurazione. Un agente di servizio viene creato automaticamente quando crei la prima sottoscrizione di esportazione in un progetto. L'errore di autorizzazione dovrebbe essere risolto automaticamente entro 10 minuti.

Per risolvere il problema, verifica se all'agente di servizio è stata concessa l'autorizzazione o il ruolo corretti. Vedi Agenti di servizio.

Passaggi successivi

Scegli tra Pub/Sub o Pub/Sub Lite.