Esportare messaggi Pub/Sub Lite in Pub/Sub

Nota: Pub/Sub Lite è deprecato. In vigore 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 è più disponibile per i nuovi clienti dopo il 18 settembre 2024.

Puoi eseguire la migrazione del tuo servizio Pub/Sub Lite ad Apache Kafka per BigQuery o Pub/Sub

Questo documento descrive come configurare l'esportazione automatica di di 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.
• Usa le funzionalità avanzate di Pub/Sub, come le sottoscrizioni push e di un'applicazione esistente basata su in Pub/Sub Lite.
• Consolidare più pipeline di dati.

Panoramica

Per esportare i messaggi da Pub/Sub Lite a Pub/Sub: crei un tipo speciale di sottoscrizione chiamato sottoscrizione per l'esportazione. Un di esportazione riceve messaggi da un argomento Lite, li converte in Pub/Sub e invia i messaggi convertiti a un Pub/Sub di destinazione.

Un argomento Lite può avere una combinazione sia di sottoscrizioni di esportazione che di abbonamenti. I due tipi di abbonamento sono identici in termini di utilizzo della quota e velocità effettiva di prenotazione. Una sottoscrizione per l'esportazione utilizza la capacità di velocità effettiva della sottoscrizione Lite e viene addebitato Velocità effettiva di pubblicazione di Pub/Sub.

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

Autenticazione

Una sottoscrizione di esportazione accede sia a Pub/Sub Lite delle risorse Pub/Sub. Per creare una sottoscrizione per l'esportazione, è necessario le seguenti autorizzazioni:

• pubsublite.subscriptions.create. I seguenti ruoli predefiniti contengono 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 viene pubblicata in un argomento Pub/Sub sul tuo per conto tuo. A questo scopo, utilizza una di servizio.

Dopo aver creato la prima sottoscrizione di esportazione in un progetto, L'agente di servizio Pub/Sub Lite viene creato automaticamente. Se sottoscrizioni di esportazione aggiuntive nello stesso progetto, utilizzano lo stesso dell'agente di servizio di servizio di Google Cloud. 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 necessarie per pubblicare su tutti Argomenti Pub/Sub e Pub/Sub Lite all'interno dello stesso progetto come sottoscrizione di esportazione. Se Pub/Sub di destinazione si trova in un progetto diverso dalla sottoscrizione di esportazione, devi concedere Ulteriori autorizzazioni dell'agente di servizio aggiungendo il ruolo Pub/Sub Publisher (roles/pubsub.publisher). Puoi concedere le autorizzazioni per un intero progetto oppure un singolo argomento. Consigliamo di concedere le autorizzazioni a livello di argomento, seguendo il principio del privilegio minimo.

Per ulteriori informazioni, vedi Controllo dell'accesso tramite la console Google Cloud Puoi utilizzare anche 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 del Pub/Sub di destinazione per aggiungere l'associazione dei criteri IAM.
• PROJECT_NUMBER: il numero del progetto Progetto di esportazione della sottoscrizione 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à di Lite dall'argomento a cui è allegato. 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 sono compatibili con Pub/Sub. Per ulteriori informazioni, consulta la sezione Compatibilità dei messaggi.

Una volta creata, non puoi modificare 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 i messaggi immediatamente o Recapita i messaggi dopo archiviati.

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 riceveranno 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 dell'esportazione abbonamento.

10. Fai clic su Crea.

gcloud

Per creare una sottoscrizione per l'esportazione, utilizza 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 posizione di Lite abbonamento.
• TOPIC_ID: l'ID dell'argomento Lite da allegare a Lite abbonamento.
• PUBSUB_TOPIC_NAME: il nome dell'argomento Pub/Sub in esporta in. 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 essere in la stessa località (zona o regione) e lo 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 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 per l'esportazione Lite, invia una richiesta POST come il seguenti:

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 che deve creare Sottoscrizione Lite.
• LOCATION: il nome di una posizione in cui Pub/Sub Lite Google Cloud.
• 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, DELIVER_AFTER_STORED o DELIVER_IMMEDIATELY.
• DESIRED_STATE: lo stato iniziale dell'abbonamento. La sono supportati i seguenti valori:
  • ACTIVE: la sottoscrizione esporta i messaggi Lite in 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 essere nello stesso località (zona o regione) e progetto come abbonamento per l'esportazione.
• PUBSUB_TOPIC_NAME: il nome dell'argomento Pub/Sub in esporta in. Formato di esempio: projects/my-project-id/topics/my-topic-id.

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

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

Vai

Prima di provare questo esempio, segui le istruzioni di configurazione di Go in Guida rapida all'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 in Librerie client 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 in Librerie client 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'operazione può richiedere fino a 30 secondi per l'applicazione delle nuove impostazioni.

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 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 posizione di Lite abbonamento.
• DELIVERY_REQUIREMENT: facoltativo. Il requisito di recapito, deliver-after-stored o deliver-immediately.
• PUBSUB_TOPIC_NAME: facoltativo. Il nome del 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 essere nello stesso località (zona o regione) e progetto come abbonamento per l'esportazione.
• DESIRED_STATE: facoltativo. Lo stato desiderato della sottoscrizione. Sono supportati i seguenti valori:
  • active: la sottoscrizione esporta i messaggi Lite in 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 Lite è stato creato un abbonamento.
• 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, DELIVER_AFTER_STORED o DELIVER_IMMEDIATELY.
• DESIRED_STATE: lo stato desiderato per l'abbonamento. La sono supportati i seguenti valori:
  • ACTIVE: la sottoscrizione esporta i messaggi Lite in 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 essere nello stesso località (zona o regione) e progetto come abbonamento per l'esportazione.
• PUBSUB_TOPIC_NAME: il nome della destinazione Pub/Sub. Formato di esempio: projects/my-project-id/topics/my-topic-id.

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

{
"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 alle esportazioni hanno un'impostazione chiamata stato desiderato, che ha uno dei seguenti: 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 oppure l'API Pub/Sub Lite. Consulta Aggiornare un abbonamento per l'esportazione.

Best practice

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

Prenotazioni

Ti consigliamo di utilizzare un abbonamento per l'esportazione con un reservation, anziché impostare esplicitamente la capacità di velocità effettiva della sottoscrizione.

Compatibilità dei messaggi

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

Quando pubblichi messaggi nell'argomento Lite, tieni presente quanto segue 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 garantire la compatibilità, La chiave Pub/Sub Lite deve contenere solo caratteri UTF-8.

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

  • Per la compatibilità, tutti gli attributi dei messaggi Pub/Sub Lite deve avere un singolo valore. Pub/Sub Lite supporta i messaggi con più valori, ma Pub/Sub supporta solo attributi a singolo valore.
  • Gli attributi dei messaggi non devono superare Limiti dei messaggi Pub/Sub, inclusi il numero massimo di attributi per messaggio e la dimensione massima di chiave e valore per .

Argomento messaggi non recapitabili

Per conservare e gestire i messaggi non compatibili, ti consigliamo di utilizzare un messaggio non recapitabile per ogni argomento. Puoi assegnare un argomento messaggi non recapitabili durante la creazione dell'esportazione o aggiornare una sottoscrizione all'esportazione esistente per utilizzare un argomento messaggi non recapitabili. Se la sottoscrizione riceve un messaggio incompatibile con Pub/Sub, pubblica il messaggio nell'argomento messaggi non recapitabili.

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

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

Errori di recapito

Una sottoscrizione di esportazione tenta di recapitare tutti i messaggi compatibili al Pub/Sub di destinazione. Se il recapito del messaggio non va a buon fine, l'esportazione è sospeso. Per individuare la categoria di errore, controlla la subscription/export_status metrica. 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, la destinazione l'argomento non esiste.

Per ulteriori informazioni sulla risoluzione dei problemi, vedi Risolvi i problemi di esportazione delle iscrizioni.

Una volta risolto l'errore, la sottoscrizione all'esportazione viene riavviata automaticamente a causa di nuovi tentativi periodici.

Prezzi

Ti vengono addebitati i costi per Pub/Sub Lite e Pub/Sub e le risorse utilizzate dalla sottoscrizione di esportazione. Nello specifico, ti verranno addebitati per la velocità effettiva dell'abbonamento allocato e lo spazio di archiviazione sottoscrizione Pub/Sub Lite, che è configurata per Pub/Sub Lite. Ti viene addebitata anche la pubblicazione nell' Pub/Sub di destinazione. Consulta Prezzi di Pub/Sub.

Non sono previsti costi aggiuntivi per l'utilizzo della funzione di esportazione e non sono previsti differenza di prezzo tra le sottoscrizioni esportate in Pub/Sub Lite abbonamenti 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 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 un'esportazione sottoscrizione o eliminare l'argomento messaggi non recapitabili, si verifica un errore.

Per rilevare questo problema:

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

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

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

Se Pub/Sub di destinazione è stato eliminato, ricrea l'argomento con con lo stesso nome. La pubblicazione della sottoscrizione all'esportazione riprenderà, a condizione che le autorizzazioni non sono cambiate.

Se l'argomento messaggi non recapitabili è stato eliminato, creane uno nuovo e aggiorna 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 conteggio di messaggi incompatibili che non è stato possibile esportare.

Per risolvere il problema, utilizza un argomento messaggi non recapitabili per conservare i messaggi incompatibili. Esamina i messaggi per determinare la causa, quindi trasformarli e ripubblicarli, se necessario. Consulta Compatibilità dei messaggi.

L'esportazione è limitata

Per rilevare questo problema:

• Metriche: la metrica subscription/flow_control_status mostra un controllo del flusso motivo di NO_CLIENT_TOKENS, che indica che il limite per partizione di di byte o messaggi in sospeso. Finché il problema non viene 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 di 1 MiB/s per chiave. La sottoscrizione di esportazione scrive le chiavi di messaggio Lite come Chiavi di ordinamento Pub/Sub e Pub/Sub ha 1 MiB/s limit per ogni chiave di ordinamento. Limite superato può causare la limitazione.

Utente non autorizzato a eseguire questa azione

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

Per rilevare questo problema:

• Console Google Cloud: visualizza dettagli dell'abbonamento. Se ci sono 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 corretta o un ruolo per pubblicare messaggi nell'argomento Pub/Sub di destinazione per un altro progetto.
• L'agente di servizio è stato rimosso dal criterio IAM dell'esportazione progetto padre della sottoscrizione.
• L'agente di servizio Pub/Sub Lite è ancora in fase di configurazione. Un servizio dell'agente 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, controlla se all'agente di servizio è stato concesso il corretto autorizzazione o ruolo. Vedi Agenti di servizio.

Passaggi successivi

Scegli tra Pub/Sub o Pub/Sub Lite.