Esportare messaggi Pub/Sub Lite in Pub/Sub

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

Ecco alcuni scenari in cui potresti utilizzare questa funzionalità:

• Interoperano tra carichi di lavoro che utilizzano una combinazione di Pub/Sub Lite e Pub/Sub.
• Esegui la migrazione di un carico di lavoro Pub/Sub Lite a 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 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 abbonamenti standard. I due tipi di sottoscrizione sono identici in termini di utilizzo delle quote e velocità effettiva di prenotazione. Una sottoscrizione di esportazione consuma la capacità della velocità effettiva della sottoscrizione Lite e viene addebitata per la velocità effettiva di pubblicazione di Pub/Sub.

Una sottoscrizione di esportazione connette un argomento Lite a un argomento Pub/Sub. Tuttavia, un argomento Lite può avere più sottoscrizioni di esportazione che si connettono a diversi argomenti Pub/Sub (architettura di fan-out). Puoi inoltre 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 all'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 viene pubblicata in un argomento Pub/Sub per tuo conto. Per farlo, viene utilizzato un account di servizio gestito da Google.

Quando crei la prima sottoscrizione di esportazione in un progetto, viene creato automaticamente un agente di servizio Pub/Sub Lite gestito da Google. Se crei ulteriori sottoscrizioni di esportazione nello stesso progetto, utilizzeranno 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 un singolo argomento. Ti consigliamo di concedere le autorizzazioni a livello di argomento, seguendo il principio del privilegio minimo.

Per maggiori 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 una sottoscrizione per l'esportazione Lite con la console Google Cloud, Google Cloud CLI o l'API Pub/Sub Lite.

Una sottoscrizione Lite Export deve trovarsi nello stesso progetto e nella stessa località dell'argomento Lite a cui è collegata. Per creare l'argomento Lite, vedi 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 saperne di più, consulta Compatibilità dei messaggi.

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

Console

1. Vai alla pagina Lite Subscriptions (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 Consegna i messaggi immediatamente o Consegna 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 Attiva messaggi non recapitabili.
   2. Seleziona un argomento Lite da utilizzare come argomento messaggi non recapitabili oppure 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 per l'esportazione.

10. Fai clic su Crea.

gcloud

Per creare una sottoscrizione all'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 posizione 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 dell'abbonamento per l'esportazione.
• DESIRED_STATE: facoltativo. Lo stato iniziale dell'abbonamento. Sono supportati i seguenti valori:
  • active: la sottoscrizione esporta i messaggi Lite in Pub/Sub. (valore predefinito).
  • paused: l'esportazione dei messaggi Lite è sospesa.

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

Created [SUBSCRIPTION_ID].

Protocollo

Per creare una sottoscrizione Lite Export, 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 pubblicazione, 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 dei 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 della sottoscrizione 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 nella Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Go Pub/Sub.

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

Aggiornare 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 Lite Subscriptions (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 posizione 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 della sottoscrizione di esportazione.
• DESIRED_STATE: facoltativo. Lo stato desiderato dell'abbonamento. Sono supportati i seguenti valori:
  • active: la sottoscrizione esporta i messaggi Lite in Pub/Sub. (valore predefinito).
  • paused: l'esportazione dei 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 un abbonamento 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 pubblicazione, ovvero DELIVER_AFTER_STORED o DELIVER_IMMEDIATELY.
• DESIRED_STATE: lo stato desiderato dell'abbonamento. Sono supportati i seguenti valori:
  • ACTIVE: la sottoscrizione esporta i messaggi Lite in Pub/Sub.
  • PAUSED: l'esportazione dei 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 della sottoscrizione 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 iscrizioni per l'esportazione hanno un'impostazione chiamata stato desiderato, che ha uno di due valori:

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

Per modificare lo stato desiderato nella console Google Cloud:

1. Vai alla pagina Lite Subscriptions (Abbonamenti Lite).

   Vai agli abbonamenti Lite

2. Fai clic sull'ID sottoscrizione Lite.

3. Nella pagina Dettagli 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 per l'esportazione.

best practice

In questa sezione vengono descritte alcune best practice relative all'utilizzo delle sottoscrizioni per l'esportazione.

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. ma inserisce il messaggio nell'argomento 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 sono di 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 hanno 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 attributi a valore singolo.
  • Gli attributi del messaggio 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 incompatibili, consigliamo di utilizzare un argomento messaggi non recapitabili. Puoi assegnare un argomento messaggi non recapitabili quando crei la sottoscrizione di esportazione oppure puoi aggiornare una sottoscrizione per l'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 di Pub/Sub Lite. Deve trovarsi nella stessa località e nello stesso progetto della sottoscrizione di esportazione e deve essere un argomento diverso dall'argomento di origine.

In genere, un argomento messaggi non recapitabili ha un utilizzo ridotto della velocità effettiva. Di conseguenza, consigliamo di assegnare una prenotazione all'argomento messaggi non recapitabili, anziché assegnare la velocità effettiva all'argomento.

Errori di recapito

Una sottoscrizione di esportazione tenta di recapitare tutti i messaggi compatibili all'argomento Pub/Sub di destinazione. Se la consegna del messaggio non va a buon fine, l'abbonamento all'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: non sono state trovate una o più risorse. Ad esempio, l'argomento di destinazione non esiste.

Per maggiori informazioni sulla risoluzione dei problemi, consulta Risolvere i problemi relativi all'esportazione degli abbonamenti.

Una volta risolto l'errore, la sottoscrizione di esportazione viene riavviata 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 addebitati i costi relativi alla velocità effettiva della sottoscrizione allocata e allo spazio di archiviazione nella sottoscrizione Pub/Sub Lite, che sono configurate per l'argomento Pub/Sub Lite. Ti viene addebitato anche il costo della pubblicazione nell'argomento Pub/Sub di destinazione. Consulta la pagina relativa ai 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 quelle standard.

Risolvere i problemi relativi all'esportazione delle iscrizioni

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 messa in pausa, non viene 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 associato a una sottoscrizione di esportazione o elimini 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 ne è stato configurato uno).

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

Se l'argomento messaggi non recapitabili è stato eliminato, crea un nuovo argomento messaggi non recapitabili e aggiorna la sottoscrizione di esportazione in modo che faccia 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. Vedi Compatibilità dei messaggi.

L'esportazione è limitata

Per rilevare questo problema:

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

Questo errore ha diverse possibili cause principali. La maggior parte delle possibili cause si verifica nel back-end, 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 si verificano errori di autorizzazione, lo stato attuale è Permission denied.

• Metriche: la metrica subscription/export_status è PERMISSON_DENIED.

Ad esempio, questo errore può essere causato dalle seguenti situazioni:

• L'agente di servizio Pub/Sub Lite non dispone dell'autorizzazione o del ruolo corretti per pubblicare messaggi nell'argomento Pub/Sub di destinazione in un altro progetto.
• L'agente di servizio è stato rimosso dal criterio IAM del progetto padre dell'abbonamento 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 sono stati concessi l'autorizzazione o il ruolo corretto. Vedi Agenti di servizio.

Passaggi successivi

Scegli tra Pub/Sub e Pub/Sub Lite.